api-invoke 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1359 @@
+/**
+ * Classified API errors with human/agent-readable suggestions.
+ * Each error has a `kind` for programmatic handling and `retryable` for retry logic.
+ */
+/**
+ * Error classification constants. Use with {@link ApiInvokeError.kind} for programmatic error handling.
+ *
+ * @example
+ * ```ts
+ * if (error.kind === ErrorKind.RATE_LIMIT) {
+ *   // Wait and retry
+ * }
+ * ```
+ */
+declare const ErrorKind: {
+    readonly CORS: "cors";
+    readonly NETWORK: "network";
+    readonly AUTH: "auth";
+    readonly HTTP: "http";
+    readonly PARSE: "parse";
+    readonly RATE_LIMIT: "rate-limit";
+    readonly TIMEOUT: "timeout";
+    readonly GRAPHQL: "graphql";
+};
+type ErrorKind = (typeof ErrorKind)[keyof typeof ErrorKind];
+/** Error name constant used on all ApiInvokeError instances. Useful for cross-realm `instanceof` checks. */
+declare const API_INVOKE_ERROR_NAME: "ApiInvokeError";
+/**
+ * Structured error thrown by api-invoke for all API failures.
+ * Includes a machine-readable `kind`, a human-readable `suggestion`, and a `retryable` flag.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.execute('getUser', { userId: 123 })
+ * } catch (error) {
+ *   if (error instanceof ApiInvokeError) {
+ *     console.log(error.kind)       // 'auth', 'network', 'rate-limit', etc.
+ *     console.log(error.suggestion) // Human-readable recovery advice
+ *     console.log(error.retryable)  // Whether retrying might succeed
+ *   }
+ * }
+ * ```
+ */
+declare class ApiInvokeError extends Error {
+    /** Error classification for programmatic handling. */
+    readonly kind: ErrorKind | string;
+    /** HTTP status code, if the error originated from an HTTP response. */
+    readonly status?: number;
+    /** Human-readable suggestion for how to resolve this error. */
+    readonly suggestion: string;
+    /** Whether retrying the request might succeed (e.g. true for rate limits, network errors). */
+    readonly retryable: boolean;
+    /** Response body from the API (when available). May be parsed JSON, a string, or binary data depending on the response content type. */
+    readonly responseBody?: unknown;
+    constructor(opts: {
+        kind: ErrorKind | string;
+        message: string;
+        suggestion: string;
+        retryable?: boolean;
+        status?: number;
+        responseBody?: unknown;
+    });
+}
+/**
+ * Create a CORS error for when a browser request is blocked by the same-origin policy.
+ * @param url - The URL that was blocked
+ * @returns An `ApiInvokeError` with `kind: 'cors'` and `retryable: false`
+ */
+declare function corsError(url: string): ApiInvokeError;
+/**
+ * Create a network error for connection failures.
+ * @param url - The URL that failed to connect
+ * @returns An `ApiInvokeError` with `kind: 'network'` and `retryable: true`
+ */
+declare function networkError(url: string): ApiInvokeError;
+/**
+ * Create an authentication/authorization error (401 or 403).
+ * @param url - The URL that returned the error
+ * @param status - HTTP status code (401 or 403)
+ * @param responseBody - Parsed response body, if available
+ * @returns An `ApiInvokeError` with `kind: 'auth'` and `retryable: false`
+ */
+declare function authError(url: string, status: 401 | 403, responseBody?: unknown): ApiInvokeError;
+/**
+ * Create an HTTP error for non-2xx responses (excluding 401/403 which use {@link authError}).
+ * Status 429 is classified as `kind: 'rate-limit'`; all others as `kind: 'http'`.
+ * @param url - The URL that returned the error
+ * @param status - HTTP status code
+ * @param statusText - HTTP status text (e.g. 'Not Found')
+ * @param responseBody - Parsed response body, if available
+ * @returns An `ApiInvokeError` with `retryable: true` for 429 and 5xx status codes
+ */
+declare function httpError(url: string, status: number, statusText: string, responseBody?: unknown): ApiInvokeError;
+/**
+ * Create a parse error for when the response body cannot be read as the expected format.
+ * @param url - The URL that returned the unparseable response
+ * @param expectedType - The expected format (default: 'JSON')
+ * @returns An `ApiInvokeError` with `kind: 'parse'` and `retryable: false`
+ */
+declare function parseError(url: string, expectedType?: string): ApiInvokeError;
+/**
+ * Create a GraphQL error for when the response contains errors and no data (total failure).
+ * @param messages - Joined error messages from the GraphQL response
+ * @param status - HTTP status code (usually 200 for GraphQL)
+ * @param responseBody - Full GraphQL response body
+ * @returns An `ApiInvokeError` with `kind: 'graphql'` and `retryable: false`
+ */
+declare function graphqlError(messages: string, status?: number, responseBody?: unknown): ApiInvokeError;
+/**
+ * Create a timeout error for when a request exceeds the configured `timeoutMs`.
+ * @param url - The URL that timed out
+ * @returns An `ApiInvokeError` with `kind: 'timeout'` and `retryable: true`
+ */
+declare function timeoutError(url: string): ApiInvokeError;
+
+/**
+ * Core types for api-invoke.
+ * Spec-agnostic — these work with any API format (OpenAPI, GraphQL, raw URL, manual builder).
+ * All enums use `as const` objects for autocomplete + extensibility.
+ */
+
+/** Standard HTTP methods supported by api-invoke. */
+declare const HttpMethod: {
+    readonly GET: "GET";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly PATCH: "PATCH";
+    readonly DELETE: "DELETE";
+    readonly HEAD: "HEAD";
+    readonly OPTIONS: "OPTIONS";
+};
+type HttpMethod = (typeof HttpMethod)[keyof typeof HttpMethod];
+/** Where a parameter is located in the HTTP request. */
+declare const ParamLocation: {
+    readonly PATH: "path";
+    readonly QUERY: "query";
+    readonly HEADER: "header";
+    readonly COOKIE: "cookie";
+};
+type ParamLocation = (typeof ParamLocation)[keyof typeof ParamLocation];
+/** Supported authentication types. */
+declare const AuthType: {
+    readonly BEARER: "bearer";
+    readonly BASIC: "basic";
+    readonly API_KEY: "apiKey";
+    readonly QUERY_PARAM: "queryParam";
+    readonly OAUTH2: "oauth2";
+    readonly COOKIE: "cookie";
+};
+type AuthType = (typeof AuthType)[keyof typeof AuthType];
+/** Detected API specification format. */
+declare const SpecFormat: {
+    readonly OPENAPI_3: "openapi-3";
+    readonly OPENAPI_2: "openapi-2";
+    readonly RAW_URL: "raw-url";
+    readonly MANUAL: "manual";
+    readonly GRAPHQL: "graphql";
+};
+type SpecFormat = (typeof SpecFormat)[keyof typeof SpecFormat];
+/** Well-known HTTP header names used internally. */
+declare const HeaderName: {
+    readonly ACCEPT: "Accept";
+    readonly AUTHORIZATION: "Authorization";
+    readonly CONTENT_TYPE: "Content-Type";
+    readonly COOKIE: "Cookie";
+};
+type HeaderName = (typeof HeaderName)[keyof typeof HeaderName];
+/**
+ * A parsed API specification, normalized into a spec-agnostic format.
+ * This is the central data model — all adapters (OpenAPI, GraphQL, raw URL, manual builder) produce this shape.
+ */
+interface ParsedAPI {
+    /** Human-readable API title (e.g. 'Petstore API'). */
+    title: string;
+    /** API version string from the spec (e.g. '1.0.0'). */
+    version: string;
+    /** Base URL for all operations (e.g. 'https://api.example.com/v1'). */
+    baseUrl: string;
+    /** All available API operations extracted from the spec. */
+    operations: Operation[];
+    /** Authentication schemes declared in the spec. */
+    authSchemes: AuthScheme[];
+    /** Which adapter produced this ParsedAPI. */
+    specFormat: SpecFormat | string;
+    /** Raw spec version string from the spec (e.g. '3.0.3', '2.0'). Only set for OpenAPI specs. */
+    rawSpecVersion?: string;
+}
+/**
+ * A single API operation (endpoint + method).
+ * Produced by parsing a spec or using the manual builder.
+ */
+interface Operation {
+    /** Unique identifier for this operation (e.g. 'listUsers', 'get_users'). */
+    id: string;
+    /** URL path template with placeholders (e.g. '/users/{userId}'). */
+    path: string;
+    /** HTTP method (e.g. 'GET', 'POST'). */
+    method: HttpMethod | string;
+    /** Short summary of what this operation does. */
+    summary?: string;
+    /** Longer description of the operation's behavior. */
+    description?: string;
+    /** Parameters accepted by this operation (path, query, header, cookie). */
+    parameters: Parameter[];
+    /** Request body definition, if the operation accepts one. */
+    requestBody?: RequestBody;
+    /** Primary response schema for the operation's success case. For OpenAPI specs, this is the first 2xx schema found (see parser for priority). Useful for code generation or validation. */
+    responseSchema?: unknown;
+    /** Success and default response schemas keyed by HTTP status code (e.g. '200', '201', 'default'). Codes without schemas (e.g. 204 No Content) are omitted. Error codes (4xx/5xx) are not extracted. */
+    responseSchemas?: Record<string, unknown>;
+    /** Primary response content type (e.g. 'application/json', 'application/xml'). Used as the default Accept header. */
+    responseContentType?: ContentType | string;
+    /** Error response descriptions keyed by HTTP status code (e.g. '404' → 'User not found'). Extracted from 4xx/5xx responses in the spec. */
+    errorHints?: Record<string, string>;
+    /** Tags for grouping operations (e.g. ['users', 'admin']). */
+    tags: string[];
+    /**
+     * Custom body builder for protocol adapters (e.g., GraphQL).
+     * When set and no explicit 'body' key is in args, the executor calls this instead of flat-arg assembly to construct the request body.
+     * Receives the full args map and returns the body data to be serialized.
+     */
+    buildBody?: (args: Record<string, unknown>) => unknown;
+}
+/**
+ * A parameter accepted by an API operation.
+ */
+interface Parameter {
+    /** Parameter name as used in the request (e.g. 'userId', 'page'). */
+    name: string;
+    /** Where this parameter appears in the request. */
+    in: ParamLocation;
+    /** Whether this parameter must be provided. Path parameters are always required. */
+    required: boolean;
+    /** Human-readable description of the parameter. */
+    description: string;
+    /** Type and constraint information for this parameter. */
+    schema: ParameterSchema;
+}
+/**
+ * Type and constraint information for a parameter.
+ */
+interface ParameterSchema {
+    /** Data type (e.g. 'string', 'integer', 'boolean', 'array'). */
+    type: string;
+    /** Format hint (e.g. 'int32', 'date-time', 'email', 'uuid'). */
+    format?: string;
+    /** Allowed values for this parameter. */
+    enum?: unknown[];
+    /** Default value used when the parameter is not provided. */
+    default?: unknown;
+    /** Example value for documentation and testing. */
+    example?: unknown;
+    /** Minimum value for numeric parameters. */
+    minimum?: number;
+    /** Maximum value for numeric parameters. */
+    maximum?: number;
+    /** Maximum length for string parameters. */
+    maxLength?: number;
+    /** Element schema for array parameters. */
+    items?: ParameterSchema;
+}
+/** Well-known MIME content types. */
+declare const ContentType: {
+    readonly JSON: "application/json";
+    readonly FORM_URLENCODED: "application/x-www-form-urlencoded";
+    readonly MULTIPART: "multipart/form-data";
+    readonly XML: "application/xml";
+    readonly OCTET_STREAM: "application/octet-stream";
+    readonly TEXT: "text/plain";
+    readonly SSE: "text/event-stream";
+};
+type ContentType = (typeof ContentType)[keyof typeof ContentType];
+/**
+ * Request body definition for an operation.
+ */
+interface RequestBody {
+    /** Whether the request body is required for this operation. */
+    required: boolean;
+    /** Human-readable description of the request body. */
+    description?: string;
+    /** Content type for the request body (e.g. 'application/json'). */
+    contentType: ContentType | string;
+    /** Schema describing the request body structure. */
+    schema: RequestBodySchema;
+}
+/**
+ * Schema for a request body, with flattened top-level properties for easy access.
+ */
+interface RequestBodySchema {
+    /** Top-level type (usually 'object'). */
+    type: string;
+    /** Original unprocessed schema from the spec. Useful for advanced use cases like code generation. */
+    raw: unknown;
+    /** Flattened top-level properties, keyed by property name. Only present when type is 'object'. */
+    properties?: Record<string, RequestBodyProperty>;
+    /** Names of required properties. */
+    required?: string[];
+}
+/**
+ * A single property within a request body schema.
+ */
+interface RequestBodyProperty {
+    /** Data type (e.g. 'string', 'integer', 'boolean'). */
+    type: string;
+    /** Format hint (e.g. 'date-time', 'email'). */
+    format?: string;
+    /** Human-readable description of this property. */
+    description?: string;
+    /** Allowed values for this property. */
+    enum?: unknown[];
+    /** Default value for this property. */
+    default?: unknown;
+    /** Example value for documentation and testing. */
+    example?: unknown;
+    /** True when this property is an object or array with nested structure. Useful for UI rendering decisions. */
+    nested?: boolean;
+}
+/**
+ * An authentication scheme declared in the API spec.
+ * Describes how the API expects credentials to be provided, but does not contain actual credentials.
+ */
+interface AuthScheme {
+    /** Scheme name from the spec (e.g. 'bearerAuth', 'api_key'). */
+    name: string;
+    /** Mapped auth type, or null if the scheme is unsupported. */
+    authType: AuthType | null;
+    /** Additional scheme-specific metadata (e.g. header name for API keys, OAuth2 URLs). */
+    metadata: Record<string, string>;
+    /** Human-readable description of the auth scheme. */
+    description: string;
+}
+/**
+ * Credentials for authenticating API requests.
+ * Discriminated union on `type` — use the `AuthType` constants to construct.
+ *
+ * @example
+ * // Bearer token
+ * const auth: Auth = { type: AuthType.BEARER, token: 'sk-...' }
+ *
+ * @example
+ * // API key in a header
+ * const auth: Auth = { type: AuthType.API_KEY, location: ParamLocation.HEADER, name: 'X-API-Key', value: 'my-key' }
+ */
+type Auth = {
+    type: typeof AuthType.BEARER;
+    token: string;
+} | {
+    type: typeof AuthType.BASIC;
+    username: string;
+    password: string;
+} | {
+    type: typeof AuthType.API_KEY;
+    location: typeof ParamLocation.HEADER | typeof ParamLocation.QUERY;
+    name: string;
+    value: string;
+} | {
+    type: typeof AuthType.OAUTH2;
+    accessToken: string;
+    refreshToken?: string;
+    tokenUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+} | {
+    type: typeof AuthType.COOKIE;
+    name: string;
+    value: string;
+};
+/**
+ * A fully constructed HTTP request ready to be sent (or previewed).
+ * Produced by {@link buildRequest} and included in execution results for debugging.
+ */
+interface BuiltRequest {
+    /** HTTP method (e.g. 'GET', 'POST'). */
+    method: HttpMethod | string;
+    /** Fully resolved URL with path and query parameters substituted. */
+    url: string;
+    /** Request headers including auth, content-type, and accept. */
+    headers: Record<string, string>;
+    /** Serialized request body, if present. String for JSON/form-urlencoded, FormData for multipart. */
+    body?: string | FormData;
+}
+/**
+ * Subset of {@link ErrorKind} that can appear on {@link ExecutionResult.errorKind}.
+ * Only HTTP-response errors — client-side errors (CORS, NETWORK, TIMEOUT) always throw regardless of `throwOnHttpError`.
+ */
+type ResultErrorKind = typeof ErrorKind.AUTH | typeof ErrorKind.RATE_LIMIT | typeof ErrorKind.HTTP;
+/**
+ * Result of executing an API operation.
+ * Contains the parsed response data, status, headers, timing, and the original request for debugging.
+ */
+interface ExecutionResult {
+    /** HTTP status code (e.g. 200, 404, 500). */
+    status: number;
+    /** Parsed response body. JSON responses are parsed to objects; binary responses are ArrayBuffers; others attempt JSON parsing before falling back to strings. */
+    data: unknown;
+    /** Response content type from the Content-Type header (e.g. 'application/json', 'text/xml'). */
+    contentType: string;
+    /** Response headers as a flat key-value map. */
+    headers: Record<string, string>;
+    /** The request that was sent, useful for debugging and logging. */
+    request: BuiltRequest;
+    /** Request duration in milliseconds (from send to response headers received, before body parsing). */
+    elapsedMs: number;
+    /** Set when `throwOnHttpError` is false and the response is an error. Allows programmatic error classification without throwing. */
+    errorKind?: ResultErrorKind;
+}
+/**
+ * A parsed Server-Sent Event.
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
+ */
+interface SSEEvent {
+    /** Event type (e.g. 'message', 'error'). Absent when no `event:` field was set in the stream. */
+    event?: string;
+    /** Event payload. For JSON-encoded events, this is the raw string — parse it with `JSON.parse()`. */
+    data: string;
+    /** Last event ID. Per spec, values containing U+0000 NULL are ignored by the parser. */
+    id?: string;
+    /** Reconnection time in milliseconds. Must be a non-negative integer per spec. */
+    retry?: number;
+}
+/**
+ * Result of a streaming API call. Errors always throw before this object is constructed,
+ * so `status` is guaranteed to be 2xx. The `stream` is single-use — iterating it twice
+ * will fail since the underlying ReadableStream reader can only be consumed once.
+ * Unlike `ExecutionResult`, `elapsedMs` measures time to receive the response headers (not total stream consumption time)
+ * and `errorKind` is absent (errors throw, no non-throwing mode for streams).
+ */
+interface StreamingExecutionResult {
+    /** HTTP status code (guaranteed 2xx). */
+    status: number;
+    /** Async iterable of SSE events. Single-use — can only be iterated once. */
+    stream: AsyncIterable<SSEEvent>;
+    /** Response content type (expected: 'text/event-stream'). */
+    contentType: string;
+    /** Response headers as a flat key-value map. */
+    headers: Record<string, string>;
+    /** The request that was sent. */
+    request: BuiltRequest;
+    /** Time-to-first-byte in milliseconds (not total stream consumption time). */
+    elapsedMs: number;
+}
+/**
+ * Post-processing hook that transforms a ParsedAPI after parsing.
+ * Useful for adding custom operations, modifying base URLs, or injecting metadata.
+ */
+interface Enricher {
+    /** Enricher name for identification in logs and debugging. */
+    readonly name: string;
+    /**
+     * Transform the parsed API. May return a new object or modify in place.
+     * Can be async for enrichers that need to fetch external data.
+     */
+    enrichAPI(api: ParsedAPI): ParsedAPI | Promise<ParsedAPI>;
+}
+/**
+ * Configuration options for {@link ApiInvokeClient} and {@link createClient}.
+ */
+interface ClientOptions {
+    /** Original spec URL, used for base URL fallback when the spec has no servers/host field. */
+    specUrl?: string;
+    /** Default authentication credentials for all operations. Can be overridden per-call. */
+    auth?: Auth | Auth[];
+    /** Middleware pipeline applied to every request/response (e.g. logging, CORS proxy). */
+    middleware?: Middleware[];
+    /** Custom fetch implementation. Defaults to `globalThis.fetch`. Useful for testing or wrapping with {@link withRetry}. */
+    fetch?: typeof globalThis.fetch;
+    /** Post-parse enricher that transforms the ParsedAPI before client construction. */
+    enricher?: Enricher;
+    /** Default timeout in milliseconds for all operations. 0 = no timeout (default). */
+    timeoutMs?: number;
+}
+/**
+ * Middleware hook for intercepting requests and responses.
+ * All hooks are optional — implement only the ones you need.
+ */
+interface Middleware {
+    /** Middleware name for identification in logs and debugging. */
+    name?: string;
+    /**
+     * Called before each request is sent. Can modify the URL and request init.
+     * Middleware runs in order — later middleware sees changes from earlier ones.
+     */
+    onRequest?(url: string, init: RequestInit): {
+        url: string;
+        init: RequestInit;
+    } | Promise<{
+        url: string;
+        init: RequestInit;
+    }>;
+    /**
+     * Called after receiving a response. Can transform or replace the response.
+     * Runs in order — later middleware sees the response from earlier ones.
+     */
+    onResponse?(response: Response): Response | Promise<Response>;
+    /**
+     * Called when a fetch error occurs (network failure, CORS, timeout).
+     * For logging/monitoring only — cannot recover from the error.
+     * Exceptions thrown by this handler are suppressed (logged as warnings).
+     */
+    onError?(error: Error): void;
+}
+
+/**
+ * Main client — the public API for api-invoke.
+ * Supports three tiers: full spec (OpenAPI/GraphQL), raw URL, and zero-spec execution.
+ */
+
+/**
+ * High-level API client. Wraps a {@link ParsedAPI} and provides methods to execute operations by ID.
+ * Created via {@link createClient} (recommended) or by constructing directly with a `ParsedAPI`.
+ *
+ * @example
+ * ```ts
+ * const client = await createClient('https://petstore.swagger.io/v2/swagger.json')
+ * const result = await client.execute('getInventory')
+ * console.log(result.data)
+ * ```
+ */
+declare class ApiInvokeClient {
+    /** The parsed API specification backing this client. */
+    readonly api: ParsedAPI;
+    private auth;
+    private middleware;
+    private fetchFn;
+    private timeoutMs;
+    /**
+     * @param api - Parsed API specification (from any adapter)
+     * @param options - Client configuration (auth, middleware, fetch, timeout)
+     */
+    constructor(api: ParsedAPI, options?: ClientOptions);
+    /** The resolved base URL for this API. */
+    get baseUrl(): string;
+    /** All available operations from the parsed spec. */
+    get operations(): Operation[];
+    /** Authentication schemes declared in the spec. Useful for building auth UIs. */
+    get authSchemes(): AuthScheme[];
+    /**
+     * Set authentication credentials for all subsequent requests.
+     * @param auth - Single credential or array for composing multiple schemes
+     */
+    setAuth(auth: Auth | Auth[]): void;
+    /**
+     * Clear authentication credentials.
+     */
+    clearAuth(): void;
+    /**
+     * Find an operation by its ID.
+     * @param operationId - The operation ID to search for (e.g. 'listUsers', 'get_users_userId')
+     * @returns The operation, or undefined if not found
+     */
+    findOperation(operationId: string): Operation | undefined;
+    /**
+     * Execute an operation by ID with arguments.
+     *
+     * @param operationId - The operation ID from the parsed spec
+     * @param args - Key-value pairs for path, query, header, and body parameters
+     * @param options - Per-call overrides for auth, accept header, error behavior, and redirect mode
+     * @returns The execution result with status, parsed data, and response metadata
+     * @throws {ApiInvokeError} For network, CORS, timeout, and (by default) HTTP errors
+     * @throws {Error} If the operation ID is not found
+     *
+     * @example
+     * ```ts
+     * const result = await client.execute('getUser', { userId: 123 })
+     * console.log(result.status, result.data)
+     * ```
+     */
+    execute(operationId: string, args?: Record<string, unknown>, options?: {
+        auth?: Auth | Auth[];
+        accept?: string;
+        throwOnHttpError?: boolean;
+        redirect?: RequestInit['redirect'];
+    }): Promise<ExecutionResult>;
+    /**
+     * Execute an operation as a stream, returning an async iterable of SSE events.
+     * Errors always throw (no non-throwing mode for streams).
+     *
+     * @param operationId - The operation ID from the parsed spec
+     * @param args - Key-value pairs for path, query, header, and body parameters
+     * @param options - Per-call overrides for auth, accept header, abort signal, and event callback. The client-level `timeoutMs` applies to the initial connection.
+     * @returns Streaming result with an async iterable `stream` property
+     * @throws {ApiInvokeError} For network, CORS, timeout, and HTTP errors
+     * @throws {Error} If the operation ID is not found
+     *
+     * @example
+     * ```ts
+     * const result = await client.executeStream('chatCompletion', {
+     *   model: 'gpt-4', messages: [{ role: 'user', content: 'Hi' }], stream: true,
+     * })
+     * for await (const event of result.stream) {
+     *   console.log(event.data)
+     * }
+     * ```
+     */
+    executeStream(operationId: string, args?: Record<string, unknown>, options?: {
+        auth?: Auth | Auth[];
+        accept?: string;
+        signal?: AbortSignal;
+        onEvent?: (event: SSEEvent) => void;
+    }): Promise<StreamingExecutionResult>;
+}
+/**
+ * Create a client from an OpenAPI spec URL, GraphQL endpoint, spec object, or raw API URL.
+ *
+ * Auto-detection logic:
+ * - OpenAPI spec URL (e.g. ends with `/openapi.json`) → parsed spec with all operations
+ * - GraphQL endpoint URL (path contains `/graphql`) → introspection query, one operation per field
+ * - Raw URL → attempts content-based spec detection, falls back to single-operation raw mode
+ * - GraphQL introspection object (`{ __schema }` or `{ data: { __schema } }`) → parsed directly
+ * - OpenAPI spec object (parsed JSON/YAML) → parsed directly
+ *
+ * @param input - OpenAPI spec URL, GraphQL endpoint URL, raw API URL, or pre-parsed spec/introspection object
+ * @param options - Client configuration (auth, middleware, fetch, enricher, timeout)
+ * @returns A configured {@link ApiInvokeClient} ready to execute operations
+ * @throws {Error} If the spec cannot be fetched or parsed
+ *
+ * @example
+ * ```ts
+ * // From OpenAPI spec URL
+ * const client = await createClient('https://petstore.swagger.io/v2/swagger.json')
+ *
+ * // From GraphQL endpoint
+ * const client = await createClient('https://countries.trevorblades.com/graphql')
+ *
+ * // From raw API URL
+ * const client = await createClient('https://api.example.com/users?page=1')
+ *
+ * // From spec object
+ * const client = await createClient(specJson, { auth: { type: 'bearer', token: 'sk-...' } })
+ * ```
+ */
+declare function createClient(input: string | object, options?: ClientOptions): Promise<ApiInvokeClient>;
+
+/**
+ * HTTP request execution with body serialization (JSON, form-urlencoded, multipart) and error classification.
+ * Pluggable: uses global fetch by default, can be overridden.
+ */
+
+/**
+ * Options for {@link buildRequest} — only request-construction concerns, no runtime/execution options.
+ */
+interface BuildRequestOptions {
+    /** Authentication credentials to inject into the request. */
+    auth?: Auth | Auth[];
+    /** Override the Accept header. Defaults to `operation.responseContentType` or `'application/json'`. */
+    accept?: string;
+}
+/**
+ * Options for {@link executeOperation} and {@link executeOperationStream}.
+ * Extends {@link BuildRequestOptions} with runtime and execution concerns.
+ */
+interface ExecuteOptions extends BuildRequestOptions {
+    /** Middleware pipeline applied to the request/response. */
+    middleware?: Middleware[];
+    /** Custom fetch implementation. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** If false, return ExecutionResult for all HTTP errors instead of throwing. Client-side errors (CORS, network, timeout) always throw regardless. Default: true. */
+    throwOnHttpError?: boolean;
+    /** Timeout in milliseconds. 0 = no timeout (default). */
+    timeoutMs?: number;
+    /** AbortSignal to cancel the request. */
+    signal?: AbortSignal;
+    /** Redirect behavior passed to fetch. Unset by default (fetch implementations typically default to 'follow'). */
+    redirect?: RequestInit['redirect'];
+    /** Extra headers to merge into the request. Applied after buildRequest, so they override spec-derived headers. */
+    headers?: Record<string, string>;
+}
+
+/**
+ * Build a request without executing it (dry-run / preview).
+ * Validates parameters, assembles the body, and injects auth — but does not send.
+ *
+ * @param baseUrl - Base URL for the API (e.g. 'https://api.example.com/v1')
+ * @param operation - The operation to build a request for
+ * @param args - Key-value pairs for path, query, header, and body parameters
+ * @param options - Auth and accept header overrides
+ * @returns A fully constructed request ready to inspect or send manually
+ * @throws {Error} If required parameters are missing
+ * @throws {TypeError} If the URL is malformed when using query-based API key auth
+ */
+declare function buildRequest(baseUrl: string, operation: Operation, args: Record<string, unknown>, options?: BuildRequestOptions): BuiltRequest;
+/**
+ * Execute an API call for an operation with arguments.
+ * Builds the URL, injects auth, applies middleware, and classifies errors.
+ *
+ * @param baseUrl - Base URL for the API
+ * @param operation - The operation to execute
+ * @param args - Key-value pairs for path, query, header, and body parameters
+ * @param options - Execution options (auth, middleware, fetch, timeout, error behavior)
+ * @returns The execution result with parsed response data
+ * @throws {ApiInvokeError} For network, CORS, timeout, parse, and (by default) HTTP errors
+ */
+declare function executeOperation(baseUrl: string, operation: Operation, args: Record<string, unknown>, options?: ExecuteOptions): Promise<ExecutionResult>;
+/**
+ * Execute a raw HTTP request without an API spec (Tier 3: zero spec).
+ * Still provides error classification, response parsing, and timing.
+ *
+ * @param url - Full URL to request
+ * @param options - Request options (method, headers, body, auth, middleware)
+ * @returns The execution result with parsed response data
+ * @throws {ApiInvokeError} For network, CORS, timeout, parse, and (by default) HTTP errors
+ */
+declare function executeRaw(url: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    auth?: Auth | Auth[];
+    middleware?: Middleware[];
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    accept?: string;
+    redirect?: RequestInit['redirect'];
+}): Promise<ExecutionResult>;
+/**
+ * Execute an API call and return a streaming async iterable of SSE events.
+ * Errors always throw (no non-throwing mode for streams).
+ *
+ * @param baseUrl - Base URL for the API
+ * @param operation - The operation to execute
+ * @param args - Key-value pairs for path, query, header, and body parameters
+ * @param options - Execution options, plus optional `onEvent` callback for each SSE event
+ * @returns Streaming result with an async iterable `stream` property
+ * @throws {ApiInvokeError} For network, CORS, timeout, parse, and HTTP errors
+ */
+declare function executeOperationStream(baseUrl: string, operation: Operation, args: Record<string, unknown>, options?: ExecuteOptions & {
+    onEvent?: (event: SSEEvent) => void;
+}): Promise<StreamingExecutionResult>;
+/**
+ * Execute a raw streaming HTTP request without an API spec (Tier 3: zero spec).
+ * Returns an async iterable of SSE events.
+ *
+ * @param url - Full URL to request
+ * @param options - Request options (method, headers, body, auth, middleware, onEvent callback)
+ * @returns Streaming result with an async iterable `stream` property
+ * @throws {ApiInvokeError} For network, CORS, timeout, parse, and HTTP errors
+ */
+declare function executeRawStream(url: string, options?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    auth?: Auth | Auth[];
+    middleware?: Middleware[];
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    accept?: string;
+    redirect?: RequestInit['redirect'];
+    onEvent?: (event: SSEEvent) => void;
+}): Promise<StreamingExecutionResult>;
+
+/**
+ * Parse a Server-Sent Events stream into an async iterable of events.
+ * Implements the WHATWG SSE parsing algorithm.
+ *
+ * @param body - ReadableStream from a fetch response (e.g. `response.body`)
+ * @returns Async generator yielding parsed {@link SSEEvent} objects
+ * @throws {Error} If the stream contains invalid UTF-8 data
+ * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#parsing-an-event-stream
+ */
+declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEEvent>;
+
+/**
+ * Heuristics for detecting API spec formats from URLs and content.
+ * Used by `createClient()` for auto-detection and available for consumers
+ * that implement their own detection pipelines.
+ */
+/**
+ * Detect if a URL likely points to an OpenAPI/Swagger spec by URL pattern.
+ * Checks for common spec file extensions and path patterns.
+ *
+ * @param url - Absolute URL to check
+ * @returns `true` if the URL matches a known spec URL pattern
+ */
+declare function isSpecUrl(url: string): boolean;
+/**
+ * Detect if a parsed JSON object is an OpenAPI/Swagger spec by checking
+ * for the required top-level `openapi` (3.x) or `swagger` (2.0) key.
+ *
+ * @param data - Parsed JSON value to check
+ * @returns `true` if the data looks like an OpenAPI/Swagger spec
+ */
+declare function isSpecContent(data: unknown): data is Record<string, unknown>;
+/**
+ * Detect if a URL likely points to a GraphQL endpoint by URL pattern.
+ * Checks for common GraphQL path suffixes.
+ *
+ * @param url - Absolute URL to check
+ * @returns `true` if the URL matches a known GraphQL endpoint pattern
+ */
+declare function isGraphQLUrl(url: string): boolean;
+
+/**
+ * URL and parameter construction utilities.
+ * Handles path parameter interpolation, query params, header params, cookie params, and slash normalization.
+ */
+
+/**
+ * Build a full URL from base URL, operation path, and arguments.
+ * Handles path parameter interpolation, query parameter serialization, and slash normalization.
+ *
+ * @param baseUrl - Base URL for the API (e.g. 'https://api.example.com/v1')
+ * @param operation - The operation containing path template and parameter definitions
+ * @param args - Key-value pairs for path and query parameters
+ * @returns Fully resolved URL string with parameters substituted
+ */
+declare function buildUrl(baseUrl: string, operation: Operation, args: Record<string, unknown>): string;
+/**
+ * Derive a base URL from a spec URL by stripping the filename.
+ * e.g., `"https://api.example.com/v1/openapi.json"` → `"https://api.example.com/v1"`
+ *
+ * @param specUrl - URL pointing to an API spec file
+ * @returns Base URL with the filename removed, or empty string if the URL is invalid
+ */
+declare function deriveBaseUrl(specUrl: string): string;
+
+/**
+ * Authentication injection into HTTP requests.
+ * Supports Bearer, Basic, API Key (header/query), OAuth2, and Cookie.
+ */
+
+/**
+ * A request with authentication applied (URL may be modified for query-based auth).
+ */
+interface AuthenticatedRequest {
+    /** URL, potentially modified with query-based auth parameters. */
+    url: string;
+    /** Headers with auth credentials injected. */
+    headers: Record<string, string>;
+}
+/**
+ * Inject authentication credentials into a request URL and headers.
+ * Accepts a single Auth or an array for composing multiple schemes (e.g. API key + bearer).
+ *
+ * @param url - The request URL
+ * @param headers - Existing request headers (shallow-copied internally)
+ * @param auth - Credentials to inject (single or array)
+ * @returns New URL and headers with auth applied
+ */
+declare function injectAuth(url: string, headers: Record<string, string>, auth: Auth | Auth[]): AuthenticatedRequest;
+/** Result from an OAuth2 token refresh. */
+interface OAuth2TokenResult {
+    /** The new access token. */
+    accessToken: string;
+    /** A new refresh token, if the server issued one. */
+    refreshToken?: string;
+    /** Token lifetime in seconds, if provided by the server. */
+    expiresIn?: number;
+}
+/**
+ * Exchange a refresh token for a new access token at the OAuth2 token endpoint.
+ *
+ * @param tokenUrl - The OAuth2 token endpoint URL
+ * @param refreshToken - The refresh token to exchange
+ * @param options - Optional client credentials, scopes, and custom fetch
+ * @returns The new token set
+ * @throws {ApiInvokeError} With `kind: 'auth'` if the token endpoint returns a non-OK response or the response is missing `access_token`
+ * @throws {ApiInvokeError} With `kind: 'parse'` if the response body is not valid JSON
+ */
+declare function refreshOAuth2Token(tokenUrl: string, refreshToken: string, options?: {
+    clientId?: string;
+    clientSecret?: string;
+    scopes?: string[];
+    fetch?: typeof globalThis.fetch;
+}): Promise<OAuth2TokenResult>;
+/**
+ * Mask credential values for safe logging. Shows the auth type and a redacted value.
+ *
+ * @param auth - The auth credentials to mask
+ * @returns A human-readable string with sensitive values replaced by `***`
+ */
+declare function maskAuth(auth: Auth): string;
+
+/**
+ * Flat auth configuration for CLI consumers.
+ * Converts simple config objects (from CLI args, env vars, config files)
+ * into api-invoke's discriminated Auth union.
+ */
+
+/** Simplified auth type constants for flat configuration (CLI, env vars, config files). */
+declare const AuthConfigType: {
+    readonly BEARER: "bearer";
+    readonly HEADER: "header";
+    readonly API_KEY: "apikey";
+    readonly NONE: "none";
+};
+type AuthConfigType = (typeof AuthConfigType)[keyof typeof AuthConfigType];
+/**
+ * Flat auth configuration for CLI consumers.
+ * Unlike {@link Auth}, this is a single object with optional fields rather than a discriminated union.
+ * Use {@link toAuth} to convert to the full `Auth` type.
+ */
+interface AuthConfig {
+    /** Auth type to use. */
+    type: AuthConfigType;
+    /** Bearer token (used when `type` is 'bearer'). */
+    token?: string;
+    /** Custom header name (used when `type` is 'header'). */
+    headerName?: string;
+    /** Custom header value (used when `type` is 'header'). */
+    headerValue?: string;
+    /** Query parameter name (used when `type` is 'apikey'). */
+    paramName?: string;
+    /** Query parameter value (used when `type` is 'apikey'). */
+    paramValue?: string;
+}
+/**
+ * Convert a flat {@link AuthConfig} to api-invoke's {@link Auth} discriminated union.
+ * Returns undefined if required credentials are missing or type is `NONE`.
+ *
+ * @param config - Flat auth configuration
+ * @returns The `Auth` object, or undefined if credentials are incomplete
+ */
+declare function toAuth(config: AuthConfig): Auth | undefined;
+
+/**
+ * Retry fetch wrapper — exponential backoff with Retry-After header support.
+ *
+ * Works by wrapping the fetch function rather than using middleware hooks,
+ * since retry logic needs to re-execute the entire request.
+ */
+interface RetryOptions {
+    /** Max retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in ms (default: 1000) */
+    initialDelayMs?: number;
+    /** Max delay in ms (default: 30000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier (default: 2) */
+    multiplier?: number;
+    /** Jitter factor 0-1 (default: 0.1) */
+    jitter?: number;
+    /** Which status codes to retry (default: [429, 500, 502, 503, 504]) */
+    retryableStatuses?: number[];
+    /** Called on each retry with attempt info */
+    onRetry?: (attempt: number, delayMs: number, status?: number) => void;
+}
+/**
+ * Create a fetch wrapper that retries on transient failures.
+ * Implements exponential backoff with jitter, and respects the `Retry-After` header.
+ *
+ * @param options - Retry configuration (max retries, delays, retryable statuses)
+ * @param baseFetch - Base fetch function to wrap. Defaults to `globalThis.fetch`.
+ * @returns A fetch-compatible function with retry behavior
+ *
+ * @example
+ * ```ts
+ * const client = await createClient(url, {
+ *   fetch: withRetry({ maxRetries: 3 }),
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Wrap a custom fetch
+ * const client = await createClient(url, {
+ *   fetch: withRetry({ maxRetries: 3 }, myCustomFetch),
+ * })
+ * ```
+ */
+declare function withRetry(options?: RetryOptions, baseFetch?: typeof globalThis.fetch): typeof globalThis.fetch;
+
+/**
+ * CORS proxy middleware — rewrites request URLs through a proxy.
+ *
+ * Useful when APIs block browser CORS requests. Supports custom
+ * proxy URL patterns or the common `/api-proxy/{encodedUrl}` convention.
+ */
+
+interface CorsProxyOptions {
+    /**
+     * URL rewrite function. Receives the original URL, returns the proxied URL.
+     * Default: `/api-proxy/{encodeURIComponent(url)}`
+     */
+    rewrite?: (url: string) => string;
+    /**
+     * Only proxy URLs matching this predicate.
+     * Default: proxies all absolute HTTP(S) URLs.
+     */
+    shouldProxy?: (url: string) => boolean;
+}
+/**
+ * Create a CORS proxy middleware that rewrites request URLs through a proxy server.
+ * Useful when APIs block browser CORS requests.
+ *
+ * @param options - Proxy configuration (custom rewrite function, proxy filter)
+ * @returns A {@link Middleware} that rewrites URLs through the proxy
+ *
+ * @example
+ * ```ts
+ * // Default: rewrites to /api-proxy/{encodedUrl}
+ * const client = await createClient(url, {
+ *   middleware: [corsProxy()],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom proxy URL
+ * const client = await createClient(url, {
+ *   middleware: [corsProxy({
+ *     rewrite: (url) => `https://my-proxy.com/?url=${encodeURIComponent(url)}`,
+ *   })],
+ * })
+ * ```
+ */
+declare function corsProxy(options?: CorsProxyOptions): Middleware;
+
+/**
+ * Logging middleware — request/response logging with automatic secret masking.
+ *
+ * Masks Authorization headers, API keys in query strings, and other
+ * sensitive values to prevent credential leakage in logs.
+ */
+
+interface LoggingOptions {
+    /** Custom log function (default: console.log) */
+    log?: (message: string) => void;
+    /** Log response bodies (default: false) */
+    logBody?: boolean;
+    /** Additional header names to mask (always masks Authorization) */
+    sensitiveHeaders?: string[];
+    /** Query parameter names to mask (e.g., ['api_key', 'token']) */
+    sensitiveParams?: string[];
+    /** Label prefix for log messages (default: 'api-invoke') */
+    prefix?: string;
+}
+/**
+ * Create a logging middleware that logs requests and responses.
+ * Automatically masks sensitive headers (Authorization, cookies) and query parameters.
+ *
+ * @param options - Logging configuration (custom logger, body logging, sensitive fields)
+ * @returns A {@link Middleware} that logs request/response details
+ *
+ * @example
+ * ```ts
+ * const client = await createClient(url, {
+ *   middleware: [logging()],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom logger
+ * const client = await createClient(url, {
+ *   middleware: [logging({ log: myLogger.info })],
+ * })
+ * ```
+ */
+declare function logging(options?: LoggingOptions): Middleware;
+
+/**
+ * OAuth2 token refresh fetch wrapper.
+ * Intercepts 401 responses, refreshes the token, and retries the request.
+ *
+ * Note: Requests with `ReadableStream` bodies cannot be retried — if a stream body
+ * is detected after a 401, the original response is returned with a warning.
+ */
+
+/** Configuration for the OAuth2 token refresh fetch wrapper ({@link withOAuthRefresh}). */
+interface OAuthRefreshOptions {
+    /** OAuth2 token endpoint URL. */
+    tokenUrl: string;
+    /** Refresh token to exchange for a new access token. */
+    refreshToken: string;
+    /** OAuth2 client ID (if required by the token endpoint). */
+    clientId?: string;
+    /** OAuth2 client secret (if required by the token endpoint). */
+    clientSecret?: string;
+    /** OAuth2 scopes to request. */
+    scopes?: string[];
+    /** Called after a successful token refresh. Use this to persist the new tokens. May be async. */
+    onTokenRefresh?: (tokens: OAuth2TokenResult) => void | Promise<void>;
+}
+/**
+ * Create a fetch wrapper that auto-refreshes OAuth2 tokens on 401 responses.
+ * On a 401, exchanges the refresh token for a new access token and retries the original request.
+ * Concurrent 401s are deduplicated — only one refresh and one `onTokenRefresh` callback fire per refresh cycle.
+ *
+ * @param options - Refresh configuration (token URL, refresh token, client credentials)
+ * @param baseFetch - Base fetch function to wrap. Defaults to `globalThis.fetch`.
+ * @returns A fetch-compatible function with auto-refresh behavior
+ *
+ * @example
+ * ```ts
+ * const client = await createClient(specUrl, {
+ *   auth: { type: AuthType.OAUTH2, accessToken: 'current-token' },
+ *   fetch: withOAuthRefresh({
+ *     tokenUrl: 'https://auth.example.com/token',
+ *     refreshToken: 'rt_...',
+ *     onTokenRefresh: (tokens) => saveTokens(tokens),
+ *   }),
+ * })
+ * ```
+ */
+declare function withOAuthRefresh(options: OAuthRefreshOptions, baseFetch?: typeof globalThis.fetch): typeof globalThis.fetch;
+
+/**
+ * Parse OpenAPI 2.0/3.x specs into the spec-agnostic ParsedAPI format.
+ * Extracted and consolidated from api2aux/semantic-analysis.
+ */
+
+/**
+ * Parse an OpenAPI 2.0 (Swagger) or 3.x spec into a spec-agnostic {@link ParsedAPI}.
+ * Handles dereferencing, operation extraction, auth scheme mapping, and base URL resolution.
+ *
+ * @param specUrlOrObject - URL string pointing to a spec, or a pre-parsed spec object
+ * @param options - Parse options
+ * @param options.specUrl - Original spec URL (used for base URL fallback when spec has no servers/host field)
+ * @returns A normalized ParsedAPI with all operations, auth schemes, and metadata
+ * @throws {Error} If the spec cannot be fetched, parsed, or dereferenced
+ */
+declare function parseOpenAPISpec(specUrlOrObject: string | object, options?: {
+    specUrl?: string;
+}): Promise<ParsedAPI>;
+
+/**
+ * Raw URL adapter — creates a ParsedAPI from one or more plain URL endpoints (no spec).
+ * Supports custom methods, IDs, and summaries per endpoint.
+ * Auto-detects query parameters as configurable operation parameters.
+ */
+
+/**
+ * A raw URL endpoint definition (no spec required).
+ */
+interface RawEndpoint {
+    /** Full URL for the endpoint (must be absolute). */
+    url: string;
+    /** HTTP method. Default: 'GET'. */
+    method?: string;
+    /** Custom operation ID. Auto-generated from method + path if omitted. */
+    id?: string;
+    /** Short summary. Defaults to `'{METHOD} {hostname}{path}'`. */
+    summary?: string;
+}
+/**
+ * Parse a raw URL into a {@link ParsedAPI} with a single operation.
+ * Query parameters from the URL become configurable operation parameters.
+ * Repeated keys (e.g. `?tags=a&tags=b`) and bracket notation (e.g. `?ids[]=1&ids[]=2`) produce array-typed parameters.
+ *
+ * @param url - Absolute URL (e.g. 'https://api.example.com/users?page=1')
+ * @returns A ParsedAPI with a single operation (defaults to GET)
+ * @throws {Error} If the URL is not a valid absolute URL
+ */
+declare function parseRawUrl(url: string): ParsedAPI;
+/**
+ * Parse multiple raw URL endpoints into a single {@link ParsedAPI}.
+ * All endpoints must share the same origin. Query parameters become configurable operation parameters.
+ * Repeated keys and bracket notation (e.g. `?ids[]=1&ids[]=2`) produce array-typed parameters.
+ * Nested brackets (e.g. `[][]`) are flattened to a 1D array. Indexed brackets (e.g. `[0]`, `[1]`) are not recognized.
+ *
+ * @param endpoints - Array of raw endpoint definitions
+ * @returns A ParsedAPI with one operation per endpoint
+ * @throws {Error} If endpoints is empty, URLs are invalid, or origins don't match
+ */
+declare function parseRawUrls(endpoints: RawEndpoint[]): ParsedAPI;
+
+/**
+ * Manual API definition builder — define APIs without writing a full OpenAPI spec.
+ * Supports multiple endpoints, methods, parameters, and request bodies.
+ *
+ * @example
+ * ```ts
+ * const api = defineAPI('My API')
+ *   .baseUrl('https://api.example.com')
+ *   .get('/users', { id: 'listUsers', summary: 'List all users' })
+ *   .post('/users', {
+ *     id: 'createUser',
+ *     body: { contentType: 'application/json', properties: { name: 'string', email: 'string' } },
+ *   })
+ *   .build()
+ * ```
+ */
+
+/**
+ * Options for defining an endpoint in the manual builder.
+ */
+interface EndpointOptions {
+    /** Custom operation ID. Auto-generated from method + path if omitted (e.g. 'get_users'). */
+    id?: string;
+    /** Short summary of what this endpoint does. */
+    summary?: string;
+    /** Longer description of the endpoint's behavior. */
+    description?: string;
+    /** Parameter definitions. Keys are parameter names; values are type strings (shorthand) or full {@link ParamDef} objects. Path parameters from `{placeholders}` are auto-detected. */
+    params?: Record<string, ParamDef | string>;
+    /** Request body definition. */
+    body?: BodyDef;
+    /** Expected response content type. Used as the default Accept header. */
+    responseContentType?: ContentType | string;
+    /** Tags for grouping this endpoint. */
+    tags?: string[];
+}
+/**
+ * Parameter definition for the manual builder.
+ * All fields are optional — defaults to a non-required query string parameter of type 'string'.
+ */
+type ParamDef = {
+    /** Where the parameter appears. Default: 'query' (path params are always forced to 'path'). */
+    in?: ParamLocation;
+    /** Whether this parameter is required. Default: false (path params are always required). */
+    required?: boolean;
+    /** Data type. Default: 'string'. */
+    type?: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Default value when the parameter is not provided. */
+    default?: unknown;
+};
+/**
+ * Request body definition for the manual builder.
+ */
+type BodyDef = {
+    /** Content type for the body. Default: 'application/json'. */
+    contentType?: string;
+    /** Whether the body is required. Default: true. */
+    required?: boolean;
+    /** Body properties. Keys are property names; values are type strings (shorthand) or full {@link PropertyDef} objects. */
+    properties?: Record<string, string | PropertyDef>;
+    /** Names of required properties within the body. */
+    requiredFields?: string[];
+};
+/**
+ * Property definition within a request body.
+ */
+type PropertyDef = {
+    /** Data type (e.g. 'string', 'integer', 'boolean'). */
+    type: string;
+    /** Human-readable description. */
+    description?: string;
+    /** Format hint (e.g. 'date-time', 'email'). */
+    format?: string;
+    /** Allowed values for this property. */
+    enum?: unknown[];
+};
+/**
+ * Fluent builder for manually defining APIs without an OpenAPI spec.
+ * Use {@link defineAPI} to create an instance.
+ *
+ * @example
+ * ```ts
+ * const api = defineAPI('Users API')
+ *   .baseUrl('https://api.example.com')
+ *   .get('/users', { id: 'listUsers' })
+ *   .get('/users/{userId}', { id: 'getUser' })
+ *   .post('/users', { id: 'createUser', body: { properties: { name: 'string' } } })
+ *   .build()
+ * ```
+ */
+declare class APIBuilder {
+    private _title;
+    private _version;
+    private _baseUrl;
+    private _operations;
+    constructor(title: string);
+    /**
+     * Set the API version string.
+     * @param v - Version string (e.g. '2.0.0'). Default: '1.0.0'.
+     */
+    version(v: string): this;
+    /**
+     * Set the base URL for all endpoints.
+     * @param url - Base URL (e.g. 'https://api.example.com/v1'). Required before calling {@link build}.
+     */
+    baseUrl(url: string): this;
+    /** Add a GET endpoint. */
+    get(path: string, options?: EndpointOptions): this;
+    /** Add a POST endpoint. */
+    post(path: string, options?: EndpointOptions): this;
+    /** Add a PUT endpoint. */
+    put(path: string, options?: EndpointOptions): this;
+    /** Add a PATCH endpoint. */
+    patch(path: string, options?: EndpointOptions): this;
+    /** Add a DELETE endpoint. */
+    delete(path: string, options?: EndpointOptions): this;
+    /**
+     * Add an endpoint with any HTTP method.
+     * Path parameters are auto-detected from `{placeholder}` segments.
+     *
+     * @param method - HTTP method (e.g. 'GET', 'POST')
+     * @param path - URL path template (e.g. '/users/{userId}')
+     * @param options - Endpoint configuration
+     */
+    endpoint(method: string, path: string, options?: EndpointOptions): this;
+    /**
+     * Build the {@link ParsedAPI} from the configured endpoints.
+     * @returns A ParsedAPI ready to use with {@link ApiInvokeClient}
+     * @throws {Error} If `baseUrl` is not set or no endpoints are defined
+     */
+    build(): ParsedAPI;
+}
+/**
+ * Create a new API builder with a fluent interface.
+ *
+ * @param title - Human-readable API title
+ * @returns A new {@link APIBuilder} instance
+ *
+ * @example
+ * ```ts
+ * const api = defineAPI('My API')
+ *   .baseUrl('https://api.example.com')
+ *   .get('/health', { id: 'healthCheck' })
+ *   .build()
+ * ```
+ */
+declare function defineAPI(title: string): APIBuilder;
+
+/**
+ * GraphQL adapter — parses introspection schemas into ParsedAPI.
+ * Accepts a live endpoint URL (runs introspection) or an introspection JSON object.
+ */
+
+/** Options for parsing a GraphQL schema. */
+interface GraphQLParseOptions {
+    /** GraphQL endpoint URL. Strongly recommended when input is introspection JSON — without it, baseUrl defaults to '/graphql' (a relative path). Inferred automatically when input is a URL string. */
+    endpoint?: string;
+    /** Custom fetch implementation for introspection queries. Defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Maximum depth for auto-generated query selection sets. Default: 2. */
+    maxDepth?: number;
+}
+/**
+ * Parse a GraphQL schema into a ParsedAPI.
+ *
+ * @param input - Either an endpoint URL (string starting with http) or an introspection result object.
+ *   URL: runs introspection query against the endpoint.
+ *   Object: expects `{ data: { __schema: ... } }` or `{ __schema: ... }` shape.
+ * @param options - Configuration options.
+ * @returns A ParsedAPI with one operation per query/mutation/subscription field.
+ */
+declare function parseGraphQLSchema(input: string | object, options?: GraphQLParseOptions): Promise<ParsedAPI>;
+
+/**
+ * GraphQL error detection and handling utilities.
+ * GraphQL APIs return HTTP 200 even on errors — these helpers inspect the response body.
+ */
+
+/** A single GraphQL error from the response `errors` array. */
+interface GraphQLError {
+    message: string;
+    locations?: Array<{
+        line: number;
+        column: number;
+    }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, unknown>;
+}
+/** Check if an ExecutionResult contains GraphQL errors. Returns true for both total and partial errors. Use {@link throwOnGraphQLErrors} to throw only on total failures (when `data` is null). */
+declare function hasGraphQLErrors(result: ExecutionResult): boolean;
+/** Extract GraphQL errors from an ExecutionResult. Returns empty array if none. */
+declare function getGraphQLErrors(result: ExecutionResult): GraphQLError[];
+/**
+ * Throw if the result has GraphQL errors and no data (total failure).
+ * Partial errors (data + errors both present) do not throw — the caller decides how to handle them.
+ */
+declare function throwOnGraphQLErrors(result: ExecutionResult): void;
+
+export { APIBuilder, API_INVOKE_ERROR_NAME, ApiInvokeClient, ApiInvokeError, type Auth, type AuthConfig, AuthConfigType, type AuthScheme, AuthType, type AuthenticatedRequest, type BodyDef, type BuildRequestOptions, type BuiltRequest, type ClientOptions, ContentType, type CorsProxyOptions, type EndpointOptions, type Enricher, ErrorKind, type ExecuteOptions, type ExecutionResult, type GraphQLError, type GraphQLParseOptions, HeaderName, HttpMethod, type LoggingOptions, type Middleware, type OAuth2TokenResult, type OAuthRefreshOptions, type Operation, type ParamDef, ParamLocation, type Parameter, type ParameterSchema, type ParsedAPI, type PropertyDef, type RawEndpoint, type RequestBody, type RequestBodyProperty, type RequestBodySchema, type ResultErrorKind, type RetryOptions, type SSEEvent, SpecFormat, type StreamingExecutionResult, authError, buildRequest, buildUrl, corsError, corsProxy, createClient, defineAPI, deriveBaseUrl, executeOperation, executeOperationStream, executeRaw, executeRawStream, getGraphQLErrors, graphqlError, hasGraphQLErrors, httpError, injectAuth, isGraphQLUrl, isSpecContent, isSpecUrl, logging, maskAuth, networkError, parseError, parseGraphQLSchema, parseOpenAPISpec, parseRawUrl, parseRawUrls, parseSSE, refreshOAuth2Token, throwOnGraphQLErrors, timeoutError, toAuth, withOAuthRefresh, withRetry };