@igniter-js/caller 0.1.0

package/dist/index.js

@@ -0,0 +1,1343 @@
+'use strict';
+
+var core = require('@igniter-js/core');
+
+// 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
+    );
+  }
+  /**
+   * 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(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 core.IgniterError {
+  constructor(payload) {
+    const metadata = {
+      ...payload.metadata,
+      operation: payload.operation,
+      statusText: payload.statusText
+    };
+    const details = payload.details ?? (payload.cause !== void 0 ? { cause: payload.cause } : void 0);
+    super({
+      code: payload.code,
+      message: payload.message,
+      statusCode: payload.statusCode,
+      causer: "@igniter-js/caller",
+      details,
+      metadata,
+      logger: payload.logger
+    });
+    this.name = "IgniterCallerError";
+    this.operation = payload.operation;
+    this.statusText = payload.statusText;
+    this.cause = payload.cause;
+  }
+  static is(error) {
+    return error instanceof _IgniterCallerError;
+  }
+};
+
+// src/utils/body.ts
+var IgniterCallerBodyUtils = class {
+  /**
+   * Returns true when the request body should be passed to `fetch` as-is.
+   */
+  static isRawBody(body) {
+    if (!body) return false;
+    if (typeof FormData !== "undefined" && body instanceof FormData) return true;
+    if (typeof Blob !== "undefined" && body instanceof Blob) return true;
+    if (typeof ArrayBuffer !== "undefined" && body instanceof ArrayBuffer)
+      return true;
+    if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams)
+      return true;
+    if (typeof ReadableStream !== "undefined" && body instanceof ReadableStream)
+      return true;
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(body)) return true;
+    if (typeof ArrayBuffer !== "undefined" && ArrayBuffer.isView(body))
+      return true;
+    return false;
+  }
+  /**
+   * Removes Content-Type for FormData so fetch can set boundaries automatically.
+   */
+  static normalizeHeadersForBody(headers, body) {
+    if (!headers) return headers;
+    const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
+    if (!isFormData) return headers;
+    if (!("Content-Type" in headers)) return headers;
+    const { "Content-Type": _contentType, ...rest } = headers;
+    return rest;
+  }
+};
+
+// src/utils/cache.ts
+var _IgniterCallerCacheUtils = class _IgniterCallerCacheUtils {
+  /**
+   * 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.
+   */
+  static setStore(store, options) {
+    _IgniterCallerCacheUtils.store = store;
+    if (options) {
+      _IgniterCallerCacheUtils.storeOptions = {
+        ..._IgniterCallerCacheUtils.storeOptions,
+        ...options
+      };
+    }
+  }
+  /**
+   * Gets the configured store adapter.
+   */
+  static getStore() {
+    return _IgniterCallerCacheUtils.store;
+  }
+  /**
+   * Gets cached data if it exists and is not stale.
+   */
+  static async get(key, staleTime) {
+    const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
+    if (_IgniterCallerCacheUtils.store) {
+      try {
+        const data = await _IgniterCallerCacheUtils.store.get(prefixedKey);
+        if (data !== null) {
+          return data;
+        }
+      } catch (error) {
+        console.error("IgniterCaller: Store get failed", error);
+      }
+    }
+    const entry = _IgniterCallerCacheUtils.cache.get(prefixedKey);
+    if (!entry) return void 0;
+    if (staleTime && Date.now() - entry.timestamp > staleTime) {
+      _IgniterCallerCacheUtils.cache.delete(prefixedKey);
+      return void 0;
+    }
+    return entry.data;
+  }
+  /**
+   * Stores data in cache with current timestamp.
+   */
+  static async set(key, data, ttl) {
+    const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
+    const effectiveTtl = ttl || _IgniterCallerCacheUtils.storeOptions.ttl || 3600;
+    if (_IgniterCallerCacheUtils.store) {
+      try {
+        await _IgniterCallerCacheUtils.store.set(prefixedKey, data, {
+          ttl: effectiveTtl
+        });
+        return;
+      } catch (error) {
+        console.error("IgniterCaller: Store set failed", error);
+      }
+    }
+    _IgniterCallerCacheUtils.cache.set(prefixedKey, {
+      data,
+      timestamp: Date.now()
+    });
+  }
+  /**
+   * Clears a specific cache entry.
+   */
+  static async clear(key) {
+    const prefixedKey = _IgniterCallerCacheUtils.getPrefixedKey(key);
+    if (_IgniterCallerCacheUtils.store) {
+      try {
+        await _IgniterCallerCacheUtils.store.delete(prefixedKey);
+      } catch (error) {
+        console.error("IgniterCaller: Store delete failed", error);
+      }
+    }
+    _IgniterCallerCacheUtils.cache.delete(prefixedKey);
+  }
+  /**
+   * Clears all cache entries matching a pattern.
+   *
+   * @param pattern Glob pattern (e.g., '/users/*') or exact key
+   */
+  static async clearPattern(pattern) {
+    const prefixedPattern = _IgniterCallerCacheUtils.getPrefixedKey(pattern);
+    const regex = _IgniterCallerCacheUtils.globToRegex(prefixedPattern);
+    for (const key of _IgniterCallerCacheUtils.cache.keys()) {
+      if (regex.test(key)) {
+        _IgniterCallerCacheUtils.cache.delete(key);
+      }
+    }
+    if (_IgniterCallerCacheUtils.store) {
+      console.warn(
+        "IgniterCaller: Pattern-based cache invalidation in store requires manual implementation"
+      );
+    }
+  }
+  /**
+   * Clears all cache entries.
+   */
+  static async clearAll() {
+    _IgniterCallerCacheUtils.cache.clear();
+    if (_IgniterCallerCacheUtils.store) {
+      console.warn(
+        "IgniterCaller: clearAll() only clears in-memory cache. Store cache requires manual cleanup."
+      );
+    }
+  }
+  /**
+   * Adds the configured prefix to a key.
+   */
+  static getPrefixedKey(key) {
+    const prefix = _IgniterCallerCacheUtils.storeOptions.keyPrefix || "";
+    return `${prefix}${key}`;
+  }
+  /**
+   * Converts a glob pattern to a RegExp.
+   */
+  static globToRegex(pattern) {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
+    return new RegExp(`^${escaped}$`);
+  }
+};
+_IgniterCallerCacheUtils.cache = /* @__PURE__ */ new Map();
+_IgniterCallerCacheUtils.store = null;
+_IgniterCallerCacheUtils.storeOptions = {
+  ttl: 3600,
+  keyPrefix: "igniter:caller:",
+  fallbackToFetch: true
+};
+var IgniterCallerCacheUtils = _IgniterCallerCacheUtils;
+
+// src/utils/schema.ts
+var IgniterCallerSchemaUtils = class _IgniterCallerSchemaUtils {
+  /**
+   * Matches a URL path against schema map paths (supports path parameters).
+   *
+   * @example
+   * ```ts
+   * matchPath('/users/123', '/users/:id') // { matched: true, params: { id: '123' } }
+   * matchPath('/users', '/users/:id')     // { matched: false }
+   * ```
+   */
+  static matchPath(actualPath, schemaPath) {
+    if (actualPath === schemaPath) {
+      return { matched: true, params: {} };
+    }
+    const paramNames = [];
+    const regexPattern = schemaPath.replace(/:[^/]+/g, (match2) => {
+      paramNames.push(match2.slice(1));
+      return "([^/]+)";
+    }).replace(/\//g, "\\/");
+    const regex = new RegExp(`^${regexPattern}$`);
+    const match = actualPath.match(regex);
+    if (!match) {
+      return { matched: false };
+    }
+    const params = {};
+    for (let i = 0; i < paramNames.length; i++) {
+      params[paramNames[i]] = match[i + 1];
+    }
+    return { matched: true, params };
+  }
+  /**
+   * Finds the schema for a given path and method from the schema map.
+   */
+  static findSchema(schemaMap, path, method) {
+    if (!schemaMap) {
+      return { schema: void 0, params: {} };
+    }
+    const exactMatch = schemaMap[path]?.[method];
+    if (exactMatch) {
+      return { schema: exactMatch, params: {} };
+    }
+    for (const [schemaPath, methods] of Object.entries(schemaMap)) {
+      const matchResult = _IgniterCallerSchemaUtils.matchPath(path, schemaPath);
+      if (matchResult.matched) {
+        const schema = methods?.[method];
+        if (schema) {
+          return { schema, params: matchResult.params || {} };
+        }
+      }
+    }
+    return { schema: void 0, params: {} };
+  }
+  /**
+   * Validates input using StandardSchemaV1.
+   *
+   * If the schema provides `~standard.validate`, it will be used.
+   * Otherwise, returns the input as-is.
+   */
+  static async validateWithStandardSchema(schema, input) {
+    const standard = schema?.["~standard"];
+    if (!standard?.validate) {
+      return input;
+    }
+    const result = await standard.validate(input);
+    if (result?.issues?.length) {
+      throw {
+        issues: result.issues,
+        _standardSchemaValidationError: true
+      };
+    }
+    return result?.value ?? input;
+  }
+  /**
+   * Validates request body against schema.
+   *
+   * @returns Validated data or throws/logs error based on validation mode
+   */
+  static async validateRequest(data, schema, options, context, logger) {
+    if (!schema || options?.mode === "off") {
+      return data;
+    }
+    try {
+      const validated = await _IgniterCallerSchemaUtils.validateWithStandardSchema(schema, data);
+      return validated;
+    } catch (error) {
+      if (options?.onValidationError && error?._standardSchemaValidationError) {
+        options.onValidationError(error, { ...context, statusCode: 0 });
+      }
+      if (options?.mode === "soft") {
+        logger?.warn("Request validation failed (soft mode)", {
+          url: context.url,
+          method: context.method,
+          errors: error?.issues
+        });
+        return data;
+      }
+      throw new IgniterCallerError({
+        code: "IGNITER_CALLER_REQUEST_VALIDATION_FAILED",
+        message: `Request validation failed for ${context.method} ${context.url}`,
+        statusCode: 400,
+        details: error?.issues,
+        operation: "validateRequest"
+      });
+    }
+  }
+  /**
+   * Validates response data against schema.
+   *
+   * @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") {
+      return data;
+    }
+    try {
+      const validated = await _IgniterCallerSchemaUtils.validateWithStandardSchema(schema, data);
+      return validated;
+    } catch (error) {
+      if (options?.onValidationError && error?._standardSchemaValidationError) {
+        options.onValidationError(error, { ...context, statusCode });
+      }
+      if (options?.mode === "soft") {
+        logger?.warn("Response validation failed (soft mode)", {
+          url: context.url,
+          method: context.method,
+          statusCode,
+          errors: error?.issues
+        });
+        return data;
+      }
+      throw new IgniterCallerError({
+        code: "IGNITER_CALLER_RESPONSE_VALIDATION_FAILED",
+        message: `Response validation failed for ${context.method} ${context.url} (${statusCode})`,
+        statusCode,
+        details: error?.issues,
+        operation: "validateResponse"
+      });
+    }
+  }
+};
+
+// src/utils/url.ts
+var IgniterCallerUrlUtils = class {
+  static buildUrl(params) {
+    const { url, baseURL, query } = params;
+    let fullUrl = url;
+    if (baseURL && !/^https?:\/\//i.test(url)) {
+      fullUrl = baseURL + url;
+    }
+    if (query && Object.keys(query).length > 0) {
+      const queryParams = new URLSearchParams(
+        Object.entries(query).map(([key, value]) => [key, String(value)])
+      ).toString();
+      fullUrl += (fullUrl.includes("?") ? "&" : "?") + queryParams;
+    }
+    return fullUrl;
+  }
+};
+
+// src/builder/igniter-caller-request.builder.ts
+var IgniterCallerRequestBuilder = class {
+  constructor(params) {
+    this.options = {
+      method: "GET",
+      url: "",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      timeout: 3e4,
+      cache: "default"
+    };
+    if (params.baseURL) this.options.baseURL = params.baseURL;
+    if (params.defaultHeaders) {
+      this.options.headers = {
+        ...this.options.headers,
+        ...params.defaultHeaders
+      };
+    }
+    if (params.defaultCookies) {
+      const cookieStr = Object.entries(params.defaultCookies).map(([k, v]) => `${k}=${v}`).join("; ");
+      this.options.headers = { ...this.options.headers, Cookie: cookieStr };
+    }
+    this.logger = params.logger;
+    this.requestInterceptors = params.requestInterceptors;
+    this.responseInterceptors = params.responseInterceptors;
+    this.eventEmitter = params.eventEmitter;
+    this.schemas = params.schemas;
+    this.schemaValidation = params.schemaValidation;
+  }
+  /**
+   * Overrides the logger for this request chain.
+   */
+  withLogger(logger) {
+    this.logger = logger;
+    return this;
+  }
+  method(method) {
+    this.options.method = method;
+    return this;
+  }
+  url(url) {
+    this.options.url = url;
+    return this;
+  }
+  body(body) {
+    this.options.body = body;
+    return this;
+  }
+  params(params) {
+    this.options.params = params;
+    return this;
+  }
+  headers(headers) {
+    this.options.headers = { ...this.options.headers, ...headers };
+    return this;
+  }
+  timeout(timeout) {
+    this.options.timeout = timeout;
+    return this;
+  }
+  cache(cache, key) {
+    this.options.cache = cache;
+    this.cacheKey = key;
+    return this;
+  }
+  /**
+   * Configures retry behavior for failed requests.
+   */
+  retry(maxAttempts, options) {
+    this.retryOptions = { maxAttempts, ...options };
+    return this;
+  }
+  /**
+   * Provides a fallback value if the request fails.
+   */
+  fallback(fn) {
+    this.fallbackFn = fn;
+    return this;
+  }
+  /**
+   * Sets cache stale time in milliseconds.
+   */
+  stale(milliseconds) {
+    this.staleTime = milliseconds;
+    return this;
+  }
+  responseType(schema) {
+    this.options.responseSchema = schema;
+    return this;
+  }
+  /**
+   * Downloads a file via GET request.
+   */
+  getFile(url) {
+    this.options.method = "GET";
+    this.options.url = url;
+    return {
+      execute: async () => {
+        const {
+          url: finalUrl,
+          requestInit,
+          controller,
+          timeoutId
+        } = this.buildRequest();
+        this.logger?.debug("IgniterCaller.getFile started", { url: finalUrl });
+        try {
+          const response = await fetch(finalUrl, {
+            ...requestInit,
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          if (!response.ok) {
+            const errorText = await response.text().catch(() => "");
+            return {
+              file: null,
+              error: new IgniterCallerError({
+                code: "IGNITER_CALLER_HTTP_ERROR",
+                operation: "download",
+                message: errorText || `HTTP error! status: ${response.status}`,
+                statusText: response.statusText,
+                statusCode: response.status,
+                logger: this.logger,
+                metadata: { url: finalUrl }
+              })
+            };
+          }
+          const data = await response.blob();
+          const contentType = response.headers.get("content-type");
+          const extension = contentType?.split("/")[1];
+          const filenameHeader = response.headers.get("content-disposition");
+          const filename = filenameHeader?.split("filename=")[1];
+          const filenameExtension = filename?.split(".").pop();
+          if (typeof File === "undefined") {
+            return {
+              file: null,
+              error: new IgniterCallerError({
+                code: "IGNITER_CALLER_UNKNOWN_ERROR",
+                operation: "download",
+                message: "`File` is not available in this runtime. Consider using `response.blob()` directly.",
+                logger: this.logger,
+                metadata: { url: finalUrl }
+              })
+            };
+          }
+          const file = new File(
+            [data],
+            filename || `file.${extension || filenameExtension || "unknown"}`
+          );
+          this.logger?.info("IgniterCaller.getFile success", {
+            url: finalUrl,
+            size: file.size,
+            type: file.type
+          });
+          return { file, error: null };
+        } catch (error) {
+          clearTimeout(timeoutId);
+          if (error instanceof Error && error.name === "AbortError") {
+            return {
+              file: null,
+              error: new IgniterCallerError({
+                code: "IGNITER_CALLER_TIMEOUT",
+                operation: "download",
+                message: `Request timeout after ${this.options.timeout || 3e4}ms`,
+                statusCode: 408,
+                logger: this.logger,
+                metadata: { url: finalUrl },
+                cause: error
+              })
+            };
+          }
+          return {
+            file: null,
+            error: new IgniterCallerError({
+              code: "IGNITER_CALLER_UNKNOWN_ERROR",
+              operation: "download",
+              message: error?.message || "Failed to download file",
+              logger: this.logger,
+              metadata: { url: finalUrl },
+              cause: error
+            })
+          };
+        }
+      }
+    };
+  }
+  async execute() {
+    const effectiveCacheKey = this.cacheKey || this.options.url;
+    if (effectiveCacheKey && this.staleTime) {
+      const cached = await IgniterCallerCacheUtils.get(
+        effectiveCacheKey,
+        this.staleTime
+      );
+      if (cached !== void 0) {
+        this.logger?.debug("IgniterCaller.execute cache hit", {
+          key: effectiveCacheKey
+        });
+        const cachedResult = { data: cached, error: void 0 };
+        await this.emitEvent(cachedResult);
+        return cachedResult;
+      }
+    }
+    const result = await this.executeWithRetry();
+    if (result.error && this.fallbackFn) {
+      this.logger?.debug("IgniterCaller.execute applying fallback", {
+        error: result.error
+      });
+      const fallbackResult = { data: this.fallbackFn(), error: void 0 };
+      await this.emitEvent(fallbackResult);
+      return fallbackResult;
+    }
+    if (!result.error && result.data !== void 0 && effectiveCacheKey) {
+      await IgniterCallerCacheUtils.set(
+        effectiveCacheKey,
+        result.data,
+        this.staleTime
+      );
+    }
+    await this.emitEvent(result);
+    return result;
+  }
+  async executeWithRetry() {
+    const maxAttempts = this.retryOptions?.maxAttempts || 1;
+    const baseDelay = this.retryOptions?.baseDelay || 1e3;
+    const backoff = this.retryOptions?.backoff || "linear";
+    const retryOnStatus = this.retryOptions?.retryOnStatus || [
+      408,
+      429,
+      500,
+      502,
+      503,
+      504
+    ];
+    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
+        });
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+      const result = await this.executeSingleRequest();
+      if (!result.error) {
+        return result;
+      }
+      const shouldRetry = result.error instanceof IgniterCallerError && result.error.statusCode && retryOnStatus.includes(result.error.statusCode);
+      if (!shouldRetry || attempt === maxAttempts - 1) {
+        return result;
+      }
+      lastError = result.error;
+    }
+    return {
+      data: void 0,
+      error: lastError
+    };
+  }
+  async executeSingleRequest() {
+    const { responseSchema } = this.options;
+    let { url, requestInit, controller, timeoutId } = this.buildRequest();
+    this.logger?.debug("IgniterCaller.execute started", {
+      method: this.options.method,
+      url
+    });
+    if (this.requestInterceptors && this.requestInterceptors.length > 0) {
+      let modifiedOptions = { ...this.options, url };
+      for (const interceptor of this.requestInterceptors) {
+        modifiedOptions = await interceptor(modifiedOptions);
+      }
+      this.options = modifiedOptions;
+      const rebuilt = this.buildRequest();
+      url = rebuilt.url;
+      requestInit = rebuilt.requestInit;
+      controller = rebuilt.controller;
+      timeoutId = rebuilt.timeoutId;
+    }
+    if (this.schemas && this.options.body) {
+      const { schema: endpointSchema } = IgniterCallerSchemaUtils.findSchema(
+        this.schemas,
+        url,
+        this.options.method
+      );
+      if (endpointSchema?.request) {
+        try {
+          await IgniterCallerSchemaUtils.validateRequest(
+            this.options.body,
+            endpointSchema.request,
+            this.schemaValidation,
+            { url, method: this.options.method },
+            this.logger
+          );
+        } catch (error) {
+          return {
+            data: void 0,
+            error
+          };
+        }
+      }
+    }
+    try {
+      const httpResponse = await fetch(url, {
+        ...requestInit,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (!httpResponse.ok) {
+        const errorText = await httpResponse.text().catch(() => "");
+        return {
+          data: void 0,
+          error: new IgniterCallerError({
+            code: "IGNITER_CALLER_HTTP_ERROR",
+            operation: "execute",
+            message: errorText || `HTTP error! status: ${httpResponse.status}`,
+            statusText: httpResponse.statusText,
+            statusCode: httpResponse.status,
+            logger: this.logger,
+            metadata: {
+              method: this.options.method,
+              url
+            }
+          })
+        };
+      }
+      const contentType = httpResponse.headers.get("content-type");
+      const data = contentType?.includes("application/json") ? await httpResponse.json() : await httpResponse.text();
+      let validatedData = data;
+      if (this.schemas) {
+        const { schema: endpointSchema } = IgniterCallerSchemaUtils.findSchema(
+          this.schemas,
+          url,
+          this.options.method
+        );
+        const responseSchema2 = endpointSchema?.responses?.[httpResponse.status];
+        if (responseSchema2) {
+          try {
+            validatedData = await IgniterCallerSchemaUtils.validateResponse(
+              data,
+              responseSchema2,
+              httpResponse.status,
+              this.schemaValidation,
+              { url, method: this.options.method },
+              this.logger
+            );
+          } catch (error) {
+            return {
+              data: void 0,
+              error
+            };
+          }
+        }
+      }
+      if (responseSchema) {
+        const result = responseSchema.safeParse(data);
+        if (!result.success) {
+          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: 500,
+              metadata: {
+                method: this.options.method,
+                url
+              },
+              cause: result.error
+            })
+          };
+        }
+        let response2 = {
+          data: result.data,
+          error: void 0
+        };
+        if (this.responseInterceptors && this.responseInterceptors.length > 0) {
+          for (const interceptor of this.responseInterceptors) {
+            response2 = await interceptor(response2);
+          }
+        }
+        return response2;
+      }
+      let response = {
+        data: validatedData,
+        error: void 0
+      };
+      if (this.responseInterceptors && this.responseInterceptors.length > 0) {
+        for (const interceptor of this.responseInterceptors) {
+          response = await interceptor(response);
+        }
+      }
+      return response;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        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
+          })
+        };
+      }
+      return {
+        data: void 0,
+        error: new IgniterCallerError({
+          code: "IGNITER_CALLER_UNKNOWN_ERROR",
+          operation: "execute",
+          message: error?.message || "Unknown error occurred during request",
+          statusCode: 500,
+          logger: this.logger,
+          metadata: {
+            method: this.options.method,
+            url
+          },
+          cause: error
+        })
+      };
+    }
+  }
+  buildRequest() {
+    const { method, url, body, params, headers, timeout, baseURL, cache } = this.options;
+    const fullUrl = IgniterCallerUrlUtils.buildUrl({
+      url,
+      baseURL,
+      query: params
+    });
+    const rawBody = IgniterCallerBodyUtils.isRawBody(body);
+    const finalHeaders = IgniterCallerBodyUtils.normalizeHeadersForBody(
+      headers,
+      body
+    );
+    const requestInit = {
+      method,
+      headers: finalHeaders,
+      cache,
+      ...body && method !== "GET" && method !== "HEAD" ? { body: rawBody ? body : JSON.stringify(body) } : {}
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout || 3e4);
+    return {
+      url: fullUrl,
+      requestInit,
+      controller,
+      timeoutId
+    };
+  }
+  /**
+   * 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/igniter-caller-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());
+    }
+    const callbacks = this.patternListeners.get(pattern);
+    if (callbacks) {
+      callbacks.add(callback);
+    }
+    return () => {
+      const callbacks2 = this.patternListeners.get(pattern);
+      if (callbacks2) {
+        callbacks2.delete(callback);
+        if (callbacks2.size === 0) {
+          this.patternListeners.delete(pattern);
+        }
+      }
+    };
+  }
+  /**
+   * Removes a specific listener or all listeners for a pattern.
+   */
+  off(pattern, callback) {
+    if (typeof pattern === "string") {
+      if (callback !== void 0) {
+        this.listeners.get(pattern)?.delete(callback);
+      } else {
+        this.listeners.delete(pattern);
+      }
+    } else {
+      if (callback !== void 0) {
+        this.patternListeners.get(pattern)?.delete(callback);
+      } else {
+        this.patternListeners.delete(pattern);
+      }
+    }
+  }
+  /**
+   * Emits an event to all matching listeners.
+   *
+   * @internal
+   */
+  async emit(url, method, result) {
+    const context = {
+      url,
+      method,
+      timestamp: Date.now()
+    };
+    const exactListeners = this.listeners.get(url);
+    if (exactListeners) {
+      for (const callback of exactListeners) {
+        try {
+          await callback(result, context);
+        } catch (error) {
+          console.error("Error in IgniterCaller event listener:", error);
+        }
+      }
+    }
+    for (const [pattern, callbacks] of this.patternListeners.entries()) {
+      if (pattern.test(url)) {
+        for (const callback of callbacks) {
+          try {
+            await callback(result, context);
+          } catch (error) {
+            console.error("Error in IgniterCaller event listener:", error);
+          }
+        }
+      }
+    }
+  }
+  /**
+   * Removes all listeners.
+   */
+  clear() {
+    this.listeners.clear();
+    this.patternListeners.clear();
+  }
+};
+
+// src/core/igniter-caller.ts
+var _IgniterCaller = class _IgniterCaller {
+  constructor(baseURL, opts) {
+    this.baseURL = baseURL;
+    this.headers = opts?.headers;
+    this.cookies = opts?.cookies;
+    this.logger = opts?.logger;
+    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;
+  }
+  get() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      },
+      schemas: this.schemas,
+      schemaValidation: this.schemaValidation
+    }).method("GET");
+  }
+  post() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      },
+      schemas: this.schemas,
+      schemaValidation: this.schemaValidation
+    }).method("POST");
+  }
+  put() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      },
+      schemas: this.schemas,
+      schemaValidation: this.schemaValidation
+    }).method("PUT");
+  }
+  patch() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      },
+      schemas: this.schemas,
+      schemaValidation: this.schemaValidation
+    }).method("PATCH");
+  }
+  delete() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      },
+      schemas: this.schemas,
+      schemaValidation: this.schemaValidation
+    }).method("DELETE");
+  }
+  request() {
+    return new IgniterCallerRequestBuilder({
+      baseURL: this.baseURL,
+      defaultHeaders: this.headers,
+      defaultCookies: this.cookies,
+      logger: this.logger,
+      requestInterceptors: this.requestInterceptors,
+      responseInterceptors: this.responseInterceptors,
+      eventEmitter: async (url, method, result) => {
+        await _IgniterCaller.emitEvent(url, method, result);
+      }
+    });
+  }
+  /**
+   * Executes multiple requests in parallel and returns results as an array.
+   *
+   * This is useful for batching independent API calls.
+   */
+  static async batch(requests) {
+    return Promise.all(requests);
+  }
+  /**
+   * Registers a global event listener for HTTP responses.
+   *
+   * This allows observing API responses across the application for:
+   * - Debugging and logging
+   * - Real-time monitoring
+   * - Cache invalidation triggers
+   * - Analytics and telemetry
+   *
+   * @param pattern URL string (exact match) or RegExp pattern
+   * @param callback Function to execute when a response matches
+   * @returns Cleanup function to remove the listener
+   *
+   * @example
+   * ```ts
+   * // Listen to all user endpoints
+   * const cleanup = IgniterCaller.on(/^\/users/, (result, context) => {
+   *   console.log(`${context.method} ${context.url}`, result)
+   * })
+   *
+   * // Cleanup when done
+   * cleanup()
+   * ```
+   */
+  static on(pattern, callback) {
+    return _IgniterCaller.events.on(pattern, callback);
+  }
+  /**
+   * Removes event listeners for a pattern.
+   */
+  static off(pattern, callback) {
+    _IgniterCaller.events.off(pattern, callback);
+  }
+  /**
+   * Invalidates a specific cache entry.
+   *
+   * This is useful after mutations to ensure fresh data on next fetch.
+   *
+   * @example
+   * ```ts
+   * // After creating a user
+   * await api.post().url('/users').body(newUser).execute()
+   * await IgniterCaller.invalidate('/users') // Clear users list cache
+   * ```
+   */
+  static async invalidate(key) {
+    await IgniterCallerCacheUtils.clear(key);
+  }
+  /**
+   * Invalidates all cache entries matching a pattern.
+   *
+   * @param pattern Glob pattern (e.g., '/users/*') or exact key
+   *
+   * @example
+   * ```ts
+   * // Invalidate all user-related caches
+   * await IgniterCaller.invalidatePattern('/users/*')
+   * ```
+   */
+  static async invalidatePattern(pattern) {
+    await IgniterCallerCacheUtils.clearPattern(pattern);
+  }
+  /**
+   * Emits an event to all registered listeners.
+   *
+   * @internal
+   */
+  static async emitEvent(url, method, result) {
+    await _IgniterCaller.events.emit(url, method, result);
+  }
+};
+/** Global event emitter for observing HTTP responses */
+_IgniterCaller.events = new IgniterCallerEvents();
+var IgniterCaller = _IgniterCaller;
+
+// src/utils/testing.ts
+var IgniterCallerMock = class {
+  /**
+   * Creates a successful mock response.
+   */
+  static mockResponse(data) {
+    return { data, error: void 0 };
+  }
+  /**
+   * Creates an error mock response.
+   */
+  static mockError(code, message = "Mock error") {
+    return {
+      data: void 0,
+      error: new IgniterCallerError({
+        code,
+        operation: "execute",
+        message
+      })
+    };
+  }
+  /**
+   * Creates a successful file download mock.
+   */
+  static mockFile(filename, content) {
+    const blob = typeof content === "string" ? new Blob([content]) : content;
+    const file = new File([blob], filename);
+    return { file, error: null };
+  }
+  /**
+   * Creates a failed file download mock.
+   */
+  static mockFileError(message = "Mock file error") {
+    return {
+      file: null,
+      error: new IgniterCallerError({
+        code: "IGNITER_CALLER_UNKNOWN_ERROR",
+        operation: "download",
+        message
+      })
+    };
+  }
+};
+
+exports.IgniterCaller = IgniterCaller;
+exports.IgniterCallerBodyUtils = IgniterCallerBodyUtils;
+exports.IgniterCallerBuilder = IgniterCallerBuilder;
+exports.IgniterCallerCacheUtils = IgniterCallerCacheUtils;
+exports.IgniterCallerError = IgniterCallerError;
+exports.IgniterCallerEvents = IgniterCallerEvents;
+exports.IgniterCallerMock = IgniterCallerMock;
+exports.IgniterCallerRequestBuilder = IgniterCallerRequestBuilder;
+exports.IgniterCallerSchemaUtils = IgniterCallerSchemaUtils;
+exports.IgniterCallerUrlUtils = IgniterCallerUrlUtils;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map