@igniter-js/caller 0.1.3 → 0.1.5

package/dist/index.d.mts

@@ -1,402 +1,157 @@
-import { StandardSchemaV1, IgniterLogger, IgniterError } from '@igniter-js/core';
-import { z } from 'zod';
+import { h as IgniterCallerUrlPattern, i as IgniterCallerEventCallback, b as IgniterCallerSchemaMap, j as IIgniterCallerMockManager, k as IgniterCallerMockRegistry, c as IgniterCallerSchemaMethod, l as IgniterCallerMockResolvedHandler, m as IgniterCallerRequestInterceptor, n as IgniterCallerResponseInterceptor, o as IgniterCallerSchemaInput, p as IgniterCallerSchemaValidationOptions, q as IgniterCallerSchemaMapFrom, r as IgniterCallerMockConfig, I as IgniterCallerManager, s as IgniterCallerEndpointSchema, t as IgniterCallerSchemaRegistry, S as SchemaArray, u as SchemaNullable, v as SchemaOptional, w as SchemaRecord, x as IgniterCallerSchemaEndpointConfig, y as IgniterCallerSchemaBuildResult, z as SchemaMapPaths, A as IgniterCallerMockPathDefinition, a as IgniterCallerApiResponse, B as IgniterCallerFileResponse } from './manager-DWvX2zsz.mjs';
+export { D as DeletePaths, E as EndpointInfo, U as ExtractPathParams, ak as GetEndpoint, G as GetPaths, H as HeadPaths, al as IIgniterCallerManager, J as IgniterCallerBaseRequestOptions, ag as IgniterCallerBuilderState, L as IgniterCallerDirectRequestOptions, F as IgniterCallerHttpMethod, ai as IgniterCallerMethodRequestBuilder, a9 as IgniterCallerMockDefaultStatus, ae as IgniterCallerMockHandler, af as IgniterCallerMockHandlerDefinition, aa as IgniterCallerMockRequest, ad as IgniterCallerMockResponse, ac as IgniterCallerMockResponseDefault, ab as IgniterCallerMockResponseForStatus, a8 as IgniterCallerMockStatus, C as IgniterCallerRequestBuilder, ah as IgniterCallerRequestBuilderParams, K as IgniterCallerRequestOptions, M as IgniterCallerResponseContentType, O as IgniterCallerResponseMarker, Q as IgniterCallerRetryOptions, a7 as IgniterCallerSchemaGetters, a6 as IgniterCallerSchemaInfer, e as IgniterCallerTypedRequestBuilder, N as IgniterCallerValidatableContentType, Y as InferAllResponseTypes, V as InferRequestType, d as InferResponse, W as InferResponseType, aj as InferSuccessResponse, X as InferSuccessResponseType, g as PatchPaths, _ as PathsForMethod, P as PostPaths, f as PutPaths, R as ResolveStatusKey, $ as SchemaMapEndpoint, Z as SchemaMapMethods, a4 as SchemaMapRequestSchema, a1 as SchemaMapRequestType, a5 as SchemaMapResponseSchema, a0 as SchemaMapResponseType, a2 as SchemaMapResponses, a3 as SchemaMapResponsesType, T as TypedRequestBuilder } from './manager-DWvX2zsz.mjs';
+import { IgniterLogger, StandardSchemaV1, IgniterError } from '@igniter-js/common';
+import { IgniterTelemetryManager } from '@igniter-js/telemetry';
+import { I as IgniterCallerStoreAdapter, a as IgniterCallerStoreOptions } from './store-D2p2dqGN.mjs';
+export { MockCallerStoreAdapter } from './adapters/index.mjs';
+import 'zod';
 
 /**
- * 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>;
-    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) */
-    responseSchema?: z.ZodSchema<any>;
-    /** 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> {
-    data?: T;
-    error?: Error;
-    /** 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: File | null;
-    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 = any, TResponses extends Record<number, StandardSchemaV1> = Record<number, StandardSchemaV1>> = {
-    /** Request body schema (optional) */
-    request?: TRequest;
-    /** Response schemas by status code */
-    responses: TResponses;
-};
-/**
- * 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>>>>;
-/**
- * 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> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? Status extends keyof Responses ? Responses[Status] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<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> ? 200 extends keyof Responses ? Responses[200] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[200]> : never : 201 extends keyof Responses ? Responses[201] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<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, 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 = 200> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<any, infer Responses> ? TStatus extends keyof Responses ? Responses[TStatus] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<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;
-}
-
-/**
- * Store adapter interface compatible with Igniter.js Store.
+ * Event emitter for observing HTTP responses across the application.
  *
- * This allows IgniterCaller to use any store implementation (Redis, in-memory, etc.)
- * for persistent caching across requests and deployments.
+ * This allows developers to listen to API responses globally for:
+ * - Debugging and logging
+ * - Real-time monitoring
+ * - Cache invalidation triggers
+ * - Analytics and telemetry
  */
