@igniter-js/caller 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -1,5 +1,8 @@
-import { StandardSchemaV1, IgniterLogger, IgniterError } from '@igniter-js/core';
+import { StandardSchemaV1, IgniterError, IgniterLogger } from '@igniter-js/core';
+import { IgniterTelemetryManager } from '@igniter-js/telemetry';
 import { z } from 'zod';
+import { I as IgniterCallerStoreAdapter, a as IgniterCallerStoreOptions } from './index-COZVROi_.js';
+export { M as MockCallerStoreAdapter } from './index-COZVROi_.js';
 
 /**
  * Supported HTTP methods for `IgniterCaller` requests.
@@ -42,7 +45,7 @@ interface IgniterCallerRequestOptions<TBody = unknown> extends IgniterCallerBase
     url: string;
     body?: TBody;
     params?: Record<string, string | number | boolean>;
-    responseSchema?: z.ZodSchema<any>;
+    responseSchema?: z.ZodSchema<any> | StandardSchemaV1;
     cache?: RequestCache;
 }
 /**
@@ -60,8 +63,8 @@ interface IgniterCallerDirectRequestOptions<TBody = unknown> extends IgniterCall
     params?: Record<string, string | number | boolean>;
     /** Cookies to send with the request */
     cookies?: Record<string, string>;
-    /** Response validation schema (Zod) */
-    responseSchema?: z.ZodSchema<any>;
+    /** Response validation schema (Zod or any StandardSchemaV1 implementation) */
+    responseSchema?: z.ZodSchema<any> | StandardSchemaV1;
     /** Cache strategy */
     cache?: RequestCache;
     /** Cache key for stale-while-revalidate */
