@beyonk/http 12.1.1 → 12.2.0

package/dist/index.d.cts

@@ -0,0 +1,310 @@
+/**
+ * API Configuration options
+ */
+type ApiOptions = {
+    /** Base URL for API requests */
+    baseUrl?: string;
+    /** Mock client for testing */
+    mock?: FetchClient;
+    /** Fetch client for HTTP requests */
+    fetch?: FetchClient;
+    /** Whether to retry failed requests */
+    retry?: RetryOptions | false;
+    /** Whether to parse error responses as JSON */
+    parseErrors?: boolean;
+    /** Global error handlers */
+    handlers?: ErrorHandlers;
+};
+/**
+ * Retry configuration
+ */
+type RetryOptions = {
+    /** Number of retry attempts */
+    attempts: number;
+    /** Error codes to retry on */
+    errors: string[];
+};
+/**
+ * Context object for API requests
+ */
+type ApiContext = {
+    /** Fetch client */
+    fetch?: FetchClient;
+    /** Additional context properties */
+    [key: string]: any;
+};
+/**
+ * Handler function for HTTP errors
+ */
+type ErrorHandler = (error: HttpError, context?: ApiContext) => any;
+/**
+ * Map of error handlers
+ */
+type ErrorHandlers = {
+    accessDenied?: ErrorHandler;
+    paymentRequired?: ErrorHandler;
+    forbidden?: ErrorHandler;
+    notFound?: ErrorHandler;
+    notAcceptable?: ErrorHandler;
+    conflict?: ErrorHandler;
+    gone?: ErrorHandler;
+    preconditionFailed?: ErrorHandler;
+    expectationFailed?: ErrorHandler;
+    badData?: ErrorHandler;
+    tooManyRequests?: ErrorHandler;
+    [key: string]: ErrorHandler | undefined;
+};
+/**
+ * Function to transform API response
+ */
+type ResponseTransformer<T = any> = (json: any, httpStatus: number) => T;
+/**
+ * Fetch client interface
+ */
+type FetchClient = (url: string, options: Record<string, any>) => Promise<Response>;
+/**
+ * Fetch response interface
+ */
+type Response = {
+    status: number;
+    statusText: string;
+    json(): Promise<any>;
+    text(): Promise<string>;
+    headers: Map<string, string> | {
+        get(name: string): string | null;
+    };
+    ok?: boolean;
+};
+
+/**
+ * @fileoverview Consolidated API client with error handling
+ * @import {
+ * ApiOptions,
+ * ApiContext,
+ * ErrorHandler,
+ * FetchClient,
+ * RequestConfig,
+ * ResponseTransformer,
+ * QueryResult
+ * } from './types.js'
+ */
+/**
+ * Base HTTP error class
+ */
+declare class HttpError extends Error {
+    /**
+     * Create a new HTTP error
+     * @param {string} message - Error message
+     * @param {any} body - Error response body
+     */
+    constructor(message: string, body: any);
+    body: any;
+}
+declare namespace _default {
+    export { create };
+    export { configure };
+}
+
+type Config = ApiOptions | undefined;
+/**
+ * API client with chainable interface for making HTTP requests
+ */
+declare class Api {
+    /**
+     * Creates a new API instance
+     * @param {ApiOptions} options - API configuration options
+     */
+    constructor(options: ApiOptions);
+    config: any;
+    /** @type {Record<string, ErrorHandler>} */
+    handlers: Record<string, ErrorHandler>;
+    /** @type {FetchClient|null} */
+    client: FetchClient | null;
+    /** @type {ApiContext|null} */
+    ctx: ApiContext | null;
+    /** @type {ErrorHandler|null} */
+    defaultHandler: ErrorHandler | null;
+    /** @type {ApiOptions} */
+    options: ApiOptions;
+    /**
+     * Reset the request configuration to defaults
+     */
+    resetRequest(): void;
+    /**
+     * Get the HTTP client to use for requests
+     * @returns {FetchClient} HTTP client
+     * @throws {Error} If no client is available
+     */
+    getClient(): FetchClient;
+    /**
+     * Handle an error
+     * @param {HttpError} e - Error instance
+     * @param {ApiContext} [ctx] - API context
+     * @returns {any} Result of error handler
+     */
+    handle(e: HttpError, ctx?: ApiContext): any;
+    /**
+     * Send the HTTP request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    send<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Set the context for the request
+     * @param {ApiContext} ctx - Request context
+     * @returns {this} Current instance
+     */
+    context(ctx: ApiContext): this;
+    /**
+     * Set request overrides
+     * @param {Record<string, any>} override - Request overrides
+     * @returns {this} Current instance
+     */
+    override(override: Record<string, any>): this;
+    /**
+     * Set request headers
+     * @param {Record<string, string>} headers - Request headers
+     * @returns {this} Current instance
+     */
+    headers(headers: Record<string, string>): this;
+    /**
+     * Perform a GET request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    get<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a POST request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    post<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a PATCH request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    patch<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a PUT request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    put<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a DELETE request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    del<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Set the API endpoint
+     * @param {string} endpoint - API endpoint
+     * @returns {this} Current instance
+     */
+    endpoint(endpoint: string): this;
+    /**
+     * Set query parameters
+     * @param {Record<string, any>} query - Query parameters
+     * @returns {this} Current instance
+     */
+    query(query: Record<string, any>): this;
+    /**
+     * Set request payload
+     * @param {any} payload - Request payload
+     * @returns {this} Current instance
+     */
+    payload(payload: any): this;
+    /**
+     * Register a default error handler
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    default(fn: ErrorHandler): this;
+    /**
+     * Register a handler for AccessDenied (401) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    accessDenied(fn: ErrorHandler): this;
+    /**
+     * Register a handler for PaymentRequired (402) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    paymentRequired(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Forbidden (403) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    forbidden(fn: ErrorHandler): this;
+    /**
+     * Register a handler for NotFound (404) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    notFound(fn: ErrorHandler): this;
+    /**
+     * Register a handler for NotAcceptable (406) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    notAcceptable(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Conflict (409) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    conflict(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Gone (410) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    gone(fn: ErrorHandler): this;
+    /**
+     * Register a handler for PreconditionFailed (412) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    preconditionFailed(fn: ErrorHandler): this;
+    /**
+     * Register a handler for ExpectationFailed (417) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    expectationFailed(fn: ErrorHandler): this;
+    /**
+     * Register a handler for BadData (422) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    badData(fn: ErrorHandler): this;
+    /**
+     * Register a handler for TooManyRequests (429) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    tooManyRequests(fn: ErrorHandler): this;
+    #private;
+}
+/**
+ * Create a new API client instance
+ * @returns {Api} API client instance
+ * @throws {Error} If API client is not configured
+ */
+declare function create(): Api;
+/**
+ * Configure the API client
+ * @param {ApiOptions} options - API configuration options
+ */
+declare function configure(options: ApiOptions): void;
+
+export { Api, type Config, HttpError, _default as default };

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * API Configuration options
+ */
+type ApiOptions = {
+    /** Base URL for API requests */
+    baseUrl?: string;
+    /** Mock client for testing */
+    mock?: FetchClient;
+    /** Fetch client for HTTP requests */
+    fetch?: FetchClient;
+    /** Whether to retry failed requests */
+    retry?: RetryOptions | false;
+    /** Whether to parse error responses as JSON */
+    parseErrors?: boolean;
+    /** Global error handlers */
+    handlers?: ErrorHandlers;
+};
+/**
+ * Retry configuration
+ */
+type RetryOptions = {
+    /** Number of retry attempts */
+    attempts: number;
+    /** Error codes to retry on */
+    errors: string[];
+};
+/**
+ * Context object for API requests
+ */
+type ApiContext = {
+    /** Fetch client */
+    fetch?: FetchClient;
+    /** Additional context properties */
+    [key: string]: any;
+};
+/**
+ * Handler function for HTTP errors
+ */
+type ErrorHandler = (error: HttpError, context?: ApiContext) => any;
+/**
+ * Map of error handlers
+ */
+type ErrorHandlers = {
+    accessDenied?: ErrorHandler;
+    paymentRequired?: ErrorHandler;
+    forbidden?: ErrorHandler;
+    notFound?: ErrorHandler;
+    notAcceptable?: ErrorHandler;
+    conflict?: ErrorHandler;
+    gone?: ErrorHandler;
+    preconditionFailed?: ErrorHandler;
+    expectationFailed?: ErrorHandler;
+    badData?: ErrorHandler;
+    tooManyRequests?: ErrorHandler;
+    [key: string]: ErrorHandler | undefined;
+};
+/**
+ * Function to transform API response
+ */
+type ResponseTransformer<T = any> = (json: any, httpStatus: number) => T;
+/**
+ * Fetch client interface
+ */
+type FetchClient = (url: string, options: Record<string, any>) => Promise<Response>;
+/**
+ * Fetch response interface
+ */
+type Response = {
+    status: number;
+    statusText: string;
+    json(): Promise<any>;
+    text(): Promise<string>;
+    headers: Map<string, string> | {
+        get(name: string): string | null;
+    };
+    ok?: boolean;
+};
+
+/**
+ * @fileoverview Consolidated API client with error handling
+ * @import {
+ * ApiOptions,
+ * ApiContext,
+ * ErrorHandler,
+ * FetchClient,
+ * RequestConfig,
+ * ResponseTransformer,
+ * QueryResult
+ * } from './types.js'
+ */
+/**
+ * Base HTTP error class
+ */
+declare class HttpError extends Error {
+    /**
+     * Create a new HTTP error
+     * @param {string} message - Error message
+     * @param {any} body - Error response body
+     */
+    constructor(message: string, body: any);
+    body: any;
+}
+declare namespace _default {
+    export { create };
+    export { configure };
+}
+
+type Config = ApiOptions | undefined;
+/**
+ * API client with chainable interface for making HTTP requests
+ */
+declare class Api {
+    /**
+     * Creates a new API instance
+     * @param {ApiOptions} options - API configuration options
+     */
+    constructor(options: ApiOptions);
+    config: any;
+    /** @type {Record<string, ErrorHandler>} */
+    handlers: Record<string, ErrorHandler>;
+    /** @type {FetchClient|null} */
+    client: FetchClient | null;
+    /** @type {ApiContext|null} */
+    ctx: ApiContext | null;
+    /** @type {ErrorHandler|null} */
+    defaultHandler: ErrorHandler | null;
+    /** @type {ApiOptions} */
+    options: ApiOptions;
+    /**
+     * Reset the request configuration to defaults
+     */
+    resetRequest(): void;
+    /**
+     * Get the HTTP client to use for requests
+     * @returns {FetchClient} HTTP client
+     * @throws {Error} If no client is available
+     */
+    getClient(): FetchClient;
+    /**
+     * Handle an error
+     * @param {HttpError} e - Error instance
+     * @param {ApiContext} [ctx] - API context
+     * @returns {any} Result of error handler
+     */
+    handle(e: HttpError, ctx?: ApiContext): any;
+    /**
+     * Send the HTTP request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    send<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Set the context for the request
+     * @param {ApiContext} ctx - Request context
+     * @returns {this} Current instance
+     */
+    context(ctx: ApiContext): this;
+    /**
+     * Set request overrides
+     * @param {Record<string, any>} override - Request overrides
+     * @returns {this} Current instance
+     */
+    override(override: Record<string, any>): this;
+    /**
+     * Set request headers
+     * @param {Record<string, string>} headers - Request headers
+     * @returns {this} Current instance
+     */
+    headers(headers: Record<string, string>): this;
+    /**
+     * Perform a GET request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    get<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a POST request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    post<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a PATCH request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    patch<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a PUT request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    put<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Perform a DELETE request
+     * @template T
+     * @param {ResponseTransformer<T>} [fn] - Function to transform the response
+     * @returns {Promise<T>} Response data
+     */
+    del<T>(fn?: ResponseTransformer<T>): Promise<T>;
+    /**
+     * Set the API endpoint
+     * @param {string} endpoint - API endpoint
+     * @returns {this} Current instance
+     */
+    endpoint(endpoint: string): this;
+    /**
+     * Set query parameters
+     * @param {Record<string, any>} query - Query parameters
+     * @returns {this} Current instance
+     */
+    query(query: Record<string, any>): this;
+    /**
+     * Set request payload
+     * @param {any} payload - Request payload
+     * @returns {this} Current instance
+     */
+    payload(payload: any): this;
+    /**
+     * Register a default error handler
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    default(fn: ErrorHandler): this;
+    /**
+     * Register a handler for AccessDenied (401) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    accessDenied(fn: ErrorHandler): this;
+    /**
+     * Register a handler for PaymentRequired (402) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    paymentRequired(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Forbidden (403) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    forbidden(fn: ErrorHandler): this;
+    /**
+     * Register a handler for NotFound (404) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    notFound(fn: ErrorHandler): this;
+    /**
+     * Register a handler for NotAcceptable (406) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    notAcceptable(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Conflict (409) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    conflict(fn: ErrorHandler): this;
+    /**
+     * Register a handler for Gone (410) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    gone(fn: ErrorHandler): this;
+    /**
+     * Register a handler for PreconditionFailed (412) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    preconditionFailed(fn: ErrorHandler): this;
+    /**
+     * Register a handler for ExpectationFailed (417) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    expectationFailed(fn: ErrorHandler): this;
+    /**
+     * Register a handler for BadData (422) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    badData(fn: ErrorHandler): this;
+    /**
+     * Register a handler for TooManyRequests (429) errors
+     * @param {ErrorHandler} fn - Error handler function
+     * @returns {this} Current instance
+     */
+    tooManyRequests(fn: ErrorHandler): this;
+    #private;
+}
+/**
+ * Create a new API client instance
+ * @returns {Api} API client instance
+ * @throws {Error} If API client is not configured
+ */
+declare function create(): Api;
+/**
+ * Configure the API client
+ * @param {ApiOptions} options - API configuration options
+ */
+declare function configure(options: ApiOptions): void;
+
+export { Api, type Config, HttpError, _default as default };