@igniter-js/caller 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,738 @@
+import { StandardSchemaV1, IgniterLogger, IgniterError } from '@igniter-js/core';
+import { z } from 'zod';
+
+/**
+ * Supported HTTP methods for `IgniterCaller` requests.
+ *
+ * This type is designed to remain stable when extracted to `@igniter-js/caller`.
+ */
+type IgniterCallerHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+
+/**
+ * Base configuration options for HTTP requests.
+ */
+interface IgniterCallerBaseRequestOptions {
+    /** Base URL for all requests (e.g. `https://api.example.com`). */
+    baseURL?: string;
+    /** Default headers merged into each request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * Complete request configuration extending base options.
+ */
+interface IgniterCallerRequestOptions<TBody = unknown> extends IgniterCallerBaseRequestOptions {
+    method: IgniterCallerHttpMethod;
+    /** Endpoint URL path. If absolute, `baseURL` is ignored. */
+    url: string;
+    body?: TBody;
+    params?: Record<string, string | number | boolean>;
+    responseSchema?: z.ZodSchema<any>;
+    cache?: RequestCache;
+}
+
+/**
+ * Response object containing either successful data or an error.
+ */
+interface IgniterCallerApiResponse<T> {
+    data?: T;
+    error?: Error;
+}
+/**
+ * Response object for file downloads.
+ */
+interface IgniterCallerFileResponse {
+    file: File | null;
+    error: Error | null;
+}
+
+/**
+ * Function that can modify request configuration before execution.
+ */
+type IgniterCallerRequestInterceptor = (config: IgniterCallerRequestOptions) => Promise<IgniterCallerRequestOptions> | IgniterCallerRequestOptions;
+/**
+ * Function that can transform responses after execution.
+ */
+type IgniterCallerResponseInterceptor = <T>(response: IgniterCallerApiResponse<T>) => Promise<IgniterCallerApiResponse<T>> | IgniterCallerApiResponse<T>;
+
+/**
+ * HTTP methods supported for schema mapping.
+ */
+type IgniterCallerSchemaMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Schema definition for a single endpoint.
+ *
+ * Maps status codes to response schemas with optional request schema.
+ */
+type IgniterCallerEndpointSchema<TRequest extends StandardSchemaV1 = any, TResponses extends Record<number, StandardSchemaV1> = Record<number, StandardSchemaV1>> = {
+    /** Request body schema (optional) */
+    request?: TRequest;
+    /** Response schemas by status code */
+    responses: TResponses;
+};
+/**
+ * Schema map for multiple endpoints.
+ *
+ * Structure: { [path]: { [method]: EndpointSchema } }
+ *
+ * @example
+ * ```ts
+ * const schemas = {
+ *   '/users': {
+ *     GET: {
+ *       responses: {
+ *         200: z.array(UserSchema),
+ *         401: z.object({ error: z.string() }),
+ *       },
+ *     },
+ *     POST: {
+ *       request: CreateUserSchema,
+ *       responses: {
+ *         201: UserSchema,
+ *         400: z.object({ errors: z.array(z.string()) }),
+ *       },
+ *     },
+ *   },
+ *   '/users/:id': {
+ *     GET: {
+ *       responses: {
+ *         200: UserSchema,
+ *         404: z.object({ error: z.string() }),
+ *       },
+ *     },
+ *   },
+ * }
+ * ```
+ */
+type IgniterCallerSchemaMap = Record<string, Partial<Record<IgniterCallerSchemaMethod, IgniterCallerEndpointSchema<any, any>>>>;
+/**
+ * Extract path parameters from a URL pattern.
+ *
+ * @example
+ * ```ts
+ * type Params = ExtractPathParams<'/users/:id/posts/:postId'>
+ * // { id: string; postId: string }
+ * ```
+ */
+type ExtractPathParams<T extends string> = T extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof ExtractPathParams<`/${Rest}`>]: string;
+} : T extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : Record<never, never>;
+/**
+ * Infer request type from endpoint schema.
+ */
+type InferRequestType<T> = T extends IgniterCallerEndpointSchema<infer R, any> ? R extends StandardSchemaV1 ? StandardSchemaV1.InferInput<R> : never : never;
+/**
+ * Infer response type by status code from endpoint schema.
+ */
+type InferResponseType<T, Status extends number> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? Status extends keyof Responses ? Responses[Status] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[Status]> : never : never : never;
+/**
+ * Infer all possible response types (union) from endpoint schema.
+ */
+type InferAllResponseTypes<T> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? Responses extends Record<number, StandardSchemaV1> ? {
+    [K in keyof Responses]: Responses[K] extends StandardSchemaV1 ? {
+        status: K;
+        data: StandardSchemaV1.InferOutput<Responses[K]>;
+    } : never;
+}[keyof Responses] : never : never;
+/**
+ * Options for schema validation behavior.
+ */
+interface IgniterCallerSchemaValidationOptions {
+    /**
+     * Validation mode:
+     * - 'strict': Throw error on validation failure (default)
+     * - 'soft': Log error but return raw data
+     * - 'off': Skip validation entirely
+     */
+    mode?: 'strict' | 'soft' | 'off';
+    /**
+     * Custom error handler for validation failures.
+     */
+    onValidationError?: (error: any, context: {
+        url: string;
+        method: string;
+        statusCode: number;
+    }) => void;
+}
+
+/**
+ * Store adapter interface compatible with Igniter.js Store.
+ *
+ * This allows IgniterCaller to use any store implementation (Redis, in-memory, etc.)
+ * for persistent caching across requests and deployments.
+ */
+interface IgniterCallerStoreAdapter<TClient = any> {
+    /** The underlying client instance (e.g., Redis client). */
+    readonly client: TClient;
+    /**
+     * Retrieves a value from the store by its key.
+     * @param key The key to retrieve.
+     * @returns The value if found (auto-deserialized), otherwise null.
+     */
+    get<T = any>(key: string): Promise<T | null>;
+    /**
+     * Stores a value in the store.
+     * @param key The key to store the value under.
+     * @param value The value to store (will be auto-serialized).
+     * @param options Configuration options, such as TTL.
+     */
+    set(key: string, value: any, options?: {
+        ttl?: number;
+        [key: string]: any;
+    }): Promise<void>;
+    /**
+     * Deletes a key from the store.
+     * @param key The key to delete.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Checks if a key exists in the store.
+     * @param key The key to check.
+     * @returns `true` if the key exists, otherwise `false`.
+     */
+    has(key: string): Promise<boolean>;
+}
+/**
+ * Configuration options for store-based caching.
+ */
+interface IgniterCallerStoreOptions {
+    /** Default TTL in seconds for cached entries (default: 3600 = 1 hour). */
+    ttl?: number;
+    /** Prefix for all cache keys (default: 'igniter:caller:'). */
+    keyPrefix?: string;
+    /** Whether to fallback to fetch cache when store is unavailable (default: true). */
+    fallbackToFetch?: boolean;
+}
+
+type IgniterCallerBuilderState<TSchemas extends IgniterCallerSchemaMap = any> = {
+    baseURL?: string;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    logger?: IgniterLogger;
+    requestInterceptors?: IgniterCallerRequestInterceptor[];
+    responseInterceptors?: IgniterCallerResponseInterceptor[];
+    store?: IgniterCallerStoreAdapter;
+    storeOptions?: IgniterCallerStoreOptions;
+    schemas?: TSchemas;
+    schemaValidation?: IgniterCallerSchemaValidationOptions;
+};
+type IgniterCallerBuilderFactory<TCaller, TSchemas extends IgniterCallerSchemaMap = any> = (state: IgniterCallerBuilderState<TSchemas>) => TCaller;
+/**
+ * Builder used by developers to initialize the `IgniterCaller` client.
+ *
+ * This API is designed to remain stable when extracted to `@igniter-js/caller`.
+ */
+declare class IgniterCallerBuilder<TCaller = unknown, TSchemas extends IgniterCallerSchemaMap = any> {
+    private readonly state;
+    private readonly factory;
+    private constructor();
+    /**
+     * Creates a new builder instance.
+     */
+    static create<TCaller, TSchemas extends IgniterCallerSchemaMap = any>(factory: IgniterCallerBuilderFactory<TCaller, TSchemas>): IgniterCallerBuilder<TCaller, TSchemas>;
+    /** Sets the base URL for all requests. */
+    withBaseUrl(baseURL: string): IgniterCallerBuilder<TCaller, TSchemas>;
+    /** Merges default headers for all requests. */
+    withHeaders(headers: Record<string, string>): IgniterCallerBuilder<TCaller>;
+    /** Sets default cookies (sent as the `Cookie` header). */
+    withCookies(cookies: Record<string, string>): IgniterCallerBuilder<TCaller>;
+    /** Attaches a logger instance. */
+    withLogger(logger: IgniterLogger): IgniterCallerBuilder<TCaller, TSchemas>;
+    /** Adds a request interceptor that runs before each request. */
+    withRequestInterceptor(interceptor: IgniterCallerRequestInterceptor): IgniterCallerBuilder<TCaller, TSchemas>;
+    /** Adds a response interceptor that runs after each request. */
+    withResponseInterceptor(interceptor: IgniterCallerResponseInterceptor): IgniterCallerBuilder<TCaller, TSchemas>;
+    /**
+     * Configures a persistent store adapter for caching.
+     *
+     * When configured, cache operations will use the store (e.g., Redis)
+     * instead of in-memory cache, enabling persistent cache across deployments.
+     */
+    withStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): IgniterCallerBuilder<TCaller, TSchemas>;
+    /**
+     * Configures schema-based type safety and validation.
+     *
+     * Enables automatic type inference for requests/responses based on
+     * route and method, with optional runtime validation via Zod.
+     *
+     * @example
+     * ```ts
+     * const api = IgniterCaller.create()
+     *   .withSchemas({
+     *     '/users': {
+     *       GET: {
+     *         responses: {
+     *           200: z.array(UserSchema),
+     *           401: ErrorSchema,
+     *         },
+     *       },
+     *       POST: {
+     *         request: CreateUserSchema,
+     *         responses: {
+     *           201: UserSchema,
+     *           400: ValidationErrorSchema,
+     *         },
+     *       },
+     *     },
+     *   })
+     *   .build()
+     * ```
+     */
+    withSchemas<TNewSchemas extends IgniterCallerSchemaMap>(schemas: TNewSchemas, validation?: IgniterCallerSchemaValidationOptions): IgniterCallerBuilder<TCaller, TNewSchemas>;
+    /**
+     * Builds the `IgniterCaller` instance.
+     */
+    build(): TCaller;
+}
+
+/**
+ * Retry configuration for failed requests.
+ */
+interface IgniterCallerRetryOptions {
+    /** Maximum number of retry attempts. */
+    maxAttempts: number;
+    /** Backoff strategy between retries. */
+    backoff?: 'linear' | 'exponential';
+    /** Base delay in milliseconds (default: 1000). */
+    baseDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]). */
+    retryOnStatus?: number[];
+}
+
+/**
+ * Fluent request builder for `IgniterCaller`.
+ */
+declare class IgniterCallerRequestBuilder {
+    private options;
+    private logger?;
+    private retryOptions?;
+    private fallbackFn?;
+    private cacheKey?;
+    private staleTime?;
+    private requestInterceptors?;
+    private responseInterceptors?;
+    private eventEmitter?;
+    private schemas?;
+    private schemaValidation?;
+    constructor(params: {
+        baseURL?: string;
+        defaultHeaders?: Record<string, string>;
+        defaultCookies?: Record<string, string>;
+        logger?: IgniterLogger;
+        requestInterceptors?: IgniterCallerRequestInterceptor[];
+        responseInterceptors?: IgniterCallerResponseInterceptor[];
+        eventEmitter?: (url: string, method: string, result: any) => Promise<void>;
+        schemas?: IgniterCallerSchemaMap;
+        schemaValidation?: IgniterCallerSchemaValidationOptions;
+    });
+    /**
+     * Overrides the logger for this request chain.
+     */
+    withLogger(logger: IgniterLogger): this;
+    method(method: IgniterCallerHttpMethod): this;
+    url(url: string): this;
+    body<TBody>(body: TBody): this;
+    params(params: Record<string, string | number | boolean>): this;
+    headers(headers: Record<string, string>): this;
+    timeout(timeout: number): this;
+    cache(cache: RequestCache, key?: string): this;
+    /**
+     * Configures retry behavior for failed requests.
+     */
+    retry(maxAttempts: number, options?: Omit<IgniterCallerRetryOptions, 'maxAttempts'>): this;
+    /**
+     * Provides a fallback value if the request fails.
+     */
+    fallback<T>(fn: () => T): this;
+    /**
+     * Sets cache stale time in milliseconds.
+     */
+    stale(milliseconds: number): this;
+    responseType<T>(schema?: z.ZodSchema<T>): this;
+    /**
+     * Downloads a file via GET request.
+     */
+    getFile(url: string): {
+        execute: () => Promise<IgniterCallerFileResponse>;
+    };
+    execute<T = unknown>(): Promise<IgniterCallerApiResponse<T>>;
+    private executeWithRetry;
+    private executeSingleRequest;
+    private buildRequest;
+    /**
+     * Emits event for this response using injected emitter.
+     */
+    private emitEvent;
+}
+
+/**
+ * Callback function for event listeners.
+ */
+type IgniterCallerEventCallback<T = any> = (result: IgniterCallerApiResponse<T>, context: {
+    url: string;
+    method: string;
+    timestamp: number;
+}) => void | Promise<void>;
+/**
+ * Pattern for matching URLs (string or RegExp).
+ */
+type IgniterCallerUrlPattern = string | RegExp;
+
+/**
+ * HTTP client runtime for Igniter.js.
+ *
+ * This module is intentionally structured to be extracted into a standalone package
+ * in the Igniter.js ecosystem as `@igniter-js/caller`.
+ */
+declare class IgniterCaller {
+    /** Global event emitter for observing HTTP responses */
+    private static readonly events;
+    private baseURL?;
+    private headers?;
+    private cookies?;
+    private logger?;
+    private requestInterceptors?;
+    private responseInterceptors?;
+    private schemas?;
+    private schemaValidation?;
+    constructor(baseURL?: string, opts?: {
+        headers?: Record<string, string>;
+        cookies?: Record<string, string>;
+        logger?: IgniterLogger;
+        requestInterceptors?: IgniterCallerRequestInterceptor[];
+        responseInterceptors?: IgniterCallerResponseInterceptor[];
+        schemas?: IgniterCallerSchemaMap;
+        schemaValidation?: IgniterCallerSchemaValidationOptions;
+    });
+    /**
+     * Canonical initialization entrypoint.
+     *
+     * This is designed to remain stable when extracted to `@igniter-js/caller`.
+     */
+    static create(): IgniterCallerBuilder<IgniterCaller>;
+    /**
+     * Returns a new client with the same config and a new logger.
+     */
+    withLogger(logger: IgniterLogger): IgniterCaller;
+    setBaseURL(baseURL: string): this;
+    setHeaders(headers: Record<string, string>): this;
+    setCookies(cookies: Record<string, string>): this;
+    get(): IgniterCallerRequestBuilder;
+    post(): IgniterCallerRequestBuilder;
+    put(): IgniterCallerRequestBuilder;
+    patch(): IgniterCallerRequestBuilder;
+    delete(): IgniterCallerRequestBuilder;
+    request(): IgniterCallerRequestBuilder;
+    /**
+     * Executes multiple requests in parallel and returns results as an array.
+     *
+     * This is useful for batching independent API calls.
+     */
+    static batch<T extends readonly Promise<IgniterCallerApiResponse<any>>[]>(requests: [...T]): Promise<{
+        [K in keyof T]: T[K] extends Promise<infer R> ? R : never;
+    }>;
+    /**
+     * Registers a global event listener for HTTP responses.
+     *
+     * This allows observing API responses across the application for:
+     * - Debugging and logging
+     * - Real-time monitoring
+     * - Cache invalidation triggers
+     * - Analytics and telemetry
+     *
+     * @param pattern URL string (exact match) or RegExp pattern
+     * @param callback Function to execute when a response matches
+     * @returns Cleanup function to remove the listener
+     *
+     * @example
+     * ```ts
+     * // Listen to all user endpoints
+     * const cleanup = IgniterCaller.on(/^\/users/, (result, context) => {
+     *   console.log(`${context.method} ${context.url}`, result)
+     * })
+     *
+     * // Cleanup when done
+     * cleanup()
+     * ```
+     */
+    static on(pattern: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
+    /**
+     * Removes event listeners for a pattern.
+     */
+    static off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
+    /**
+     * 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 invalidate(key: string): Promise<void>;
+    /**
+     * 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 invalidatePattern(pattern: string): Promise<void>;
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @internal
+     */
+    static emitEvent(url: string, method: string, result: IgniterCallerApiResponse<any>): Promise<void>;
+}
+
+/**
+ * Event emitter for observing HTTP responses across the application.
+ *
+ * This allows developers to listen to API responses globally for:
+ * - Debugging and logging
+ * - Real-time monitoring
+ * - Cache invalidation triggers
+ * - Analytics and telemetry
+ */
+declare class IgniterCallerEvents {
+    private listeners;
+    private patternListeners;
+    /**
+     * 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: IgniterCallerUrlPattern, callback: IgniterCallerEventCallback): () => void;
+    /**
+     * Removes a specific listener or all listeners for a pattern.
+     */
+    off(pattern: IgniterCallerUrlPattern, callback?: IgniterCallerEventCallback): void;
+    /**
+     * Emits an event to all matching listeners.
+     *
+     * @internal
+     */
+    emit(url: string, method: string, result: any): Promise<void>;
+    /**
+     * Removes all listeners.
+     */
+    clear(): void;
+}
+
+type IgniterCallerErrorCode = 'IGNITER_CALLER_HTTP_ERROR' | 'IGNITER_CALLER_TIMEOUT' | 'IGNITER_CALLER_REQUEST_VALIDATION_FAILED' | 'IGNITER_CALLER_RESPONSE_VALIDATION_FAILED' | 'IGNITER_CALLER_UNKNOWN_ERROR';
+type IgniterCallerOperation = 'execute' | 'download' | 'buildRequest' | 'parseResponse' | 'validateRequest' | 'validateResponse';
+/**
+ * Payload used to create an {@link IgniterCallerError}.
+ */
+type IgniterCallerErrorPayload = {
+    /** Machine-readable error code. */
+    code: IgniterCallerErrorCode;
+    /** Where the error happened. */
+    operation: IgniterCallerOperation;
+    /** Human-readable message. */
+    message: string;
+    /** Optional HTTP status code when surfacing errors through HTTP boundaries. */
+    statusCode?: number;
+    /** Optional HTTP status text (when available). */
+    statusText?: string;
+    /** Extra diagnostic details (e.g. response body or schema issues). */
+    details?: unknown;
+    /** Arbitrary metadata for debugging. */
+    metadata?: Record<string, unknown>;
+    /** Optional original cause. */
+    cause?: unknown;
+    /** Optional logger used by IgniterError. */
+    logger?: IgniterLogger;
+};
+/**
+ * Typed error for predictable failures in `IgniterCaller`.
+ *
+ * Designed to be extracted into `@igniter-js/caller`.
+ */
+declare class IgniterCallerError extends IgniterError {
+    readonly code: IgniterCallerErrorCode;
+    readonly operation: IgniterCallerOperation;
+    readonly statusText?: string;
+    readonly cause?: unknown;
+    constructor(payload: IgniterCallerErrorPayload);
+    static is(error: unknown): error is IgniterCallerError;
+}
+
+declare class IgniterCallerBodyUtils {
+    /**
+     * Returns true when the request body should be passed to `fetch` as-is.
+     */
+    static isRawBody(body: unknown): boolean;
+    /**
+     * Removes Content-Type for FormData so fetch can set boundaries automatically.
+     */
+    static normalizeHeadersForBody(headers: Record<string, string> | undefined, body: unknown): Record<string, string> | undefined;
+}
+
+/**
+ * Cache interface for HTTP responses.
+ *
+ * Supports both in-memory caching and persistent store-based caching (Redis, etc).
+ */
+declare class IgniterCallerCacheUtils {
+    private static cache;
+    private static store;
+    private static storeOptions;
+    /**
+     * Configures a persistent store adapter for caching.
+     *
+     * When configured, cache operations will use the store (e.g., Redis)
+     * instead of in-memory cache, enabling persistent cache across deployments.
+     */
+    static setStore(store: IgniterCallerStoreAdapter, options?: IgniterCallerStoreOptions): void;
+    /**
+     * Gets the configured store adapter.
+     */
+    static getStore(): IgniterCallerStoreAdapter | null;
+    /**
+     * Gets cached data if it exists and is not stale.
+     */
+    static get<T>(key: string, staleTime?: number): Promise<T | undefined>;
+    /**
+     * Stores data in cache with current timestamp.
+     */
+    static set(key: string, data: unknown, ttl?: number): Promise<void>;
+    /**
+     * Clears a specific cache entry.
+     */
+    static clear(key: string): Promise<void>;
+    /**
+     * Clears all cache entries matching a pattern.
+     *
+     * @param pattern Glob pattern (e.g., '/users/*') or exact key
+     */
+    static clearPattern(pattern: string): Promise<void>;
+    /**
+     * Clears all cache entries.
+     */
+    static clearAll(): Promise<void>;
+    /**
+     * Adds the configured prefix to a key.
+     */
+    private static getPrefixedKey;
+    /**
+     * Converts a glob pattern to a RegExp.
+     */
+    private static globToRegex;
+}
+
+/**
+ * Utilities for schema matching and validation.
+ *
+ * @internal
+ */
+declare 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: string, schemaPath: string): {
+        matched: boolean;
+        params?: Record<string, string>;
+    };
+    /**
+     * Finds the schema for a given path and method from the schema map.
+     */
+    static findSchema(schemaMap: IgniterCallerSchemaMap | undefined, path: string, method: string): {
+        schema: IgniterCallerEndpointSchema | undefined;
+        params: Record<string, string>;
+    };
+    /**
+     * Validates input using StandardSchemaV1.
+     *
+     * If the schema provides `~standard.validate`, it will be used.
+     * Otherwise, returns the input as-is.
+     */
+    private static validateWithStandardSchema;
+    /**
+     * Validates request body against schema.
+     *
+     * @returns Validated data or throws/logs error based on validation mode
+     */
+    static validateRequest<T>(data: unknown, schema: StandardSchemaV1 | undefined, options: IgniterCallerSchemaValidationOptions | undefined, context: {
+        url: string;
+        method: string;
+    }, logger?: IgniterLogger): Promise<T>;
+    /**
+     * Validates response data against schema.
+     *
+     * @returns Validated data or throws/logs error based on validation mode
+     */
+    static validateResponse<T>(data: unknown, schema: StandardSchemaV1 | undefined, statusCode: number, options: IgniterCallerSchemaValidationOptions | undefined, context: {
+        url: string;
+        method: string;
+    }, logger?: IgniterLogger): Promise<T>;
+}
+
+/**
+ * Testing utilities for `IgniterCaller`.
+ *
+ * Designed to simplify mocking HTTP responses in unit tests.
+ */
+declare class IgniterCallerMock {
+    /**
+     * Creates a successful mock response.
+     */
+    static mockResponse<T>(data: T): IgniterCallerApiResponse<T>;
+    /**
+     * Creates an error mock response.
+     */
+    static mockError<T = never>(code: IgniterCallerErrorCode, message?: string): IgniterCallerApiResponse<T>;
+    /**
+     * Creates a successful file download mock.
+     */
+    static mockFile(filename: string, content: string | Blob): IgniterCallerFileResponse;
+    /**
+     * Creates a failed file download mock.
+     */
+    static mockFileError(message?: string): IgniterCallerFileResponse;
+}
+
+declare class IgniterCallerUrlUtils {
+    static buildUrl(params: {
+        url: string;
+        baseURL?: string;
+        query?: Record<string, string | number | boolean>;
+    }): string;
+}
+
+export { type ExtractPathParams, IgniterCaller, type IgniterCallerApiResponse, type IgniterCallerBaseRequestOptions, IgniterCallerBodyUtils, IgniterCallerBuilder, type IgniterCallerBuilderFactory, type IgniterCallerBuilderState, IgniterCallerCacheUtils, type IgniterCallerEndpointSchema, IgniterCallerError, type IgniterCallerErrorCode, type IgniterCallerErrorPayload, type IgniterCallerEventCallback, IgniterCallerEvents, type IgniterCallerFileResponse, type IgniterCallerHttpMethod, IgniterCallerMock, type IgniterCallerOperation, IgniterCallerRequestBuilder, type IgniterCallerRequestInterceptor, type IgniterCallerRequestOptions, type IgniterCallerResponseInterceptor, type IgniterCallerRetryOptions, type IgniterCallerSchemaMap, type IgniterCallerSchemaMethod, IgniterCallerSchemaUtils, type IgniterCallerSchemaValidationOptions, type IgniterCallerStoreAdapter, type IgniterCallerStoreOptions, type IgniterCallerUrlPattern, IgniterCallerUrlUtils, type InferAllResponseTypes, type InferRequestType, type InferResponseType };