/**
 * Sidecar HTTP router and test server factory.
 *
 * Exports the {@link SidecarRouter} class for method+path-based HTTP routing,
 * JSON response helpers, and a {@link createServer} convenience function for
 * spinning up a test server with all SC-02 routes wired.
 *
 * @module sidecar/server/handler
 */
import type { IncomingMessage, ServerResponse } from "node:http";
import type { SidecarDependencyRegistry } from "./registry.js";
/** Context passed to a domain route handler after URL parsing. */
export interface RouteContext {
    params: Record<string, string>;
    query: Record<string, string>;
    body: unknown;
}
/** Standard result envelope returned by domain route handlers. */
export interface RouteResult {
    ok: boolean;
    data?: unknown;
    error?: {
        code: string;
        message: string;
    };
    /** Optional HTTP response headers override (e.g. for SSE Content-Type). */
    _headers?: Record<string, string>;
    /** Optional raw body to send instead of JSON-serialised RouteResult. */
    _rawBody?: string;
}
/**
 * A domain route entry. Used by route modules (state, sessions, tools,
 * events, catalog) to declare their endpoints.
 *
 * The `handler` receives a parsed context and returns a structured result
 * that the router serialises as JSON.
 */
export interface Route {
    method: string;
    path: string;
    handler: (ctx: RouteContext, registry: SidecarDependencyRegistry) => Promise<RouteResult>;
}
/**
 * Send a JSON response with the given status code and body.
 *
 * @param res    - HTTP server response.
 * @param status - HTTP status code.
 * @param body   - Serializable body.
 * @param headers - Optional extra response headers.
 */
export declare function sendJson(res: ServerResponse, status: number, body: unknown, headers?: Record<string, string>): void;
/**
 * Send a transport-level error response (not a {@link RouteResult}).
 *
 * @param res     - HTTP server response.
 * @param status  - HTTP error status code.
 * @param code    - Machine-readable error code.
 * @param message - Human-readable error description.
 */
export declare function sendError(res: ServerResponse, status: number, code: string, message: string): void;
/**
 * Method+path HTTP router for the sidecar server.
 *
 * Routes are declared as lazy {@link Route} arrays and compiled to
 * RegExp patterns on construction. URL parameters (e.g. `:id`) are
 * extracted as named capture groups.
 *
 * @example
 * ```ts
 * const router = new SidecarRouter(routes, registry)
 * const server = http.createServer((req, res) => { void router.handle(req, res) })
 * server.listen(0, "127.0.0.1")
 * ```
 */
export declare class SidecarRouter {
    #private;
    constructor(routes: Route[], registry: SidecarDependencyRegistry);
    /**
     * Handle an incoming HTTP request.
     *
     * 1. Matches the HTTP method + URL path against compiled routes.
     * 2. If matched, extracts URL params, parses query string, reads body.
     * 3. Calls the route handler and sends the result as JSON.
     * 4. If not matched → 404.
     * 5. If method mismatch → 405.
     *
     * @param req - Incoming HTTP request.
     * @param res - HTTP server response.
     */
    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
}
export interface SidecarServerHandle {
    port: number;
    close: () => Promise<void>;
}
/**
 * Create a test HTTP server with all SC-02 routes wired.
 *
 * This function is a convenience for the handler smoke test. It attempts
 * to dynamically import every route module; imports that fail (routes
 * not yet implemented) are silently skipped so the function works from
 * W1 onward.
 *
 * @param options - Server options including the dependency registry.
 * @returns A server handle bound to `127.0.0.1:0`.
 */
export declare function createServer(options: {
    registry: SidecarDependencyRegistry;
}): Promise<SidecarServerHandle>;
//# sourceMappingURL=handler.d.ts.map