@igniter-js/caller 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -8,6 +8,20 @@ import { z } from 'zod';
  */
 type IgniterCallerHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
 
+/**
+ * Retry configuration for failed requests.
+ */
+interface IgniterCallerRetryOptions {
+    /** Maximum number of retry attempts. */
+    maxAttempts: number;
+    /** Backoff strategy between retries. */
+    backoff?: 'linear' | 'exponential';
+    /** Base delay in milliseconds (default: 1000). */
+    baseDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]). */
+    retryOnStatus?: number[];
+}
+
 /**
  * Base configuration options for HTTP requests.
  */
@@ -31,6 +45,34 @@ interface IgniterCallerRequestOptions<TBody = unknown> extends IgniterCallerBase
     responseSchema?: z.ZodSchema<any>;
     cache?: RequestCache;
 }
+/**
+ * Options for the direct request() method (axios-style).
+ * All options in one object, executes immediately.
+ */
+interface IgniterCallerDirectRequestOptions<TBody = unknown> extends IgniterCallerBaseRequestOptions {
+    /** HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD) */
+    method: IgniterCallerHttpMethod;
+    /** Endpoint URL path. If absolute, `baseURL` is ignored. */
+    url: string;
+    /** Request body (for POST, PUT, PATCH) */
+    body?: TBody;
+    /** URL query parameters */
+    params?: Record<string, string | number | boolean>;
+    /** Cookies to send with the request */
+    cookies?: Record<string, string>;
+    /** Response validation schema (Zod) */
+    responseSchema?: z.ZodSchema<any>;
+    /** Cache strategy */
+    cache?: RequestCache;
+    /** Cache key for stale-while-revalidate */
+    cacheKey?: string;
+    /** Stale time in milliseconds for caching */
+    staleTime?: number;
+    /** Retry configuration */
+    retry?: IgniterCallerRetryOptions;
+    /** Fallback value if request fails */
+    fallback?: () => any;
+}
 
 /**
  * Response object containing either successful data or an error.
@@ -38,14 +80,32 @@ interface IgniterCallerRequestOptions<TBody = unknown> extends IgniterCallerBase
 interface IgniterCallerApiResponse<T> {
     data?: T;
     error?: Error;
+    /** HTTP status code from the response */
+    status?: number;
+    /** Response headers */
+    headers?: Headers;
 }
 /**
  * Response object for file downloads.
+ * @deprecated Use execute() with responseType<File>() instead
  */
 interface IgniterCallerFileResponse {
     file: File | null;
     error: Error | null;
 }
+/**
+ * Supported response content types that can be auto-detected.
+ */
+type IgniterCallerResponseContentType = 'json' | 'xml' | 'csv' | 'text' | 'html' | 'blob' | 'stream' | 'arraybuffer' | 'formdata';
+/**
+ * Content types that support schema validation.
+ */
+type IgniterCallerValidatableContentType = 'json' | 'xml' | 'csv';
+/**
+ * Marker types for responseType() to indicate expected response format.
+ * These are used for typing only and don't affect runtime behavior.
+ */
+type IgniterCallerResponseMarker = File | Blob | ReadableStream | ArrayBuffer | FormData;
 
 /**
  * Function that can modify request configuration before execution.
@@ -59,7 +119,7 @@ type IgniterCallerResponseInterceptor = <T>(response: IgniterCallerApiResponse<T
 /**
  * HTTP methods supported for schema mapping.
  */
-type IgniterCallerSchemaMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+type IgniterCallerSchemaMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
 /**
  * Schema definition for a single endpoint.
  *
@@ -128,6 +188,10 @@ type InferRequestType<T> = T extends IgniterCallerEndpointSchema<infer R, any> ?
  * Infer response type by status code from endpoint schema.
  */
 type InferResponseType<T, Status extends number> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? Status extends keyof Responses ? Responses[Status] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[Status]> : never : never : never;