-interface IgniterCallerStoreAdapter<TClient = any> {
-    /** The underlying client instance (e.g., Redis client). */
-    readonly client: TClient;
+declare class IgniterCallerEvents {
+    private listeners;
+    private patternListeners;
     /**
-     * Retrieves a value from the store by its key.
-     * @param key The key to retrieve.
-     * @returns The value if found (auto-deserialized), otherwise null.
+     * Registers a listener for a specific URL or pattern.
+     *
+     * @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 specific endpoint
+     * const cleanup = api.on('/users', (result) => {
+     *   console.log('Users fetched:', result.data)
+     * })
+     *
+     * // Listen to pattern
+     * api.on(/^\/users\/\d+$/, (result) => {
+     *   console.log('User detail fetched')
+     * })
+     *
+     * // Cleanup when done
+     * cleanup()
+     * ```
      */
-    get<T = any>(key: string): Promise<T | null>;
+    on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
     /**
-     * Stores a value in the store.
-     * @param key The key to store the value under.
-     * @param value The value to store (will be auto-serialized).
-     * @param options Configuration options, such as TTL.
+     * Removes a specific listener or all listeners for a pattern.
+     *
+     * @param pattern - URL string or RegExp pattern.
+     * @param callback - Optional specific callback to remove.
      */
-    set(key: string, value: any, options?: {
-        ttl?: number;
-        [key: string]: any;
-    }): Promise<void>;
+    off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
     /**
-     * Deletes a key from the store.
-     * @param key The key to delete.
+     * Emits an event to all matching listeners.
+     *
+     * @internal
+     *
+     * @param url - Request URL to match listeners against.
+     * @param method - HTTP method.
+     * @param result - Response envelope.
      */
-    delete(key: string): Promise<void>;
+    emit(url: string, method: string, result: any): Promise<void>;
     /**
-     * Checks if a key exists in the store.
-     * @param key The key to check.
-     * @returns `true` if the key exists, otherwise `false`.
+     * Removes all listeners.
+     *
+     * @returns Nothing.
      */
-    has(key: string): Promise<boolean>;
+    clear(): void;
 }
+
 /**
- * Configuration options for store-based caching.
+ * Runtime mock registry resolver for caller requests.
  */
-interface IgniterCallerStoreOptions {
-    /** Default TTL in seconds for cached entries (default: 3600 = 1 hour). */
-    ttl?: number;
-    /** Prefix for all cache keys (default: 'igniter:caller:'). */
-    keyPrefix?: string;
-    /** Whether to fallback to fetch cache when store is unavailable (default: true). */
-    fallbackToFetch?: boolean;
+declare class IgniterCallerMockManager<TSchemas extends IgniterCallerSchemaMap> implements IIgniterCallerMockManager<TSchemas> {
+    private readonly registry;
+    constructor(registry: IgniterCallerMockRegistry<TSchemas>);
+    /**
+     * Resolves a mock handler for a path+method pair.
+     *
+     * @param path - Request path (normalized).
+     * @param method - HTTP method.
+     * @returns Resolved handler info or null when no match is found.
+     */
+    resolve(path: string, method: IgniterCallerSchemaMethod): IgniterCallerMockResolvedHandler<TSchemas> | null;
 }
 
-type IgniterCallerBuilderState<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> = {
-    baseURL?: string;
-    headers?: Record<string, string>;
-    cookies?: Record<string, string>;
-    logger?: IgniterLogger;
-    requestInterceptors?: IgniterCallerRequestInterceptor[];
-    responseInterceptors?: IgniterCallerResponseInterceptor[];
-    store?: IgniterCallerStoreAdapter;
-    storeOptions?: IgniterCallerStoreOptions;
-    schemas?: TSchemas;
-    schemaValidation?: IgniterCallerSchemaValidationOptions;
-};
-type IgniterCallerBuilderFactory<TCaller, TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> = (state: IgniterCallerBuilderState<TSchemas>) => TCaller;
-/**
- * Utility type to replace the schema type in a caller.
- * Used by withSchemas to properly type the returned caller.
- */
-type ReplaceCallerSchema<TCaller, TNewSchemas extends IgniterCallerSchemaMap> = TCaller extends {
-    schemas?: infer _;
-} ? Omit<TCaller, 'schemas'> & {
-    schemas?: TNewSchemas;
-} : TCaller;
 /**
  * Builder used by developers to initialize the `IgniterCaller` client.
  *
  * This API is designed to remain stable when extracted to `@igniter-js/caller`.
  */
-declare class IgniterCallerBuilder<TCaller = unknown, TSchemas extends IgniterCallerSchemaMap = any> {
+declare class IgniterCallerBuilder<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
     private readonly state;
-    private readonly factory;
     private constructor();
     /**
      * Creates a new builder instance.
+     *
+     * @returns New builder instance with empty state.
      */
-    static create<TCaller, TSchemas extends IgniterCallerSchemaMap = any>(factory: IgniterCallerBuilderFactory<TCaller, TSchemas>): IgniterCallerBuilder<TCaller, TSchemas>;
-    /** Sets the base URL for all requests. */
-    withBaseUrl(baseURL: string): IgniterCallerBuilder<TCaller, TSchemas>;
-    /** Merges default headers for all requests. */
-    withHeaders(headers: Record<string, string>): IgniterCallerBuilder<TCaller>;
-    /** Sets default cookies (sent as the `Cookie` header). */
-    withCookies(cookies: Record<string, string>): IgniterCallerBuilder<TCaller>;
-    /** Attaches a logger instance. */
-    withLogger(logger: IgniterLogger): IgniterCallerBuilder<TCaller, TSchemas>;
-    /** Adds a request interceptor that runs before each request. */
-    withRequestInterceptor(interceptor: IgniterCallerRequestInterceptor): IgniterCallerBuilder<TCaller, TSchemas>;
-    /** Adds a response interceptor that runs after each request. */
-    withResponseInterceptor(interceptor: IgniterCallerResponseInterceptor): IgniterCallerBuilder<TCaller, TSchemas>;
+    static create(): IgniterCallerBuilder<{}>;
+    /**
+     * Sets the base URL for all requests.
+     *
+     * @param baseURL - Base URL prefix for outgoing requests.
+     */
+    withBaseUrl(baseURL: string): IgniterCallerBuilder<TSchemas>;
+    /**
+     * Merges default headers for all requests.
+     *
+     * @param headers - Header map merged into every request.
+     */
+    withHeaders(headers: Record<string, string>): IgniterCallerBuilder<TSchemas>;
+    /**
+     * Sets default cookies (sent as the `Cookie` header).
+     *
+     * @param cookies - Cookie key/value pairs.
+     */
+    withCookies(cookies: Record<string, string>): IgniterCallerBuilder<TSchemas>;
+    /**
+     * Attaches a logger instance.
+     *
+     * @param logger - Logger implementation from `@igniter-js/common`.
+     */
+    withLogger(logger: IgniterLogger): IgniterCallerBuilder<TSchemas>;
+    /**
+     * Adds a request interceptor that runs before each request.
+     *
+     * @param interceptor - Interceptor called with request options.
+     */
+    withRequestInterceptor(interceptor: IgniterCallerRequestInterceptor): IgniterCallerBuilder<TSchemas>;
+    /**
+     * Adds a response interceptor that runs after each request.
+     *
+     * @param interceptor - Interceptor called with the response result.
+     */
+    withResponseInterceptor(interceptor: IgniterCallerResponseInterceptor): IgniterCallerBuilder<TSchemas>;
     /**
      * Configures a persistent store adapter for caching.
      *
      * When configured, cache operations will use the store (e.g., Redis)
      * instead of in-memory cache, enabling persistent cache across deployments.
+     *
+     * @param store - Store adapter implementation.
+     * @param options - Store options (ttl, keyPrefix, fallback).
      */
-    withStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): IgniterCallerBuilder<TCaller, TSchemas>;
+    withStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): IgniterCallerBuilder<TSchemas>;
     /**
      * Configures schema-based type safety and validation.
      *
      * Enables automatic type inference for requests/responses based on
-     * route and method, with optional runtime validation via Zod.
+     * route and method, with optional runtime validation via StandardSchemaV1
+     * (Zod is supported).
+     *
+     * @param schemas - Schema map keyed by URL path and method.
+     * @param validation - Validation options for request/response checks.
      *
      * @example
      * ```ts
@@ -421,511 +176,217 @@ declare class IgniterCallerBuilder<TCaller = unknown, TSchemas extends IgniterCa
      *   .build()
      * ```
      */
-    withSchemas<TNewSchemas extends IgniterCallerSchemaMap>(schemas: TNewSchemas, validation?: IgniterCallerSchemaValidationOptions): IgniterCallerBuilder<TCaller, TNewSchemas>;
-    /**
-     * Builds the `IgniterCaller` instance.
-     */
-    build(): TCaller;
-}
-
-/**
- * Constructor params for the request builder.
- */
-interface IgniterCallerRequestBuilderParams {
-    baseURL?: string;
-    defaultHeaders?: Record<string, string>;
-    defaultCookies?: Record<string, string>;
-    logger?: IgniterLogger;
-    requestInterceptors?: IgniterCallerRequestInterceptor[];
-    responseInterceptors?: IgniterCallerResponseInterceptor[];
-    eventEmitter?: (url: string, method: string, result: any) => Promise<void>;
-    schemas?: IgniterCallerSchemaMap;
-    schemaValidation?: IgniterCallerSchemaValidationOptions;
-}
-/**
- * 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 retryOptions?;
-    private fallbackFn?;
-    private cacheKey?;
-    private staleTime?;
-    private requestInterceptors?;
-    private responseInterceptors?;
-    private eventEmitter?;
-    private schemas?;
-    private schemaValidation?;
-    private responseTypeSchema?;
-    constructor(params: IgniterCallerRequestBuilderParams);
-    /**
-     * Sets the HTTP method for this request.
-     * @internal Used by IgniterCaller.request() for generic requests.
-     */
-    _setMethod(method: IgniterCallerHttpMethod): this;
+    withSchemas<TNewSchemas extends IgniterCallerSchemaInput>(schemas: TNewSchemas, validation?: IgniterCallerSchemaValidationOptions): IgniterCallerBuilder<IgniterCallerSchemaMapFrom<TNewSchemas>>;
     /**
-     * Sets the URL for this request.
-     * @internal Used when URL is passed to HTTP method directly.
-     */
-    _setUrl(url: string): this;
-    /**
-     * Overrides the logger for this request chain.
-     */
-    withLogger(logger: IgniterLogger): this;
-    /**
-     * Sets the request URL.
-     */
-    url(url: string): this;
-    /**
-     * Sets the request body.
-     * For GET/HEAD requests, body will be automatically converted to query params.
-     */
-    body<TBody>(body: TBody): this;
-    /**
-     * Sets URL query parameters.
-     */
-    params(params: Record<string, string | number | boolean>): this;
-    /**
-     * Merges additional headers into the request.
-     */
-    headers(headers: Record<string, string>): this;
-    /**
-     * Sets request timeout in milliseconds.
-     */
-    timeout(timeout: number): this;
-    /**
-     * Sets cache strategy and optional cache key.
-     */
-    cache(cache: RequestCache, key?: string): this;
-    /**
-     * Configures retry behavior for failed requests.
-     */
-    retry(maxAttempts: number, options?: Omit<IgniterCallerRetryOptions, 'maxAttempts'>): this;
-    /**
-     * Provides a fallback value if the request fails.
-     */
-    fallback<T>(fn: () => T): this;
-    /**
-     * Sets cache stale time in milliseconds.
-     */
-    stale(milliseconds: number): this;
-    /**
-     * Sets the expected response type for TypeScript inference.
+     * Attaches telemetry for request monitoring and observability.
      *
-     * - 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
+     * Telemetry is optional and only emits events when a manager is provided.
      *
-     * The actual parsing is based on Content-Type headers, not this setting.
+     * Telemetry events emitted by the caller package include:
+     * - `request.execute.started`
+     * - `request.execute.success`
+     * - `request.execute.error`
+     * - `request.timeout.error`
+     * - `cache.read.hit`
+     * - `retry.attempt.started`
+     * - `validation.request.error`
+     * - `validation.response.error`
+     *
+     * @param telemetry - Telemetry manager instance.
      *
      * @example
      * ```ts
-     * // With Zod schema (validates JSON response)
-     * const result = await api.get('/users').responseType(UserSchema).execute()
+     * import { IgniterTelemetry } from '@igniter-js/telemetry'
+     * import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry'
+     *
+     * const telemetry = IgniterTelemetry.create()
+     *   .withService('my-api')
+     *   .addEvents(IgniterCallerTelemetryEvents)
+     *   .build()
      *
-     * // With type marker (typing only, no validation)
-     * const result = await api.get('/file').responseType<Blob>().execute()
+     * const api = IgniterCaller.create()
+     *   .withBaseUrl('https://api.example.com')
+     *   .withTelemetry(telemetry)
+     *   .build()
      * ```
      */
