import type { HttpResponse } from "@nanobpm/urban/runtime";
/** OpenAPI HTTP method keys, lower-cased as they appear on a Path Item Object. */
declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "patch", "options", "head"];
type HttpMethod = (typeof HTTP_METHODS)[number];
/** One enumerated operation: its id, HTTP method, and OpenAPI path template.
 *  `pathParams` are the `{name}` placeholders in the template — the names a caller MUST supply. */
export interface ApiOperation {
    readonly operationId: string;
    readonly method: HttpMethod;
    /** The OpenAPI path template, e.g. "/invoices/{id}" (WITHOUT the `/app/api` base). */
    readonly path: string;
    /** Placeholder names in `path`, e.g. ["id"] for "/invoices/{id}". */
    readonly pathParams: readonly string[];
}
/**
 * Parse an OpenAPI document from text. JSON is tried first (fast path + precise errors; also covers
 * a generated `openapi.json`), then YAML (which subsumes JSON, so authored `.yaml`/`.yml` load).
 * Mirrors urban's own `parseSpec` so a spec that loads in production loads here too — including its
 * root-shape guard: a non-object root (e.g. `42`, `[]`, `null`) is rejected, so a malformed spec
 * fails fast here exactly as the runtime rejects it ("spec must be an object"), rather than silently
 * enumerating zero operations and surfacing later as a confusing "unknown operationId".
 */
export declare function parseOpenApi(text: string): unknown;
/**
 * Enumerate the operations of an OpenAPI document exactly as the runtime does: walk `paths` → each
 * HTTP method → the operation's `operationId`. Operations without an `operationId` are skipped (the
 * runtime cannot dispatch them either), as are those whose `operationId` is not a safe path segment
 * (`isSafeOperationId`) — the runtime never mounts those, so listing them here would let a test call
 * an operation that does not exist. Paths are visited in sorted order for a stable enumeration.
 */
export declare function collectOperations(doc: unknown): ApiOperation[];
/** A route invocation against the in-process router — the low-level primitive the driver builds on. */
export interface DriverRouteRequest {
    method: string;
    path: string;
    query?: Record<string, string> | URLSearchParams;
    headers?: Record<string, string> | Headers;
    body?: string;
}
/** The response returned by {@link ApiDriver.call} and {@link ApiDriver.callRoute}. */
export interface ApiResponse<T = unknown> {
    /** HTTP status (defaults to 200 when the handler omitted it, matching the runtime). */
    readonly status: number;
    /** Response headers. */
    readonly headers: Headers;
    /** The raw response body text (empty string when the handler returned no body). */
    readonly text: string;
    /** The response body parsed as JSON when it is JSON (by `content-type` or a successful parse),
     *  otherwise the raw text. Typed as `T` for caller convenience; no runtime cast is performed. */
    readonly body: T;
}
/** Per-call inputs for {@link ApiDriver.call}. All are optional. */
export interface ApiCallOptions {
    /** Values for the operation's `{name}` path placeholders. Every placeholder must be supplied. */
    params?: Record<string, string | number | boolean>;
    /** Query-string parameters (appended to the URL). */
    query?: Record<string, string | number | boolean> | URLSearchParams;
    /** Request body — JSON-serialized, with `content-type: application/json` set automatically.
     *  Omit for a body-less request (e.g. a GET); pass a string via {@link ApiDriver.callRoute} for
     *  a non-JSON body. */
    body?: unknown;
    /** Extra request headers (merged over the automatic `content-type`). */
    headers?: Record<string, string> | Headers;
}
/** Drives a booted app's OpenAPI operations by `operationId`, plus raw routes via `callRoute`. */
export interface ApiDriver {
    /**
     * Call an operation by its `operationId`. Fills the path template from `params`, prefixes the
     * `/app/api` base, JSON-serializes `body`, and dispatches through the in-process router. Throws
     * on an unknown `operationId` or a missing required path parameter (a test bug, surfaced loudly).
     */
    call<T = unknown>(operationId: string, opts?: ApiCallOptions): Promise<ApiResponse<T>>;
    /**
     * Call a raw route (a page action, a hook, or any path not in the operation set) by method + path.
     * A thin, response-parsing wrapper over the low-level `ui.call`; the caller supplies the exact
     * path (no `/app/api` base is added).
     */
    callRoute<T = unknown>(req: DriverRouteRequest): Promise<ApiResponse<T>>;
    /** The `operationId`s this app exposes, in enumeration order (feeds a coverage gate later). */
    operationIds(): string[];
    /** Look up one enumerated operation by id (its method + path template), or undefined. */
    operation(operationId: string): ApiOperation | undefined;
}
/**
 * Build an {@link ApiDriver} over an enumerated operation set and a low-level route caller (the
 * harness's `ui.call`). Self-contained: no urban runtime imports beyond the `HttpResponse` type.
 */
export declare function createApiDriver(operations: readonly ApiOperation[], uiCall: (req: DriverRouteRequest) => Promise<HttpResponse>): ApiDriver;
export {};