@igniter-js/caller 0.1.3 → 0.1.5

package/dist/index.mjs

@@ -1,110 +1,13 @@
-import { IgniterError } from '@igniter-js/core';
+import { IgniterError } from '@igniter-js/common';
+import { z } from 'zod';
 
-// src/builder/igniter-caller.builder.ts
-var IgniterCallerBuilder = class _IgniterCallerBuilder {
-  constructor(state, factory) {
-    this.state = state;
-    this.factory = factory;
-  }
-  /**
-   * Creates a new builder instance.
-   */
-  static create(factory) {
-    return new _IgniterCallerBuilder({}, factory);
-  }
-  /** Sets the base URL for all requests. */
-  withBaseUrl(baseURL) {
-    return new _IgniterCallerBuilder({ ...this.state, baseURL }, this.factory);
-  }
-  /** Merges default headers for all requests. */
-  withHeaders(headers) {
-    return new _IgniterCallerBuilder({ ...this.state, headers }, this.factory);
-  }
-  /** Sets default cookies (sent as the `Cookie` header). */
-  withCookies(cookies) {
-    return new _IgniterCallerBuilder({ ...this.state, cookies }, this.factory);
-  }
-  /** Attaches a logger instance. */
-  withLogger(logger) {
-    return new _IgniterCallerBuilder({ ...this.state, logger }, this.factory);
-  }
-  /** Adds a request interceptor that runs before each request. */
-  withRequestInterceptor(interceptor) {
-    const requestInterceptors = [
-      ...this.state.requestInterceptors || [],
-      interceptor
-    ];
-    return new _IgniterCallerBuilder(
-      { ...this.state, requestInterceptors },
-      this.factory
-    );
-  }
-  /** Adds a response interceptor that runs after each request. */
-  withResponseInterceptor(interceptor) {
-    const responseInterceptors = [
-      ...this.state.responseInterceptors || [],
-      interceptor
-    ];
-    return new _IgniterCallerBuilder(
-      { ...this.state, responseInterceptors },
-      this.factory
-    );
-  }
-  /**
-   * 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, options) {
-    return new _IgniterCallerBuilder(
-      { ...this.state, store, storeOptions: options },
-      this.factory
-    );
-  }
+// src/errors/caller.error.ts
+var IgniterCallerError = class _IgniterCallerError extends IgniterError {
   /**
-   * Configures schema-based type safety and validation.
+   * Creates a new typed caller error.
    *
-   * 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()
-   * ```
+   * @param payload - Error payload with code, message, and metadata.
    */
-  withSchemas(schemas, validation) {
-    return new _IgniterCallerBuilder(
-      { ...this.state, schemas, schemaValidation: validation },
-      this.factory
-    );
-  }
-  /**
-   * Builds the `IgniterCaller` instance.
-   */
-  build() {
-    return this.factory(this.state);
-  }
-};
-var IgniterCallerError = class _IgniterCallerError extends IgniterError {
   constructor(payload) {
     const metadata = {
       ...payload.metadata,
@@ -119,13 +22,19 @@ var IgniterCallerError = class _IgniterCallerError extends IgniterError {
       causer: "@igniter-js/caller",
       details,
       metadata,
-      logger: payload.logger
+      logger: payload.logger,
+      cause: payload.cause
     });
     this.name = "IgniterCallerError";
     this.operation = payload.operation;
     this.statusText = payload.statusText;
     this.cause = payload.cause;
   }
+  /**
+   * Type guard for `IgniterCallerError`.
+   *
+   * @param error - Value to check.
+   */
   static is(error) {
     return error instanceof _IgniterCallerError;
   }
@@ -135,6 +44,9 @@ var IgniterCallerError = class _IgniterCallerError extends IgniterError {
 var IgniterCallerBodyUtils = class {
   /**
    * 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.
    */
   static isRawBody(body) {
     if (!body) return false;
@@ -153,6 +65,10 @@ var IgniterCallerBodyUtils = class {
   }
   /**
    * 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.
    */
   static normalizeHeadersForBody(headers, body) {
     if (!headers) return headers;
@@ -171,6 +87,9 @@ var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
    *
    * 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, options) {
     _IgniterCallerCacheUtils.store = store;
@@ -183,12 +102,18 @@ var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
   }
   /**
    * Gets the configured store adapter.
+   *
+   * @returns Store adapter or null when unset.
    */
   static getStore() {
     return _IgniterCallerCacheUtils.store;
   }
   /**
    * 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 async get(key, staleTime) {
     const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
@@ -212,6 +137,10 @@ var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
   }
   /**
    * 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 async set(key, data, ttl) {
     const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
@@ -233,6 +162,8 @@ var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
   }
   /**
    * Clears a specific cache entry.
+   *
+   * @param key - Cache key (without prefix).
    */
   static async clear(key) {
     const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
@@ -266,6 +197,8 @@ var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
   }
   /**
    * Clears all cache entries.
+   *
+   * @returns Promise that resolves when in-memory cache is cleared.
    */
   static async clearAll() {
     _IgniterCallerCacheUtils.cache.clear();
@@ -304,6 +237,10 @@ var IgniterCallerSchemaUtils = 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' } }
@@ -332,6 +269,11 @@ var IgniterCallerSchemaUtils = 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, path, method) {
     if (!schemaMap) {
@@ -357,6 +299,10 @@ var IgniterCallerSchemaUtils = 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.
    */
   static async validateWithStandardSchema(schema, input) {
     const standard = schema?.["~standard"];
@@ -375,7 +321,12 @@ var IgniterCallerSchemaUtils = class _IgniterCallerSchemaUtils {
   /**
    * 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 async validateRequest(data, schema, options, context, logger) {
     if (!schema || options?.mode === "off") {
@@ -408,7 +359,13 @@ var IgniterCallerSchemaUtils = 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 async validateResponse(data, schema, statusCode, options, context, logger) {
     if (!schema || options?.mode === "off") {
@@ -443,6 +400,12 @@ var IgniterCallerSchemaUtils = class _IgniterCallerSchemaUtils {
 
 // src/utils/url.ts
 var IgniterCallerUrlUtils = class {
+  /**
+   * Builds a full URL with optional base URL and query parameters.
+   *
+   * @param params - URL construction parameters.
+   * @returns Full URL string.
+   */
   static buildUrl(params) {
     const { url, baseURL, query } = params;
     let fullUrl = url;
@@ -459,7 +422,7 @@ var IgniterCallerUrlUtils = class {
   }
 };
 
-// src/builder/igniter-caller-request.builder.ts
+// src/builders/request.builder.ts
 var VALIDATABLE_CONTENT_TYPES = [
   "json",
   "xml",
@@ -507,6 +470,11 @@ async function parseResponseByContentType(response, contentType) {
   }
 }
 var IgniterCallerRequestBuilder = class {
+  /**
+   * Creates a new request builder instance.
+   *
+   * @param params - Builder configuration from the manager.
+   */
   constructor(params) {
     this.options = {
       method: "GET",
@@ -529,15 +497,19 @@ var IgniterCallerRequestBuilder = class {
       this.options.headers = { ...this.options.headers, Cookie: cookieStr };
     }
     this.logger = params.logger;
+    this.telemetry = params.telemetry;
     this.requestInterceptors = params.requestInterceptors;
     this.responseInterceptors = params.responseInterceptors;
     this.eventEmitter = params.eventEmitter;
     this.schemas = params.schemas;
     this.schemaValidation = params.schemaValidation;
+    this.mock = params.mock;
   }
   /**
    * Sets the HTTP method for this request.
    * @internal Used by IgniterCaller.request() for generic requests.
+   *
+   * @param method - HTTP method for the request.
    */
   _setMethod(method) {
     this.options.method = method;
@@ -546,6 +518,8 @@ var IgniterCallerRequestBuilder = class {
   /**
    * Sets the URL for this request.
    * @internal Used when URL is passed to HTTP method directly.
+   *
+   * @param url - Request URL or path.
    */
   _setUrl(url) {
     this.options.url = url;
@@ -553,6 +527,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Overrides the logger for this request chain.
+   *
+   * @param logger - Logger implementation from `@igniter-js/common`.
    */
   withLogger(logger) {
     this.logger = logger;
@@ -560,6 +536,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Sets the request URL.
+   *
+   * @param url - Request URL or path.
    */
   url(url) {
     this.options.url = url;
@@ -568,6 +546,8 @@ var IgniterCallerRequestBuilder = class {
   /**
    * Sets the request body.
    * For GET/HEAD requests, body will be automatically converted to query params.
+   *
+   * @param body - Body payload for the request.
    */
   body(body) {
     this.options.body = body;
@@ -575,6 +555,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Sets URL query parameters.
+   *
+   * @param params - Query string parameters.
    */
   params(params) {
     this.options.params = params;
@@ -582,6 +564,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Merges additional headers into the request.
+   *
+   * @param headers - Header map merged into existing headers.
    */
   headers(headers) {
     this.options.headers = { ...this.options.headers, ...headers };
@@ -589,6 +573,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Sets request timeout in milliseconds.
+   *
+   * @param timeout - Timeout in milliseconds.
    */
   timeout(timeout) {
     this.options.timeout = timeout;
@@ -596,6 +582,9 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Sets cache strategy and optional cache key.
+   *
+   * @param cache - Cache strategy for the request.
+   * @param key - Optional cache key override.
    */
   cache(cache, key) {
     this.options.cache = cache;
@@ -604,6 +593,9 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Configures retry behavior for failed requests.
+   *
+   * @param maxAttempts - Maximum number of attempts.
+   * @param options - Retry options excluding `maxAttempts`.
    */
   retry(maxAttempts, options) {
     this.retryOptions = { maxAttempts, ...options };
@@ -611,6 +603,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Provides a fallback value if the request fails.
+   *
+   * @param fn - Fallback factory called when the request fails.
    */
   fallback(fn) {
     this.fallbackFn = fn;
@@ -618,6 +612,8 @@ var IgniterCallerRequestBuilder = class {
   }
   /**
    * Sets cache stale time in milliseconds.
+   *
+   * @param milliseconds - Stale time in milliseconds.
    */
   stale(milliseconds) {
     this.staleTime = milliseconds;
@@ -631,6 +627,8 @@ var IgniterCallerRequestBuilder = class {
    *
    * 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)
@@ -649,6 +647,8 @@ var IgniterCallerRequestBuilder = class {
   /**
    * 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) {
     this.options.method = "GET";
@@ -723,7 +723,7 @@ var IgniterCallerRequestBuilder = class {
                 statusCode: 408,
                 logger: this.logger,
                 metadata: { url: finalUrl },
-                cause: error
+                cause: error instanceof Error ? error : void 0
               })
             };
           }
@@ -735,7 +735,7 @@ var IgniterCallerRequestBuilder = class {
               message: error?.message || "Failed to download file",
               logger: this.logger,
               metadata: { url: finalUrl },
-              cause: error
+              cause: error instanceof Error ? error : void 0
             })
           };
         }
@@ -754,8 +754,32 @@ var IgniterCallerRequestBuilder = class {
    * - `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.
    */
   async execute() {
+    const startTime = Date.now();
+    const { safeUrl } = this.resolveUrl();
+    const method = this.options.method;
+    const baseURL = this.options.baseURL;
+    const timeoutMs = this.options.timeout;
+    this.telemetry?.emit(
+      "igniter.caller.request.execute.started",
+      {
+        level: "debug",
+        attributes: {
+          "ctx.request.method": method,
+          "ctx.request.url": safeUrl,
+          "ctx.request.baseUrl": baseURL,
+          "ctx.request.timeoutMs": timeoutMs
+        }
+      }
+    );
+    this.logger?.debug("IgniterCaller.request.execute started", {
+      method,
+      url: safeUrl,
+      baseURL
+    });
     const effectiveCacheKey = this.cacheKey || this.options.url;
     if (effectiveCacheKey && this.staleTime) {
       const cached = await IgniterCallerCacheUtils.get(
@@ -763,8 +787,36 @@ var IgniterCallerRequestBuilder = class {
         this.staleTime
       );
       if (cached !== void 0) {
-        this.logger?.debug("IgniterCaller.execute cache hit", {
-          key: effectiveCacheKey
+        this.telemetry?.emit(
+          "igniter.caller.cache.read.hit",
+          {
+            level: "debug",
+            attributes: {
+              "ctx.request.method": method,
+              "ctx.request.url": safeUrl,
+              "ctx.cache.key": effectiveCacheKey,
+              "ctx.cache.staleTime": this.staleTime
+            }
+          }
+        );
+        const durationMs2 = Date.now() - startTime;
+        this.telemetry?.emit(
+          "igniter.caller.request.execute.success",
+          {
+            level: "info",
+            attributes: {
+              "ctx.request.method": method,
+              "ctx.request.url": safeUrl,
+              "ctx.request.durationMs": durationMs2,
+              "ctx.cache.hit": true
+            }
+          }
+        );
+        this.logger?.info("IgniterCaller.request.execute success (cache)", {
+          key: effectiveCacheKey,
+          method,
+          url: safeUrl,
+          durationMs: durationMs2
         });
         const cachedResult = {
           data: cached,
@@ -776,13 +828,33 @@ var IgniterCallerRequestBuilder = class {
     }
     const result = await this.executeWithRetry();
     if (result.error && this.fallbackFn) {
-      this.logger?.debug("IgniterCaller.execute applying fallback", {
+      this.logger?.debug("IgniterCaller.request.execute applying fallback", {
+        method,
+        url: safeUrl,
         error: result.error
       });
       const fallbackResult = {
         data: this.fallbackFn(),
         error: void 0
       };
+      const durationMs2 = Date.now() - startTime;
+      this.telemetry?.emit(
+        "igniter.caller.request.execute.success",
+        {
+          level: "info",
+          attributes: {
+            "ctx.request.method": method,
+            "ctx.request.url": safeUrl,
+            "ctx.request.durationMs": durationMs2,
+            "ctx.request.fallback": true
+          }
+        }
+      );
+      this.logger?.info("IgniterCaller.request.execute success (fallback)", {
+        method,
+        url: safeUrl,
+        durationMs: durationMs2
+      });
       await this.emitEvent(fallbackResult);
       return fallbackResult;
     }
@@ -793,12 +865,57 @@ var IgniterCallerRequestBuilder = class {
         this.staleTime
       );
     }
+    const durationMs = Date.now() - startTime;
+    if (result.error) {
+      this.telemetry?.emit(
+        "igniter.caller.request.execute.error",
+        {
+          level: "error",
+          attributes: {
+            "ctx.request.method": method,
+            "ctx.request.url": safeUrl,
+            "ctx.request.durationMs": durationMs,
+            "ctx.error.code": result.error instanceof IgniterCallerError ? result.error.code : "IGNITER_CALLER_UNKNOWN_ERROR",
+            "ctx.error.message": result.error.message,
+            "ctx.response.status": result.status
+          }
+        }
+      );
+      this.logger?.error("IgniterCaller.request.execute failed", {
+        method,
+        url: safeUrl,
+        durationMs,
+        error: result.error
+      });
+    } else {
+      const contentType = result.headers?.get("content-type") || void 0;
+      this.telemetry?.emit(
+        "igniter.caller.request.execute.success",
+        {
+          level: "info",
+          attributes: {
+            "ctx.request.method": method,
+            "ctx.request.url": safeUrl,
+            "ctx.request.durationMs": durationMs,
+            "ctx.response.status": result.status,
+            "ctx.response.contentType": contentType,
+            "ctx.cache.hit": false
+          }
+        }
+      );
+      this.logger?.info("IgniterCaller.request.execute success", {
+        method,
+        url: safeUrl,
+        durationMs,
+        status: result.status
+      });
+    }
     await this.emitEvent(result);
     return result;
   }
   async executeWithRetry() {
     const maxAttempts = this.retryOptions?.maxAttempts || 1;
-    const baseDelay = this.retryOptions?.baseDelay || 1e3;
+    const baseDelay = this.retryOptions?.baseDelay ?? 1e3;
     const backoff = this.retryOptions?.backoff || "linear";
     const retryOnStatus = this.retryOptions?.retryOnStatus || [
       408,
@@ -808,13 +925,30 @@ var IgniterCallerRequestBuilder = class {
       503,
       504
     ];
+    const { safeUrl } = this.resolveUrl();
+    const method = this.options.method;
     let lastError;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       if (attempt > 0) {
         const delay = backoff === "exponential" ? baseDelay * 2 ** (attempt - 1) : baseDelay * attempt;
-        this.logger?.debug("IgniterCaller.execute retrying", {
-          attempt,
-          delay
+        this.telemetry?.emit(
+          "igniter.caller.retry.attempt.started",
+          {
+            level: "debug",
+            attributes: {
+              "ctx.request.method": method,
+              "ctx.request.url": safeUrl,
+              "ctx.retry.attempt": attempt + 1,
+              "ctx.retry.maxAttempts": maxAttempts,
+              "ctx.retry.delayMs": delay
+            }
+          }
+        );
+        this.logger?.debug("IgniterCaller.request.execute retrying", {
+          method,
+          url: safeUrl,
+          attempt: attempt + 1,
+          delayMs: delay
         });
         await new Promise((resolve) => setTimeout(resolve, delay));
       }
@@ -835,10 +969,8 @@ var IgniterCallerRequestBuilder = class {
   }
   async executeSingleRequest() {
     let { url, requestInit, controller, timeoutId } = this.buildRequest();
-    this.logger?.debug("IgniterCaller.execute started", {
-      method: this.options.method,
-      url
-    });
+    const { safeUrl } = this.resolveUrl();
+    const method = this.options.method;
     if (this.requestInterceptors && this.requestInterceptors.length > 0) {
       let modifiedOptions = { ...this.options, url };
       for (const interceptor of this.requestInterceptors) {
@@ -868,13 +1000,36 @@ var IgniterCallerRequestBuilder = class {
           );
         } catch (error) {
           clearTimeout(timeoutId);
+          const err = error;
+          this.telemetry?.emit(
+            "igniter.caller.validation.request.error",
+            {
+              level: "error",
+              attributes: {
+                "ctx.request.method": method,
+                "ctx.request.url": safeUrl,
+                "ctx.validation.type": "request",
+                "ctx.validation.error": err.message
+              }
+            }
+          );
+          this.logger?.error("IgniterCaller.request.validation failed", {
+            method,
+            url: safeUrl,
+            error: err
+          });
           return {
             data: void 0,
-            error
+            error: err
           };
         }
       }
     }
+    const mockResult = await this.executeMockRequest(url, safeUrl);
+    if (mockResult) {
+      clearTimeout(timeoutId);
+      return mockResult;
+    }
     try {
       const httpResponse = await fetch(url, {
         ...requestInit,
@@ -924,9 +1079,29 @@ var IgniterCallerRequestBuilder = class {
                 this.logger
               );
             } catch (error) {
+              const err = error;
+              this.telemetry?.emit(
+                "igniter.caller.validation.response.error",
+                {
+                  level: "error",
+                  attributes: {
+                    "ctx.request.method": method,
+                    "ctx.request.url": safeUrl,
+                    "ctx.validation.type": "response",
+                    "ctx.validation.error": err.message,
+                    "ctx.response.status": httpResponse.status
+                  }
+                }
+              );
+              this.logger?.error("IgniterCaller.response.validation failed", {
+                method,
+                url: safeUrl,
+                status: httpResponse.status,
+                error: err
+              });
               return {
                 data: void 0,
-                error,
+                error: err,
                 status: httpResponse.status,
                 headers: httpResponse.headers
               };
@@ -938,20 +1113,40 @@ var IgniterCallerRequestBuilder = class {
             const zodSchema = this.responseTypeSchema;
             const result = zodSchema.safeParse(data);
             if (!result.success) {
+              const err = new IgniterCallerError({
+                code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+                operation: "parseResponse",
+                message: `Response validation failed: ${result.error.message}`,
+                logger: this.logger,
+                statusCode: httpResponse.status,
+                metadata: {
+                  method: this.options.method,
+                  url
+                },
+                cause: result.error
+              });
+              this.telemetry?.emit(
+                "igniter.caller.validation.response.error",
+                {
+                  level: "error",
+                  attributes: {
+                    "ctx.request.method": method,
+                    "ctx.request.url": safeUrl,
+                    "ctx.validation.type": "response",
+                    "ctx.validation.error": err.message,
+                    "ctx.response.status": httpResponse.status
+                  }
+                }
+              );
+              this.logger?.error("IgniterCaller.response.validation failed", {
+                method,
+                url: safeUrl,
+                status: httpResponse.status,
+                error: err
+              });
               return {
                 data: void 0,
-                error: new IgniterCallerError({
-                  code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
-                  operation: "parseResponse",
-                  message: `Response validation failed: ${result.error.message}`,
-                  logger: this.logger,
-                  statusCode: httpResponse.status,
-                  metadata: {
-                    method: this.options.method,
-                    url
-                  },
-                  cause: result.error
-                }),
+                error: err,
                 status: httpResponse.status,
                 headers: httpResponse.headers
               };
@@ -962,40 +1157,80 @@ var IgniterCallerRequestBuilder = class {
               const standardSchema = this.responseTypeSchema;
               const result = await standardSchema["~standard"].validate(data);
               if (result.issues) {
+                const err = new IgniterCallerError({
+                  code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+                  operation: "parseResponse",
+                  message: `Response validation failed`,
+                  logger: this.logger,
+                  statusCode: httpResponse.status,
+                  metadata: {
+                    method: this.options.method,
+                    url,
+                    issues: result.issues
+                  }
+                });
+                this.telemetry?.emit(
+                  "igniter.caller.validation.response.error",
+                  {
+                    level: "error",
+                    attributes: {
+                      "ctx.request.method": method,
+                      "ctx.request.url": safeUrl,
+                      "ctx.validation.type": "response",
+                      "ctx.validation.error": err.message,
+                      "ctx.response.status": httpResponse.status
+                    }
+                  }
+                );
+                this.logger?.error("IgniterCaller.response.validation failed", {
+                  method,
+                  url: safeUrl,
+                  status: httpResponse.status,
+                  error: err
+                });
                 return {
                   data: void 0,
-                  error: new IgniterCallerError({
-                    code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
-                    operation: "parseResponse",
-                    message: `Response validation failed`,
-                    logger: this.logger,
-                    statusCode: httpResponse.status,
-                    metadata: {
-                      method: this.options.method,
-                      url,
-                      issues: result.issues
-                    }
-                  }),
+                  error: err,
                   status: httpResponse.status,
                   headers: httpResponse.headers
                 };
               }
               data = result.value;
             } catch (error) {
+              const err = new IgniterCallerError({
+                code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+                operation: "parseResponse",
+                message: error?.message || "Response validation failed",
+                logger: this.logger,
+                statusCode: httpResponse.status,
+                metadata: {
+                  method: this.options.method,
+                  url
+                },
+                cause: error instanceof Error ? error : void 0
+              });
+              this.telemetry?.emit(
+                "igniter.caller.validation.response.error",
+                {
+                  level: "error",
+                  attributes: {
+                    "ctx.request.method": method,
+                    "ctx.request.url": safeUrl,
+                    "ctx.validation.type": "response",
+                    "ctx.validation.error": err.message,
+                    "ctx.response.status": httpResponse.status
+                  }
+                }
+              );
+              this.logger?.error("IgniterCaller.response.validation failed", {
+                method,
+                url: safeUrl,
+                status: httpResponse.status,
+                error: err
+              });
               return {
                 data: void 0,
-                error: new IgniterCallerError({
-                  code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
-                  operation: "parseResponse",
-                  message: error?.message || "Response validation failed",
-                  logger: this.logger,
-                  statusCode: httpResponse.status,
-                  metadata: {
-                    method: this.options.method,
-                    url
-                  },
-                  cause: error
-                }),
+                error: err,
                 status: httpResponse.status,
                 headers: httpResponse.headers
               };
@@ -1018,20 +1253,38 @@ var IgniterCallerRequestBuilder = class {
     } catch (error) {
       clearTimeout(timeoutId);
       if (error instanceof Error && error.name === "AbortError") {
+        const err = new IgniterCallerError({
+          code: "IGNITER_CALLER_TIMEOUT",
+          operation: "execute",
+          message: `Request timeout after ${this.options.timeout || 3e4}ms`,
+          statusCode: 408,
+          logger: this.logger,
+          metadata: {
+            method: this.options.method,
+            url
+          },
+          cause: error instanceof Error ? error : void 0
+        });
+        this.telemetry?.emit(
+          "igniter.caller.request.timeout.error",
+          {
+            level: "error",
+            attributes: {
+              "ctx.request.method": method,
+              "ctx.request.url": safeUrl,
+              "ctx.request.timeoutMs": this.options.timeout || 3e4
+            }
+          }
+        );
+        this.logger?.error("IgniterCaller.request.execute timeout", {
+          method,
+          url: safeUrl,
+          timeoutMs: this.options.timeout || 3e4,
+          error: err
+        });
         return {
           data: void 0,
-          error: new IgniterCallerError({
-            code: "IGNITER_CALLER_TIMEOUT",
-            operation: "execute",
-            message: `Request timeout after ${this.options.timeout || 3e4}ms`,
-            statusCode: 408,
-            logger: this.logger,
-            metadata: {
-              method: this.options.method,
-              url
-            },
-            cause: error
-          })
+          error: err
         };
       }
       return {
@@ -1046,13 +1299,13 @@ var IgniterCallerRequestBuilder = class {
             method: this.options.method,
             url
           },
-          cause: error
+          cause: error instanceof Error ? error : void 0
         })
       };
     }
   }
-  buildRequest() {
-    const { method, url, body, params, headers, timeout, baseURL, cache } = this.options;
+  resolveUrl() {
+    const { method, url, body, params, baseURL } = this.options;
     let finalParams = params;
     if ((method === "GET" || method === "HEAD") && body && typeof body === "object") {
       const bodyParams = {};
@@ -1068,6 +1321,14 @@ var IgniterCallerRequestBuilder = class {
       baseURL,
       query: finalParams
     });
+    return {
+      url: fullUrl,
+      safeUrl: fullUrl.split("?")[0]
+    };
+  }
+  buildRequest() {
+    const { method, body, headers, timeout, cache } = this.options;
+    const { url } = this.resolveUrl();
     const shouldIncludeBody = body && method !== "GET" && method !== "HEAD";
     const rawBody = shouldIncludeBody && IgniterCallerBodyUtils.isRawBody(body);
     const finalHeaders = IgniterCallerBodyUtils.normalizeHeadersForBody(
@@ -1083,73 +1344,363 @@ var IgniterCallerRequestBuilder = class {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout || 3e4);
     return {
-      url: fullUrl,
+      url,
       requestInit,
       controller,
       timeoutId
     };
   }
   /**
-   * Emits event for this response using injected emitter.
+   * Normalizes a URL into a path for mock matching.
    */
-  async emitEvent(result) {
-    if (this.eventEmitter) {
+  normalizeMockPath(url, baseURL) {
+    if (/^https?:\/\//i.test(url)) {
       try {
-        await this.eventEmitter(this.options.url, this.options.method, result);
-      } catch (error) {
-        this.logger?.debug("Failed to emit event", { error });
+        return new URL(url).pathname;
+      } catch {
+        return url;
       }
     }
-  }
-};
-
-// src/core/igniter-caller-events.ts
-var IgniterCallerEvents = class {
-  constructor() {
-    this.listeners = /* @__PURE__ */ new Map();
-    this.patternListeners = /* @__PURE__ */ new Map();
+    if (baseURL && /^https?:\/\//i.test(baseURL)) {
+      try {
+        const resolved = IgniterCallerUrlUtils.buildUrl({ url, baseURL });
+        return new URL(resolved).pathname;
+      } catch {
+        return url;
+      }
+    }
+    return url.startsWith("/") ? url : `/${url}`;
   }
   /**
-   * 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()
-   * ```
+   * Resolves the final query object (merges GET/HEAD body into params).
    */
-  on(pattern, callback) {
-    if (typeof pattern === "string") {
-      if (!this.listeners.has(pattern)) {
-        this.listeners.set(pattern, /* @__PURE__ */ new Set());
-      }
-      const callbacks2 = this.listeners.get(pattern);
-      if (callbacks2) {
-        callbacks2.add(callback);
-      }
-      return () => {
-        const callbacks3 = this.listeners.get(pattern);
-        if (callbacks3) {
-          callbacks3.delete(callback);
-          if (callbacks3.size === 0) {
-            this.listeners.delete(pattern);
-          }
+  getFinalQuery() {
+    const { method, body, params } = this.options;
+    if ((method === "GET" || method === "HEAD") && body && typeof body === "object") {
+      const bodyParams = {};
+      for (const [key, value] of Object.entries(body)) {
+        if (value !== void 0 && value !== null) {
+          bodyParams[key] = String(value);
         }
-      };
+      }
+      return { ...bodyParams, ...params || {} };
+    }
+    return params || {};
+  }
+  /**
+   * Executes a mock handler when enabled and matched.
+   */
+  async executeMockRequest(url, safeUrl) {
+    if (!this.mock?.enabled) return null;
+    const path = this.normalizeMockPath(this.options.url, this.options.baseURL);
+    const method = this.options.method;
+    const resolved = this.mock.mock.resolve(path, method);
+    if (!resolved) return null;
+    const query = this.getFinalQuery();
+    const mockRequest = {
+      method,
+      path: resolved.path,
+      url,
+      safeUrl,
+      baseURL: this.options.baseURL,
+      headers: this.options.headers || {},
+      query,
+      params: resolved.params || {},
+      body: this.options.body,
+      timeoutMs: this.options.timeout,
+      cache: this.options.cache,
+      cacheKey: this.cacheKey,
+      staleTime: this.staleTime,
+      responseTypeSchema: this.responseTypeSchema
+    };
+    const response = await this.resolveMockResponse(
+      resolved.handler,
+      mockRequest
+    );
+    if (response.delayMs && response.delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, response.delayMs));
+    }
+    const status = response.status;
+    const headers = new Headers(response.headers);
+    if (status >= 400) {
+      return {
+        data: void 0,
+        error: new IgniterCallerError({
+          code: "IGNITER_CALLER_MOCK_HTTP_ERROR",
+          operation: "execute",
+          message: response.errorMessage || `Mocked request failed with status ${status}`,
+          statusCode: status,
+          logger: this.logger,
+          metadata: {
+            method,
+            url
+          }
+        }),
+        status,
+        headers
+      };
+    }
+    let data = response.response;
+    if (this.schemas) {
+      const { schema: endpointSchema } = IgniterCallerSchemaUtils.findSchema(
+        this.schemas,
+        path,
+        method
+      );
+      const responseSchema = endpointSchema?.responses?.[status];
+      if (responseSchema) {
+        try {
+          data = await IgniterCallerSchemaUtils.validateResponse(
+            data,
+            responseSchema,
+            status,
+            this.schemaValidation,
+            { url: safeUrl, method },
+            this.logger
+          );
+        } catch (error) {
+          const err = error;
+          this.telemetry?.emit(
+            "igniter.caller.validation.response.error",
+            {
+              level: "error",
+              attributes: {
+                "ctx.request.method": method,
+                "ctx.request.url": safeUrl,
+                "ctx.validation.type": "response",
+                "ctx.validation.error": err.message,
+                "ctx.response.status": status
+              }
+            }
+          );
+          this.logger?.error("IgniterCaller.response.validation failed", {
+            method,
+            url: safeUrl,
+            status,
+            error: err
+          });
+          return {
+            data: void 0,
+            error: err,
+            status,
+            headers
+          };
+        }
+      }
+    }
+    if (this.responseTypeSchema) {
+      if ("safeParse" in this.responseTypeSchema) {
+        const zodSchema = this.responseTypeSchema;
+        const result = zodSchema.safeParse(data);
+        if (!result.success) {
+          const err = new IgniterCallerError({
+            code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+            operation: "parseResponse",
+            message: `Response validation failed: ${result.error.message}`,
+            logger: this.logger,
+            statusCode: status,
+            metadata: {
+              method,
+              url
+            },
+            cause: result.error
+          });
+          this.telemetry?.emit(
+            "igniter.caller.validation.response.error",
+            {
+              level: "error",
+              attributes: {
+                "ctx.request.method": method,
+                "ctx.request.url": safeUrl,
+                "ctx.validation.type": "response",
+                "ctx.validation.error": err.message,
+                "ctx.response.status": status
+              }
+            }
+          );
+          this.logger?.error("IgniterCaller.response.validation failed", {
+            method,
+            url: safeUrl,
+            status,
+            error: err
+          });
+          return {
+            data: void 0,
+            error: err,
+            status,
+            headers
+          };
+        }
+        data = result.data;
+      } else if ("~standard" in this.responseTypeSchema) {
+        try {
+          const standardSchema = this.responseTypeSchema;
+          const result = await standardSchema["~standard"].validate(data);
+          if (result.issues) {
+            const err = new IgniterCallerError({
+              code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+              operation: "parseResponse",
+              message: `Response validation failed`,
+              logger: this.logger,
+              statusCode: status,
+              metadata: {
+                method,
+                url,
+                issues: result.issues
+              }
+            });
+            this.telemetry?.emit(
+              "igniter.caller.validation.response.error",
+              {
+                level: "error",
+                attributes: {
+                  "ctx.request.method": method,
+                  "ctx.request.url": safeUrl,
+                  "ctx.validation.type": "response",
+                  "ctx.validation.error": err.message,
+                  "ctx.response.status": status
+                }
+              }
+            );
+            this.logger?.error("IgniterCaller.response.validation failed", {
+              method,
+              url: safeUrl,
+              status,
+              error: err
+            });
+            return {
+              data: void 0,
+              error: err,
+              status,
+              headers
+            };
+          }
+          data = result.value;
+        } catch (error) {
+          const err = error;
+          this.telemetry?.emit(
+            "igniter.caller.validation.response.error",
+            {
+              level: "error",
+              attributes: {
+                "ctx.request.method": method,
+                "ctx.request.url": safeUrl,
+                "ctx.validation.type": "response",
+                "ctx.validation.error": err.message,
+                "ctx.response.status": status
+              }
+            }
+          );
+          this.logger?.error("IgniterCaller.response.validation failed", {
+            method,
+            url: safeUrl,
+            status,
+            error: err
+          });
+          return {
+            data: void 0,
+            error: err,
+            status,
+            headers
+          };
+        }
+      }
+    }
+    let responseResult = {
+      data,
+      error: void 0,
+      status,
+      headers
+    };
+    if (this.responseInterceptors && this.responseInterceptors.length > 0) {
+      for (const interceptor of this.responseInterceptors) {
+        responseResult = await interceptor(responseResult);
+      }
+    }
+    return responseResult;
+  }
+  /**
+   * Normalizes a mock handler result into a response payload with status.
+   */
+  async resolveMockResponse(handler, request) {
+    const result = typeof handler === "function" ? await handler(request) : handler;
+    const hasStatus = typeof result.status === "number";
+    if (hasStatus) {
+      return result;
+    }
+    const schemas = this.schemas;
+    const schemaMatch = schemas ? IgniterCallerSchemaUtils.findSchema(
+      schemas,
+      request.path,
+      request.method
+    ).schema : void 0;
+    const fallbackStatus = schemaMatch?.responses?.[200] ? 200 : schemaMatch?.responses?.[201] ? 201 : 200;
+    return {
+      ...result,
+      status: fallbackStatus
+    };
+  }
+  /**
+   * Emits event for this response using injected emitter.
+   */
+  async emitEvent(result) {
+    if (this.eventEmitter) {
+      try {
+        await this.eventEmitter(this.options.url, this.options.method, result);
+      } catch (error) {
+        this.logger?.debug("Failed to emit event", { error });
+      }
+    }
+  }
+};
+
+// src/core/events.ts
+var IgniterCallerEvents = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.patternListeners = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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()
+   * ```
+   */
+  on(pattern, callback) {
+    if (typeof pattern === "string") {
+      if (!this.listeners.has(pattern)) {
+        this.listeners.set(pattern, /* @__PURE__ */ new Set());
+      }
+      const callbacks2 = this.listeners.get(pattern);
+      if (callbacks2) {
+        callbacks2.add(callback);
+      }
+      return () => {
+        const callbacks3 = this.listeners.get(pattern);
+        if (callbacks3) {
+          callbacks3.delete(callback);
+          if (callbacks3.size === 0) {
+            this.listeners.delete(pattern);
+          }
+        }
+      };
     }
     if (!this.patternListeners.has(pattern)) {
       this.patternListeners.set(pattern, /* @__PURE__ */ new Set());
@@ -1170,6 +1721,9 @@ var IgniterCallerEvents = class {
   }
   /**
    * 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, callback) {
     if (typeof pattern === "string") {
@@ -1190,6 +1744,10 @@ var IgniterCallerEvents = class {
    * Emits an event to all matching listeners.
    *
    * @internal
+   *
+   * @param url - Request URL to match listeners against.
+   * @param method - HTTP method.
+   * @param result - Response envelope.
    */
   async emit(url, method, result) {
     const context = {
@@ -1221,6 +1779,8 @@ var IgniterCallerEvents = class {
   }
   /**
    * Removes all listeners.
+   *
+   * @returns Nothing.
    */
   clear() {
     this.listeners.clear();
@@ -1228,64 +1788,25 @@ var IgniterCallerEvents = class {
   }
 };
 
-// src/core/igniter-caller.ts
-var _IgniterCaller = class _IgniterCaller {
+// src/core/manager.ts
+var _IgniterCallerManager = class _IgniterCallerManager {
+  /**
+   * Creates a new manager instance.
+   *
+   * @param baseURL - Base URL prefix for requests.
+   * @param opts - Optional configuration (headers, cookies, telemetry, schemas).
+   */
   constructor(baseURL, opts) {
     this.baseURL = baseURL;
     this.headers = opts?.headers;
     this.cookies = opts?.cookies;
     this.logger = opts?.logger;
+    this.telemetry = opts?.telemetry;
     this.requestInterceptors = opts?.requestInterceptors;
     this.responseInterceptors = opts?.responseInterceptors;
     this.schemas = opts?.schemas;
     this.schemaValidation = opts?.schemaValidation;
-  }
-  /**
-   * Canonical initialization entrypoint.
-   *
-   * This is designed to remain stable when extracted to `@igniter-js/caller`.
-   */
-  static create() {
-    return IgniterCallerBuilder.create((state) => {
-      if (state.store) {
-        IgniterCallerCacheUtils.setStore(state.store, state.storeOptions);
-      }
-      return new _IgniterCaller(state.baseURL, {
-        headers: state.headers,
-        cookies: state.cookies,
-        logger: state.logger,
-        requestInterceptors: state.requestInterceptors,
-        responseInterceptors: state.responseInterceptors,
-        schemas: state.schemas,
-        schemaValidation: state.schemaValidation
-      });
-    });
-  }
-  /**
-   * Returns a new client with the same config and a new logger.
-   */
-  withLogger(logger) {
-    return new _IgniterCaller(this.baseURL, {
-      headers: this.headers,
-      cookies: this.cookies,
-      logger,
-      requestInterceptors: this.requestInterceptors,
-      responseInterceptors: this.responseInterceptors,
-      schemas: this.schemas,
-      schemaValidation: this.schemaValidation
-    });
-  }
-  setBaseURL(baseURL) {
-    this.baseURL = baseURL;
-    return this;
-  }
-  setHeaders(headers) {
-    this.headers = headers;
-    return this;
-  }
-  setCookies(cookies) {
-    this.cookies = cookies;
-    return this;
+    this.mock = opts?.mock;
   }
   /**
    * Creates common request builder params.
@@ -1296,24 +1817,17 @@ var _IgniterCaller = class _IgniterCaller {
       defaultHeaders: this.headers,
       defaultCookies: this.cookies,
       logger: this.logger,
+      telemetry: this.telemetry,
       requestInterceptors: this.requestInterceptors,
       responseInterceptors: this.responseInterceptors,
       eventEmitter: async (url, method, result) => {
-        await _IgniterCaller.emitEvent(url, method, result);
+        await _IgniterCallerManager.emitEvent(url, method, result);
       },
       schemas: this.schemas,
-      schemaValidation: this.schemaValidation
+      schemaValidation: this.schemaValidation,
+      mock: this.mock
     };
   }
-  /**
-   * Resolves the full URL path by prepending baseURL if needed.
-   */
-  resolveSchemaPath(url) {
-    if (this.baseURL && !url.startsWith("http")) {
-      return `${this.baseURL}${url}`;
-    }
-    return url;
-  }
   get(url) {
     const builder = new IgniterCallerRequestBuilder(this.createBuilderParams());
     builder._setMethod("GET");
@@ -1356,6 +1870,9 @@ var _IgniterCaller = class _IgniterCaller {
    * 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({
@@ -1422,6 +1939,9 @@ var _IgniterCaller = class _IgniterCaller {
    * 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 async batch(requests) {
     return Promise.all(requests);
@@ -1442,7 +1962,7 @@ var _IgniterCaller = class _IgniterCaller {
    * @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)
    * })
    *
@@ -1451,24 +1971,29 @@ var _IgniterCaller = class _IgniterCaller {
    * ```
    */
   static on(pattern, callback) {
-    return _IgniterCaller.events.on(pattern, callback);
+    return _IgniterCallerManager.events.on(pattern, callback);
   }
   /**
    * Removes event listeners for a pattern.
+   *
+   * @param pattern - URL string or RegExp pattern.
+   * @param callback - Callback to remove (optional).
    */
   static off(pattern, callback) {
-    _IgniterCaller.events.off(pattern, callback);
+    _IgniterCallerManager.events.off(pattern, callback);
   }
   /**
    * Invalidates a specific cache entry.
    *
    * This is useful after mutations to ensure fresh data on next fetch.
    *
+   * @param key - Cache key to invalidate.
+   *
    * @example
    * ```ts
    * // After creating a user
    * await api.post('/users').body(newUser).execute()
-   * await IgniterCaller.invalidate('/users') // Clear users list cache
+   * await IgniterCallerManager.invalidate('/users') // Clear users list cache
    * ```
    */
   static async invalidate(key) {
@@ -1478,11 +2003,12 @@ var _IgniterCaller = class _IgniterCaller {
    * 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 async invalidatePattern(pattern) {
@@ -1492,25 +2018,637 @@ var _IgniterCaller = class _IgniterCaller {
    * Emits an event to all registered listeners.
    *
    * @internal
+   *
+   * @param url - Request URL (resolved).
+   * @param method - HTTP method.
+   * @param result - Response envelope.
    */
   static async emitEvent(url, method, result) {
-    await _IgniterCaller.events.emit(url, method, result);
+    await _IgniterCallerManager.events.emit(url, method, result);
   }
 };
 /** Global event emitter for observing HTTP responses */
-_IgniterCaller.events = new IgniterCallerEvents();
-var IgniterCaller = _IgniterCaller;
+_IgniterCallerManager.events = new IgniterCallerEvents();
+var IgniterCallerManager = _IgniterCallerManager;
+
+// src/core/mock.ts
+var IgniterCallerMockManager = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  /**
+   * 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, method) {
+    const direct = this.registry[path]?.[method];
+    if (direct) {
+      return {
+        handler: direct,
+        params: {},
+        path,
+        method
+      };
+    }
+    for (const [registeredPath, methods] of Object.entries(this.registry)) {
+      if (!methods) continue;
+      const match = IgniterCallerSchemaUtils.matchPath(path, registeredPath);
+      if (!match.matched) continue;
+      const handler = methods[method];
+      if (!handler) continue;
+      return {
+        handler,
+        params: match.params || {},
+        path: registeredPath,
+        method
+      };
+    }
+    return null;
+  }
+};
+
+// src/builders/main.builder.ts
+var IgniterCallerBuilder = class _IgniterCallerBuilder {
+  constructor(state) {
+    this.state = state;
+  }
+  /**
+   * Creates a new builder instance.
+   *
+   * @returns New builder instance with empty state.
+   */
+  static create() {
+    return new _IgniterCallerBuilder({});
+  }
+  /**
+   * Sets the base URL for all requests.
+   *
+   * @param baseURL - Base URL prefix for outgoing requests.
+   */
+  withBaseUrl(baseURL) {
+    return new _IgniterCallerBuilder({ ...this.state, baseURL });
+  }
+  /**
+   * Merges default headers for all requests.
+   *
+   * @param headers - Header map merged into every request.
+   */
+  withHeaders(headers) {
+    return new _IgniterCallerBuilder({ ...this.state, headers });
+  }
+  /**
+   * Sets default cookies (sent as the `Cookie` header).
+   *
+   * @param cookies - Cookie key/value pairs.
+   */
+  withCookies(cookies) {
+    return new _IgniterCallerBuilder({ ...this.state, cookies });
+  }
+  /**
+   * Attaches a logger instance.
+   *
+   * @param logger - Logger implementation from `@igniter-js/common`.
+   */
+  withLogger(logger) {
+    return new _IgniterCallerBuilder({ ...this.state, logger });
+  }
+  /**
+   * Adds a request interceptor that runs before each request.
+   *
+   * @param interceptor - Interceptor called with request options.
+   */
+  withRequestInterceptor(interceptor) {
+    const requestInterceptors = [
+      ...this.state.requestInterceptors || [],
+      interceptor
+    ];
+    return new _IgniterCallerBuilder({ ...this.state, requestInterceptors });
+  }
+  /**
+   * Adds a response interceptor that runs after each request.
+   *
+   * @param interceptor - Interceptor called with the response result.
+   */
+  withResponseInterceptor(interceptor) {
+    const responseInterceptors = [
+      ...this.state.responseInterceptors || [],
+      interceptor
+    ];
+    return new _IgniterCallerBuilder({ ...this.state, responseInterceptors });
+  }
+  /**
+   * 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, options) {
+    return new _IgniterCallerBuilder({
+      ...this.state,
+      store,
+      storeOptions: options
+    });
+  }
+  /**
+   * 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()
+   * ```
+   */
+  withSchemas(schemas, validation) {
+    const nextState = {
+      ...this.state,
+      schemas,
+      schemaValidation: validation
+    };
+    return new _IgniterCallerBuilder(nextState);
+  }
+  /**
+   * 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()
+   * ```
+   */
+  withTelemetry(telemetry) {
+    return new _IgniterCallerBuilder({ ...this.state, telemetry });
+  }
+  /**
+   * Enables request mocking using a mock registry.
+   *
+   * When enabled, matching requests are routed to the mock handlers instead of fetch.
+   *
+   * @param config - Mock configuration with registry and enable flag.
+   */
+  withMock(config) {
+    return new _IgniterCallerBuilder({ ...this.state, mock: config });
+  }
+  /**
+   * Builds the `IgniterCaller` instance.
+   *
+   * @returns Configured manager instance.
+   */
+  build() {
+    if (this.state.store) {
+      IgniterCallerCacheUtils.setStore(this.state.store, this.state.storeOptions);
+    }
+    const manager = new IgniterCallerManager(this.state.baseURL, {
+      headers: this.state.headers,
+      cookies: this.state.cookies,
+      logger: this.state.logger,
+      telemetry: this.state.telemetry,
+      requestInterceptors: this.state.requestInterceptors,
+      responseInterceptors: this.state.responseInterceptors,
+      schemas: this.state.schemas,
+      schemaValidation: this.state.schemaValidation,
+      mock: this.state.mock
+    });
+    this.state.logger?.info("IgniterCaller initialized", {
+      baseURL: this.state.baseURL,
+      hasTelemetry: Boolean(this.state.telemetry),
+      hasStore: Boolean(this.state.store),
+      hasSchemas: Boolean(this.state.schemas)
+    });
+    return manager;
+  }
+};
+var IgniterCaller = {
+  create: IgniterCallerBuilder.create
+};
+var IgniterCallerSchemaPathBuilder = class _IgniterCallerSchemaPathBuilder {
+  constructor(methods, registry) {
+    this.methods = methods;
+    this.registry = registry;
+  }
+  /**
+   * Creates a new path builder for the provided registry.
+   */
+  static create(registry) {
+    return new _IgniterCallerSchemaPathBuilder({}, registry);
+  }
+  /**
+   * Returns a registry reference helper for a given key.
+   * The helper exposes optional Zod-based wrappers (array/optional/nullable/record).
+   */
+  ref(key) {
+    const schema = this.registry[key];
+    const zodSchema = schema;
+    return {
+      schema,
+      array: () => z.array(zodSchema),
+      nullable: () => zodSchema.nullable(),
+      optional: () => zodSchema.optional(),
+      record: (keyType) => z.record(
+        z.any(),
+        zodSchema
+      )
+    };
+  }
+  /**
+   * Defines a GET endpoint.
+   */
+  get(config) {
+    return this.addMethod("GET", config);
+  }
+  /**
+   * Defines a POST endpoint.
+   */
+  post(config) {
+    return this.addMethod("POST", config);
+  }
+  /**
+   * Defines a PUT endpoint.
+   */
+  put(config) {
+    return this.addMethod("PUT", config);
+  }
+  /**
+   * Defines a PATCH endpoint.
+   */
+  patch(config) {
+    return this.addMethod("PATCH", config);
+  }
+  /**
+   * Defines a DELETE endpoint.
+   */
+  delete(config) {
+    return this.addMethod("DELETE", config);
+  }
+  /**
+   * Defines a HEAD endpoint.
+   */
+  head(config) {
+    return this.addMethod("HEAD", config);
+  }
+  /**
+   * Builds the accumulated method map for the path.
+   */
+  build() {
+    return this.methods;
+  }
+  addMethod(method, config) {
+    if (method in this.methods) {
+      throw new IgniterCallerError({
+        code: "IGNITER_CALLER_SCHEMA_DUPLICATE",
+        operation: "buildSchema",
+        message: `Schema for method "${method}" is already defined on this path.`,
+        statusCode: 400,
+        metadata: { method }
+      });
+    }
+    return new _IgniterCallerSchemaPathBuilder(
+      {
+        ...this.methods,
+        [method]: {
+          ...config
+        }
+      },
+      this.registry
+    );
+  }
+};
+
+// src/builders/schema.builder.ts
+var IgniterCallerSchema = class _IgniterCallerSchema {
+  constructor(schemas, registry) {
+    this.schemas = schemas;
+    this.registry = registry;
+  }
+  /**
+   * Creates a new empty schema builder.
+   */
+  static create() {
+    return new _IgniterCallerSchema({}, {});
+  }
+  /**
+   * Registers a reusable schema in the registry.
+   */
+  schema(key, schema, options) {
+    ensureValidSchemaKey(key);
+    if (key in this.registry) {
+      throw new IgniterCallerError({
+        code: "IGNITER_CALLER_SCHEMA_DUPLICATE",
+        operation: "buildSchema",
+        message: `Schema registry key "${key}" is already defined.`,
+        statusCode: 400,
+        metadata: { key }
+      });
+    }
+    const nextRegistry = {
+      ...this.registry,
+      [key]: schema
+    };
+    void options?.internal;
+    return new _IgniterCallerSchema(this.schemas, nextRegistry);
+  }
+  /**
+   * Defines a path with its methods using a fluent builder.
+   */
+  path(path, builder) {
+    ensureValidPath(path);
+    const pathBuilder = IgniterCallerSchemaPathBuilder.create(this.registry);
+    const builtMethods = builder(pathBuilder).build();
+    const existing = this.schemas[path] ?? {};
+    for (const method of Object.keys(
+      builtMethods
+    )) {
+      if (method in existing) {
+        throw new IgniterCallerError({
+          code: "IGNITER_CALLER_SCHEMA_DUPLICATE",
+          operation: "buildSchema",
+          message: `Schema for "${path}" with method "${method}" is already defined.`,
+          statusCode: 400,
+          metadata: { path, method }
+        });
+      }
+    }
+    const merged = {
+      ...existing,
+      ...builtMethods
+    };
+    const nextSchemas = {
+      ...this.schemas,
+      [path]: merged
+    };
+    return new _IgniterCallerSchema(nextSchemas, this.registry);
+  }
+  /**
+   * Builds the schema map and attaches inference + runtime helpers.
+   */
+  build() {
+    const result = {
+      ...this.schemas
+    };
+    const inferHelpers = createInferHelpers();
+    const getHelpers = createGetHelpers(this.schemas, this.registry);
+    Object.defineProperty(result, "$Infer", {
+      value: inferHelpers,
+      enumerable: false
+    });
+    Object.defineProperty(result, "get", {
+      value: getHelpers,
+      enumerable: false
+    });
+    return result;
+  }
+};
+function createInferHelpers() {
+  return {
+    Path: void 0,
+    Endpoint: (() => void 0),
+    Request: (() => void 0),
+    Response: (() => void 0),
+    Responses: (() => void 0),
+    Schema: (() => void 0)
+  };
+}
+function createGetHelpers(schemas, registry) {
+  return {
+    path: (path) => schemas[path],
+    endpoint: (path, method) => schemas[path][method],
+    request: (path, method) => schemas[path][method]?.request,
+    response: (path, method, status) => schemas[path][method]?.responses?.[status],
+    schema: (key) => registry[key]
+  };
+}
+function ensureValidPath(path) {
+  if (!path || path.trim().length === 0) {
+    throw new IgniterCallerError({
+      code: "IGNITER_CALLER_SCHEMA_INVALID",
+      operation: "buildSchema",
+      message: "Path cannot be empty.",
+      statusCode: 400
+    });
+  }
+  if (!path.startsWith("/")) {
+    throw new IgniterCallerError({
+      code: "IGNITER_CALLER_SCHEMA_INVALID",
+      operation: "buildSchema",
+      message: `Path "${path}" must start with "/".`,
+      statusCode: 400,
+      metadata: { path }
+    });
+  }
+}
+function ensureValidSchemaKey(key) {
+  if (!key || key.trim().length === 0) {
+    throw new IgniterCallerError({
+      code: "IGNITER_CALLER_SCHEMA_INVALID",
+      operation: "buildSchema",
+      message: "Schema registry key cannot be empty.",
+      statusCode: 400
+    });
+  }
+}
+
+// src/builders/mock.builder.ts
+var IgniterCallerMockBuilder = class _IgniterCallerMockBuilder {
+  constructor(state) {
+    this.state = state;
+  }
+  /**
+   * Creates a new mock builder.
+   */
+  static create() {
+    return new _IgniterCallerMockBuilder({ registry: {} });
+  }
+  /**
+   * Sets schemas to enable typed mock definitions.
+   *
+   * @param _schemas - Schema map or build result.
+   */
+  withSchemas(_schemas) {
+    return new _IgniterCallerMockBuilder({
+      registry: this.state.registry
+    });
+  }
+  /**
+   * Registers mock handlers for a path.
+   *
+   * @param path - Schema path.
+   * @param handlers - Method handlers or static responses.
+   */
+  mock(path, handlers) {
+    const registry = {
+      ...this.state.registry,
+      [path]: {
+        ...this.state.registry[path] || {},
+        ...handlers
+      }
+    };
+    return new _IgniterCallerMockBuilder({ registry });
+  }
+  /**
+   * Builds a mock manager instance.
+   */
+  build() {
+    return new IgniterCallerMockManager(this.state.registry);
+  }
+};
+var IgniterCallerMock = {
+  create: IgniterCallerMockBuilder.create
+};
+
+// src/adapters/mock.adapter.ts
+var MockCallerStoreAdapter = class _MockCallerStoreAdapter {
+  constructor() {
+    /** Underlying in-memory store. */
+    this.client = /* @__PURE__ */ new Map();
+    /** Tracks all calls for assertions. */
+    this.calls = {
+      get: 0,
+      set: 0,
+      delete: 0,
+      has: 0
+    };
+    /** Captures recent operations. */
+    this.history = {
+      get: [],
+      set: [],
+      delete: [],
+      has: []
+    };
+  }
+  /** Creates a new mock adapter instance. */
+  static create() {
+    return new _MockCallerStoreAdapter();
+  }
+  /**
+   * Retrieves a cached value by key.
+   *
+   * @param key - Cache key (without prefix).
+   * @returns Cached value or null.
+   */
+  async get(key) {
+    this.calls.get += 1;
+    this.history.get.push(key);
+    return this.client.has(key) ? this.client.get(key) : null;
+  }
+  /**
+   * Stores a cached value.
+   *
+   * @param key - Cache key (without prefix).
+   * @param value - Value to store.
+   * @param options - Cache options (ttl, etc).
+   */
+  async set(key, value, options) {
+    this.calls.set += 1;
+    this.history.set.push({ key, value, options });
+    this.client.set(key, value);
+  }
+  /**
+   * Removes a cached value.
+   *
+   * @param key - Cache key (without prefix).
+   */
+  async delete(key) {
+    this.calls.delete += 1;
+    this.history.delete.push(key);
+    this.client.delete(key);
+  }
+  /**
+   * Checks if a cached value exists.
+   *
+   * @param key - Cache key (without prefix).
+   * @returns True when the key exists.
+   */
+  async has(key) {
+    this.calls.has += 1;
+    this.history.has.push(key);
+    return this.client.has(key);
+  }
+  /**
+   * Clears all tracked state.
+   *
+   * @returns Nothing.
+   */
+  clear() {
+    this.client.clear();
+    this.calls.get = 0;
+    this.calls.set = 0;
+    this.calls.delete = 0;
+    this.calls.has = 0;
+    this.history.get = [];
+    this.history.set = [];
+    this.history.delete = [];
+    this.history.has = [];
+  }
+};
 
 // src/utils/testing.ts
-var IgniterCallerMock = class {
+var IgniterCallerHttpMock = class {
   /**
    * Creates a successful mock response.
+   *
+   * @param data - Mock response data.
    */
   static mockResponse(data) {
     return { data, error: void 0 };
   }
   /**
    * Creates an error mock response.
+   *
+   * @param code - Error code to use.
+   * @param message - Optional error message.
    */
   static mockError(code, message = "Mock error") {
     return {
@@ -1524,6 +2662,9 @@ var IgniterCallerMock = class {
   }
   /**
    * Creates a successful file download mock.
+   *
+   * @param filename - File name for the mock.
+   * @param content - File contents as string or Blob.
    */
   static mockFile(filename, content) {
     const blob = typeof content === "string" ? new Blob([content]) : content;
@@ -1532,6 +2673,8 @@ var IgniterCallerMock = class {
   }
   /**
    * Creates a failed file download mock.
+   *
+   * @param message - Optional error message.
    */
   static mockFileError(message = "Mock file error") {
     return {
@@ -1545,6 +2688,6 @@ var IgniterCallerMock = class {
   }
 };
 
-export { IgniterCaller, IgniterCallerBodyUtils, IgniterCallerBuilder, IgniterCallerCacheUtils, IgniterCallerError, IgniterCallerEvents, IgniterCallerMock, IgniterCallerRequestBuilder, IgniterCallerSchemaUtils, IgniterCallerUrlUtils };
+export { IgniterCaller, IgniterCallerBodyUtils, IgniterCallerBuilder, IgniterCallerCacheUtils, IgniterCallerError, IgniterCallerEvents, IgniterCallerHttpMock, IgniterCallerManager, IgniterCallerMock, IgniterCallerMockBuilder, IgniterCallerMockManager, IgniterCallerRequestBuilder, IgniterCallerSchema, IgniterCallerSchemaPathBuilder, IgniterCallerSchemaUtils, IgniterCallerUrlUtils, MockCallerStoreAdapter };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map