-    responseType<T>(schema?: z.ZodSchema<T> | StandardSchemaV1): IgniterCallerRequestBuilder<T>;
+    withTelemetry(telemetry: IgniterTelemetryManager<any>): IgniterCallerBuilder<TSchemas>;
     /**
-     * Downloads a file via GET request.
-     * @deprecated Use `.responseType<File>().execute()` instead. The response type is auto-detected.
-     */
-    getFile(url: string): {
-        execute: () => Promise<IgniterCallerFileResponse>;
-    };
-    /**
-     * Executes the HTTP request.
+     * Enables request mocking using a mock registry.
      *
-     * 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
+     * When enabled, matching requests are routed to the mock handlers instead of fetch.
      *
-     * Schema validation (if configured) only runs for validatable content types (JSON, XML, CSV).
+     * @param config - Mock configuration with registry and enable flag.
      */
-    execute(): Promise<IgniterCallerApiResponse<TResponse>>;
-    private executeWithRetry;
-    private executeSingleRequest;
-    private buildRequest;
+    withMock(config: IgniterCallerMockConfig<TSchemas>): IgniterCallerBuilder<TSchemas>;
     /**
-     * Emits event for this response using injected emitter.
+     * Builds the `IgniterCaller` instance.
+     *
+     * @returns Configured manager instance.
      */
