react-native-fetch-client 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1744 @@
+/**
+ * Error hierarchy for react-native-fetch-client.
+ *
+
+ * Key design decision: HttpError is NOT a subclass of NetworkError.
+ * A 404 or 500 is a received HTTP response — not a failure to connect.
+ * Use the `.code` property or `instanceof` to distinguish error types.
+ */
+
+type BaseOptions = {
+    config?: ResolvedRequestConfig;
+    cause?: unknown;
+};
+/**
+ * Base class for all errors thrown by react-native-fetch-client.
+ * Extends the native Error class and adds a discriminant `code` field.
+ */
+declare class FetchNativeError extends Error {
+    /** Discriminant code identifying the specific error type. */
+    readonly code: ErrorCode;
+    /**
+     * The resolved request configuration at the time of the error.
+     * Authorization header values are redacted to '[REDACTED]'.
+     */
+    readonly config?: ResolvedRequestConfig;
+    constructor(message: string, code: ErrorCode, options?: BaseOptions);
+}
+/**
+ * Thrown when the server returns a non-2xx HTTP response.
+ *
+ * This is NOT a network error. The request was successfully sent and a
+ * response was received — it just carried an error status code.
+ */
+declare class HttpError extends FetchNativeError {
+    /** HTTP status code (e.g. 404, 500). */
+    readonly status: number;
+    /** HTTP status text (e.g. 'Not Found', 'Internal Server Error'). */
+    readonly statusText: string;
+    /**
+     * Parsed response body, if available and parseable.
+     * May be a string, object, or null depending on the response content.
+     */
+    readonly data: unknown;
+    /** Response headers from the server. Keys are normalized to lowercase. */
+    readonly headers: Record<string, string>;
+    /**
+     * The original Fetch Response object.
+     * Do not log this directly — it may contain sensitive header values.
+     */
+    readonly response: Response;
+    constructor(message: string, options: {
+        status: number;
+        statusText: string;
+        data: unknown;
+        headers: Record<string, string>;
+        response: Response;
+        config?: ResolvedRequestConfig;
+    });
+}
+/**
+ * Thrown when fetch() rejects before any response is received.
+ * This represents a true network failure: DNS failure, connection refused,
+ * offline, CORS preflight failure, etc.
+ *
+ * Distinct from HttpError: no HTTP response was received.
+ */
+declare class NetworkError extends FetchNativeError {
+    constructor(message: string, options?: {
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a request exceeds the configured timeout.
+ * The request was aborted — no response was received.
+ *
+ * Note: This is a distinct class from NetworkError, even though both represent
+ * cases where no HTTP response was received. Callers can distinguish them with
+ * `instanceof` or the `.code` field ('TIMEOUT' vs 'NETWORK_ERROR').
+ */
+declare class TimeoutError extends FetchNativeError {
+    /** The timeout that was exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, options?: {
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a request is cancelled via an AbortSignal provided by the caller.
+ *
+ * Note: Timeout cancellations throw TimeoutError, not CancelError.
+ * CancelError is only for caller-initiated cancellation.
+ */
+declare class CancelError extends FetchNativeError {
+    constructor(options?: {
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a response body cannot be parsed as the expected type.
+ * The HTTP request succeeded (2xx), but the body was malformed.
+ */
+declare class ParseError extends FetchNativeError {
+    /** HTTP status code of the response whose body could not be parsed. */
+    readonly status: number;
+    /** The raw response body text that failed to parse, if retrievable. */
+    readonly rawBody: string | null;
+    constructor(message: string, options: {
+        status: number;
+        rawBody: string | null;
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a request cannot be dispatched due to invalid configuration.
+ * Examples: missing URL, invalid base URL, conflicting options.
+ */
+declare class ConfigError extends FetchNativeError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when all retry attempts have been consumed and the last attempt failed.
+ * Wraps the last error as `cause` for full diagnostics.
+ */
+declare class RetryExhaustedError extends FetchNativeError {
+    /** The total number of attempts made (initial + retries). */
+    readonly attempts: number;
+    /** The error from the last failed attempt. */
+    readonly lastError: unknown;
+    constructor(attempts: number, lastError: unknown, options?: {
+        config?: ResolvedRequestConfig;
+    });
+}
+/**
+ * Thrown when response data fails schema validation (e.g. via Zod, Standard Schema,
+ * or a custom functional validator).
+ */
+declare class ValidationError extends FetchNativeError {
+    /** The raw unvalidated data returned by the server. */
+    readonly data: unknown;
+    /** Detailed validation issue objects or messages if provided by the validator. */
+    readonly issues?: unknown;
+    constructor(message: string, options?: {
+        data?: unknown;
+        issues?: unknown;
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a request is short-circuited because the circuit breaker is currently OPEN
+ * due to consecutive upstream failures.
+ */
+declare class CircuitBreakerError extends FetchNativeError {
+    /** Current state of the circuit breaker at the moment of the rejection ('OPEN' | 'HALF_OPEN'). */
+    readonly state: 'OPEN' | 'HALF_OPEN';
+    /** Configured cooldown period before canary trial in milliseconds. */
+    readonly resetTimeoutMs: number;
+    constructor(message: string, options: {
+        state: 'OPEN' | 'HALF_OPEN';
+        resetTimeoutMs: number;
+        config?: ResolvedRequestConfig;
+        cause?: unknown;
+    });
+}
+/** Returns true if `err` is any react-native-fetch-client error. */
+declare function isFetchNativeError(err: unknown): err is FetchNativeError;
+/** Returns true if `err` is an HttpError (non-2xx response received). */
+declare function isHttpError(err: unknown): err is HttpError;
+/** Returns true if `err` is a NetworkError (no response received). */
+declare function isNetworkError(err: unknown): err is NetworkError;
+/** Returns true if `err` is a TimeoutError. */
+declare function isTimeoutError(err: unknown): err is TimeoutError;
+/** Returns true if `err` is a CancelError (caller-initiated cancellation). */
+declare function isCancelError(err: unknown): err is CancelError;
+/** Returns true if `err` is a RetryExhaustedError. */
+declare function isRetryExhaustedError(err: unknown): err is RetryExhaustedError;
+/** Returns true if `err` is a ValidationError. */
+declare function isValidationError(err: unknown): err is ValidationError;
+/** Returns true if `err` is a CircuitBreakerError. */
+declare function isCircuitBreakerError(err: unknown): err is CircuitBreakerError;
+
+/**
+ * Public types for react-native-fetch-client.
+ *
+
+ * All types in this file form the stable public API surface.
+ * Implementation details are kept in their respective modules.
+ *
+ * Design principles:
+ * - Zero production runtime dependencies (`dependencies: {}`)
+ * - Fetch-native primitives (Request, Response, Headers, ReadableStream)
+ * - Strict type inference with TypeScript 5+
+ * - Comprehensive JSDoc definitions for enhanced developer experience
+ */
+
+/** Supported HTTP methods. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+/** The expected response body format. */
+type ResponseType = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'none' | 'stream';
+/** A fetch implementation compatible with the global `fetch` signature. */
+type FetchImpl = typeof globalThis.fetch;
+/**
+ * Progress event payload emitted by download and upload progress callbacks.
+ */
+interface ProgressEvent {
+    /** Number of bytes transferred so far. */
+    loaded: number;
+    /** Total number of bytes if known (from Content-Length header or body size). */
+    total?: number;
+    /** Fraction of transfer completed (0.0 to 1.0) if total is known. */
+    progress?: number;
+    /** Number of bytes transferred in the most recent chunk. */
+    bytes: number;
+}
+/**
+ * Path parameters for URL template interpolation.
+ * Replaces `:paramName` or `{paramName}` placeholders in the URL with URI-encoded values.
+ *
+ * @example
+ * ```ts
+ * client.get('/users/:id/orders/{orderId}', {
+ *   pathParams: { id: 123, orderId: 'ord-456' }
+ * });
+ * // Dispatches GET to: /users/123/orders/ord-456
+ * ```
+ */
+type PathParams = Record<string, string | number | boolean>;
+/**
+ * Query parameters accepted on a request.
+ * Values of `null` or `undefined` are omitted from the serialized query string.
+ */
+type QueryParams = Record<string, string | number | boolean | null | undefined>;
+/**
+ * Standard Schema V1 interface compliant with the cross-library specification.
+ * Supported by modern versions of Zod (3.24+), Valibot, ArkType, etc.
+ */
+interface StandardSchemaV1<T = unknown> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            readonly value: T;
+            readonly issues?: never;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<unknown>;
+            }>;
+            readonly value?: never;
+        } | Promise<{
+            readonly value: T;
+            readonly issues?: never;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<unknown>;
+            }>;
+            readonly value?: never;
+        }>;
+    };
+}
+/**
+ * Zod-like validator interface exposing `.parse()` or `.safeParse()`.
+ */
+interface ZodLikeSchema<T = unknown> {
+    parse?(data: unknown): T;
+    safeParse?(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            message: string;
+            issues?: unknown;
+        };
+    };
+}
+/**
+ * Plain synchronous or asynchronous function validator.
+ */
+type FunctionalValidator<T = unknown> = (data: unknown) => T | Promise<T>;
+/**
+ * Duck-typed schema validator accepted by react-native-fetch-client.
+ * Compatible with:
+
+ * 1. Standard Schema v1 (`~standard`)
+ * 2. Zod (`z.object({...})`)
+ * 3. Valibot / ArkType / Yup / Superstruct
+ * 4. Plain validation functions `(data: unknown) => T`
+ */
+type SchemaValidator<T = unknown> = StandardSchemaV1<T> | ZodLikeSchema<T> | FunctionalValidator<T>;
+/**
+ * An event emitted by a Server-Sent Events (SSE) or chunk stream.
+ * Parsed according to the WHATWG EventSource specification.
+ */
+interface StreamEvent {
+    /** The event type specified in `event: <name>`. Defaults to undefined (standard message). */
+    event?: string;
+    /** The text payload accumulated from `data: <content>` lines. */
+    data: string;
+    /** The event ID specified in `id: <id>`. */
+    id?: string;
+    /** The reconnection time in milliseconds specified in `retry: <ms>`. */
+    retry?: number;
+}
+/**
+ * Options for streaming requests via `api.stream()`.
+ */
+interface StreamOptions extends Omit<RequestConfig, 'responseType'> {
+    /**
+     * If true, yields raw non-empty text lines rather than parsing SSE event envelopes.
+     * Default: false (parses SSE lines into StreamEvent objects).
+     */
+    rawLines?: boolean;
+}
+/**
+ * Concurrency configuration for capping simultaneous HTTP requests.
+ */
+interface ConcurrencyConfig {
+    /**
+     * Maximum number of concurrent in-flight requests permitted simultaneously.
+     * Requests exceeding this limit wait in an in-memory FIFO queue.
+     * 0 or undefined means unlimited. Default: undefined.
+     */
+    maxConcurrentRequests?: number;
+}
+/** State of the circuit breaker state machine. */
+type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+/**
+ * Configuration for the request circuit breaker.
+ * Prevents cascading outages by short-circuiting calls to repeatedly failing endpoints.
+ */
+interface CircuitBreakerConfig {
+    /** Must be set to true to enable the circuit breaker. Default: false. */
+    enabled: boolean;
+    /** Number of consecutive failures before tripping from CLOSED to OPEN. Default: 5. */
+    failureThreshold?: number;
+    /** Time in milliseconds to remain OPEN before testing in HALF_OPEN state. Default: 30000 (30s). */
+    resetTimeoutMs?: number;
+    /** Custom predicate to determine whether an error counts towards failure threshold. */
+    isFailure?: (error: unknown) => boolean;
+}
+/**
+ * Result tuple returned by `api.safe.*` methods.
+ * Implements Go / Rust result semantics: `[data, null]` on success, `[null, error]` on failure.
+ * Eliminates try/catch boilerplate in application code.
+ */
+type SafeResult<T> = [data: T, error: null] | [data: null, error: FetchNativeError];
+/**
+ * Diagnostic log event generated when `debug: true` or a custom logger is enabled.
+ */
+interface DebugLogEntry {
+    /** HTTP method of the request. */
+    method: HttpMethod;
+    /** Target request URL. */
+    url: string;
+    /** HTTP status code (if a response was received). */
+    status?: number;
+    /** Total elapsed round-trip duration in milliseconds. */
+    durationMs: number;
+    /** Normalized request headers with authorization tokens redacted. */
+    headers?: Record<string, string>;
+    /** Whether the response was served from the in-memory cache. */
+    cached?: boolean;
+    /** Whether the response was returned from an in-flight duplicate deduplication. */
+    fromDedup?: boolean;
+    /** Error object if the request failed. */
+    error?: unknown;
+}
+/**
+ * Custom logger function accepted by the `debug` option.
+ */
+type DebugLogger = (entry: DebugLogEntry) => void;
+/**
+ * Supported file input types for `api.upload()`.
+ */
+type UploadFileSource = Blob | File | FormData | ArrayBuffer | Uint8Array | Record<string, unknown>;
+/**
+ * Additional options for `api.upload()`.
+ */
+interface UploadOptions extends Omit<RequestConfig, 'body'> {
+    /**
+     * The form field name used when wrapping a raw Blob / File into FormData.
+     * Default: `'file'`.
+     */
+    fieldName?: string;
+    /**
+     * Optional file name passed to `FormData.append(fieldName, blob, fileName)`.
+     */
+    fileName?: string;
+    /**
+     * Additional text or metadata fields appended to the FormData.
+     */
+    extraFields?: Record<string, string | number | boolean>;
+}
+/**
+ * Per-request configuration. All fields are optional.
+ * Merged on top of ClientConfig defaults; per-request values take precedence.
+ */
+interface RequestConfig {
+    /** Absolute URL, or path appended to `baseURL`. */
+    url?: string;
+    /** HTTP method (default: 'GET'). */
+    method?: HttpMethod;
+    /**
+     * Base URL prepended to `url` when `url` is a relative path.
+     * Overrides the client-level baseURL for this request only.
+     */
+    baseURL?: string;
+    /**
+     * HTTP headers. Merged with client-level defaults; per-request values win.
+     * Header names are case-insensitive.
+     */
+    headers?: HeadersInit;
+    /**
+     * Query parameters appended to the URL.
+     * Merged with any params already present in `url`.
+     */
+    params?: QueryParams;
+    /**
+     * Path parameters interpolated into `:paramName` or `{paramName}` placeholders in the URL.
+     */
+    pathParams?: PathParams;
+    /**
+     * Request body.
+     * - Objects and arrays are JSON-serialized; Content-Type is set to application/json.
+     * - `FormData` is passed through; Content-Type is intentionally NOT set (Fetch sets it with boundary).
+     * - `string`, `Blob`, `ArrayBuffer`, `URLSearchParams` are passed through as-is.
+     * - `null` / `undefined` result in no body.
+     */
+    body?: BodyInit | Record<string, unknown> | unknown[] | null;
+    /**
+     * Request timeout in milliseconds.
+     * 0 means no timeout.
+     * Overrides the client-level timeout for this request.
+     */
+    timeout?: number;
+    /**
+     * An AbortSignal for caller-controlled cancellation.
+     * Composed with the internal timeout signal using AbortSignal.any() or a polyfill.
+     */
+    signal?: AbortSignal;
+    /**
+     * Expected response body type.
+     * Defaults to 'json'. Use 'none' for responses with no body (e.g. 204 No Content).
+     * 'json' falls back to 'text' if the body is empty to avoid parse errors.
+     */
+    responseType?: ResponseType;
+    /** Controls credentials (cookies) behavior. Passed directly to fetch(). */
+    credentials?: RequestCredentials;
+    /**
+     * Fetch redirect mode ('follow' | 'manual' | 'error').
+     * Passed directly to fetch(). Default: 'follow'.
+     */
+    redirect?: RequestRedirect;
+    /**
+     * Node.js Undici Dispatcher (ProxyAgent, custom Agent, mTLS).
+     * Passed through to fetch() in Node.js 18+ environments.
+     */
+    dispatcher?: unknown;
+    /**
+     * If true, serializes a plain object body to application/x-www-form-urlencoded
+     * using URLSearchParams.
+     */
+    formUrlEncoded?: boolean;
+    /**
+     * Callback invoked as response bytes are received.
+     * Uses WHATWG ReadableStream under the hood.
+     */
+    onDownloadProgress?: (event: ProgressEvent) => void;
+    /**
+     * Callback invoked as request body bytes are uploaded.
+     */
+    onUploadProgress?: (event: ProgressEvent) => void;
+    /**
+     * Per-request retry policy override.
+     * Set to `false` to disable retry for this request even if the client has a default policy.
+     */
+    retry?: Partial<RetryPolicy> | false;
+    /**
+     * Override the Fetch implementation for this specific request.
+     * Useful for testing or platform-specific transports.
+     */
+    fetchImpl?: FetchImpl;
+    /**
+     * Request-level authentication override.
+     * Set to `false` or `{ skip: true }` to bypass token attachment and refresh for this request.
+     */
+    auth?: boolean | {
+        skip?: boolean;
+    };
+    /**
+     * Static or dynamic Bearer token string or async getter function.
+     * Automatically attaches `Authorization: Bearer <token>` if no Authorization header exists.
+     */
+    bearerToken?: string | (() => string | null | undefined | Promise<string | null | undefined>);
+    /**
+     * Request-level deduplication override.
+     * Set to `true` or `{ enabled: true }` to enable in-flight deduplication for this request.
+     * Set to `false` or `{ enabled: false }` to disable.
+     */
+    dedup?: DedupConfig | boolean;
+    /**
+     * Request-level cache override.
+     * Set to `true` to enable caching for this request (uses default TTL).
+     * Set to `false` or `{ skip: true }` to bypass caching.
+     * Pass `{ ttl: number }` to specify a custom TTL in milliseconds.
+     */
+    cache?: RequestCacheConfig | boolean;
+    /**
+     * Optional schema validator (Zod, Standard Schema, Valibot, or function) to parse and validate
+     * the response data before returning.
+     */
+    schema?: SchemaValidator<unknown>;
+    /**
+     * If true, unwraps the response and returns `response.data` directly instead of the full envelope.
+     */
+    unwrap?: boolean;
+    /**
+     * Enables diagnostic logging to the console, or invokes a custom logger function.
+     */
+    debug?: boolean | DebugLogger;
+    /**
+     * Per-request circuit breaker override or configuration.
+     */
+    circuitBreaker?: CircuitBreakerConfig | boolean;
+    /**
+     * Internal tracking flag indicating whether this request is a post-refresh retry.
+     */
+    _isRefreshed?: boolean;
+    /** Internal tracking flag indicating whether this request is being executed inside dedup wrapper. */
+    _isFromDedup?: boolean;
+    /** Internal tracking flag indicating whether this request has already acquired a concurrency slot. */
+    _isFromConcurrency?: boolean;
+    /**
+     * Callback fired when background revalidation finishes in 'stale-while-revalidate' mode.
+     */
+    onRevalidated?: (response: HttpResponse<unknown>) => void;
+    /** Internal tracking flag indicating whether this request is a background SWR revalidation. */
+    _isRevalidating?: boolean;
+}
+/**
+ * Client-level defaults. All values apply to every request unless overridden.
+ * Extends RequestConfig so any RequestConfig field can be set as a client default.
+ */
+interface ClientConfig extends Omit<RequestConfig, 'url' | 'method' | 'signal' | 'auth' | 'dedup' | 'cache' | 'circuitBreaker'> {
+    /**
+     * Base URL prepended to all relative request URLs.
+     * Must not include a trailing slash (enforced at runtime with a warning).
+     */
+    baseURL?: string;
+    /**
+     * Default timeout for all requests in milliseconds. Default: 0 (no timeout).
+     */
+    timeout?: number;
+    /**
+     * Default retry policy applied to all requests.
+     * Individual requests can override or disable via RequestConfig.retry.
+     */
+    retry?: Partial<RetryPolicy>;
+    /**
+     * Request deduplication configuration.
+     * Disabled by default — must be explicitly enabled.
+     */
+    dedup?: DedupConfig;
+    /**
+     * In-memory cache configuration.
+     * Disabled by default — must be explicitly enabled.
+     */
+    cache?: CacheConfig;
+    /**
+     * Authentication configuration.
+     * Provides callbacks for attaching tokens and refreshing them on 401.
+     */
+    auth?: AuthConfig;
+    /**
+     * Static or dynamic Bearer token string or async getter function.
+     * Automatically attaches `Authorization: Bearer <token>` if no Authorization header exists.
+     */
+    bearerToken?: string | (() => string | null | undefined | Promise<string | null | undefined>);
+    /**
+     * Maximum number of concurrent HTTP requests permitted simultaneously.
+     * Excess requests wait in a FIFO queue. Default: undefined (unlimited).
+     */
+    maxConcurrentRequests?: number;
+    /**
+     * Circuit breaker configuration to prevent cascading failures.
+     */
+    circuitBreaker?: CircuitBreakerConfig;
+    /**
+     * Custom Fetch implementation used for all requests from this client.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetchImpl?: FetchImpl;
+    /**
+     * Enables diagnostic logging for all requests dispatched by this client.
+     */
+    debug?: boolean | DebugLogger;
+    /**
+     * Default unwrapping behavior. When true, returns `response.data` directly.
+     */
+    unwrap?: boolean;
+}
+/**
+ * The fully resolved configuration after merging client defaults and per-request overrides.
+ * Exposed on HttpResponse and error objects for debugging.
+ * Authorization headers are redacted before being stored here.
+ */
+interface ResolvedRequestConfig {
+    url: string;
+    method: HttpMethod;
+    headers: Record<string, string>;
+    params?: QueryParams;
+    pathParams?: PathParams;
+    timeout: number;
+    responseType: ResponseType;
+    credentials?: RequestCredentials;
+    retry: ResolvedRetryPolicy;
+}
+/**
+ * The resolved response envelope returned from client methods.
+ * @template T The type of the parsed response body.
+ */
+interface HttpResponse<T = unknown> {
+    /** Parsed response data. Type depends on `responseType` and `schema`. */
+    data: T;
+    /** HTTP status code (e.g. 200, 404). */
+    status: number;
+    /** HTTP status text (e.g. 'OK', 'Not Found'). */
+    statusText: string;
+    /** Response headers. Keys are normalized to lowercase. */
+    headers: Record<string, string>;
+    /** The resolved configuration used for this request. Authorization is redacted. */
+    config: ResolvedRequestConfig;
+    /** True when data was served from the in-memory cache or 304 Not Modified. */
+    cached: boolean;
+    /** True when data was served from stale cache in stale-while-revalidate mode. */
+    stale?: boolean;
+    /** True when this response was shared with another in-flight duplicate request. */
+    fromDedup: boolean;
+    /** The original Fetch Request object. */
+    request: Request;
+}
+/**
+ * Retry policy for a request.
+ * Only idempotent methods are retried by default.
+ */
+interface RetryPolicy {
+    /**
+     * Maximum number of retry attempts after the initial request.
+     * Default: 0 (no retries).
+     */
+    attempts: number;
+    /**
+     * Backoff strategy between retries.
+     * - 'exponential': delay doubles each attempt (e.g. 1s, 2s, 4s).
+     * - 'linear': delay grows linearly (delay * attempt).
+     * Default: 'exponential'.
+     */
+    backoff: 'exponential' | 'linear';
+    /**
+     * Base delay in milliseconds between retries.
+     * Default: 1000.
+     */
+    delay: number;
+    /**
+     * Maximum delay cap in milliseconds (for exponential backoff).
+     * Default: 30000.
+     */
+    maxDelay: number;
+    /**
+     * Add random jitter to the retry delay to avoid thundering herd.
+     * Default: true.
+     */
+    jitter: boolean;
+    /**
+     * HTTP status codes or predicate function that triggers a retry.
+     * Default: [429, 500, 502, 503, 504].
+     */
+    retryOn: number[] | ((error: unknown, attempt: number) => boolean);
+    /**
+     * Methods that are eligible for retry.
+     * Default: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'].
+     * POST and PATCH are excluded to prevent duplicate mutations.
+     */
+    safeMethods: HttpMethod[];
+    /**
+     * Whether to respect the Retry-After response header.
+     * When true, uses the header value as the retry delay (up to maxDelay).
+     * Default: true.
+     */
+    respectRetryAfter: boolean;
+    /**
+     * Optional custom retry predicate. When provided, evaluated to decide if retry occurs.
+     */
+    retryCondition?: (error: unknown, attempt: number) => boolean;
+}
+/** Internal resolved retry policy with all required fields guaranteed present. */
+interface ResolvedRetryPolicy {
+    attempts: number;
+    backoff: 'exponential' | 'linear';
+    delay: number;
+    maxDelay: number;
+    jitter: boolean;
+    retryOn: number[] | ((error: unknown, attempt: number) => boolean);
+    safeMethods: HttpMethod[];
+    respectRetryAfter: boolean;
+    retryCondition?: (error: unknown, attempt: number) => boolean;
+}
+/**
+ * Authentication configuration provided at client creation.
+ * The library does not manage token storage — that is the caller's responsibility.
+ */
+interface AuthConfig {
+    /**
+     * Called before each request. Must return the current access token string,
+     * or `null`/`undefined` to skip adding an Authorization header.
+     */
+    getToken: () => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * Called when a 401 response is received.
+     * Must refresh the access token and return the new token string.
+     * Throw from this function to signal that refresh failed.
+     * Multiple concurrent 401s share a single refresh call (single-flight).
+     */
+    refreshToken?: () => string | Promise<string>;
+    /**
+     * HTTP status codes that trigger a token refresh attempt.
+     * Default: [401].
+     */
+    refreshOn?: number[];
+    /**
+     * Header name to attach the token to.
+     * Default: 'Authorization'.
+     */
+    headerName?: string;
+    /**
+     * Token prefix placed before the token value.
+     * Default: 'Bearer '.
+     */
+    tokenPrefix?: string;
+    /**
+     * URLs that should NOT trigger a token refresh when they return 401.
+     * Typically includes the refresh endpoint itself to prevent recursive refresh.
+     * Accepts exact strings or RegExp patterns.
+     */
+    refreshExcludeUrls?: Array<string | RegExp>;
+}
+/**
+ * In-flight request deduplication configuration.
+ * When enabled, concurrent identical GET requests share one network call.
+ */
+interface DedupConfig {
+    /** Must be explicitly set to true to enable deduplication. Default: false. */
+    enabled: boolean;
+    /**
+     * Methods eligible for deduplication.
+     * Default: ['GET', 'HEAD'].
+     * POST, PUT, PATCH, DELETE are excluded to prevent deduplicating mutations.
+     */
+    methods?: HttpMethod[];
+}
+/**
+ * Pluggable persistent storage adapter for response caching (MMKV, AsyncStorage, localStorage, etc.).
+ */
+interface CacheStorageAdapter {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+    clear?(): Promise<void> | void;
+}
+/**
+ * Request-level cache configuration.
+ */
+interface RequestCacheConfig {
+    /** Time-to-live for this specific request in milliseconds. */
+    ttl?: number;
+    /** Explicitly bypass the cache for this request. Default: false. */
+    skip?: boolean;
+    /**
+     * Enable RFC 7234 conditional validation (ETag / If-None-Match, Last-Modified / If-Modified-Since).
+     * When true, sends validation headers and reuses cached body on 304 Not Modified.
+     */
+    etag?: boolean;
+    /**
+     * Caching strategy for this request:
+     * - 'cache-first': Return cached data if fresh; otherwise hit network. (Default)
+     * - 'stale-while-revalidate': Return stale cached data immediately (0ms), then revalidate in background.
+     */
+    strategy?: 'cache-first' | 'stale-while-revalidate';
+    /**
+     * Callback fired when background revalidation finishes in 'stale-while-revalidate' mode.
+     */
+    onRevalidated?: (response: HttpResponse<unknown>) => void;
+}
+/** In-memory and persistent cache configuration for client-level setup. */
+interface CacheConfig {
+    /** Must be explicitly set to true to enable caching. Default: false. */
+    enabled: boolean;
+    /**
+     * Default time-to-live for cached entries in milliseconds.
+     * Default: 60000 (1 minute).
+     */
+    defaultTtl?: number;
+    /** Legacy alias or shorthand for defaultTtl. */
+    ttl?: number;
+    /**
+     * Maximum number of cached responses in memory before LRU eviction.
+     * Default: 100 entries.
+     */
+    maxSize?: number;
+    /**
+     * Methods whose responses are eligible for caching.
+     * Default: ['GET', 'HEAD'].
+     * POST, PUT, PATCH, and DELETE are strictly disallowed.
+     */
+    methods?: HttpMethod[];
+    /**
+     * Whether to allow caching authenticated requests (requests with an Authorization header).
+     * When true, cache keys partition responses per unique authorization header.
+     * When false (default), requests carrying Authorization are never cached.
+     * Default: false.
+     */
+    allowAuthenticated?: boolean;
+    /**
+     * Enable RFC 7234 conditional validation (ETag / If-None-Match) globally.
+     * Default: true when cache is enabled.
+     */
+    etag?: boolean;
+    /**
+     * Optional persistent storage adapter (e.g. MMKV, AsyncStorage, localStorage, MemoryStorageAdapter).
+     * When configured, cached responses survive application reboots and are hydrated on initialization.
+     */
+    storage?: CacheStorageAdapter;
+    /**
+     * Storage key prefix or key name used when persisting cache entries to `storage`.
+     * Default: 'rnfc_http_cache'.
+     */
+    storageKey?: string;
+    /**
+     * Default caching strategy across all cacheable requests:
+     * - 'cache-first' (default)
+     * - 'stale-while-revalidate'
+     */
+    strategy?: 'cache-first' | 'stale-while-revalidate';
+    /**
+     * Alias for `strategy`.
+     */
+    defaultStrategy?: 'cache-first' | 'stale-while-revalidate';
+}
+/**
+ * Public interface of the response cache manager.
+ */
+interface ResponseCache {
+    /** Get a cached response by key if present and not expired. */
+    get<T = unknown>(key: string): HttpResponse<T> | undefined;
+    /** Store a response in cache with optional TTL. */
+    set<T = unknown>(key: string, response: HttpResponse<T>, ttlMs?: number): void;
+    /** Check if a key exists in cache and is not expired. */
+    has(key: string): boolean;
+    /** Delete a specific cache entry. */
+    delete(key: string): boolean;
+    /** Delete all cache entries matching a string prefix or RegExp pattern. */
+    deletePattern(pattern: string | RegExp): number;
+    /** Clear all cache entries. */
+    clear(): void;
+    /** Number of currently cached entries in memory. */
+    readonly size: number;
+    /** Hydrate cache store from persistent storage adapter if configured. */
+    hydrate(): Promise<void>;
+    /** Persist current in-memory cache to storage adapter if configured. */
+    persist(): Promise<void>;
+}
+/**
+ * A fulfilled interceptor handler.
+ * @template V The value type this handler receives and may return.
+ */
+type InterceptorFulfilled<V> = (value: V) => V | Promise<V>;
+/**
+ * A rejected interceptor handler.
+ * Receives the error. May rethrow, transform, or recover by returning a value.
+ */
+type InterceptorRejected = (error: unknown) => unknown;
+/** A registered interceptor pair. */
+interface Interceptor<V> {
+    fulfilled: InterceptorFulfilled<V>;
+    rejected?: InterceptorRejected;
+}
+/**
+ * Manages a list of interceptors of a specific type.
+ * @template V The value type flowing through the interceptor chain.
+ */
+interface InterceptorManager<V> {
+    /**
+     * Register a new interceptor.
+     * @returns A numeric ID that can be passed to `eject()` to remove the interceptor.
+     */
+    use(fulfilled: InterceptorFulfilled<V>, rejected?: InterceptorRejected): number;
+    /** Remove a previously registered interceptor by its ID. */
+    eject(id: number): void;
+    /** Remove all registered interceptors. */
+    clear(): void;
+}
+/** Discriminant code on all FetchNativeError instances. */
+type ErrorCode = 'HTTP_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'CANCELLED' | 'PARSE_ERROR' | 'CONFIG_ERROR' | 'RETRY_EXHAUSTED' | 'VALIDATION_ERROR' | 'CIRCUIT_OPEN';
+/**
+ * Safe client methods that return `[data, error]` tuples instead of throwing.
+ */
+interface SafeHttpClient {
+    /** Send a safe GET request. */
+    get<T = unknown>(url: string, config?: RequestConfig): Promise<SafeResult<T>>;
+    /** Send a safe POST request. */
+    post<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<SafeResult<T>>;
+    /** Send a safe PUT request. */
+    put<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<SafeResult<T>>;
+    /** Send a safe PATCH request. */
+    patch<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<SafeResult<T>>;
+    /** Send a safe DELETE request. */
+    delete<T = unknown>(url: string, config?: RequestConfig): Promise<SafeResult<T>>;
+    /** Send a safe request with arbitrary method. */
+    request<T = unknown>(config: RequestConfig & {
+        url: string;
+        method: HttpMethod;
+    }): Promise<SafeResult<T>>;
+}
+/**
+ * Options for configuring auto-pagination traversal.
+ */
+interface PaginationConfig<T = unknown> {
+    /**
+     * Strategy:
+     * - 'page': Increments page number query param. (Default)
+     * - 'offset': Increments offset query param by limit/pageSize.
+     * - 'cursor': Uses cursor token extracted from response.
+     * - 'linkHeader': Parses RFC 5988 / 8288 `Link: <url>; rel="next"` header.
+     */
+    type?: 'page' | 'offset' | 'cursor' | 'linkHeader';
+    /** Query parameter name for page number. Default: 'page'. */
+    pageParam?: string;
+    /** Alias for pageParam. */
+    param?: string;
+    /** Initial page index (usually 1 or 0). Default: 1. */
+    initialPage?: number;
+    /** Query parameter name for page size / limit. Default: 'limit'. */
+    pageSizeParam?: string;
+    /** Alias for pageSizeParam. */
+    limitParam?: string;
+    /** Page size limit value. */
+    pageSize?: number;
+    /** Alias for pageSize. */
+    limit?: number;
+    /** Query parameter name for offset. Default: 'offset'. */
+    offsetParam?: string;
+    /** Initial offset index. Default: 0. */
+    initialOffset?: number;
+    /** Query parameter name for cursor token. Default: 'cursor'. */
+    cursorParam?: string;
+    /** Initial cursor token value. */
+    initialCursor?: string | number;
+    /**
+     * Custom function to extract the next cursor from the response.
+     * Return null or undefined when no further pages exist.
+     */
+    getNextCursor?: (response: HttpResponse<T>) => string | number | null | undefined;
+    /**
+     * Custom function to extract the next URL directly from the response envelope.
+     * Return null or undefined when no further pages exist.
+     */
+    getNextUrl?: (response: HttpResponse<T>) => string | null | undefined;
+    /**
+     * Custom function to extract the array of items from response data.
+     * Default: returns `data` if it is an Array, or the first Array property found in `data`.
+     */
+    getItems?: (data: T) => unknown[];
+    /** Maximum number of pages to fetch to prevent infinite loops. Default: 50. */
+    maxPages?: number;
+    /** Alias for maxPages. */
+    totalPages?: number;
+}
+/**
+ * Request options extended with pagination configuration.
+ */
+interface PaginateOptions<T = unknown> extends Omit<RequestConfig, 'params'> {
+    params?: QueryParams;
+    pagination?: PaginationConfig<T>;
+}
+/**
+ * Auto-pagination helper attached to the client instance (`api.paginate`).
+ */
+interface PaginateHelper {
+    /**
+     * Yields items individually across paginated endpoints.
+     *
+     * @example
+     * ```ts
+     * for await (const user of api.paginate<User>('/users')) {
+     *   console.log(user.name);
+     * }
+     * ```
+     */
+    <TItem = unknown, TResponse = unknown>(url: string, options?: PaginateOptions<TResponse>): AsyncGenerator<TItem, void, unknown>;
+    /**
+     * Yields full HttpResponse page objects across paginated endpoints.
+     */
+    pages<TResponse = unknown>(url: string, options?: PaginateOptions<TResponse>): AsyncGenerator<HttpResponse<TResponse>, void, unknown>;
+    /**
+     * Collects all paginated items into a single flattened array.
+     */
+    all<TItem = unknown, TResponse = unknown>(url: string, options?: PaginateOptions<TResponse>): Promise<TItem[]>;
+}
+/**
+ * Dynamic callback generating a mock response based on the dispatched request config.
+ */
+type MockReplyCallback<T = unknown> = (config: RequestConfig & {
+    url: string;
+    method: HttpMethod;
+}) => [number, T?, Record<string, string>?] | Promise<[number, T?, Record<string, string>?]>;
+/**
+ * Route handler definition for the mock adapter.
+ */
+interface MockHandler {
+    readonly method: HttpMethod | 'ANY';
+    readonly url: string | RegExp;
+    /** Respond with a specific HTTP status code, data, and optional headers. */
+    reply(status: number, data?: unknown, headers?: Record<string, string>): void;
+    /** Respond with a dynamic callback returning [status, data, headers]. */
+    reply(callback: MockReplyCallback): void;
+    /** Simulate a network timeout error (`TimeoutError`). */
+    replyWithTimeout(): void;
+    /** Simulate a network connection failure (`NetworkError`). */
+    replyWithNetworkError(message?: string): void;
+}
+/**
+ * Captured history record of a request intercepted by the mock adapter.
+ */
+interface MockHistoryItem {
+    url: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    body?: unknown;
+    params?: QueryParams;
+    pathParams?: PathParams;
+}
+/**
+ * Mock adapter instance returned by `createMockAdapter(client)`.
+ */
+interface MockAdapter {
+    onGet(url?: string | RegExp): MockHandler;
+    onPost(url?: string | RegExp): MockHandler;
+    onPut(url?: string | RegExp): MockHandler;
+    onPatch(url?: string | RegExp): MockHandler;
+    onDelete(url?: string | RegExp): MockHandler;
+    onAny(url?: string | RegExp): MockHandler;
+    /** Clear all mock route handlers and captured history. */
+    reset(): void;
+    /** Clear all registered mock route handlers. */
+    resetHandlers(): void;
+    /** Clear captured request history. */
+    resetHistory(): void;
+    /** Restore the original fetch implementation on the client. */
+    restore(): void;
+    /** Captured request history grouped by method. */
+    history: Record<Lowercase<HttpMethod> | 'all', MockHistoryItem[]>;
+}
+/**
+ * An HTTP client instance returned by `createClient()`.
+ */
+interface HttpClient {
+    /**
+     * Send a GET request.
+     * @template T Expected type of the parsed response body.
+     */
+    get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Send a POST request.
+     * @template T Expected type of the parsed response body.
+     */
+    post<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Send a PUT request.
+     * @template T Expected type of the parsed response body.
+     */
+    put<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Send a PATCH request.
+     * @template T Expected type of the parsed response body.
+     */
+    patch<T = unknown>(url: string, body?: RequestConfig['body'], config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Send a DELETE request.
+     * @template T Expected type of the parsed response body.
+     */
+    delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Send a request with full configuration control.
+     * All other methods delegate to this.
+     */
+    request<T = unknown>(config: RequestConfig & {
+        url: string;
+        method: HttpMethod;
+    }): Promise<HttpResponse<T>>;
+    /** Response cache manager. */
+    cache: ResponseCache;
+    /** Request and response interceptor managers. */
+    interceptors: {
+        request: InterceptorManager<RequestConfig>;
+        response: InterceptorManager<HttpResponse<unknown>>;
+    };
+    /**
+     * Safe request interface returning Go/Rust style `[data, error]` tuples without throwing.
+     */
+    safe: SafeHttpClient;
+    /**
+     * Stream Server-Sent Events (SSE) or chunked responses using an AsyncGenerator.
+     */
+    stream(url: string, options?: StreamOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * Upload helper that simplifies file and FormData uploads with automatic boundary handling
+     * and progress tracking.
+     */
+    upload<T = unknown>(url: string, file: UploadFileSource, options?: UploadOptions): Promise<HttpResponse<T>>;
+    /**
+     * Auto-pagination traversal helper.
+     */
+    paginate: PaginateHelper;
+}
+
+/**
+ * Main HTTP Client Factory for react-native-fetch-client.
+ *
+
+ * Provides a modern, Fetch-native HTTP client instance with:
+ * - Axios-like convenience methods (`.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.request()`)
+ * - Safe error handling (`.safe.get()`, `.safe.post()`, etc.) returning `[data, error]` tuples
+ * - Native AI / SSE streaming (`.stream()`) using WHATWG ReadableStream and AsyncGenerator
+ * - File and FormData upload helper (`.upload()`) with progress tracking
+ * - Interceptors for requests and responses
+ * - Pluggable in-memory caching and deduplication
+ * - Concurrency throttling and Circuit Breaker resiliency
+ *
+ * @module client
+ */
+
+/**
+ * Creates and configures a new `HttpClient` instance.
+ *
+ * @param config Optional client-level configuration defaults.
+ * @returns An initialized `HttpClient` instance.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'react-native-fetch-client';
+ *
+
+ * const api = createClient({
+ *   baseURL: 'https://api.example.com/v1',
+ *   timeout: 10000,
+ *   bearerToken: 'my-jwt-token',
+ *   retry: { attempts: 3 },
+ * });
+ *
+ * // Standard request
+ * const res = await api.get('/users/123');
+ * console.log(res.data);
+ *
+ * // Safe request without try/catch
+ * const [user, error] = await api.safe.get('/users/123');
+ * if (error) {
+ *   console.error('Request failed:', error.message);
+ * }
+ * ```
+ */
+declare function createClient(config?: ClientConfig): HttpClient;
+
+/**
+ * Manages authentication token attachment and single-flight token refresh.
+ * Scoped to each client instance to ensure state isolation.
+ */
+declare class AuthManager {
+    private readonly config?;
+    private activeRefreshPromise;
+    constructor(config?: AuthConfig | undefined);
+    /** Returns the configured header name in lowercase, defaulting to 'authorization'. */
+    getHeaderName(): string;
+    /**
+     * Attaches the access token retrieved from `getToken()` to request headers.
+     * Does not overwrite an existing explicit header of the same name.
+     */
+    attachToken(headers: Record<string, string>, _url: string, requestAuth?: boolean | {
+        skip?: boolean;
+    }): Promise<void>;
+    /**
+     * Checks whether an error from a request URL is eligible for a token refresh attempt.
+     */
+    isEligibleForRefresh(error: unknown, url: string, isRefreshed?: boolean, requestAuth?: boolean | {
+        skip?: boolean;
+    }): boolean;
+    /**
+     * Initiates or shares an in-flight single-flight token refresh operation.
+     * Concurrent 401s await the same Promise. Cleared on completion or error.
+     */
+    refresh(): Promise<string>;
+    /**
+     * Waits for token refresh while respecting the caller's request cancellation signal.
+     */
+    waitForRefresh(signal?: AbortSignal): Promise<string>;
+    private isExcludedUrl;
+}
+
+/**
+ * Generates a stable, deterministic key representing an in-flight request identity.
+ * Accounts for method, normalized URL, sorted relevant headers, credentials, and body.
+ */
+declare function generateDedupKey(method: string, url: string, headers?: Record<string, string>, credentials?: RequestCredentials, body?: unknown): string;
+/**
+ * Coordinates in-flight request deduplication with fine-grained cancellation semantics.
+ * Each client maintains its own DedupManager instance for complete isolation.
+ */
+declare class DedupManager {
+    private inFlight;
+    /**
+     * Executes or joins an in-flight request for the given deduplication key.
+     * If a matching request is already in flight, the caller subscribes to it.
+     * If an individual caller cancels their AbortSignal, that caller immediately rejects,
+     * but the underlying request continues for other subscribers.
+     * The underlying request is only aborted if all subscribers have cancelled.
+     */
+    execute<T>(key: string, factory: (signal: AbortSignal) => Promise<HttpResponse<T>>, callerSignal?: AbortSignal): Promise<HttpResponse<T>>;
+    /** Returns the current number of active in-flight deduplicated requests. */
+    getActiveCount(): number;
+    /** Clears all in-flight entries. */
+    clear(): void;
+}
+
+/** Internal cache entry storing the cloned response and expiration timestamp. */
+interface CacheEntry<T = unknown> {
+    response: HttpResponse<T>;
+    expiresAt: number;
+    etag?: string;
+    lastModified?: string;
+}
+/**
+ * Deep clones data to prevent consumer mutation of cached objects or
+ * mutation of returned responses corrupting cache storage.
+ */
+declare function cloneData<T>(data: T): T;
+/**
+ * Generates a cache key for a request.
+ * Normalizes URL and includes authorization header hash/slice if authenticated caching is allowed.
+ */
+declare function generateCacheKey(method: string, url: string, headers?: Record<string, string>, allowAuthenticated?: boolean): string;
+/**
+ * Checks if a request method and headers are eligible for caching.
+ * Unsafe methods (POST, PUT, PATCH, DELETE) are never eligible.
+ */
+declare function isCacheEligible(method: string, headers: Record<string, string> | undefined, requestCache: RequestCacheConfig | boolean | undefined, clientCache: CacheConfig | undefined): boolean;
+/**
+ * LRU cache manager supporting in-memory and persistent storage adapters (MMKV / AsyncStorage)
+ * with RFC 7234 conditional validation and Stale-While-Revalidate (SWR) support.
+ */
+declare class CacheManager implements ResponseCache {
+    private readonly store;
+    private readonly defaultTtl;
+    private readonly maxSize;
+    readonly storage?: CacheStorageAdapter;
+    readonly storageKey: string;
+    readonly defaultStrategy: 'cache-first' | 'stale-while-revalidate';
+    constructor(config?: CacheConfig);
+    /**
+     * Hydrates cached entries from persistent storage into memory.
+     */
+    hydrate(): Promise<void>;
+    /**
+     * Persists active (non-expired) cache entries to storage adapter.
+     */
+    persist(): Promise<void>;
+    /**
+     * Retrieves a cached response by key.
+     * If expired and allowStale is false, evicts the entry and returns undefined.
+     */
+    get<T = unknown>(key: string, options?: {
+        allowStale?: boolean;
+    }): HttpResponse<T> | undefined;
+    /**
+     * Checks if an entry exists and is expired (stale).
+     */
+    isStale(key: string): boolean;
+    /**
+     * Retrieves the raw cache entry (including expired entries) for conditional revalidation.
+     */
+    getEntry<T = unknown>(key: string): CacheEntry<T> | undefined;
+    /**
+     * Revalidates an existing cache entry on receiving an HTTP 304 Not Modified response.
+     * Updates headers, extends TTL, and returns the response with fresh cached data.
+     */
+    updateFrom304<T = unknown>(key: string, newHeaders: Record<string, string>, ttlMs?: number): HttpResponse<T> | undefined;
+    set<T = unknown>(key: string, response: HttpResponse<T>, ttlMs?: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    deletePattern(pattern: string | RegExp): number;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Manages an ordered chain of request or response interceptors.
+ */
+declare class DefaultInterceptorManager<V> implements InterceptorManager<V> {
+    private handlers;
+    private nextId;
+    /**
+     * Register a new interceptor.
+     * @returns Numeric registration ID used to eject.
+     */
+    use(fulfilled: InterceptorFulfilled<V>, rejected?: InterceptorRejected): number;
+    /**
+     * Remove a registered interceptor by ID.
+     */
+    eject(id: number): void;
+    /**
+     * Remove all registered interceptors.
+     */
+    clear(): void;
+    /**
+     * Returns active interceptors in registration order.
+     */
+    getInterceptors(): Array<Interceptor<V>>;
+}
+
+/**
+ * Circuit Breaker State Machine for Fetch-Native-Client.
+ *
+ * Implements the classic Release It! Circuit Breaker pattern with three states:
+ *
+ *         [Consecutive failures >= threshold]
+ *  CLOSED -------------------------------------> OPEN
+ *    ^                                             |
+ *    | [Canary succeeded]                          | [resetTimeoutMs elapsed]
+ *    |                                             v
+ *    +---------------------------------------- HALF_OPEN
+ *             [Canary failed: re-open]
+ *
+ * Purpose:
+ * When an upstream microservice crashes or experiences an outage, attempting
+ * continuous HTTP requests wastes sockets, drains mobile battery, and thrashes
+ * downstream services. The circuit breaker fails fast locally with `CircuitBreakerError`,
+ * protecting both client resources and the failing server.
+ *
+ * @module circuit-breaker
+ */
+
+/**
+ * Manages the state machine for a circuit breaker instance.
+ */
+declare class CircuitBreaker {
+    readonly config: CircuitBreakerConfig;
+    private state;
+    private failureCount;
+    private nextAttemptTime;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly isFailureFn;
+    constructor(config: CircuitBreakerConfig);
+    /**
+     * Current lifecycle state of the circuit breaker.
+     */
+    getState(): CircuitState;
+    /**
+     * Current consecutive failure count.
+     */
+    getFailures(): number;
+    /**
+     * Resets the circuit breaker state to CLOSED and clears failure counts.
+     */
+    reset(): void;
+    /**
+     * Checks if a request is allowed to execute.
+     * Throws `CircuitBreakerError` if the circuit is currently OPEN.
+     */
+    beforeExecution(): void;
+    /**
+     * Records a successful execution. If the circuit was in HALF_OPEN state,
+     * it transitions back to CLOSED.
+     */
+    recordSuccess(): void;
+    /**
+     * Records an execution error. Evaluates the failure predicate and
+     * updates the circuit state accordingly.
+     */
+    recordFailure(error: unknown): void;
+    /**
+     * Executes a task wrapped in the circuit breaker lifecycle.
+     *
+     * @template T Return type of the task.
+     * @param task Function returning a Promise to execute.
+     * @returns Result of the task.
+     * @throws {CircuitBreakerError} If the circuit is OPEN.
+     */
+    execute<T>(task: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Concurrency Limiter for Fetch-Native-Client.
+ *
+ * Implements an in-memory FIFO queue to cap the maximum number of simultaneous
+ * in-flight HTTP requests dispatched by the client.
+ *
+ * Prevents socket exhaustion in Node.js, respects mobile browser connection limits
+ * (typically 6 per domain on HTTP/1.1), and prevents overwhelming backend microservices.
+ *
+ * @module concurrency
+ */
+/**
+ * Manages request concurrency with strict FIFO ordering.
+ */
+declare class ConcurrencyLimiter {
+    readonly maxConcurrent: number;
+    private activeCount;
+    private readonly queue;
+    /**
+     * @param maxConcurrent Maximum number of concurrent tasks allowed to run simultaneously.
+     * If less than or equal to 0, concurrency is unlimited.
+     */
+    constructor(maxConcurrent: number);
+    /**
+     * Acquires a concurrency slot. Resolves immediately if active count < limit,
+     * otherwise blocks until a preceding task releases a slot.
+     */
+    private acquire;
+    /**
+     * Releases an active concurrency slot and unblocks the next queued task in FIFO order.
+     */
+    private release;
+    /**
+     * Schedules an asynchronous function through the concurrency limiter.
+     *
+     * @template T The return type of the function.
+     * @param task Function returning a Promise to execute once a slot is available.
+     * @param signal Optional AbortSignal to cancel waiting in the queue.
+     * @returns The resolved value of the task.
+     */
+    run<T>(task: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Current number of actively executing requests.
+     */
+    get active(): number;
+    /**
+     * Current number of requests queued waiting for an available slot.
+     */
+    get pending(): number;
+    /**
+     * Clears all queued pending requests and rejects them with the provided error.
+     */
+    clear(error?: Error): void;
+}
+
+/**
+ * Zero-dependency Duck-Typing Schema Validation.
+ *
+ * Supports:
+ * 1. Standard Schema v1 (`~standard`) — supported by Zod 3.24+, Valibot, ArkType
+ * 2. Zod-like schemas (`.parse()` or `.safeParse()`)
+ * 3. Plain synchronous or asynchronous functions `(data: unknown) => T`
+ *
+ * Keeps `react-native-fetch-client` runtime dependencies strictly at zero (`dependencies: {}`)
+ * while providing compile-time type inference and runtime validation.
+ *
+ * @module validator
+ */
+
+/**
+ * Validates parsed HTTP response data against an arbitrary schema validator.
+ *
+ * @template T The validated data type.
+ * @param schema The schema validator to execute (Standard Schema, Zod-like, or function).
+ * @param data The raw parsed response data to validate.
+ * @param config Optional resolved request configuration for error context.
+ * @returns A promise resolving to the validated (and potentially transformed) data of type `T`.
+ * @throws {ValidationError} When the data does not conform to the schema.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * const UserSchema = z.object({ id: z.number(), name: z.string() });
+ * const user = await validateData(UserSchema, { id: 1, name: 'Alice' });
+ * ```
+ */
+declare function validateData<T>(schema: SchemaValidator<T> | undefined, data: unknown, config?: ResolvedRequestConfig): Promise<T>;
+
+/**
+ * Native AI & Server-Sent Events (SSE) Streaming.
+ *
+ * Implements the WHATWG EventSource line-parsing specification using
+ * standard `ReadableStream<Uint8Array>` and `TextDecoder`.
+ *
+ * Works in:
+ * - Browsers
+ * - Node.js 18+
+ * - Cloudflare Workers
+ * - Deno / Bun
+ *
+ * @module stream
+ */
+
+/**
+ * Parses a WHATWG ReadableStream into an AsyncGenerator of StreamEvent objects.
+ * Follows the W3C / WHATWG Server-Sent Events line format:
+ * - `event: <name>`
+ * - `data: <content>` (multiline supported via consecutive data lines)
+ * - `id: <id>`
+ * - `retry: <ms>`
+ * - Blank line (`\n\n` or `\r\n\r\n`) dispatches the event.
+ *
+ * @param stream The response body ReadableStream to consume.
+ * @param options Streaming configuration options (e.g. rawLines).
+ * @returns An AsyncGenerator yielding parsed StreamEvent items.
+ *
+ * @example
+ * ```ts
+ * for await (const chunk of parseSseStream(response.body)) {
+ *   console.log('SSE Event:', chunk.event, chunk.data);
+ * }
+ * ```
+ */
+declare function parseSseStream(stream: ReadableStream<Uint8Array>, options?: StreamOptions): AsyncGenerator<StreamEvent, void, unknown>;
+
+/**
+ * URL resolution and path parameter interpolation.
+ *
+ * Supports:
+ * - RFC 6570 / Express style path parameters (`:id`, `{id}`)
+ * - Relative vs absolute URL resolution against `baseURL`
+ * - Query parameter merging with preservation of existing query strings
+ *
+ * @module url
+ */
+
+/**
+ * Interpolates path parameters into a URL template string.
+ * Supports both Express-style (`:param`) and OpenAPI-style (`{param}`) placeholders.
+ * Parameter values are automatically URI-encoded.
+ *
+ * @param url The URL template string (e.g. `/users/:id/orders/{orderId}`).
+ * @param pathParams Object containing the parameter key/value mappings.
+ * @returns The interpolated URL string.
+ *
+ * @example
+ * ```ts
+ * interpolatePath('/users/:id/posts/{slug}', { id: 42, slug: 'my first post' });
+ * // returns: '/users/42/posts/my%20first%20post'
+ * ```
+ */
+declare function interpolatePath(url: string, pathParams?: PathParams): string;
+/**
+ * Builds a resolved URL from a base URL, a relative/absolute URL, query parameters,
+ * and path parameters.
+ *
+ * @param url The relative or absolute target URL.
+ * @param baseURL Optional base URL prepended if url is relative.
+ * @param params Optional query parameters to serialize onto the query string.
+ * @param pathParams Optional path parameters to interpolate into template placeholders.
+ * @returns Fully qualified resolved URL string.
+ */
+declare function buildUrl(url?: string, baseURL?: string, params?: QueryParams, pathParams?: PathParams): string;
+
+/**
+ * Auto-Pagination Traverser for react-native-fetch-client.
+ *
+ * Provides async generator iteration over paginated REST endpoints supporting:
+ * - Page number pagination (`page=1, 2, 3...`)
+ * - Offset / Limit pagination (`offset=0, 20, 40...`)
+ * - Cursor-based pagination (`cursor=abc...`)
+ * - RFC 5988 / RFC 8288 standard `Link` header pagination (`rel="next"`)
+ *
+ * @module paginate
+ */
+
+/**
+ * Parses an RFC 5988 / RFC 8288 `Link` header and extracts the URL for `rel="next"`.
+ * Example header: `<https://api.example.com/items?page=2>; rel="next", <...>; rel="last"`
+ */
+declare function parseNextLinkHeader(header?: string): string | null;
+/**
+ * Creates the PaginateHelper bound to an HttpClient instance.
+ */
+declare function createPaginateHelper(client: HttpClient): PaginateHelper;
+
+/**
+ * Declarative Mock Adapter for react-native-fetch-client.
+ *
+ * Enables straightforward unit testing and route stubbing without external libraries
+ * like MSW or nock. Intercepts outgoing requests, returns simulated responses or
+ * simulated network errors, and records complete request history.
+ *
+ * @module mock
+ */
+
+/**
+ * Creates an active mock adapter attached to an HttpClient instance.
+ *
+ * @param client The HttpClient instance to mock.
+ * @param options Options including delay simulation or passthrough for unmatched routes.
+ *
+ * @example
+ * ```ts
+ * const mock = createMockAdapter(api);
+ * mock.onGet('/users/1').reply(200, { id: 1, name: 'Alice' });
+ * mock.onPost('/login').reply(401, { error: 'Invalid credentials' });
+ *
+ * const res = await api.get('/users/1');
+ * expect(res.data.name).toBe('Alice');
+ * expect(mock.history.get.length).toBe(1);
+ * ```
+ */
+declare function createMockAdapter(client: HttpClient, options?: {
+    delayMs?: number;
+    passthrough?: boolean;
+}): MockAdapter;
+
+/**
+ * Storage adapter interface for persistent offline queue.
+ * Compatible with localStorage, IndexedDB, AsyncStorage, etc.
+ */
+interface OfflineStorageAdapter {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+/**
+ * A serialized representation of a request queued for offline replay.
+ */
+interface QueuedRequest {
+    id: string;
+    url: string;
+    method: HttpMethod;
+    headers?: Record<string, string>;
+    params?: QueryParams;
+    body?: string;
+    enqueuedAt: number;
+    attemptCount: number;
+    maxAttempts: number;
+    idempotencyKey: string;
+}
+/**
+ * Summary of a queue process execution.
+ */
+interface QueueProcessSummary {
+    processed: number;
+    succeeded: number;
+    failedPermanent: number;
+    failedTransient: number;
+    remaining: number;
+}
+/**
+ * Configuration for the offline request queue.
+ */
+interface OfflineQueueConfig {
+    /** The react-native-fetch-client instance used to execute replayed requests. */
+    client: {
+        request<T = unknown>(config: RequestConfig & {
+            url: string;
+            method: HttpMethod;
+        }): Promise<HttpResponse<T>>;
+    };
+    /** Storage adapter for persisting the queue. Defaults to in-memory adapter. */
+    storage?: OfflineStorageAdapter;
+    /** Storage key used by the adapter. Default: 'fnc_offline_queue'. */
+    storageKey?: string;
+    /** Maximum number of requests stored in the queue. Default: 100. */
+    maxQueueSize?: number;
+    /** Maximum retry attempts for transient errors before eviction. Default: 5. */
+    maxAttempts?: number;
+    /** Maximum age of a queued request in milliseconds before eviction. Default: 86400000 (24 hours). */
+    maxAgeMs?: number;
+    /** Header name used for idempotency keys. Default: 'Idempotency-Key'. */
+    idempotencyHeader?: string;
+    /**
+     * URLs that are strictly forbidden from offline queuing (e.g. payment/checkout).
+     * Default includes common financial / mutation endpoints.
+     */
+    disallowedUrls?: Array<string | RegExp>;
+    /** Custom predicate to evaluate whether a request is eligible to be enqueued. */
+    shouldQueue?: (config: RequestConfig, error?: unknown) => boolean;
+    /** Called when a queued request succeeds during replay. */
+    onReplaySuccess?: (request: QueuedRequest, response: HttpResponse) => void;
+    /** Called when a queued request fails permanently (e.g. 4xx) or exceeds maxAttempts. */
+    onPermanentFailure?: (request: QueuedRequest, error: unknown) => void;
+    /**
+     * Automatically listen for browser `online` events and trigger `process()`
+     * when network connectivity is restored.
+     * Gracefully ignored in non-browser (Node.js/worker) environments.
+     * Default: false.
+     */
+    autoSyncOnOnline?: boolean;
+}
+/**
+ * Public interface of the offline request queue.
+ */
+interface OfflineQueue {
+    /** Enqueue a request for offline replay. */
+    enqueue(config: RequestConfig): Promise<{
+        enqueued: boolean;
+        id: string;
+    }>;
+    /** Process the queue sequentially. Resolves with a summary of the run. */
+    process(): Promise<QueueProcessSummary>;
+    /** Check if the queue is currently processing. */
+    isProcessing(): boolean;
+    /** Get all currently queued requests. */
+    getItems(): Promise<QueuedRequest[]>;
+    /** Current count of queued requests. */
+    size(): Promise<number>;
+    /** Clear all queued requests from memory and persistent storage. */
+    clear(): Promise<void>;
+    /** Hydrate and clean stale entries from storage. Automatically called on first operation. */
+    initialize(): Promise<void>;
+    /** Unregisters any attached event listeners (e.g. `online` listener) and releases resources. */
+    destroy(): void;
+}
+
+/**
+ * Universal in-memory storage adapter for environments without persistent storage
+ * or for isolated unit testing.
+ */
+declare class MemoryStorageAdapter implements OfflineStorageAdapter {
+    private readonly store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+
+/**
+ * Creates an offline request queue with persistent storage, sequential replay,
+ * duplicate prevention via idempotency keys, and payment mutation guards.
+ */
+declare function createOfflineQueue(config: OfflineQueueConfig): OfflineQueue;
+
+export { type AuthConfig, AuthManager, type CacheConfig, CacheManager, type CacheStorageAdapter, CancelError, CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerError, type CircuitState, type ClientConfig, type ConcurrencyConfig, ConcurrencyLimiter, ConfigError, type DebugLogEntry, type DebugLogger, type DedupConfig, DedupManager, DefaultInterceptorManager, type ErrorCode, type FetchImpl, FetchNativeError, type FunctionalValidator, type HttpClient, HttpError, type HttpMethod, type HttpResponse, type Interceptor, type InterceptorFulfilled, type InterceptorManager, type InterceptorRejected, MemoryStorageAdapter, type MockAdapter, type MockHandler, type MockHistoryItem, type MockReplyCallback, NetworkError, type OfflineQueue, type OfflineQueueConfig, type OfflineStorageAdapter, type PaginateHelper, type PaginateOptions, type PaginationConfig, ParseError, type PathParams, type ProgressEvent, type QueryParams, type QueueProcessSummary, type QueuedRequest, type RequestCacheConfig, type RequestConfig, type ResolvedRequestConfig, type ResolvedRetryPolicy, type ResponseCache, type ResponseType, RetryExhaustedError, type RetryPolicy, type SafeHttpClient, type SafeResult, type SchemaValidator, type StandardSchemaV1, type StreamEvent, type StreamOptions, TimeoutError, type UploadFileSource, type UploadOptions, ValidationError, type ZodLikeSchema, buildUrl, cloneData, createClient, createMockAdapter, createOfflineQueue, createPaginateHelper, generateCacheKey, generateDedupKey, interpolatePath, isCacheEligible, isCancelError, isCircuitBreakerError, isFetchNativeError, isHttpError, isNetworkError, isRetryExhaustedError, isTimeoutError, isValidationError, parseNextLinkHeader, parseSseStream, validateData };