+/**
+ * Infer the success response type (status 200 or 201) from endpoint schema.
+ */
+type InferSuccessResponseType<T> = T extends IgniterCallerEndpointSchema<any, infer Responses> ? 200 extends keyof Responses ? Responses[200] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[200]> : never : 201 extends keyof Responses ? Responses[201] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[201]> : never : never : never;
 /**
  * Infer all possible response types (union) from endpoint schema.
  */
@@ -137,6 +201,26 @@ type InferAllResponseTypes<T> = T extends IgniterCallerEndpointSchema<any, infer
         data: StandardSchemaV1.InferOutput<Responses[K]>;
     } : never;
 }[keyof Responses] : never : never;
+/**
+ * Get all available paths from a schema map.
+ */
+type SchemaMapPaths<TSchemas extends IgniterCallerSchemaMap> = keyof TSchemas & string;
+/**
+ * Get available methods for a specific path.
+ */
+type SchemaMapMethods<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas> = keyof TSchemas[TPath] & IgniterCallerSchemaMethod;
+/**
+ * Get endpoint schema for a specific path and method.
+ */
+type SchemaMapEndpoint<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod];
+/**
+ * Infer response type from schema map for a specific path, method, and status.
+ */
+type SchemaMapResponseType<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath], TStatus extends number = 200> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<any, infer Responses> ? TStatus extends keyof Responses ? Responses[TStatus] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<Responses[TStatus]> : never : never : never;
+/**
+ * Infer request type from schema map for a specific path and method.
+ */
+type SchemaMapRequestType<TSchemas extends IgniterCallerSchemaMap, TPath extends keyof TSchemas, TMethod extends keyof TSchemas[TPath]> = TSchemas[TPath][TMethod] extends IgniterCallerEndpointSchema<infer Request, any> ? Request extends StandardSchemaV1 ? StandardSchemaV1.InferInput<Request> : never : never;
 /**
  * Options for schema validation behavior.
  */
@@ -289,23 +373,26 @@ declare class IgniterCallerBuilder<TCaller = unknown, TSchemas extends IgniterCa
 }
 
 /**
- * Retry configuration for failed requests.
+ * Constructor params for the request builder.
  */
-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[];
+interface IgniterCallerRequestBuilderParams {
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+    defaultCookies?: Record<string, string>;
+    logger?: IgniterLogger;
+    requestInterceptors?: IgniterCallerRequestInterceptor[];
+    responseInterceptors?: IgniterCallerResponseInterceptor[];
+    eventEmitter?: (url: string, method: string, result: any) => Promise<void>;
+    schemas?: IgniterCallerSchemaMap;
+    schemaValidation?: IgniterCallerSchemaValidationOptions;
 }
-
 /**
  * Fluent request builder for `IgniterCaller`.
+ *
+ * When created via specific HTTP methods (get, post, put, patch, delete),
+ * the method is already set and cannot be changed.
  */