-    private emitEvent;
+    build(): IgniterCallerManager<TSchemas>;
 }
 /**
- * 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.
- * Used when creating requests via HTTP methods with URL that matches a schema.
+ * Main entrypoint for the caller builder.
  *
- * This type ensures that the execute() method returns the correct response type
- * based on the schema map configuration.
+ * @example
+ * ```ts
+ * const api = IgniterCaller.create().withBaseUrl('https://api.example.com').build()
+ * ```
  */
-type IgniterCallerTypedRequestBuilder<TResponse = unknown> = Omit<IgniterCallerRequestBuilder<TResponse>, '_setMethod' | '_setUrl'>;
+declare const IgniterCaller: {
+    create: typeof IgniterCallerBuilder.create;
+};
 
 /**
- * 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).
+ * @fileoverview Path-first schema builder for @igniter-js/caller.
+ * @module @igniter-js/caller/builders/schema-path
  */
-type IgniterCallerUrlPattern = string | RegExp;
 
 /**
- * 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.
+ * Builder for schema methods within a single path.
  */
-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>;
-};
-/**
- * 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 IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
-    /** Global event emitter for observing HTTP responses */
-    private static readonly events;
-    private baseURL?;
-    private headers?;
-    private cookies?;
-    private logger?;
-    private requestInterceptors?;
-    private responseInterceptors?;
-    private schemas?;
-    private schemaValidation?;
-    constructor(baseURL?: string, opts?: {
-        headers?: Record<string, string>;
-        cookies?: Record<string, string>;
-        logger?: IgniterLogger;
-        requestInterceptors?: IgniterCallerRequestInterceptor[];
-        responseInterceptors?: IgniterCallerResponseInterceptor[];
-        schemas?: TSchemas;
-        schemaValidation?: IgniterCallerSchemaValidationOptions;
-    });
-    /**
-     * Canonical initialization entrypoint.
-     *
-     * This is designed to remain stable when extracted to `@igniter-js/caller`.
-     */
-    static create<TInitSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap>(): IgniterCallerBuilder<IgniterCaller<TInitSchemas>, TInitSchemas>;
-    /**
-     * Returns a new client with the same config and a new logger.
-     */
-    withLogger(logger: IgniterLogger): IgniterCaller<TSchemas>;
-    setBaseURL(baseURL: string): this;
-    setHeaders(headers: Record<string, string>): this;
-    setCookies(cookies: Record<string, string>): this;
-    /**
-     * Creates common request builder params.
-     */
-    private createBuilderParams;
-    /**
-     * Resolves the full URL path by prepending baseURL if needed.
-     */
-    private resolveSchemaPath;
-    /**
-     * 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 type is automatically inferred.
-    /**
-     * 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'>>;
+declare class IgniterCallerSchemaPathBuilder<TMethods extends Partial<Record<IgniterCallerSchemaMethod, IgniterCallerEndpointSchema<any, any>>> = {}, TRegistry extends IgniterCallerSchemaRegistry = {}> {
+    private readonly methods;
+    private readonly registry;
+    private constructor();
     /**
-     * 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()
-     * ```
+     * Creates a new path builder for the provided registry.
      */
-    put<TPath extends PutPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'PUT'>;
-    put<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'PUT'>>;
+    static create<TRegistry extends IgniterCallerSchemaRegistry>(registry: TRegistry): IgniterCallerSchemaPathBuilder<{}, TRegistry>;
     /**
-     * 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()
-     * ```
+     * Returns a registry reference helper for a given key.
+     * The helper exposes optional Zod-based wrappers (array/optional/nullable/record).
      */