@@ -78,8 +81,10 @@ interface IgniterCallerDirectRequestOptions<TBody = unknown> extends IgniterCall
  * Response object containing either successful data or an error.
  */
 interface IgniterCallerApiResponse<T> {
+    /** Parsed response data when the request succeeds. */
     data?: T;
-    error?: Error;
+    /** Error instance when the request fails. */
+    error?: IgniterError;
     /** HTTP status code from the response */
     status?: number;
     /** Response headers */
@@ -90,7 +95,9 @@ interface IgniterCallerApiResponse<T> {
  * @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;
 }
 /**
@@ -125,11 +132,17 @@ type IgniterCallerSchemaMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | '
  *
  * Maps status codes to response schemas with optional request schema.
  */
-type IgniterCallerEndpointSchema<TRequest extends StandardSchemaV1 = any, TResponses extends Record<number, StandardSchemaV1> = Record<number, StandardSchemaV1>> = {
+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.
@@ -166,6 +179,10 @@ type IgniterCallerEndpointSchema<TRequest extends StandardSchemaV1 = any, TRespo
  * ```
  */
 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.
  *
@@ -187,15 +204,15 @@ type InferRequestType<T> = T extends IgniterCallerEndpointSchema<infer R, any> ?
 /**
  * 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;
+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> ? 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;
+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, StandardSchemaV1> ? {
+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]>;
@@ -246,7 +263,7 @@ type SchemaMapEndpoint<TSchemas extends IgniterCallerSchemaMap, TPath extends ke
 /**
  * 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;
+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.
  */
@@ -289,159 +306,6 @@ interface IgniterCallerSchemaValidationOptions {
     }) => void;
 }
 
-/**
- * Store adapter interface compatible with Igniter.js Store.
- *
- * This allows IgniterCaller to use any store implementation (Redis, in-memory, etc.)
- * for persistent caching across requests and deployments.
- */
-interface IgniterCallerStoreAdapter<TClient = any> {
-    /** The underlying client instance (e.g., Redis client). */
-    readonly client: TClient;
-    /**
-     * Retrieves a value from the store by its key.
-     * @param key The key to retrieve.
-     * @returns The value if found (auto-deserialized), otherwise null.
-     */
-    get<T = any>(key: string): Promise<T | null>;
-    /**
-     * 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.
-     */
-    set(key: string, value: any, options?: {
-        ttl?: number;
-        [key: string]: any;
-    }): Promise<void>;
-    /**
-     * Deletes a key from the store.
-     * @param key The key to delete.
-     */
-    delete(key: string): Promise<void>;
-    /**
-     * Checks if a key exists in the store.
-     * @param key The key to check.
-     * @returns `true` if the key exists, otherwise `false`.
-     */
-    has(key: string): Promise<boolean>;
-}
-/**
- * Configuration options for store-based caching.
- */
-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;
-}
-
-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> {
-    private readonly state;
-    private readonly factory;
-    private constructor();
-    /**
-     * Creates a new builder instance.
-     */
-    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>;
-    /**
-     * 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.
-     */
-    withStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): IgniterCallerBuilder<TCaller, 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.
-     *
-     * @example
-     * ```ts
-     * const api = IgniterCaller.create()
-     *   .withSchemas({
-     *     '/users': {
-     *       GET: {
-     *         responses: {
-     *           200: z.array(UserSchema),
-     *           401: ErrorSchema,
-     *         },
-     *       },
-     *       POST: {
-     *         request: CreateUserSchema,
-     *         responses: {
-     *           201: UserSchema,
-     *           400: ValidationErrorSchema,
-     *         },
-     *       },
-     *     },
-     *   })
-     *   .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`.
  *
@@ -451,6 +315,7 @@ interface IgniterCallerRequestBuilderParams {
 declare class IgniterCallerRequestBuilder<TResponse = unknown> {
     private options;
     private logger?;
+    private telemetry?;
     private retryOptions?;
     private fallbackFn?;
     private cacheKey?;
@@ -461,56 +326,87 @@ declare class IgniterCallerRequestBuilder<TResponse = unknown> {
     private schemas?;
     private schemaValidation?;
     private responseTypeSchema?;
+    /**
+     * 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/core`.
      */
     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;
     /**
@@ -521,6 +417,8 @@ declare class IgniterCallerRequestBuilder<TResponse = unknown> {
      *
      * 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)
@@ -534,6 +432,8 @@ declare class IgniterCallerRequestBuilder<TResponse = unknown> {
     /**
      * 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>;
@@ -550,29 +450,86 @@ declare class IgniterCallerRequestBuilder<TResponse = unknown> {
      * - `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;
     /**
      * 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;
+};
+/**
+ * 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;
+}
 /**
  * Request builder type without internal methods.
- * Used when creating requests via specific HTTP methods (get, post, etc.)
+ * Used when creating requests via specific HTTP methods (get, post, etc.).
  */
-type IgniterCallerMethodRequestBuilder<TResponse = unknown> = Omit<IgniterCallerRequestBuilder<TResponse>, '_setMethod' | '_setUrl'>;
+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.
- *
- * This type ensures that the execute() method returns the correct response type
- * based on the schema map configuration.
  */
-type IgniterCallerTypedRequestBuilder<TResponse = unknown> = Omit<IgniterCallerRequestBuilder<TResponse>, '_setMethod' | '_setUrl'>;
+type IgniterCallerTypedRequestBuilder<TResponse = unknown> = IgniterCallerMethodRequestBuilder<TResponse>;
 
 /**
  * Callback function for event listeners.
@@ -587,6 +544,11 @@ type IgniterCallerEventCallback<T = any> = (result: IgniterCallerApiResponse<T>,
  */
 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).
  */
@@ -603,16 +565,83 @@ type InferResponse<TSchemas extends IgniterCallerSchemaMap, TPath extends string
 /**
  * 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'> & {
+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>;
+    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>;
+    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.
  *
@@ -621,47 +650,38 @@ type TypedRequestBuilder<TSchemas extends IgniterCallerSchemaMap, TPath extends
  *
  * @template TSchemas - The schema map type for type-safe requests/responses.
  */
-declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
+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?;
+    /**
+     * 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;
     });
-    /**
-     * 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.
      *
@@ -685,10 +705,6 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      */
     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.
      *
@@ -776,6 +792,9 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      * 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({
@@ -806,6 +825,9 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      * 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;
@@ -826,7 +848,7 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      * @example
      * ```ts
      * // Listen to all user endpoints
-     * const cleanup = IgniterCaller.on(/^\/users/, (result, context) => {
+     * const cleanup = IgniterCallerManager.on(/^\/users/, (result, context) => {
      *   console.log(`${context.method} ${context.url}`, result)
      * })
      *
@@ -837,6 +859,9 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
     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;
     /**
@@ -844,11 +869,13 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      *
      * 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 IgniterCaller.invalidate('/users') // Clear users list cache
+     * await IgniterCallerManager.invalidate('/users') // Clear users list cache
      * ```
      */
     static invalidate(key: string): Promise<void>;
@@ -856,11 +883,12 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      * 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 IgniterCaller.invalidatePattern('/users/*')
+     * await IgniterCallerManager.invalidatePattern('/users/*')
      * ```
      */
     static invalidatePattern(pattern: string): Promise<void>;
@@ -868,6 +896,10 @@ declare class IgniterCaller<TSchemas extends IgniterCallerSchemaMap = IgniterCal
      * 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>;
 }
@@ -910,120 +942,450 @@ declare class IgniterCallerEvents {
     on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
     /**
      * Removes a specific listener or all listeners for a pattern.
+     *
+     * @param pattern - URL string or RegExp pattern.
+     * @param callback - Optional specific callback to remove.
      */
     off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
     /**
      * Emits an event to all matching listeners.
      *
      * @internal
+     *
+     * @param url - Request URL to match listeners against.
+     * @param method - HTTP method.
+     * @param result - Response envelope.
      */
     emit(url: string, method: string, result: any): Promise<void>;
     /**
      * Removes all listeners.
+     *
+     * @returns Nothing.
      */
     clear(): void;
 }
 
-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';
 /**
- * Payload used to create an {@link IgniterCallerError}.
+ * @fileoverview Schema builder helper types for @igniter-js/caller.
+ * @module @igniter-js/caller/types/schema-builder
  */
-type IgniterCallerErrorPayload = {
-    /** Machine-readable error code. */
-    code: IgniterCallerErrorCode;
-    /** Where the error happened. */
-    operation: IgniterCallerOperation;
-    /** Human-readable message. */
-    message: string;
-    /** Optional HTTP status code when surfacing errors through HTTP boundaries. */
-    statusCode?: number;
-    /** Optional HTTP status text (when available). */
-    statusText?: string;
-    /** Extra diagnostic details (e.g. response body or schema issues). */
-    details?: unknown;
-    /** Arbitrary metadata for debugging. */
-    metadata?: Record<string, unknown>;
-    /** Optional original cause. */
-    cause?: unknown;
-    /** Optional logger used by IgniterError. */
-    logger?: IgniterLogger;
-};
+
 /**
- * Typed error for predictable failures in `IgniterCaller`.
- *
- * Designed to be extracted into `@igniter-js/caller`.
+ * Registry of reusable schemas keyed by name.
  */
-declare class IgniterCallerError extends IgniterError {
-    readonly code: IgniterCallerErrorCode;
-    readonly operation: IgniterCallerOperation;
-    readonly statusText?: string;
-    readonly cause?: unknown;
-    constructor(payload: IgniterCallerErrorPayload);
-    static is(error: unknown): error is IgniterCallerError;
-}
-
-declare class IgniterCallerBodyUtils {
-    /**
-     * Returns true when the request body should be passed to `fetch` as-is.
-     */
-    static isRawBody(body: unknown): boolean;
-    /**
-     * Removes Content-Type for FormData so fetch can set boundaries automatically.
-     */
-    static normalizeHeadersForBody(headers: Record<string, string> | undefined, body: unknown): Record<string, string> | undefined;
-}
-
+type IgniterCallerSchemaRegistry = Record<string, StandardSchemaV1>;
 /**
- * Cache interface for HTTP responses.
- *
- * Supports both in-memory caching and persistent store-based caching (Redis, etc).
+ * Configuration payload for a single endpoint method in the schema builder.
  */
-declare class IgniterCallerCacheUtils {
-    private static cache;
-    private static store;
-    private static storeOptions;
+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;
+
+/**
+ * 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<TSchemas extends IgniterCallerSchemaMap = IgniterCallerSchemaMap> {
+    private readonly state;
+    private constructor();
+    /**
+     * Creates a new builder instance.
+     *
+     * @returns New builder instance with empty state.
+     */
+    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/core`.
+     */
+    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).
      */
-    static setStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): void;
+    withStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): IgniterCallerBuilder<TSchemas>;
     /**
-     * Gets the configured store adapter.
+     * Configures schema-based type safety and validation.
+     *
+     * Enables automatic type inference for requests/responses based on
+     * 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
+     * const api = IgniterCaller.create()
+     *   .withSchemas({
+     *     '/users': {
+     *       GET: {
+     *         responses: {
+     *           200: z.array(UserSchema),
+     *           401: ErrorSchema,
+     *         },
+     *       },
+     *       POST: {
+     *         request: CreateUserSchema,
+     *         responses: {
+     *           201: UserSchema,
+     *           400: ValidationErrorSchema,
+     *         },
+     *       },
+     *     },
+     *   })
+     *   .build()
+     * ```
      */
