/**
 * In-process HTTP mock server for voice / media-understanding tests.
 *
 * DECISION (per docs/voice-rearchitecture.md §14):
 *  - Tests must NOT hit real provider endpoints. We spin up an ephemeral HTTP
 *    server (random port on 127.0.0.1) and assert request/response shapes.
 *  - SSRF tests intentionally bind to 127.0.0.1 (private). Tests that exercise
 *    the SSRF guard pass `allowPrivateNetwork: true` to the production code.
 *  - This helper is import-only from `__tests__/` files — never from runtime
 *    code. Kept under the runtime tree (not test/) so vitest picks it up via
 *    the existing co-located test discovery.
 */
import { type IncomingMessage } from 'node:http';
export interface MockResponseSpec {
    status?: number;
    headers?: Record<string, string>;
    /** Response body as string, Buffer, or async iterable for streaming. */
    body?: string | Buffer | AsyncIterable<Uint8Array>;
    /** Artificial delay before sending headers (ms). Useful for timeout tests. */
    delayMs?: number;
}
export interface MockRequestRecord {
    method: string;
    path: string;
    headers: Record<string, string | string[] | undefined>;
    body: Buffer;
    receivedAt: number;
}
export type MockHandler = (req: IncomingMessage, bodyBuffer: Buffer) => Promise<MockResponseSpec> | MockResponseSpec;
export interface MockServerHandle {
    /** Base URL like http://127.0.0.1:51234 (no trailing slash). */
    baseUrl: string;
    /** Recorded requests in receive order. */
    requests: MockRequestRecord[];
    /** Stop the server. Idempotent. */
    close(): Promise<void>;
    /** Replace the handler at runtime (e.g. flip from 401 → 200 in rotation tests). */
    setHandler(handler: MockHandler): void;
}
/**
 * Start an HTTP mock server bound to 127.0.0.1 on an ephemeral port. The
 * returned handle exposes the base URL, recorded requests, and a `close()`
 * method tests should call in `afterEach` / `afterAll`.
 */
export declare function startMockServer(initialHandler: MockHandler): Promise<MockServerHandle>;
/**
 * Convenience builder: cycle through a fixed sequence of responses (used by
 * key-rotation tests where call N gets 401 and call N+1 gets 200).
 */
export declare function cycleHandlers(specs: readonly MockResponseSpec[]): MockHandler;