-    patch<TPath extends PatchPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'PATCH'>;
-    patch<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'PATCH'>>;
+    ref<TKey extends keyof TRegistry>(key: TKey): {
+        schema: TRegistry[TKey];
+        array: () => SchemaArray<TRegistry[TKey]>;
+        nullable: () => SchemaNullable<TRegistry[TKey]>;
+        optional: () => SchemaOptional<TRegistry[TKey]>;
+        record: (keyType?: StandardSchemaV1) => SchemaRecord<TRegistry[TKey]>;
+    };
     /**
-     * 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()
-     * ```
+     * Defines a GET endpoint.
      */
-    delete<TPath extends DeletePaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'DELETE'>;
-    delete<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'DELETE'>>;
+    get<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        GET: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * 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.
+     * Defines a POST endpoint.
      */
-    head<TPath extends HeadPaths<TSchemas>>(url: TPath): TypedRequestBuilder<TSchemas, TPath, 'HEAD'>;
-    head<TPath extends string>(url?: TPath): IgniterCallerTypedRequestBuilder<InferResponse<TSchemas, TPath, 'HEAD'>>;
+    post<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        POST: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * 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.
-     *
-     * @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' },
-     * })
-     * ```
+     * Defines a PUT endpoint.
      */
-    request<T = unknown>(options: IgniterCallerDirectRequestOptions): Promise<IgniterCallerApiResponse<T>>;
+    put<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        PUT: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * Executes multiple requests in parallel and returns results as an array.
-     *
-     * This is useful for batching independent API calls.
+     * Defines a PATCH endpoint.
      */
-    static batch<T extends readonly Promise<IgniterCallerApiResponse<any>>[]>(requests: [...T]): Promise<{
-        [K in keyof T]: T[K] extends Promise<infer R> ? R : never;
-    }>;
+    patch<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        PATCH: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * 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 = IgniterCaller.on(/^\/users/, (result, context) => {
-     *   console.log(`${context.method} ${context.url}`, result)
-     * })
-     *
-     * // Cleanup when done
-     * cleanup()
-     * ```
+     * Defines a DELETE endpoint.
      */
-    static on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
+    delete<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        DELETE: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * Removes event listeners for a pattern.
+     * Defines a HEAD endpoint.
      */
-    static off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
+    head<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        HEAD: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
     /**
-     * Invalidates a specific cache entry.
-     *
-     * This is useful after mutations to ensure fresh data on next fetch.
-     *
-     * @example
-     * ```ts
-     * // After creating a user
-     * await api.post('/users').body(newUser).execute()
-     * await IgniterCaller.invalidate('/users') // Clear users list cache
-     * ```
+     * Builds the accumulated method map for the path.
      */
-    static invalidate(key: string): Promise<void>;
+    build(): TMethods;
+    private addMethod;
+}
+
+/**
+ * @fileoverview Schema builder for @igniter-js/caller.
+ * @module @igniter-js/caller/builders/schema
+ */
+
+/**
+ * Path-first builder for caller schemas with registry support.
+ */
+declare class IgniterCallerSchema<TSchemas extends IgniterCallerSchemaMap = {}, TRegistry extends IgniterCallerSchemaRegistry = {}> {
+    private readonly schemas;
+    private readonly registry;
+    private constructor();
     /**
-     * Invalidates all cache entries matching a pattern.
-     *
-     * @param pattern Glob pattern (e.g., '/users/*') or exact key
-     *
-     * @example
-     * ```ts
-     * // Invalidate all user-related caches
-     * await IgniterCaller.invalidatePattern('/users/*')
-     * ```
+     * Creates a new empty schema builder.
      */
-    static invalidatePattern(pattern: string): Promise<void>;
+    static create(): IgniterCallerSchema<{}, {}>;
     /**
-     * Emits an event to all registered listeners.
-     *
-     * @internal
+     * Registers a reusable schema in the registry.
+     */
+    schema<TKey extends string, TSchema extends StandardSchemaV1>(key: TKey, schema: TSchema, options?: {
+        internal?: boolean;
+    }): IgniterCallerSchema<TSchemas, TRegistry & {
+        [K in TKey]: TSchema;
+    }>;
+    /**
+     * Defines a path with its methods using a fluent builder.
+     */
+    path<TPath extends string, TMethods extends Partial<Record<IgniterCallerSchemaMethod, IgniterCallerEndpointSchema<any, any>>>>(path: TPath, builder: (pathBuilder: IgniterCallerSchemaPathBuilder<{}, TRegistry>) => IgniterCallerSchemaPathBuilder<TMethods, TRegistry>): IgniterCallerSchema<TSchemas & {
+        [K in TPath]: TMethods;
+    }, TRegistry>;
+    /**
+     * Builds the schema map and attaches inference + runtime helpers.
      */
-    static emitEvent(url: string, method: string, result: IgniterCallerApiResponse<any>): Promise<void>;
+    build(): IgniterCallerSchemaBuildResult<TSchemas, TRegistry>;
 }
 
 /**
- * Event emitter for observing HTTP responses across the application.
- *
- * This allows developers to listen to API responses globally for:
- * - Debugging and logging
- * - Real-time monitoring
- * - Cache invalidation triggers
- * - Analytics and telemetry
+ * Builder for typed caller mock registries.
  */