-    static getStore(): IgniterCallerStoreAdapter | null;
+    withSchemas<TNewSchemas extends IgniterCallerSchemaInput>(schemas: TNewSchemas, validation?: IgniterCallerSchemaValidationOptions): IgniterCallerBuilder<IgniterCallerSchemaMapFrom<TNewSchemas>>;
     /**
-     * Gets cached data if it exists and is not stale.
+     * Attaches telemetry for request monitoring and observability.
+     *
+     * Telemetry is optional and only emits events when a manager is provided.
+     *
+     * 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
+     * import { IgniterTelemetry } from '@igniter-js/telemetry'
+     * import { IgniterCallerTelemetryEvents } from '@igniter-js/caller/telemetry'
+     *
+     * const telemetry = IgniterTelemetry.create()
+     *   .withService('my-api')
+     *   .addEvents(IgniterCallerTelemetryEvents)
+     *   .build()
+     *
+     * const api = IgniterCaller.create()
+     *   .withBaseUrl('https://api.example.com')
+     *   .withTelemetry(telemetry)
+     *   .build()
+     * ```
      */
-    static get<T>(key: string, staleTime?: number): Promise<T | undefined>;
+    withTelemetry(telemetry: IgniterTelemetryManager<any>): IgniterCallerBuilder<TSchemas>;
     /**
-     * Stores data in cache with current timestamp.
+     * Builds the `IgniterCaller` instance.
+     *
+     * @returns Configured manager instance.
      */
