/** A plain JSON object (record of string keys to unknown values). */
export type JsonRecord = Record<string, unknown>;
/** Alias for `JsonRecord` used for request/response body shapes. */
export type JsonBody = JsonRecord;
/** A named parse schema for a daemon route request body. */
export interface RouteBodySchema<T> {
    /** Identifies which route this schema belongs to (for error messages). */
    readonly routeId: string;
    /** Parse a raw JSON body into `T`, or return an error `Response` on validation failure. */
    readonly parse: (body: JsonRecord) => T | Response;
}
/**
 * Create a typed `RouteBodySchema` from a route id and a parse function.
 *
 * @param routeId - Route identifier for error context.
 * @param parse - Function that validates and transforms a `JsonRecord` to `T`, or returns an error `Response`.
 * @returns A `RouteBodySchema<T>` ready to use in route handlers.
 */
export declare function createRouteBodySchema<T>(routeId: string, parse: (body: JsonRecord) => T | Response): RouteBodySchema<T>;
/**
 * Create a typed registry of route body schemas, inferring the full map type.
 *
 * @param schemas - Map of route ids to `RouteBodySchema` instances.
 * @returns The same map with its literal type preserved.
 */
export declare function createRouteBodySchemaRegistry<const TSchemaMap extends Record<string, RouteBodySchema<unknown>>>(schemas: TSchemaMap): TSchemaMap;
/** Type guard that returns `true` when `value` is a non-null, non-array plain object. */
export declare function isJsonRecord(value: unknown): value is JsonRecord;
/**
 * Recursively convert a value to a JSON-safe representation, replacing circular
 * references with `{ $ref: '<json-path>' }` entries.
 *
 * @param value - The value to serialize.
 * @returns A JSON-safe copy of `value`.
 */
export declare function toSerializableJson(value: unknown, stack?: Map<object, string>, path?: string): unknown;
/**
 * Create a JSON `Response` from any value, safely handling circular references.
 *
 * @param body - The value to serialize as the response body.
 * @param init - Optional `ResponseInit` (status, headers, etc.).
 * @returns A `Response` with `Content-Type: application/json`.
 */
export declare function serializableJsonResponse(body: unknown, init?: ResponseInit): Response;
/** Options for bounded integer parsing from query parameters or request bodies. */
export interface BoundedIntegerOptions {
    /** Default value to use when the input is absent or invalid. */
    readonly fallback: number;
    /** Inclusive lower bound. Defaults to `0`. */
    readonly min?: number | undefined;
    /** Inclusive upper bound. Defaults to `1000`. */
    readonly max?: number | undefined;
}
/**
 * Parse an integer from a raw query-parameter string, clamping to `[min, max]` and
 * falling back to `options.fallback` when the value is absent or non-finite.
 *
 * @param raw - The raw string value (or `null` if the parameter was absent).
 * @param options - Bounds and fallback configuration.
 * @returns A clamped integer within `[min, max]`.
 */
export declare function readBoundedInteger(raw: string | null, options: BoundedIntegerOptions): number;
/**
 * Parse a positive integer (min=1) from a query-parameter string.
 *
 * @param raw - The raw string value (or `null`).
 * @param fallback - Default when absent or invalid.
 * @param max - Upper bound; defaults to `1000`.
 * @returns A clamped integer in `[1, max]`.
 */
export declare function readBoundedPositiveInteger(raw: string | null, fallback: number, max?: number): number;
/**
 * Parse a bounded integer from a parsed JSON body value.
 *
 * @param value - The raw body value (should be `number`).
 * @param fallback - Default when absent or non-finite.
 * @param max - Inclusive upper bound.
 * @param min - Inclusive lower bound; defaults to `1`.
 * @returns A clamped integer in `[min, max]`.
 */
export declare function readBoundedBodyInteger(value: unknown, fallback: number, max: number, min?: number): number;
/**
 * Parse an optional bounded integer from a query-parameter string.
 * Returns `undefined` when the parameter is absent or non-finite.
 *
 * @param raw - The raw string value (or `null`).
 * @param min - Inclusive lower bound.
 * @param max - Inclusive upper bound.
 * @returns A clamped integer or `undefined`.
 */
export declare function readOptionalBoundedInteger(raw: string | null, min: number, max: number): number | undefined;
/**
 * Read a non-empty trimmed string from a JSON body field, returning `undefined` if absent or blank.
 *
 * @param body - The parsed request body.
 * @param key - The field key to read.
 * @returns The trimmed string, or `undefined`.
 */
export declare function readOptionalStringField(body: JsonRecord, key: string): string | undefined;
/**
 * Read an array of non-empty trimmed strings from a JSON body field.
 * Entries that are not strings or are blank are skipped. Returns `undefined` when
 * the field is absent, not an array, or all entries were invalid.
 *
 * @param body - The parsed request body.
 * @param key - The field key to read.
 * @param max - Maximum number of entries to include; defaults to `128`.
 * @returns A non-empty string array, or `undefined`.
 */
export declare function readStringArrayField(body: JsonRecord, key: string, max?: number): string[] | undefined;
/**
 * Test whether a single granted scope string covers the required scope.
 * Supports exact match, wildcard `'*'`, and prefix wildcard (e.g. `'sessions:*'`).
 *
 * @param granted - A scope string held by the caller.
 * @param required - The scope the operation requires.
 * @returns `true` if `granted` covers `required`.
 */
export declare function scopeMatches(granted: string, required: string): boolean;
/**
 * Return `true` if the caller holds at least one of the required scopes.
 *
 * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
 * @param requiredScopes - Scopes to check against.
 */
export declare function hasAnyScope(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): boolean;
/**
 * Return the subset of `requiredScopes` not covered by `grantedScopes`.
 *
 * @param grantedScopes - Scopes held by the caller (or `undefined` for no scopes).
 * @param requiredScopes - The full set of required scopes.
 * @returns An array of scope strings that are missing; empty if all are satisfied.
 */
export declare function missingScopes(grantedScopes: readonly string[] | undefined, requiredScopes: readonly string[]): string[];
/** The set of lifecycle action strings accepted by channel lifecycle endpoints. */
export type ChannelLifecycleAction = 'inspect' | 'setup' | 'retest' | 'connect' | 'disconnect' | 'start' | 'stop' | 'login' | 'logout' | 'wait_login';
/** The conversation kind values accepted by channel conversation endpoints. */
export type ChannelConversationKind = 'direct' | 'group' | 'channel' | 'thread' | 'service';
/**
 * Validate and narrow an unknown value to `ChannelLifecycleAction`.
 *
 * @param value - The raw input (typically from a URL path segment or body field).
 * @returns The typed action string, or `null` if the value is not a valid action.
 */
export declare function readChannelLifecycleAction(value: unknown): ChannelLifecycleAction | null;
/**
 * Validate and narrow an unknown value to `ChannelConversationKind`.
 *
 * @param value - The raw input (typically from a URL path segment or body field).
 * @returns The typed kind string, or `null` if the value is not a valid kind.
 */
export declare function readChannelConversationKind(value: unknown): ChannelConversationKind | null;
//# sourceMappingURL=route-helpers.d.ts.map