-declare class IgniterCallerEvents {
-    private listeners;
-    private patternListeners;
+declare class IgniterCallerMockBuilder<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
+    private readonly state;
+    private constructor();
     /**
-     * Registers a listener for a specific URL or pattern.
-     *
-     * @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 specific endpoint
-     * const cleanup = api.on('/users', (result) => {
-     *   console.log('Users fetched:', result.data)
-     * })
-     *
-     * // Listen to pattern
-     * api.on(/^\/users\/\d+$/, (result) => {
-     *   console.log('User detail fetched')
-     * })
-     *
-     * // Cleanup when done
-     * cleanup()
-     * ```
+     * Creates a new mock builder.
      */
-    on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
+    static create(): IgniterCallerMockBuilder<{}>;
     /**
-     * Removes a specific listener or all listeners for a pattern.
+     * Sets schemas to enable typed mock definitions.
+     *
+     * @param _schemas - Schema map or build result.
      */
-    off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
+    withSchemas<TNewSchemas extends IgniterCallerSchemaInput>(_schemas: TNewSchemas): IgniterCallerMockBuilder<IgniterCallerSchemaMapFrom<TNewSchemas>>;
     /**
-     * Emits an event to all matching listeners.
+     * Registers mock handlers for a path.
      *
-     * @internal
+     * @param path - Schema path.
+     * @param handlers - Method handlers or static responses.
      */
-    emit(url: string, method: string, result: any): Promise<void>;
+    mock<TPath extends SchemaMapPaths<TSchemas>>(path: TPath, handlers: IgniterCallerMockPathDefinition<TSchemas, TPath>): IgniterCallerMockBuilder<TSchemas>;
     /**
-     * Removes all listeners.
+     * Builds a mock manager instance.
      */
-    clear(): void;
+    build(): IgniterCallerMockManager<TSchemas>;
 }
+/**
+ * Public entrypoint for the mock builder.
+ */
+declare const IgniterCallerMock: {
+    create: typeof IgniterCallerMockBuilder.create;
+};
 
-type IgniterCallerErrorCode = 'IGNITER_CALLER_HTTP_ERROR' | 'IGNITER_CALLER_TIMEOUT' | 'IGNITER_CALLER_REQUEST_VALIDATION_FAILED' | 'IGNITER_CALLER_RESPONSE_VALIDATION_FAILED' | 'IGNITER_CALLER_UNKNOWN_ERROR';
-type IgniterCallerOperation = 'execute' | 'download' | 'buildRequest' | 'parseResponse' | 'validateRequest' | 'validateResponse';
+/**
+ * Stable error codes emitted by `IgniterCaller`.
+ */
+type IgniterCallerErrorCode = 'IGNITER_CALLER_HTTP_ERROR' | 'IGNITER_CALLER_MOCK_HTTP_ERROR' | 'IGNITER_CALLER_TIMEOUT' | 'IGNITER_CALLER_REQUEST_VALIDATION_FAILED' | 'IGNITER_CALLER_RESPONSE_VALIDATION_FAILED' | 'IGNITER_CALLER_SCHEMA_DUPLICATE' | 'IGNITER_CALLER_SCHEMA_INVALID' | 'IGNITER_CALLER_UNKNOWN_ERROR';
+/**
+ * Operation identifiers used to describe where an error happened.
+ */
+type IgniterCallerOperation = 'execute' | 'download' | 'buildRequest' | 'parseResponse' | 'validateRequest' | 'validateResponse' | 'buildSchema';
 /**
  * Payload used to create an {@link IgniterCallerError}.
  */
@@ -945,7 +406,7 @@ type IgniterCallerErrorPayload = {
     /** Arbitrary metadata for debugging. */
     metadata?: Record<string, unknown>;
     /** Optional original cause. */
-    cause?: unknown;
+    cause?: Error;
     /** Optional logger used by IgniterError. */
     logger?: IgniterLogger;
 };