-declare class IgniterCallerRequestBuilder {
+declare class IgniterCallerRequestBuilder<TResponse = unknown> {
     private options;
     private logger?;
     private retryOptions?;
@@ -317,27 +404,46 @@ declare class IgniterCallerRequestBuilder {
     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;
-    });
+    private responseTypeSchema?;
+    constructor(params: IgniterCallerRequestBuilderParams);
+    /**
+     * Sets the HTTP method for this request.
+     * @internal Used by IgniterCaller.request() for generic requests.
+     */
+    _setMethod(method: IgniterCallerHttpMethod): this;
+    /**
+     * Sets the URL for this request.
+     * @internal Used when URL is passed to HTTP method directly.
+     */
+    _setUrl(url: string): this;
     /**
      * Overrides the logger for this request chain.
      */
     withLogger(logger: IgniterLogger): this;
-    method(method: IgniterCallerHttpMethod): this;
+    /**
+     * Sets the request URL.
+     */
     url(url: string): this;
+    /**
+     * Sets the request body.
+     * For GET/HEAD requests, body will be automatically converted to query params.
+     */
     body<TBody>(body: TBody): this;
+    /**
+     * Sets URL query parameters.
+     */
     params(params: Record<string, string | number | boolean>): this;
+    /**
+     * Merges additional headers into the request.
+     */
     headers(headers: Record<string, string>): this;
+    /**
+     * Sets request timeout in milliseconds.
+     */
     timeout(timeout: number): this;
+    /**
+     * Sets cache strategy and optional cache key.
+     */
     cache(cache: RequestCache, key?: string): this;
     /**
      * Configures retry behavior for failed requests.
@@ -351,14 +457,45 @@ declare class IgniterCallerRequestBuilder {
      * Sets cache stale time in milliseconds.
      */
     stale(milliseconds: number): this;
-    responseType<T>(schema?: z.ZodSchema<T>): this;
+    /**
+     * Sets the expected response type for TypeScript inference.
+     *
+     * - If a Zod/StandardSchema is passed, it will validate the response (only for JSON/XML/CSV)
+     * - If a type parameter is passed (e.g., `responseType<File>()`), it's for typing only
+     *
+     * The actual parsing is based on Content-Type headers, not this setting.
+     *
+     * @example
+     * ```ts
+     * // With Zod schema (validates JSON response)
+     * const result = await api.get('/users').responseType(UserSchema).execute()
+     *
+     * // With type marker (typing only, no validation)
+     * const result = await api.get('/file').responseType<Blob>().execute()
+     * ```
+     */
+    responseType<T>(schema?: z.ZodSchema<T> | StandardSchemaV1): IgniterCallerRequestBuilder<T>;
     /**
      * Downloads a file via GET request.
+     * @deprecated Use `.responseType<File>().execute()` instead. The response type is auto-detected.
      */
     getFile(url: string): {
         execute: () => Promise<IgniterCallerFileResponse>;
     };
-    execute<T = unknown>(): Promise<IgniterCallerApiResponse<T>>;
+    /**
+     * Executes the HTTP request.
+     *
+     * Response parsing is automatic based on Content-Type headers:
+     * - `application/json` → parsed as JSON
+     * - `text/xml`, `application/xml` → returned as text (parse with your XML library)
+     * - `text/csv` → returned as text
+     * - `text/html`, `text/plain` → returned as text
+     * - `image/*`, `audio/*`, `video/*`, `application/pdf`, etc. → returned as Blob
+     * - `application/octet-stream` → returned as Blob
+     *
+     * Schema validation (if configured) only runs for validatable content types (JSON, XML, CSV).
+     */
+    execute(): Promise<IgniterCallerApiResponse<TResponse>>;
     private executeWithRetry;
     private executeSingleRequest;
     private buildRequest;
@@ -367,6 +504,11 @@ declare class IgniterCallerRequestBuilder {
      */
     private emitEvent;
 }
+/**
+ * Request builder type without internal methods.
+ * Used when creating requests via specific HTTP methods (get, post, etc.)
+ */
+type IgniterCallerMethodRequestBuilder<TResponse = unknown> = Omit<IgniterCallerRequestBuilder<TResponse>, '_setMethod' | '_setUrl'>;
 
 /**
  * Callback function for event listeners.
@@ -420,12 +562,107 @@ declare class 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;
+    /**
+     * Creates common request builder params.
+     */
+    private createBuilderParams;
+    /**
+     * Creates a GET request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     *
+     * @example
+     * ```ts
+     * // With URL directly
+     * const result = await api.get('/users').execute()
+     *
+     * // With URL via method
+     * const result = await api.get().url('/users').execute()
+     * ```
+     */
+    get(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Creates a POST request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     *
+     * @example
+     * ```ts
+     * const result = await api.post('/users').body({ name: 'John' }).execute()
+     * ```
+     */
+    post(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Creates a PUT request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     *
+     * @example
+     * ```ts
+     * const result = await api.put('/users/1').body({ name: 'Jane' }).execute()
+     * ```
+     */
+    put(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Creates a PATCH request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     *
+     * @example
+     * ```ts
+     * const result = await api.patch('/users/1').body({ name: 'Jane' }).execute()
+     * ```
+     */
+    patch(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Creates a DELETE request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     *
+     * @example
+     * ```ts
+     * const result = await api.delete('/users/1').execute()
+     * ```
+     */
+    delete(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Creates a HEAD request.
+     *
+     * @param url Optional URL for the request. Can also be set via `.url()`.
+     */
+    head(url?: string): IgniterCallerMethodRequestBuilder;
+    /**
+     * Executes a request directly with all options in one object (axios-style).
+     *
+     * This is a convenience method for making requests without using the builder pattern.
+     * Useful for dynamic requests where options are constructed programmatically.
+     *
+     * @example
+     * ```ts
+     * const result = await api.request({
+     *   method: 'POST',
+     *   url: '/users',
+     *   body: { name: 'John' },
+     *   headers: { 'X-Custom': 'value' },
+     *   timeout: 5000,
+     * })
+     *
+     * // With caching
+     * const result = await api.request({
+     *   method: 'GET',
+     *   url: '/users',
+     *   staleTime: 30000,
+     * })
+     *
+     * // With retry
+     * const result = await api.request({
+     *   method: 'GET',
+     *   url: '/health',
+     *   retry: { maxAttempts: 3, backoff: 'exponential' },
+     * })
+     * ```
+     */
+    request<T = unknown>(options: IgniterCallerDirectRequestOptions): Promise<IgniterCallerApiResponse<T>>;
     /**
      * Executes multiple requests in parallel and returns results as an array.
      *
@@ -471,7 +708,7 @@ declare class IgniterCaller {
      * @example
      * ```ts
      * // After creating a user
-     * await api.post().url('/users').body(newUser).execute()
+     * await api.post('/users').body(newUser).execute()
      * await IgniterCaller.invalidate('/users') // Clear users list cache
      * ```
      */
@@ -735,4 +972,4 @@ declare class IgniterCallerUrlUtils {
     }): 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 };
+export { type ExtractPathParams, IgniterCaller, type IgniterCallerApiResponse, type IgniterCallerBaseRequestOptions, IgniterCallerBodyUtils, IgniterCallerBuilder, type IgniterCallerBuilderFactory, type IgniterCallerBuilderState, IgniterCallerCacheUtils, type IgniterCallerDirectRequestOptions, type IgniterCallerEndpointSchema, IgniterCallerError, type IgniterCallerErrorCode, type IgniterCallerErrorPayload, type IgniterCallerEventCallback, IgniterCallerEvents, type IgniterCallerFileResponse, type IgniterCallerHttpMethod, type IgniterCallerMethodRequestBuilder, IgniterCallerMock, type IgniterCallerOperation, IgniterCallerRequestBuilder, type IgniterCallerRequestBuilderParams, type IgniterCallerRequestInterceptor, type IgniterCallerRequestOptions, type IgniterCallerResponseContentType, type IgniterCallerResponseInterceptor, type IgniterCallerResponseMarker, type IgniterCallerRetryOptions, type IgniterCallerSchemaMap, type IgniterCallerSchemaMethod, IgniterCallerSchemaUtils, type IgniterCallerSchemaValidationOptions, type IgniterCallerStoreAdapter, type IgniterCallerStoreOptions, type IgniterCallerUrlPattern, IgniterCallerUrlUtils, type IgniterCallerValidatableContentType, type InferAllResponseTypes, type InferRequestType, type InferResponseType, type InferSuccessResponseType, type SchemaMapEndpoint, type SchemaMapMethods, type SchemaMapPaths, type SchemaMapRequestType, type SchemaMapResponseType };