@igniter-js/caller 0.1.3 → 0.1.5

package/dist/manager-CVi9utzy.d.ts

@@ -0,0 +1,1121 @@
+import { StandardSchemaV1, IgniterError, IgniterLogger } from '@igniter-js/common';
+import { IgniterTelemetryManager } from '@igniter-js/telemetry';
+import { z } from 'zod';
+import { I as IgniterCallerStoreAdapter, a as IgniterCallerStoreOptions } from './store-D2p2dqGN.js';
+
+/**
+ * Supported HTTP methods for `IgniterCaller` requests.
+ *
+ * This type is designed to remain stable when extracted to `@igniter-js/caller`.
+ */
+type IgniterCallerHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+
+/**
+ * Retry configuration for failed requests.
+ */
+interface IgniterCallerRetryOptions {
+    /** Maximum number of retry attempts. */
+    maxAttempts: number;
+    /** Backoff strategy between retries. */
+    backoff?: 'linear' | 'exponential';
+    /** Base delay in milliseconds (default: 1000). */
+    baseDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]). */
+    retryOnStatus?: number[];
+}
+
+/**
+ * Base configuration options for HTTP requests.
+ */
+interface IgniterCallerBaseRequestOptions {
+    /** Base URL for all requests (e.g. `https://api.example.com`). */
+    baseURL?: string;
+    /** Default headers merged into each request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * Complete request configuration extending base options.
+ */
+interface IgniterCallerRequestOptions<TBody = unknown> extends IgniterCallerBaseRequestOptions {
+    method: IgniterCallerHttpMethod;
+    /** Endpoint URL path. If absolute, `baseURL` is ignored. */
+    url: string;
+    body?: TBody;
+    params?: Record<string, string | number | boolean>;
+    responseSchema?: z.ZodSchema<any> | StandardSchemaV1;
+    cache?: RequestCache;
+}
+/**
+ * Options for the direct request() method (axios-style).
+ * All options in one object, executes immediately.
+ */
+interface IgniterCallerDirectRequestOptions<TBody = unknown> extends IgniterCallerBaseRequestOptions {
+    /** HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD) */
+    method: IgniterCallerHttpMethod;
+    /** Endpoint URL path. If absolute, `baseURL` is ignored. */
+    url: string;
+    /** Request body (for POST, PUT, PATCH) */
+    body?: TBody;
+    /** URL query parameters */
+    params?: Record<string, string | number | boolean>;
+    /** Cookies to send with the request */
+    cookies?: Record<string, string>;
+    /** Response validation schema (Zod or any StandardSchemaV1 implementation) */
+    responseSchema?: z.ZodSchema<any> | StandardSchemaV1;
+    /** Cache strategy */
+    cache?: RequestCache;
+    /** Cache key for stale-while-revalidate */
+    cacheKey?: string;
+    /** Stale time in milliseconds for caching */
+    staleTime?: number;
+    /** Retry configuration */
+    retry?: IgniterCallerRetryOptions;
+    /** Fallback value if request fails */
+    fallback?: () => any;
+}
+
+/**
+ * Response object containing either successful data or an error.
+ */
+interface IgniterCallerApiResponse<T> {
+    /** Parsed response data when the request succeeds. */
+    data?: T;
+    /** Error instance when the request fails. */
+    error?: IgniterError;
+    /** HTTP status code from the response */
+    status?: number;
+    /** Response headers */
+    headers?: Headers;
+}
+/**
+ * Response object for file downloads.
+ * @deprecated Use execute() with responseType<File>() instead
+ */
+interface IgniterCallerFileResponse {
+    /** File instance when download succeeds. */
+    file: File | null;
+    /** Error instance when download fails. */
+    error: Error | null;
+}
+/**
+ * Supported response content types that can be auto-detected.
+ */
+type IgniterCallerResponseContentType = 'json' | 'xml' | 'csv' | 'text' | 'html' | 'blob' | 'stream' | 'arraybuffer' | 'formdata';
+/**
+ * Content types that support schema validation.
+ */
+type IgniterCallerValidatableContentType = 'json' | 'xml' | 'csv';
+/**
+ * Marker types for responseType() to indicate expected response format.
+ * These are used for typing only and don't affect runtime behavior.
+ */
+type IgniterCallerResponseMarker = File | Blob | ReadableStream | ArrayBuffer | FormData;
+
+/**
+ * Function that can modify request configuration before execution.
+ */
+type IgniterCallerRequestInterceptor = (config: IgniterCallerRequestOptions) => Promise<IgniterCallerRequestOptions> | IgniterCallerRequestOptions;
+/**
+ * Function that can transform responses after execution.
+ */
+type IgniterCallerResponseInterceptor = <T>(response: IgniterCallerApiResponse<T>) => Promise<IgniterCallerApiResponse<T>> | IgniterCallerApiResponse<T>;
+
+/**
+ * HTTP methods supported for schema mapping.
+ */
+type IgniterCallerSchemaMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+/**
+ * Schema definition for a single endpoint.
+ *
+ * Maps status codes to response schemas with optional request schema.
+ */
+type IgniterCallerEndpointSchema<TRequest extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1> = Record<number | string, StandardSchemaV1>> = {
+    /** Request body schema (optional) */
+    request?: TRequest;
+    /** Response schemas by status code */
+    responses: TResponses;
+    /** Optional summary or description for docs */
+    doc?: string;
+    /** Optional tags for grouping */
+    tags?: string[];
+    /** Optional operation identifier */
+    operationId?: string;
+};
+/**
+ * Schema map for multiple endpoints.
+ *
+ * Structure: { [path]: { [method]: EndpointSchema } }
+ *
+ * @example
+ * ```ts
+ * const schemas = {
+ *   '/users': {
+ *     GET: {
+ *       responses: {
+ *         200: z.array(UserSchema),
+ *         401: z.object({ error: z.string() }),
+ *       },
+ *     },
+ *     POST: {
+ *       request: CreateUserSchema,
+ *       responses: {
+ *         201: UserSchema,
+ *         400: z.object({ errors: z.array(z.string()) }),
+ *       },
+ *     },
+ *   },
+ *   '/users/:id': {
+ *     GET: {
+ *       responses: {
+ *         200: UserSchema,
+ *         404: z.object({ error: z.string() }),
+ *       },
+ *     },
+ *   },
+ * }
+ * ```
+ */
+type IgniterCallerSchemaMap = Record<string, Partial<Record<IgniterCallerSchemaMethod, IgniterCallerEndpointSchema<any, any>>>>;
+/**
+ * Resolves a status key against a response map.
+ */
+type ResolveStatusKey<TResponses extends Record<number | string, StandardSchemaV1>, TStatus extends number | string> = Extract<keyof TResponses, TStatus | `${TStatus}`>;
+/**
+ * Extract path parameters from a URL pattern.
+ *
+ * @example
+ * ```ts
+ * type Params = ExtractPathParams<'/users/:id/posts/:postId'>
+ * // { id: string; postId: string }
+ * ```
+ */
+type ExtractPathParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof ExtractPathParams<`/${Rest}`>]: string;
+} : T extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<never, never>;
+/**
+ * Infer request type from endpoint schema.
+ */
+type InferRequestType<T> = T extends IgniterCallerEndpointSchema<infer R, any> ? R extends StandardSchemaV1 ? StandardSchemaV1.InferInput<R> : never : never;
+/**
+ * Infer response type by status code from endpoint schema.
+ */
+type InferResponseType<T, Status extends number | string> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? ResolveStatusKey<Responses, Status> extends keyof Responses ? Responses[ResolveStatusKey<Responses, Status>] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[ResolveStatusKey<Responses, Status>]> : never : never : never;
+/**
+ * Infer the success response type (status 200 or 201) from endpoint schema.
+ */
+type InferSuccessResponseType<T> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? ResolveStatusKey<Responses, 200> extends keyof Responses ? Responses[ResolveStatusKey<Responses, 200>] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[ResolveStatusKey<Responses, 200>]> : never : ResolveStatusKey<Responses, 201> extends keyof Responses ? Responses[ResolveStatusKey<Responses, 201>] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[ResolveStatusKey<Responses, 201>]> : never : never : never;
+/**
+ * Infer all possible response types (union) from endpoint schema.
+ */
+type InferAllResponseTypes<T> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? Responses extends Record<number | string, StandardSchemaV1> ? {
+    [K in keyof Responses]: Responses[K] extends StandardSchemaV1 ? {
+        status: K;
+        data: StandardSchemaV1.InferOutput<Responses[K]>;
+    } : never;
+}[keyof Responses] : never : never;
+/**
+ * Get all available paths from a schema map.
+ */
+type SchemaMapPaths<TSchemas extends IgniterCallerSchemaMap> = keyof TSchemas & string;
+/**
+ * Get available methods for a specific path.
+ */
+type SchemaMapMethods<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas> = keyof TSchemas[TPath] & IgniterCallerSchemaMethod;
+/**
+ * Get all paths that have a specific method defined.
+ */
+type PathsForMethod<TSchemas extends IgniterCallerSchemaMap, TMethod extends IgniterCallerSchemaMethod> = {
+    [K in keyof TSchemas]: TMethod extends keyof TSchemas[K] ? K : never;
+}[keyof TSchemas] & string;
+/**
+ * Get paths available for GET method.
+ */
+type GetPaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'GET'>;
+/**
+ * Get paths available for POST method.
+ */
+type PostPaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'POST'>;
+/**
+ * Get paths available for PUT method.
+ */
+type PutPaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'PUT'>;
+/**
+ * Get paths available for PATCH method.
+ */
+type PatchPaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'PATCH'>;
+/**
+ * Get paths available for DELETE method.
+ */
+type DeletePaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'DELETE'>;
+/**
+ * Get paths available for HEAD method.
+ */
+type HeadPaths<TSchemas extends IgniterCallerSchemaMap> = PathsForMethod<TSchemas, 'HEAD'>;
+/**
+ * Get endpoint schema for a specific path and method.
+ */
+type SchemaMapEndpoint<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod];
+/**
+ * Infer response type from schema map for a specific path, method, and status.
+ */
+type SchemaMapResponseType<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath], TStatus extends number | string = 200> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<any, infer Responses> ? ResolveStatusKey<Responses, TStatus> extends keyof Responses ? Responses[ResolveStatusKey<Responses, TStatus>] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[ResolveStatusKey<Responses, TStatus>]> : never : never : never;
+/**
+ * Infer request type from schema map for a specific path and method.
+ */
+type SchemaMapRequestType<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<infer Request, any> ? Request extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Request> : never : never;
+/**
+ * Infer endpoint info for a specific path and method.
+ * Returns an object with response, request, and params types.
+ */
+type EndpointInfo<TSchemas extends IgniterCallerSchemaMap, TPath extends string, TMethod extends IgniterCallerSchemaMethod> = TPath extends keyof TSchemas ? TMethod extends keyof TSchemas[TPath] ? {
+    response: TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<any, infer R> ? 200 extends keyof R ? R[200] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R[200]> : unknown : 201 extends keyof R ? R[201] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R[201]> : unknown : unknown : unknown;
+    request: TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<infer Req, any> ? Req extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Req> : never : never;
+    params: ExtractPathParams<TPath & string>;
+} : {
+    response: unknown;
+    request: never;
+    params: Record<never, never>;
+} : {
+    response: unknown;
+    request: never;
+    params: Record<never, never>;
+};
+/**
+ * Options for schema validation behavior.
+ */
+interface IgniterCallerSchemaValidationOptions {
+    /**
+     * Validation mode:
+     * - 'strict': Throw error on validation failure (default)
+     * - 'soft': Log error but return raw data
+     * - 'off': Skip validation entirely
+     */
+    mode?: 'strict' | 'soft' | 'off';
+    /**
+     * Custom error handler for validation failures.
+     */
+    onValidationError?: (error: any, context: {
+        url: string;
+        method: string;
+        statusCode: number;
+    }) => void;
+}
+
+/**
+ * @fileoverview Schema builder helper types for @igniter-js/caller.
+ * @module @igniter-js/caller/types/schema-builder
+ */
+
+/**
+ * Registry of reusable schemas keyed by name.
+ */
+type IgniterCallerSchemaRegistry = Record<string, StandardSchemaV1>;
+/**
+ * Configuration payload for a single endpoint method in the schema builder.
+ */
+type IgniterCallerSchemaEndpointConfig<TRequest extends StandardSchemaV1 | undefined = undefined, TResponses extends Record<number | string, StandardSchemaV1> = Record<number | string, StandardSchemaV1>> = {
+    request?: TRequest;
+    responses: TResponses;
+    doc?: string;
+    tags?: string[];
+    operationId?: string;
+};
+/**
+ * Helper type for array wrappers on StandardSchemaV1.
+ */
+type SchemaArray<TSchema extends StandardSchemaV1> = StandardSchemaV1<Array<StandardSchemaV1.InferInput<TSchema>>, Array<StandardSchemaV1.InferOutput<TSchema>>>;
+/**
+ * Helper type for nullable wrappers on StandardSchemaV1.
+ */
+type SchemaNullable<TSchema extends StandardSchemaV1> = StandardSchemaV1<StandardSchemaV1.InferInput<TSchema> | null, StandardSchemaV1.InferOutput<TSchema> | null>;
+/**
+ * Helper type for optional wrappers on StandardSchemaV1.
+ */
+type SchemaOptional<TSchema extends StandardSchemaV1> = StandardSchemaV1<StandardSchemaV1.InferInput<TSchema> | undefined, StandardSchemaV1.InferOutput<TSchema> | undefined>;
+/**
+ * Helper type for record wrappers on StandardSchemaV1.
+ */
+type SchemaRecord<TSchema extends StandardSchemaV1> = StandardSchemaV1<Record<string, StandardSchemaV1.InferInput<TSchema>>, Record<string, StandardSchemaV1.InferOutput<TSchema>>>;
+/**
+ * Extracts the raw responses map (schemas) from a schema map.
+ */
+type SchemaMapResponses<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<any, infer Responses> ? Responses : never;
+/**
+ * Infers the response output types for every status in a responses map.
+ */
+type SchemaMapResponsesType<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = SchemaMapResponses<TSchemas, TPath, TMethod> extends Record<number | string, StandardSchemaV1> ? {
+    [K in keyof SchemaMapResponses<TSchemas, TPath, TMethod>]: SchemaMapResponses<TSchemas, TPath, TMethod>[K] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<SchemaMapResponses<TSchemas, TPath, TMethod>[K]> : never;
+} : never;
+/**
+ * Extracts the request schema for a path + method.
+ */
+type SchemaMapRequestSchema<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<infer Request, any> ? Request : never;
+/**
+ * Extracts the response schema for a path + method + status code.
+ */
+type SchemaMapResponseSchema<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath], TStatus extends number | string> = SchemaMapResponses<TSchemas, TPath, TMethod> extends Record<number | string, StandardSchemaV1> ? ResolveStatusKey<SchemaMapResponses<TSchemas, TPath, TMethod>, TStatus> extends keyof SchemaMapResponses<TSchemas, TPath, TMethod> ? SchemaMapResponses<TSchemas, TPath, TMethod>[ResolveStatusKey<SchemaMapResponses<TSchemas, TPath, TMethod>, TStatus>] : never : never;
+/**
+ * Type-level helpers attached to schema build outputs.
+ */
+type IgniterCallerSchemaInfer<TSchemas extends IgniterCallerSchemaMap, TRegistry extends IgniterCallerSchemaRegistry> = {
+    Path: SchemaMapPaths<TSchemas>;
+    Endpoint: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>>() => EndpointInfo<TSchemas, TPath, TMethod>;
+    Request: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>>() => SchemaMapRequestType<TSchemas, TPath, TMethod>;
+    Response: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>, TStatus extends number | string>() => SchemaMapResponseType<TSchemas, TPath, TMethod, TStatus>;
+    Responses: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>>() => SchemaMapResponsesType<TSchemas, TPath, TMethod>;
+    Schema: <TKey extends keyof TRegistry>() => StandardSchemaV1.InferOutput<TRegistry[TKey]>;
+};
+/**
+ * Runtime helpers attached to schema build outputs.
+ */
+type IgniterCallerSchemaGetters<TSchemas extends IgniterCallerSchemaMap, TRegistry extends IgniterCallerSchemaRegistry> = {
+    path: <TPath extends SchemaMapPaths<TSchemas>>(path: TPath) => TSchemas[TPath];
+    endpoint: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>>(path: TPath, method: TMethod) => SchemaMapEndpoint<TSchemas, TPath, TMethod>;
+    request: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>>(path: TPath, method: TMethod) => SchemaMapRequestSchema<TSchemas, TPath, TMethod>;
+    response: <TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>, TStatus extends number | string>(path: TPath, method: TMethod, status: TStatus) => SchemaMapResponseSchema<TSchemas, TPath, TMethod, TStatus>;
+    schema: <TKey extends keyof TRegistry>(key: TKey) => TRegistry[TKey];
+};
+/**
+ * Output type for IgniterCallerSchema.build().
+ */
+type IgniterCallerSchemaBuildResult<TSchemas extends IgniterCallerSchemaMap, TRegistry extends IgniterCallerSchemaRegistry> = TSchemas & {
+    $Infer: IgniterCallerSchemaInfer<TSchemas, TRegistry>;
+    get: IgniterCallerSchemaGetters<TSchemas, TRegistry>;
+};
+/**
+ * Accepted input types for `withSchemas`.
+ */
+type IgniterCallerSchemaInput<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap, TRegistry extends IgniterCallerSchemaRegistry = IgniterCallerSchemaRegistry> = TSchemas | IgniterCallerSchemaBuildResult<TSchemas, TRegistry>;
+/**
+ * Extracts the schema map from a build result or raw map.
+ */
+type IgniterCallerSchemaMapFrom<T> = T extends IgniterCallerSchemaBuildResult<infer TMap, any> ? TMap : T extends IgniterCallerSchemaMap ? T : never;
+
+/**
+ * @fileoverview Mock types for @igniter-js/caller.
+ * @module @igniter-js/caller/types/mock
+ */
+
+/**
+ * Resolves valid status codes for a mocked path+method based on the schema map.
+ */
+type IgniterCallerMockStatus<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = keyof SchemaMapResponses<TSchemas, TPath, TMethod> & (number | string);
+/**
+ * Picks the default success status for a mocked path+method.
+ * Prefers 200, then 201, then the first available status.
+ */
+type IgniterCallerMockDefaultStatus<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = 200 extends IgniterCallerMockStatus<TSchemas, TPath, TMethod> ? 200 : 201 extends IgniterCallerMockStatus<TSchemas, TPath, TMethod> ? 201 : IgniterCallerMockStatus<TSchemas, TPath, TMethod>;
+/**
+ * Full request context passed to mock handlers.
+ */
+interface IgniterCallerMockRequest<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> {
+    method: TMethod;
+    path: TPath;
+    url: string;
+    safeUrl: string;
+    baseURL?: string;
+    headers: Record<string, string>;
+    query: Record<string, string | number | boolean>;
+    params: EndpointInfo<TSchemas, TPath, TMethod>['params'];
+    body?: SchemaMapRequestType<TSchemas, TPath, TMethod>;
+    timeoutMs?: number;
+    cache?: RequestCache;
+    cacheKey?: string;
+    staleTime?: number;
+    responseTypeSchema?: StandardSchemaV1 | z.ZodSchema<any>;
+}
+/**
+ * Resolved mock handler for a given request path+method.
+ */
+interface IgniterCallerMockResolvedHandler<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas> = SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath> = SchemaMapMethods<TSchemas, TPath>> {
+    handler: IgniterCallerMockHandlerDefinition<TSchemas, TPath, TMethod>;
+    params: Record<string, string>;
+    path: TPath;
+    method: TMethod;
+}
+/**
+ * Contract for the mock manager used by the request builder.
+ */
+interface IIgniterCallerMockManager<TSchemas extends IgniterCallerSchemaMap> {
+    resolve(path: string, method: IgniterCallerSchemaMethod): IgniterCallerMockResolvedHandler<TSchemas> | null;
+}
+/**
+ * Mock response payload for a specific status code.
+ */
+type IgniterCallerMockResponseForStatus<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>, TStatus extends IgniterCallerMockStatus<TSchemas, TPath, TMethod>> = {
+    status: TStatus;
+    response: SchemaMapResponseType<TSchemas, TPath, TMethod, TStatus>;
+    headers?: Record<string, string>;
+    delayMs?: number;
+    errorMessage?: string;
+};
+/**
+ * Mock response payload when status is omitted (uses default success status).
+ */
+type IgniterCallerMockResponseDefault<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = {
+    response: SchemaMapResponseType<TSchemas, TPath, TMethod, IgniterCallerMockDefaultStatus<TSchemas, TPath, TMethod>>;
+    status?: undefined;
+    headers?: Record<string, string>;
+    delayMs?: number;
+    errorMessage?: string;
+};
+/**
+ * Union of all supported mock response payloads for a path+method.
+ */
+type IgniterCallerMockResponse<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = IgniterCallerMockResponseDefault<TSchemas, TPath, TMethod> | {
+    [TStatus in IgniterCallerMockStatus<TSchemas, TPath, TMethod>]: IgniterCallerMockResponseForStatus<TSchemas, TPath, TMethod, TStatus>;
+}[IgniterCallerMockStatus<TSchemas, TPath, TMethod>];
+/**
+ * Mock handler signature (receives full request context).
+ */
+type IgniterCallerMockHandler<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = (request: IgniterCallerMockRequest<TSchemas, TPath, TMethod>) => IgniterCallerMockResponse<TSchemas, TPath, TMethod> | Promise<IgniterCallerMockResponse<TSchemas, TPath, TMethod>>;
+/**
+ * Either a static mock response or a handler callback.
+ */
+type IgniterCallerMockHandlerDefinition<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>, TMethod extends SchemaMapMethods<TSchemas, TPath>> = IgniterCallerMockResponse<TSchemas, TPath, TMethod> | IgniterCallerMockHandler<TSchemas, TPath, TMethod>;
+/**
+ * Mock definitions for a single path (method -> handler/response).
+ */
+type IgniterCallerMockPathDefinition<TSchemas extends IgniterCallerSchemaMap, TPath extends SchemaMapPaths<TSchemas>> = Partial<{
+    [TMethod in SchemaMapMethods<TSchemas, TPath>]: IgniterCallerMockHandlerDefinition<TSchemas, TPath, TMethod>;
+}>;
+/**
+ * Registry of mocked paths for a schema map.
+ */
+type IgniterCallerMockRegistry<TSchemas extends IgniterCallerSchemaMap> = Partial<{
+    [TPath in SchemaMapPaths<TSchemas>]: IgniterCallerMockPathDefinition<TSchemas, TPath>;
+}>;
+/**
+ * Mock configuration passed to the caller builder.
+ */
+interface IgniterCallerMockConfig<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
+    enabled: boolean;
+    mock: IIgniterCallerMockManager<TSchemas>;
+}
+
+/**
+ * Fluent request builder for `IgniterCaller`.
+ *
+ * When created via specific HTTP methods (get, post, put, patch, delete),
+ * the method is already set and cannot be changed.
+ */
+declare class IgniterCallerRequestBuilder<TResponse = unknown> {
+    private options;
+    private logger?;
+    private telemetry?;
+    private retryOptions?;
+    private fallbackFn?;
+    private cacheKey?;
+    private staleTime?;
+    private requestInterceptors?;
+    private responseInterceptors?;
+    private eventEmitter?;
+    private schemas?;
+    private schemaValidation?;
+    private responseTypeSchema?;
+    private mock?;
+    /**
+     * Creates a new request builder instance.
+     *
+     * @param params - Builder configuration from the manager.
+     */
+    constructor(params: IgniterCallerRequestBuilderParams);
+    /**
+     * Sets the HTTP method for this request.
+     * @internal Used by IgniterCaller.request() for generic requests.
+     *
+     * @param method - HTTP method for the request.
+     */
+    _setMethod(method: IgniterCallerHttpMethod): this;
+    /**
+     * Sets the URL for this request.
+     * @internal Used when URL is passed to HTTP method directly.
+     *
+     * @param url - Request URL or path.
+     */
+    _setUrl(url: string): this;
+    /**
+     * Overrides the logger for this request chain.
+     *
+     * @param logger - Logger implementation from `@igniter-js/common`.
+     */
+    withLogger(logger: IgniterLogger): this;
+    /**
+     * Sets the request URL.
+     *
+     * @param url - Request URL or path.
+     */
+    url(url: string): this;
+    /**
+     * Sets the request body.
+     * For GET/HEAD requests, body will be automatically converted to query params.
+     *
+     * @param body - Body payload for the request.
+     */
+    body<TBody>(body: TBody): this;
+    /**
+     * Sets URL query parameters.
+     *
+     * @param params - Query string parameters.
+     */
+    params(params: Record<string, string | number | boolean>): this;
+    /**
+     * Merges additional headers into the request.
+     *
+     * @param headers - Header map merged into existing headers.
+     */
+    headers(headers: Record<string, string>): this;
+    /**
+     * Sets request timeout in milliseconds.
+     *
+     * @param timeout - Timeout in milliseconds.
+     */
+    timeout(timeout: number): this;
+    /**
+     * Sets cache strategy and optional cache key.
+     *
+     * @param cache - Cache strategy for the request.
+     * @param key - Optional cache key override.
+     */
+    cache(cache: RequestCache, key?: string): this;
+    /**
+     * Configures retry behavior for failed requests.
+     *
+     * @param maxAttempts - Maximum number of attempts.
+     * @param options - Retry options excluding `maxAttempts`.
+     */
+    retry(maxAttempts: number, options?: Omit<IgniterCallerRetryOptions, 'maxAttempts'>): this;
+    /**
+     * Provides a fallback value if the request fails.
+     *
+     * @param fn - Fallback factory called when the request fails.
+     */
+    fallback<T>(fn: () => T): this;
+    /**
+     * Sets cache stale time in milliseconds.
+     *
+     * @param milliseconds - Stale time in milliseconds.
+     */
+    stale(milliseconds: number): this;
+    /**
+     * Sets the expected response type for TypeScript inference.
+     *
+     * - If a Zod/StandardSchema is passed, it will validate the response (only for JSON/XML/CSV)
+     * - If a type parameter is passed (e.g., `responseType<File>()`), it's for typing only
+     *
+     * The actual parsing is based on Content-Type headers, not this setting.
+     *
+     * @param schema - Zod/StandardSchema instance for validation (optional).
+     *
+     * @example
+     * ```ts
+     * // With Zod schema (validates JSON response)
+     * const result = await api.get('/users').responseType(UserSchema).execute()
+     *
+     * // With type marker (typing only, no validation)
+     * const result = await api.get('/file').responseType<Blob>().execute()
+     * ```
+     */
+    responseType<T>(schema?: z.ZodSchema<T> | StandardSchemaV1): IgniterCallerRequestBuilder<T>;
+    /**
+     * Downloads a file via GET request.
+     * @deprecated Use `.responseType<File>().execute()` instead. The response type is auto-detected.
+     *
+     * @param url - URL or path to download.
+     */
+    getFile(url: string): {
+        execute: () => Promise<IgniterCallerFileResponse>;
+    };
+    /**
+     * Executes the HTTP request.
+     *
+     * Response parsing is automatic based on Content-Type headers:
+     * - `application/json` → parsed as JSON
+     * - `text/xml`, `application/xml` → returned as text (parse with your XML library)
+     * - `text/csv` → returned as text
+     * - `text/html`, `text/plain` → returned as text
+     * - `image/*`, `audio/*`, `video/*`, `application/pdf`, etc. → returned as Blob
+     * - `application/octet-stream` → returned as Blob
+     *
+     * Schema validation (if configured) only runs for validatable content types (JSON, XML, CSV).
+     *
+     * @returns Response envelope with data or error.
+     */
+    execute(): Promise<IgniterCallerApiResponse<TResponse>>;
+    private executeWithRetry;
+    private executeSingleRequest;
+    private resolveUrl;
+    private buildRequest;
+    /**
+     * Normalizes a URL into a path for mock matching.
+     */
+    private normalizeMockPath;
+    /**
+     * Resolves the final query object (merges GET/HEAD body into params).
+     */
+    private getFinalQuery;
+    /**
+     * Executes a mock handler when enabled and matched.
+     */
+    private executeMockRequest;
+    /**
+     * Normalizes a mock handler result into a response payload with status.
+     */
+    private resolveMockResponse;
+    /**
+     * Emits event for this response using injected emitter.
+     */
+    private emitEvent;
+}
+
+/**
+ * @fileoverview Builder and request builder types for @igniter-js/caller.
+ * @module @igniter-js/caller/types/builder
+ */
+
+/**
+ * Builder state for {@link IgniterCallerBuilder}.
+ */
+type IgniterCallerBuilderState<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> = {
+    /** Base URL prefix for outgoing requests. */
+    baseURL?: string;
+    /** Default headers merged into each request. */
+    headers?: Record<string, string>;
+    /** Default cookies (sent as the Cookie header). */
+    cookies?: Record<string, string>;
+    /** Logger instance for request lifecycle logs. */
+    logger?: IgniterLogger;
+    /** Telemetry manager for emitting events. */
+    telemetry?: IgniterTelemetryManager<any>;
+    /** Request interceptors executed before the request. */
+    requestInterceptors?: IgniterCallerRequestInterceptor[];
+    /** Response interceptors executed after the request. */
+    responseInterceptors?: IgniterCallerResponseInterceptor[];
+    /** Store adapter for persistent cache. */
+    store?: IgniterCallerStoreAdapter;
+    /** Store adapter options (ttl, keyPrefix, fallback). */
+    storeOptions?: IgniterCallerStoreOptions;
+    /** Schema map for request/response inference. */
+    schemas?: TSchemas;
+    /** Validation options for schema enforcement. */
+    schemaValidation?: IgniterCallerSchemaValidationOptions;
+    /** Optional mock configuration (routes requests to mock handlers). */
+    mock?: IgniterCallerMockConfig<TSchemas>;
+};
+/**
+ * Constructor params for the request builder.
+ */
+interface IgniterCallerRequestBuilderParams {
+    /** Base URL prefix for outgoing requests. */
+    baseURL?: string;
+    /** Default headers merged into each request. */
+    defaultHeaders?: Record<string, string>;
+    /** Default cookies (sent as the Cookie header). */
+    defaultCookies?: Record<string, string>;
+    /** Logger instance for request lifecycle logs. */
+    logger?: IgniterLogger;
+    /** Telemetry manager for emitting events. */
+    telemetry?: IgniterTelemetryManager<any>;
+    /** Request interceptors executed before the request. */
+    requestInterceptors?: IgniterCallerRequestInterceptor[];
+    /** Response interceptors executed after the request. */
+    responseInterceptors?: IgniterCallerResponseInterceptor[];
+    /** Callback invoked after request completion. */
+    eventEmitter?: (url: string, method: string, result: IgniterCallerApiResponse<unknown>) => Promise<void>;
+    /** Schema map for request/response inference. */
+    schemas?: IgniterCallerSchemaMap;
+    /** Validation options for schema enforcement. */
+    schemaValidation?: IgniterCallerSchemaValidationOptions;
+    /** Optional mock configuration. */
+    mock?: IgniterCallerMockConfig<any>;
+}
+/**
+ * Request builder type without internal methods.
+ * Used when creating requests via specific HTTP methods (get, post, etc.).
+ */
+type IgniterCallerMethodRequestBuilder<TResponse = unknown> = Omit<IgniterCallerRequestBuilder<TResponse>, "_setMethod" | "_setUrl">;
+/**
+ * Request builder with typed response based on schema inference.
+ */
+type IgniterCallerTypedRequestBuilder<TResponse = unknown> = IgniterCallerMethodRequestBuilder<TResponse>;
+
+/**
+ * Callback function for event listeners.
+ */
+type IgniterCallerEventCallback<T = any> = (result: IgniterCallerApiResponse<T>, context: {
+    url: string;
+    method: string;
+    timestamp: number;
+}) => void | Promise<void>;
+/**
+ * Pattern for matching URLs (string or RegExp).
+ */
+type IgniterCallerUrlPattern = string | RegExp;
+
+/**
+ * @fileoverview Type inference helpers for @igniter-js/caller.
+ * @module @igniter-js/caller/types/infer
+ */
+
+/**
+ * Infer success response type from endpoint schema (200 or 201).
+ */
+type InferSuccessResponse<T> = T extends IgniterCallerEndpointSchema<any, infer R> ? 200 extends keyof R ? R[200] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R[200]> : unknown : 201 extends keyof R ? R[201] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R[201]> : unknown : unknown : unknown;
+/**
+ * Get the endpoint schema for a path and method from a schema map.
+ */
+type GetEndpoint<TSchemas extends IgniterCallerSchemaMap, TPath extends string, TMethod extends IgniterCallerSchemaMethod> = TPath extends keyof TSchemas ? TMethod extends keyof TSchemas[TPath] ? TSchemas[TPath][TMethod] : undefined : undefined;
+/**
+ * Infer the response type for a given path and method.
+ * Returns `unknown` if the path/method is not in the schema.
+ */
+type InferResponse<TSchemas extends IgniterCallerSchemaMap, TPath extends string, TMethod extends IgniterCallerSchemaMethod> = InferSuccessResponse<GetEndpoint<TSchemas, TPath, TMethod>>;
+/**
+ * Typed request builder with inferred body and params types.
+ */
+type TypedRequestBuilder<TSchemas extends IgniterCallerSchemaMap, TPath extends string, TMethod extends IgniterCallerSchemaMethod> = Omit<IgniterCallerMethodRequestBuilder<EndpointInfo<TSchemas, TPath, TMethod>["response"]>, "body" | "params"> & {
+    /**
+     * Sets the request body with type inference from schema.
+     */
+    body: EndpointInfo<TSchemas, TPath, TMethod>["request"] extends never ? <TBody>(body: TBody) => TypedRequestBuilder<TSchemas, TPath, TMethod> : (body: EndpointInfo<TSchemas, TPath, TMethod>["request"]) => TypedRequestBuilder<TSchemas, TPath, TMethod>;
+    /**
+     * Sets URL path parameters with type inference from URL pattern.
+     */
+    params: keyof EndpointInfo<TSchemas, TPath, TMethod>["params"] extends never ? (params: Record<string, string | number | boolean>) => TypedRequestBuilder<TSchemas, TPath, TMethod> : (params: EndpointInfo<TSchemas, TPath, TMethod>["params"] & Record<string, string | number | boolean>) => TypedRequestBuilder<TSchemas, TPath, TMethod>;
+};
+
+/**
+ * @fileoverview Manager contracts for @igniter-js/caller.
+ * @module @igniter-js/caller/types/manager
+ */
+
+/**
+ * Public contract for the IgniterCaller manager runtime.
+ */
+interface IIgniterCallerManager<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
+    /**
+     * Creates a GET request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    get<TPath extends GetPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "GET">;
+    get<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "GET">>;
+    /**
+     * Creates a POST request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    post<TPath extends PostPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "POST">;
+    post<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "POST">>;
+    /**
+     * Creates a PUT request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    put<TPath extends PutPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "PUT">;
+    put<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "PUT">>;
+    /**
+     * Creates a PATCH request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    patch<TPath extends PatchPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "PATCH">;
+    patch<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "PATCH">>;
+    /**
+     * Creates a DELETE request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    delete<TPath extends DeletePaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "DELETE">;
+    delete<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "DELETE">>;
+    /**
+     * Creates a HEAD request.
+     *
+     * @param url - Optional URL for the request.
+     * @returns Typed request builder.
+     */
+    head<TPath extends HeadPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, "HEAD">;
+    head<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, "HEAD">>;
+    /**
+     * Executes a request directly with all options in one object.
+     *
+     * @param options - Request configuration.
+     * @returns Response envelope with data or error.
+     */
+    request<T = unknown>(options: IgniterCallerDirectRequestOptions): Promise<IgniterCallerApiResponse<T>>;
+}
+
+/**
+ * HTTP client runtime for Igniter.js.
+ *
+ * This module is intentionally structured to be extracted into a standalone package
+ * in the Igniter.js ecosystem as `@igniter-js/caller`.
+ *
+ * @template TSchemas - The schema map type for type-safe requests/responses.
+ */
+declare class IgniterCallerManager<TSchemas extends IgniterCallerSchemaMap> implements IIgniterCallerManager<TSchemas> {
+    /** Global event emitter for observing HTTP responses */
+    private static readonly events;
+    private baseURL?;
+    private headers?;
+    private cookies?;
+    private logger?;
+    private telemetry?;
+    private requestInterceptors?;
+    private responseInterceptors?;
+    private schemas?;
+    private schemaValidation?;
+    private mock?;
+    /**
+     * Creates a new manager instance.
+     *
+     * @param baseURL - Base URL prefix for requests.
+     * @param opts - Optional configuration (headers, cookies, telemetry, schemas).
+     */
+    constructor(baseURL?: string, opts?: {
+        headers?: Record<string, string>;
+        cookies?: Record<string, string>;
+        logger?: IgniterLogger;
+        telemetry?: IgniterTelemetryManager<any>;
+        requestInterceptors?: IgniterCallerRequestInterceptor[];
+        responseInterceptors?: IgniterCallerResponseInterceptor[];
+        schemas?: TSchemas;
+        schemaValidation?: IgniterCallerSchemaValidationOptions;
+        mock?: IgniterCallerMockConfig<TSchemas>;
+    });
+    /**
+     * Creates common request builder params.
+     */
+    private createBuilderParams;
+    /**
+     * Creates a GET request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request. When provided and matching a schema path,
+     *            enables full type inference for response, body, and path params.
+     *
+     * @example
+     * ```ts
+     * // With typed schema - full type inference
+     * const result = await api.get('/users/:id')
+     *   .params({ id: '123' })  // params are typed based on URL pattern
+     *   .execute()
+     * // result.data is typed based on schema
+     *
+     * // Without URL (set later with .url())
+     * const result = await api.get().url('/users').execute()
+     * ```
+     */
+    get<TPath extends GetPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'GET'>;
+    get<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'GET'>>;
+    /**
+     * Creates a POST request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request.
+     *
+     * @example
+     * ```ts
+     * // With typed schema - body type is inferred from schema
+     * const result = await api.post('/users')
+     *   .body({ name: 'John', email: 'john@example.com' })  // body is typed
+     *   .execute()
+     * ```
+     */
+    post<TPath extends PostPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'POST'>;
+    post<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'POST'>>;
+    /**
+     * Creates a PUT request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request.
+     *
+     * @example
+     * ```ts
+     * const result = await api.put('/users/:id')
+     *   .params({ id: '1' })
+     *   .body({ name: 'Jane' })
+     *   .execute()
+     * ```
+     */
+    put<TPath extends PutPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'PUT'>;
+    put<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'PUT'>>;
+    /**
+     * Creates a PATCH request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request.
+     *
+     * @example
+     * ```ts
+     * const result = await api.patch('/users/:id')
+     *   .params({ id: '1' })
+     *   .body({ name: 'Jane' })
+     *   .execute()
+     * ```
+     */
+    patch<TPath extends PatchPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'PATCH'>;
+    patch<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'PATCH'>>;
+    /**
+     * Creates a DELETE request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request.
+     *
+     * @example
+     * ```ts
+     * const result = await api.delete('/users/:id')
+     *   .params({ id: '1' })
+     *   .execute()
+     * ```
+     */
+    delete<TPath extends DeletePaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'DELETE'>;
+    delete<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'DELETE'>>;
+    /**
+     * Creates a HEAD request.
+     *
+     * When a URL is provided and matches a schema, the response, body, and params types
+     * are automatically inferred from the schema definition.
+     *
+     * @param url Optional URL for the request.
+     */
+    head<TPath extends HeadPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'HEAD'>;
+    head<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'HEAD'>>;
+    /**
+     * Executes a request directly with all options in one object (axios-style).
+     *
+     * This is a convenience method for making requests without using the builder pattern.
+     * Useful for dynamic requests where options are constructed programmatically.
+     *
+     * @param options - Request configuration for method, url, and behavior.
+     * @returns Response envelope with data or error.
+     *
+     * @example
+     * ```ts
+     * const result = await api.request({
+     *   method: 'POST',
+     *   url: '/users',
+     *   body: { name: 'John' },
+     *   headers: { 'X-Custom': 'value' },
+     *   timeout: 5000,
+     * })
+     *
+     * // With caching
+     * const result = await api.request({
+     *   method: 'GET',
+     *   url: '/users',
+     *   staleTime: 30000,
+     * })
+     *
+     * // With retry
+     * const result = await api.request({
+     *   method: 'GET',
+     *   url: '/health',
+     *   retry: { maxAttempts: 3, backoff: 'exponential' },
+     * })
+     * ```
+     */
+    request<T = unknown>(options: IgniterCallerDirectRequestOptions): Promise<IgniterCallerApiResponse<T>>;
+    /**
+     * Executes multiple requests in parallel and returns results as an array.
+     *
+     * This is useful for batching independent API calls.
+     *
+     * @param requests - Array of request promises.
+     * @returns Array of resolved results in the same order.
+     */
+    static batch<T extends readonly Promise<IgniterCallerApiResponse<any>>[]>(requests: [...T]): Promise<{
+        [K in keyof T]: T[K] extends Promise<infer R> ? R : never;
+    }>;
+    /**
+     * Registers a global event listener for HTTP responses.
+     *
+     * This allows observing API responses across the application for:
+     * - Debugging and logging
+     * - Real-time monitoring
+     * - Cache invalidation triggers
+     * - Analytics and telemetry
+     *
+     * @param pattern URL string (exact match) or RegExp pattern
+     * @param callback Function to execute when a response matches
+     * @returns Cleanup function to remove the listener
+     *
+     * @example
+     * ```ts
+     * // Listen to all user endpoints
+     * const cleanup = IgniterCallerManager.on(/^\/users/, (result, context) => {
+     *   console.log(`${context.method} ${context.url}`, result)
+     * })
+     *
+     * // Cleanup when done
+     * cleanup()
+     * ```
+     */
+    static on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
+    /**
+     * Removes event listeners for a pattern.
+     *
+     * @param pattern - URL string or RegExp pattern.
+     * @param callback - Callback to remove (optional).
+     */
+    static off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
+    /**
+     * Invalidates a specific cache entry.
+     *
+     * This is useful after mutations to ensure fresh data on next fetch.
+     *
+     * @param key - Cache key to invalidate.
+     *
+     * @example
+     * ```ts
+     * // After creating a user
+     * await api.post('/users').body(newUser).execute()
+     * await IgniterCallerManager.invalidate('/users') // Clear users list cache
+     * ```
+     */
+    static invalidate(key: string): Promise<void>;
+    /**
+     * Invalidates all cache entries matching a pattern.
+     *
+     * @param pattern Glob pattern (e.g., '/users/*') or exact key
+     * @returns Promise that resolves when invalidation completes.
+     *
+     * @example
+     * ```ts
+     * // Invalidate all user-related caches
+     * await IgniterCallerManager.invalidatePattern('/users/*')
+     * ```
+     */
+    static invalidatePattern(pattern: string): Promise<void>;
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @internal
+     *
+     * @param url - Request URL (resolved).
+     * @param method - HTTP method.
+     * @param result - Response envelope.
+     */
+    static emitEvent(url: string, method: string, result: IgniterCallerApiResponse<any>): Promise<void>;
+}
+
+export { type SchemaMapEndpoint as $, type IgniterCallerMockPathDefinition as A, type IgniterCallerFileResponse as B, IgniterCallerRequestBuilder as C, type DeletePaths as D, type EndpointInfo as E, type IgniterCallerHttpMethod as F, type GetPaths as G, type HeadPaths as H, IgniterCallerManager as I, type IgniterCallerBaseRequestOptions as J, type IgniterCallerRequestOptions as K, type IgniterCallerDirectRequestOptions as L, type IgniterCallerResponseContentType as M, type IgniterCallerValidatableContentType as N, type IgniterCallerResponseMarker as O, type PostPaths as P, type IgniterCallerRetryOptions as Q, type ResolveStatusKey as R, type SchemaArray as S, type TypedRequestBuilder as T, type ExtractPathParams as U, type InferRequestType as V, type InferResponseType as W, type InferSuccessResponseType as X, type InferAllResponseTypes as Y, type SchemaMapMethods as Z, type PathsForMethod as _, type IgniterCallerApiResponse as a, type SchemaMapResponseType as a0, type SchemaMapRequestType as a1, type SchemaMapResponses as a2, type SchemaMapResponsesType as a3, type SchemaMapRequestSchema as a4, type SchemaMapResponseSchema as a5, type IgniterCallerSchemaInfer as a6, type IgniterCallerSchemaGetters as a7, type IgniterCallerMockStatus as a8, type IgniterCallerMockDefaultStatus as a9, type IgniterCallerMockRequest as aa, type IgniterCallerMockResponseForStatus as ab, type IgniterCallerMockResponseDefault as ac, type IgniterCallerMockResponse as ad, type IgniterCallerMockHandler as ae, type IgniterCallerMockHandlerDefinition as af, type IgniterCallerBuilderState as ag, type IgniterCallerRequestBuilderParams as ah, type IgniterCallerMethodRequestBuilder as ai, type InferSuccessResponse as aj, type GetEndpoint as ak, type IIgniterCallerManager as al, type IgniterCallerSchemaMap as b, type IgniterCallerSchemaMethod as c, type InferResponse as d, type IgniterCallerTypedRequestBuilder as e, type PutPaths as f, type PatchPaths as g, type IgniterCallerUrlPattern as h, type IgniterCallerEventCallback as i, type IIgniterCallerMockManager as j, type IgniterCallerMockRegistry as k, type IgniterCallerMockResolvedHandler as l, type IgniterCallerRequestInterceptor as m, type IgniterCallerResponseInterceptor as n, type IgniterCallerSchemaInput as o, type IgniterCallerSchemaValidationOptions as p, type IgniterCallerSchemaMapFrom as q, type IgniterCallerMockConfig as r, type IgniterCallerEndpointSchema as s, type IgniterCallerSchemaRegistry as t, type SchemaNullable as u, type SchemaOptional as v, type SchemaRecord as w, type IgniterCallerSchemaEndpointConfig as x, type IgniterCallerSchemaBuildResult as y, type SchemaMapPaths as z };