-    static set(key: string, data: unknown, ttl?: number): Promise<void>;
+    build(): IgniterCallerManager<TSchemas>;
+}
+/**
+ * Main entrypoint for the caller builder.
+ *
+ * @example
+ * ```ts
+ * const api = IgniterCaller.create().withBaseUrl('https://api.example.com').build()
+ * ```
+ */
+declare const IgniterCaller: {
+    create: typeof IgniterCallerBuilder.create;
+};
+
+/**
+ * @fileoverview Path-first schema builder for @igniter-js/caller.
+ * @module @igniter-js/caller/builders/schema-path
+ */
+
+/**
+ * Builder for schema methods within a single path.
+ */
+declare class IgniterCallerSchemaPathBuilder<TMethods extends Partial<Record<IgniterCallerSchemaMethod, IgniterCallerEndpointSchema<any, any>>> = {}, TRegistry extends IgniterCallerSchemaRegistry = {}> {
+    private readonly methods;
+    private readonly registry;
+    private constructor();
     /**
-     * Clears a specific cache entry.
+     * Creates a new path builder for the provided registry.
      */
-    static clear(key: string): Promise<void>;
+    static create<TRegistry extends IgniterCallerSchemaRegistry>(registry: TRegistry): IgniterCallerSchemaPathBuilder<{}, TRegistry>;
     /**
-     * Clears all cache entries matching a pattern.
+     * Returns a registry reference helper for a given key.
+     * The helper exposes optional Zod-based wrappers (array/optional/nullable/record).
+     */
+    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]>;
+    };
+    /**
+     * Defines a GET endpoint.
+     */
+    get<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        GET: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Defines a POST endpoint.
+     */
+    post<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        POST: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Defines a PUT endpoint.
+     */
+    put<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        PUT: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Defines a PATCH endpoint.
+     */
+    patch<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        PATCH: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Defines a DELETE endpoint.
+     */
+    delete<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        DELETE: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Defines a HEAD endpoint.
+     */
+    head<TRequest extends StandardSchemaV1 | undefined, TResponses extends Record<number | string, StandardSchemaV1>>(config: IgniterCallerSchemaEndpointConfig<TRequest, TResponses>): IgniterCallerSchemaPathBuilder<TMethods & {
+        HEAD: IgniterCallerEndpointSchema<TRequest, TResponses>;
+    }, TRegistry>;
+    /**
+     * Builds the accumulated method map for the path.
+     */
+    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();
+    /**
+     * Creates a new empty schema builder.
+     */
+    static create(): IgniterCallerSchema<{}, {}>;
+    /**
+     * 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.
+     */
+    build(): IgniterCallerSchemaBuildResult<TSchemas, TRegistry>;
+}
+
+/**
+ * Stable error codes emitted by `IgniterCaller`.
+ */
+type IgniterCallerErrorCode = 'IGNITER_CALLER_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}.
+ */
+type IgniterCallerErrorPayload = {
+    /** Machine-readable error code. */
+    code: IgniterCallerErrorCode;
+    /** Where the error happened. */
+    operation: IgniterCallerOperation;
+    /** Human-readable message. */
+    message: string;
+    /** Optional HTTP status code when surfacing errors through HTTP boundaries. */
+    statusCode?: number;
+    /** Optional HTTP status text (when available). */
+    statusText?: string;
+    /** Extra diagnostic details (e.g. response body or schema issues). */
+    details?: unknown;
+    /** Arbitrary metadata for debugging. */
+    metadata?: Record<string, unknown>;
+    /** Optional original cause. */
+    cause?: Error;
+    /** Optional logger used by IgniterError. */
+    logger?: IgniterLogger;
+};
+/**
+ * Typed error for predictable failures in `IgniterCaller`.
+ *
+ * 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;
+    /** Optional original error cause. */
+    readonly cause?: Error;
+    /**
+     * Creates a new typed caller error.
      *
-     * @param pattern Glob pattern (e.g., '/users/*') or exact key
+     * @param payload - Error payload with code, message, and metadata.
      */
