aiwrapper/dist/http-request.d.ts

A Universal AI Wrapper for JavaScript & TypeScript

export interface HttpRequestInit {
    body?: object | string | null;
    cache?: string;
    credentials?: string;
    headers?: Record<string, string>;
    signal?: AbortSignal;
    /**
     * A cryptographic hash of the resource to be fetched by request. Sets
     * request's integrity.
     */
    integrity?: string;
    /**
     * A boolean to set request's keepalive.
     */
    keepalive?: boolean;
    /**
     * A string to set request's method.
     */
    method?: string;
    /**
     * A string to indicate whether the request will use CORS, or will be
     * restricted to same-origin URLs. Sets request's mode.
     */
    mode?: string;
    /**
     * A string indicating whether request follows redirects, results in an error
     * upon encountering a redirect, or returns the redirect (in an opaque
     * fashion). Sets request's redirect.
     */
    redirect?: string;
    /**
     * A string whose value is a same-origin URL, "about:client", or the empty
     * string, to set request's referrer.
     */
    referrer?: string;
    /**
     * A referrer policy to set request's referrerPolicy.
     */
    referrerPolicy?: string;
}
export type HttpResponseOnErrorAction = {
    retry: true;
    consumeRetry?: boolean;
} | {
    retry: false;
};
/**
 * Options for httpRequestWithRetry that adds automatic retry logic.
 *
 * Retry behavior:
 * - Network errors (timeout, DNS failures, etc.) are automatically retried
 * - HTTP 400 errors: can use `on400Error` callback to fix the request and retry, otherwise not retried
 * - HTTP 429 errors: always retried (rate limiting is usually temporary)
 * - HTTP 4xx errors (other): not retried by default (client errors that won't fix themselves)
 * - HTTP 5xx errors: always retried (server errors are usually transient)
 *
 * Custom 400 error handling:
 * - Use `on400Error` to inspect the error response and potentially fix the request:
 *   - `{ retry: true }` - fix the request and retry (consumes one retry attempt)
 *   - `{ retry: true, consumeRetry: false }` - fix the request and retry without consuming budget
 *   - `{ retry: false }` - don't retry, throw immediately
 *
 * Retry limits:
 * - `retries` - maximum number of retry attempts that can be consumed (default: 6)
 * - Total attempts are capped at `retries + 1` (initial + retries) to prevent infinite loops
 *   when using `consumeRetry: false`
 *
 * Backoff:
 * - Exponential backoff starts at `backoffMs` (default: 100ms) and doubles each retry
 * - Capped at `maxBackoffMs` (default: 3000ms)
 * - If `Retry-After` header is present in the response (e.g., 429, 503), uses that value
 *   instead of exponential backoff. Supports both seconds format and HTTP date format.
 *
 * Note: The options object is mutated during execution (retries countdown, backoff increases).
 */
export interface HttpResponseWithRetries extends HttpRequestInit {
    retries?: number;
    backoffMs?: number;
    maxBackoffMs?: number;
    /**
     * Called when a 400 Bad Request error occurs. Allows fixing the request and retrying.
     * Examples: adding missing headers, fixing data format, handling API version mismatches.
     *
     * You can modify the `options` object (e.g., `options.body`, `options.headers`) to fix
     * the request before retrying. The modified options will be used in the retry.
     *
     * @param res - The HTTP response with status 400
     * @param error - Error object with status information
     * @param options - The request options object (can be mutated to fix the request)
     * @returns Action indicating whether to retry and whether to consume retry budget
     */
    on400Error?: (res: Response, error: Error, options: HttpResponseWithRetries) => Promise<HttpResponseOnErrorAction>;
    _attemptCount?: number;
    _maxTotalAttempts?: number;
}
export declare const setHttpRequestImpl: (impl: (url: string | URL, options: object) => Promise<Response>) => void;
export declare const httpRequest: (url: string | URL, options: HttpRequestInit) => Promise<Response>;
export declare class HttpRequestError extends Error {
    response: Response | null;
    action: HttpResponseOnErrorAction;
    /**
     * Parsed JSON body if the response was JSON, otherwise undefined.
     * Only available if response was present and parseable.
     */
    body?: any;
    /**
     * Raw text body if available.
     * Only available if response was present and body could be read.
     */
    bodyText?: string;
    constructor(message: string, response: Response | null, action: HttpResponseOnErrorAction, bodyData?: {
        json?: any;
        text?: string;
    });
}
/**
 * Performs an HTTP request with automatic retry logic and exponential backoff.
 *
 * Why use this instead of plain fetch?
 * - Network errors (timeouts, DNS failures, connection issues) are common in production
 *   and should be automatically retried rather than failing immediately
 * - HTTP 5xx errors often indicate temporary server issues that resolve on retry
 * - Exponential backoff prevents overwhelming servers during outages or rate limiting
 * - Custom error handling allows fine-grained control over retry behavior per error type
 * - Provides a unified interface that works across different environments (Node.js, browsers, etc.)
 *
 * This function wraps httpRequest (which can be configured for different HTTP implementations)
 * and adds retry logic with configurable backoff and error handling strategies.
 */
export declare const httpRequestWithRetry: (url: string | URL, options: HttpResponseWithRetries) => Promise<Response>;