@@ -955,75 +416,47 @@ type IgniterCallerErrorPayload = {
  * Designed to be extracted into `@igniter-js/caller`.
  */
 declare class IgniterCallerError extends IgniterError {
+    /** Machine-readable error code. */
     readonly code: IgniterCallerErrorCode;
+    /** Operation that produced the error. */
     readonly operation: IgniterCallerOperation;
+    /** Optional HTTP status text. */
     readonly statusText?: string;
-    readonly cause?: unknown;
-    constructor(payload: IgniterCallerErrorPayload);
-    static is(error: unknown): error is IgniterCallerError;
-}
-
-declare class IgniterCallerBodyUtils {
+    /** Optional original error cause. */
+    readonly cause?: Error;
     /**
-     * Returns true when the request body should be passed to `fetch` as-is.
+     * Creates a new typed caller error.
+     *
+     * @param payload - Error payload with code, message, and metadata.
      */
-    static isRawBody(body: unknown): boolean;
+    constructor(payload: IgniterCallerErrorPayload);
     /**
-     * Removes Content-Type for FormData so fetch can set boundaries automatically.
+     * Type guard for `IgniterCallerError`.
+     *
+     * @param error - Value to check.
      */
-    static normalizeHeadersForBody(headers: Record<string, string> | undefined, body: unknown): Record<string, string> | undefined;
+    static is(error: unknown): error is IgniterCallerError;
 }
 
 /**
- * Cache interface for HTTP responses.
- *
- * Supports both in-memory caching and persistent store-based caching (Redis, etc).
+ * Body utilities for `IgniterCaller`.
  */
-declare class IgniterCallerCacheUtils {
-    private static cache;
-    private static store;
-    private static storeOptions;
+declare class IgniterCallerBodyUtils {
     /**
-     * Configures a persistent store adapter for caching.
+     * Returns true when the request body should be passed to `fetch` as-is.
      *
-     * When configured, cache operations will use the store (e.g., Redis)
-     * instead of in-memory cache, enabling persistent cache across deployments.
-     */
-    static setStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): void;
-    /**
-     * Gets the configured store adapter.
-     */
-    static getStore(): IgniterCallerStoreAdapter | null;
-    /**
-     * Gets cached data if it exists and is not stale.
-     */
-    static get<T>(key: string, staleTime?: number): Promise<T | undefined>;
-    /**
-     * Stores data in cache with current timestamp.
-     */
-    static set(key: string, data: unknown, ttl?: number): Promise<void>;
-    /**
-     * Clears a specific cache entry.
+     * @param body - Request body to inspect.
+     * @returns True if the body should be sent as raw data.
      */
-    static clear(key: string): Promise<void>;
+    static isRawBody(body: unknown): boolean;
     /**
-     * Clears all cache entries matching a pattern.
+     * Removes Content-Type for FormData so fetch can set boundaries automatically.
      *
-     * @param pattern Glob pattern (e.g., '/users/*') or exact key
-     */
-    static clearPattern(pattern: string): Promise<void>;
-    /**
-     * Clears all cache entries.
+     * @param headers - Request headers map.
+     * @param body - Request body.
+     * @returns Updated headers without Content-Type when needed.
      */
-    static clearAll(): Promise<void>;
-    /**
-     * Adds the configured prefix to a key.
-     */
-    private static getPrefixedKey;
-    /**
-     * Converts a glob pattern to a RegExp.
-     */
-    private static globToRegex;
+    static normalizeHeadersForBody(headers: Record<string, string> | undefined, body: unknown): Record<string, string> | undefined;
 }
 
 /**
@@ -1035,6 +468,10 @@ declare class IgniterCallerSchemaUtils {
     /**
      * Matches a URL path against schema map paths (supports path parameters).
      *
+     * @param actualPath - Incoming request path.
+     * @param schemaPath - Schema path pattern.
+     * @returns Match result with params when matched.
+     *
      * @example
      * ```ts
      * matchPath('/users/123', '/users/:id') // { matched: true, params: { id: '123' } }
@@ -1047,6 +484,11 @@ declare class IgniterCallerSchemaUtils {
     };
     /**
      * Finds the schema for a given path and method from the schema map.
+     *
+     * @param schemaMap - Schema map from the builder.
+     * @param path - Request path to match.
+     * @param method - HTTP method to match.
+     * @returns Matching schema and extracted params.
      */
     static findSchema(schemaMap: IgniterCallerSchemaMap | undefined, path: string, method: string): {
         schema: IgniterCallerEndpointSchema | undefined;
@@ -1057,12 +499,21 @@ declare class IgniterCallerSchemaUtils {
      *
      * If the schema provides `~standard.validate`, it will be used.
      * Otherwise, returns the input as-is.
+     *
+     * @param schema - StandardSchema instance.
+     * @param input - Input value to validate.
+     * @returns Validated input value.
      */
     private static validateWithStandardSchema;
     /**
      * Validates request body against schema.
      *
-     * @returns Validated data or throws/logs error based on validation mode
+     * @param data - Request body data.
+     * @param schema - Request schema (if any).
+     * @param options - Validation options.
+     * @param context - Request context for error reporting.
+     * @param logger - Optional logger instance.
+     * @returns Validated data or throws/logs error based on validation mode.
      */
     static validateRequest<T>(data: unknown, schema: StandardSchemaV1 | undefined, options: IgniterCallerSchemaValidationOptions | undefined, context: {
         url: string;
@@ -1071,7 +522,13 @@ declare class IgniterCallerSchemaUtils {
     /**
      * Validates response data against schema.
      *
-     * @returns Validated data or throws/logs error based on validation mode
+     * @param data - Response payload to validate.
+     * @param schema - Response schema (if any).
+     * @param statusCode - HTTP status code.
+     * @param options - Validation options.
+     * @param context - Request context for error reporting.
+     * @param logger - Optional logger instance.
+     * @returns Validated data or throws/logs error based on validation mode.
      */
     static validateResponse<T>(data: unknown, schema: StandardSchemaV1 | undefined, statusCode: number, options: IgniterCallerSchemaValidationOptions | undefined, context: {
         url: string;
@@ -1079,36 +536,124 @@ declare class IgniterCallerSchemaUtils {
     }, logger?: IgniterLogger): Promise<T>;
 }
 
+/**
+ * URL utilities for `IgniterCaller`.
+ */
+declare class IgniterCallerUrlUtils {
+    /**
+     * Builds a full URL with optional base URL and query parameters.
+     *
+     * @param params - URL construction parameters.
+     * @returns Full URL string.
+     */
+    static buildUrl(params: {
+        url: string;
+        baseURL?: string;
+        query?: Record<string, string | number | boolean>;
+    }): string;
+}
+
+/**
+ * Cache interface for HTTP responses.
+ *
+ * Supports both in-memory caching and persistent store-based caching (Redis, etc).
+ */
+declare class IgniterCallerCacheUtils {
+    private static cache;
+    private static store;
+    private static storeOptions;
+    /**
+     * Configures a persistent store adapter for caching.
+     *
+     * When configured, cache operations will use the store (e.g., Redis)
+     * instead of in-memory cache, enabling persistent cache across deployments.
+     *
+     * @param store - Store adapter implementation.
+     * @param options - Store options such as ttl and key prefix.
+     */
+    static setStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): void;
+    /**
+     * Gets the configured store adapter.
+     *
+     * @returns Store adapter or null when unset.
+     */
+    static getStore(): IgniterCallerStoreAdapter | null;
+    /**
+     * Gets cached data if it exists and is not stale.
+     *
+     * @param key - Cache key (without prefix).
+     * @param staleTime - Optional stale time in milliseconds.
+     * @returns Cached value or undefined when missing/stale.
+     */
+    static get<T>(key: string, staleTime?: number): Promise<T | undefined>;
+    /**
+     * Stores data in cache with current timestamp.
+     *
+     * @param key - Cache key (without prefix).
+     * @param data - Data to cache.
+     * @param ttl - Optional TTL override in seconds.
+     */
+    static set(key: string, data: unknown, ttl?: number): Promise<void>;
+    /**
+     * Clears a specific cache entry.
+     *
+     * @param key - Cache key (without prefix).
+     */
+    static clear(key: string): Promise<void>;
+    /**
+     * Clears all cache entries matching a pattern.
+     *
+     * @param pattern Glob pattern (e.g., '/users/*') or exact key
+     */
+    static clearPattern(pattern: string): Promise<void>;
+    /**
+     * Clears all cache entries.
+     *
+     * @returns Promise that resolves when in-memory cache is cleared.
+     */
+    static clearAll(): Promise<void>;
+    /**
+     * Adds the configured prefix to a key.
+     */
+    private static getPrefixedKey;
+    /**
+     * Converts a glob pattern to a RegExp.
+     */
+    private static globToRegex;
+}
+
 /**
  * Testing utilities for `IgniterCaller`.
  *
  * Designed to simplify mocking HTTP responses in unit tests.
  */
-declare class IgniterCallerMock {
+declare class IgniterCallerHttpMock {
     /**
      * Creates a successful mock response.
+     *
+     * @param data - Mock response data.
      */
     static mockResponse<T>(data: T): IgniterCallerApiResponse<T>;
     /**
      * Creates an error mock response.
+     *
+     * @param code - Error code to use.
+     * @param message - Optional error message.
      */
     static mockError<T = never>(code: IgniterCallerErrorCode, message?: string): IgniterCallerApiResponse<T>;
     /**
      * Creates a successful file download mock.
+     *
+     * @param filename - File name for the mock.
+     * @param content - File contents as string or Blob.
      */
     static mockFile(filename: string, content: string | Blob): IgniterCallerFileResponse;
     /**
      * Creates a failed file download mock.
+     *
+     * @param message - Optional error message.
      */
     static mockFileError(message?: string): IgniterCallerFileResponse;
 }
 
-declare class IgniterCallerUrlUtils {
-    static buildUrl(params: {
-        url: string;
-        baseURL?: string;
-        query?: Record<string, string | number | boolean>;
-    }): string;
-}
-
-export { type DeletePaths, type EndpointInfo, type ExtractPathParams, type GetPaths, type HeadPaths, IgniterCaller, type IgniterCallerApiResponse, type IgniterCallerBaseRequestOptions, IgniterCallerBodyUtils, IgniterCallerBuilder, type IgniterCallerBuilderFactory, type IgniterCallerBuilderState, IgniterCallerCacheUtils, type IgniterCallerDirectRequestOptions, type IgniterCallerEndpointSchema, IgniterCallerError, type IgniterCallerErrorCode, type IgniterCallerErrorPayload, type IgniterCallerEventCallback, IgniterCallerEvents, type IgniterCallerFileResponse, type IgniterCallerHttpMethod, type IgniterCallerMethodRequestBuilder, IgniterCallerMock, type IgniterCallerOperation, IgniterCallerRequestBuilder, type IgniterCallerRequestBuilderParams, type IgniterCallerRequestInterceptor, type IgniterCallerRequestOptions, type IgniterCallerResponseContentType, type IgniterCallerResponseInterceptor, type IgniterCallerResponseMarker, type IgniterCallerRetryOptions, type IgniterCallerSchemaMap, type IgniterCallerSchemaMethod, IgniterCallerSchemaUtils, type IgniterCallerSchemaValidationOptions, type IgniterCallerStoreAdapter, type IgniterCallerStoreOptions, type IgniterCallerTypedRequestBuilder, type IgniterCallerUrlPattern, IgniterCallerUrlUtils, type IgniterCallerValidatableContentType, type InferAllResponseTypes, type InferRequestType, type InferResponseType, type InferSuccessResponseType, type PatchPaths, type PathsForMethod, type PostPaths, type PutPaths, type ReplaceCallerSchema, type SchemaMapEndpoint, type SchemaMapMethods, type SchemaMapPaths, type SchemaMapRequestType, type SchemaMapResponseType, type TypedRequestBuilder };
+export { IIgniterCallerMockManager, IgniterCaller, IgniterCallerApiResponse, IgniterCallerBodyUtils, IgniterCallerBuilder, IgniterCallerCacheUtils, IgniterCallerEndpointSchema, IgniterCallerError, type IgniterCallerErrorCode, type IgniterCallerErrorPayload, IgniterCallerEventCallback, IgniterCallerEvents, IgniterCallerFileResponse, IgniterCallerHttpMock, IgniterCallerManager, IgniterCallerMock, IgniterCallerMockBuilder, IgniterCallerMockConfig, IgniterCallerMockManager, IgniterCallerMockPathDefinition, IgniterCallerMockRegistry, IgniterCallerMockResolvedHandler, type IgniterCallerOperation, IgniterCallerRequestInterceptor, IgniterCallerResponseInterceptor, IgniterCallerSchema, IgniterCallerSchemaBuildResult, IgniterCallerSchemaEndpointConfig, IgniterCallerSchemaInput, IgniterCallerSchemaMap, IgniterCallerSchemaMapFrom, IgniterCallerSchemaMethod, IgniterCallerSchemaPathBuilder, IgniterCallerSchemaRegistry, IgniterCallerSchemaUtils, IgniterCallerSchemaValidationOptions, IgniterCallerStoreAdapter, IgniterCallerStoreOptions, IgniterCallerUrlPattern, IgniterCallerUrlUtils, SchemaArray, SchemaMapPaths, SchemaNullable, SchemaOptional, SchemaRecord };