-    static clearPattern(pattern: string): Promise<void>;
+    constructor(payload: IgniterCallerErrorPayload);
     /**
-     * Clears all cache entries.
+     * Type guard for `IgniterCallerError`.
+     *
+     * @param error - Value to check.
      */
-    static clearAll(): Promise<void>;
+    static is(error: unknown): error is IgniterCallerError;
+}
+
+/**
+ * Body utilities for `IgniterCaller`.
+ */
+declare class IgniterCallerBodyUtils {
     /**
-     * Adds the configured prefix to a key.
+     * Returns true when the request body should be passed to `fetch` as-is.
+     *
+     * @param body - Request body to inspect.
+     * @returns True if the body should be sent as raw data.
      */
-    private static getPrefixedKey;
+    static isRawBody(body: unknown): boolean;
     /**
-     * Converts a glob pattern to a RegExp.
+     * Removes Content-Type for FormData so fetch can set boundaries automatically.
+     *
+     * @param headers - Request headers map.
+     * @param body - Request body.
+     * @returns Updated headers without Content-Type when needed.
      */
-    private static globToRegex;
+    static normalizeHeadersForBody(headers: Record<string, string> | undefined, body: unknown): Record<string, string> | undefined;
 }
 
 /**
@@ -1035,6 +1397,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 +1413,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 +1428,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 +1451,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,6 +1465,92 @@ 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`.
  *
@@ -1087,28 +1559,30 @@ declare class IgniterCallerSchemaUtils {
 declare class IgniterCallerMock {
     /**
      * 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 { type DeletePaths, type EndpointInfo, type ExtractPathParams, type GetEndpoint, type GetPaths, type HeadPaths, type IIgniterCallerManager, IgniterCaller, type IgniterCallerApiResponse, type IgniterCallerBaseRequestOptions, IgniterCallerBodyUtils, IgniterCallerBuilder, type IgniterCallerBuilderState, IgniterCallerCacheUtils, type IgniterCallerDirectRequestOptions, type IgniterCallerEndpointSchema, IgniterCallerError, type IgniterCallerErrorCode, type IgniterCallerErrorPayload, type IgniterCallerEventCallback, IgniterCallerEvents, type IgniterCallerFileResponse, type IgniterCallerHttpMethod, IgniterCallerManager, type IgniterCallerMethodRequestBuilder, IgniterCallerMock, type IgniterCallerOperation, IgniterCallerRequestBuilder, type IgniterCallerRequestBuilderParams, type IgniterCallerRequestInterceptor, type IgniterCallerRequestOptions, type IgniterCallerResponseContentType, type IgniterCallerResponseInterceptor, type IgniterCallerResponseMarker, type IgniterCallerRetryOptions, IgniterCallerSchema, type IgniterCallerSchemaBuildResult, type IgniterCallerSchemaEndpointConfig, type IgniterCallerSchemaGetters, type IgniterCallerSchemaInfer, type IgniterCallerSchemaInput, type IgniterCallerSchemaMap, type IgniterCallerSchemaMapFrom, type IgniterCallerSchemaMethod, IgniterCallerSchemaPathBuilder, type IgniterCallerSchemaRegistry, IgniterCallerSchemaUtils, type IgniterCallerSchemaValidationOptions, IgniterCallerStoreAdapter, IgniterCallerStoreOptions, type IgniterCallerTypedRequestBuilder, type IgniterCallerUrlPattern, IgniterCallerUrlUtils, type IgniterCallerValidatableContentType, type InferAllResponseTypes, type InferRequestType, type InferResponse, type InferResponseType, type InferSuccessResponse, type InferSuccessResponseType, type PatchPaths, type PathsForMethod, type PostPaths, type PutPaths, type ResolveStatusKey, type SchemaArray, type SchemaMapEndpoint, type SchemaMapMethods, type SchemaMapPaths, type SchemaMapRequestSchema, type SchemaMapRequestType, type SchemaMapResponseSchema, type SchemaMapResponseType, type SchemaMapResponses, type SchemaMapResponsesType, type SchemaNullable, type SchemaOptional, type SchemaRecord, type TypedRequestBuilder };