@daloyjs/core 0.36.0 → 0.38.0

package/dist/docs.d.ts

@@ -92,18 +92,69 @@ export interface ScalarReferenceConfiguration {
     spec?: never;
     url?: never;
 }
+/**
+ * Override CDN URLs and pin Subresource Integrity (SRI) hashes for the docs
+ * UI assets.
+ *
+ * Supplying an `*Integrity` value emits an `integrity="…"` attribute plus a
+ * `crossorigin` attribute on the matching `<script>` / `<link>` tag so the
+ * browser refuses to execute a CDN asset whose bytes don't match the pinned
+ * hash. SRI is only meaningful against a **version-pinned** URL
+ * (e.g. `…/@scalar/api-reference@1.25.0`); pair each integrity hash with a
+ * pinned `*Url`, since the framework's default URLs intentionally track the
+ * latest upstream release and therefore cannot carry a stable hash.
+ *
+ * @since 0.37.0
+ */
+export interface DocsAssetOptions {
+    /** Override the Scalar API Reference bundle URL (useful for self-hosting). */
+    scalarScriptUrl?: string;
+    /**
+     * SRI hash for {@link scalarScriptUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    scalarScriptIntegrity?: string;
+    /** Override the Swagger UI stylesheet URL (useful for self-hosting). */
+    swaggerUiCssUrl?: string;
+    /**
+     * SRI hash for {@link swaggerUiCssUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    swaggerUiCssIntegrity?: string;
+    /** Override the Swagger UI bundle URL (useful for self-hosting). */
+    swaggerUiBundleUrl?: string;
+    /**
+     * SRI hash for {@link swaggerUiBundleUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    swaggerUiBundleIntegrity?: string;
+    /**
+     * `crossorigin` attribute value emitted alongside any pinned integrity
+     * hash. SRI on a cross-origin asset requires CORS, so this defaults to
+     * `"anonymous"`; use `"use-credentials"` only when the asset host needs
+     * credentialed requests.
+     *
+     * @since 0.37.0
+     */
+    crossOrigin?: "anonymous" | "use-credentials";
+}
 /** Shared options for {@link scalarHtml} and {@link swaggerUiHtml}. */
 export interface DocsOptions {
     /** Absolute or relative URL of the OpenAPI document to render. */
     specUrl: string;
     /** `<title>` of the generated HTML page. */
     title?: string;
-    /** Override CDN URLs for the docs UI assets (useful for self-hosting). */
-    assets?: {
-        scalarScriptUrl?: string;
-        swaggerUiCssUrl?: string;
-        swaggerUiBundleUrl?: string;
-    };
+    /**
+     * Override CDN URLs and pin SRI hashes for the docs UI assets (useful for
+     * self-hosting or supply-chain hardening). See {@link DocsAssetOptions}.
+     */
+    assets?: DocsAssetOptions;
     /** CSP `nonce` to apply to inline/script tags; must match the response CSP. */
     scriptNonce?: string;
 }

package/dist/docs.js

@@ -8,9 +8,37 @@
  * (You can self-host the assets if your CSP forbids CDNs.)
  */
 const JSDELIVR_ORIGIN = "https://cdn.jsdelivr.net";
+/**
+ * Matches a single Subresource Integrity digest: a `sha256-`/`sha384-`/
+ * `sha512-` prefix followed by standard base64 (with up to two `=` pads).
+ * Linear-time / ReDoS-safe (no nested or overlapping quantifiers).
+ */
+const SRI_HASH = /^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/;
 function nonceAttr(nonce) {
     return nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 }
+/**
+ * Build the `integrity`/`crossorigin` attribute fragment for a docs asset.
+ *
+ * Returns an empty string when no `integrity` value is supplied. When one is
+ * supplied it is validated as one or more space-separated SRI digests and a
+ * `crossorigin` attribute (default `"anonymous"`) is emitted alongside it.
+ * A malformed integrity value throws a {@link TypeError} so a typo fails
+ * loudly instead of silently shipping a docs page with no SRI protection.
+ *
+ * @throws {TypeError} when `integrity` is provided but is not a valid SRI value.
+ */
+function integrityAttr(integrity, crossOrigin) {
+    if (integrity === undefined)
+        return "";
+    const tokens = integrity.trim().split(/\s+/);
+    if (integrity.trim() === "" || tokens.some((t) => !SRI_HASH.test(t))) {
+        throw new TypeError(`Invalid Subresource Integrity value: ${JSON.stringify(integrity)}. ` +
+            `Expected one or more space-separated "sha256-"/"sha384-"/"sha512-" base64 hashes.`);
+    }
+    const co = crossOrigin ?? "anonymous";
+    return ` integrity="${escapeHtml(integrity.trim())}" crossorigin="${escapeHtml(co)}"`;
+}
 /**
  * Render a Scalar API Reference HTML page that loads `opts.specUrl`.
  *
@@ -23,6 +51,7 @@ export function scalarHtml(opts) {
     const url = escapeHtml(opts.specUrl);
     const scriptUrl = escapeHtml(opts.assets?.scalarScriptUrl ??
         `${JSDELIVR_ORIGIN}/npm/@scalar/api-reference`);
+    const scriptSri = integrityAttr(opts.assets?.scalarScriptIntegrity, opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const configuration = scalarConfigurationAttr(opts.specUrl, opts.configuration);
     return `<!doctype html>
@@ -32,7 +61,7 @@ export function scalarHtml(opts) {
 <title>${title}</title>
 </head><body>
 <script id="api-reference" data-url="${url}"${configuration}${nonce}></script>
-<script src="${scriptUrl}"${nonce}></script>
+<script src="${scriptUrl}"${scriptSri}${nonce}></script>
 </body></html>`;
 }
 /**
@@ -46,16 +75,18 @@ export function swaggerUiHtml(opts) {
         `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui.css`);
     const bundleUrl = escapeHtml(opts.assets?.swaggerUiBundleUrl ??
         `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui-bundle.js`);
+    const cssSri = integrityAttr(opts.assets?.swaggerUiCssIntegrity, opts.assets?.crossOrigin);
+    const bundleSri = integrityAttr(opts.assets?.swaggerUiBundleIntegrity, opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     return `<!doctype html>
 <html><head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>${title}</title>
-<link rel="stylesheet" href="${cssUrl}" />
+<link rel="stylesheet" href="${cssUrl}"${cssSri} />
 </head><body>
 <div id="swagger"></div>
-<script src="${bundleUrl}"${nonce}></script>
+<script src="${bundleUrl}"${bundleSri}${nonce}></script>
 <script${nonce}>window.onload=()=>SwaggerUIBundle({url:"${url}",dom_id:"#swagger"});</script>
 </body></html>`;
 }

package/dist/errors.d.ts

@@ -148,6 +148,11 @@ export declare function httpError(opts: HttpErrorOptions): HttpError;
  * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
  * avoid information disclosure.
  *
+ * **Security note:** only **5xx** `detail` is scrubbed in production. A `4xx`
+ * `detail` is always returned to the client (it is assumed to be
+ * client-actionable), so never place secrets or internal diagnostics in the
+ * `detail` of a 4xx error.
+ *
  * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
  * for common statuses; instantiate `HttpError` directly only for unusual
  * status codes or fully-custom problem documents.
@@ -233,6 +238,21 @@ export declare class ValidationError extends HttpError {
 export declare class NotFoundError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `409 Conflict` — the request could not be completed because it conflicts
+ * with the current state of the target resource. The built-in
+ * {@link idempotency} middleware throws this when a second request arrives
+ * with an `Idempotency-Key` that is still being processed by an in-flight
+ * request (the original response has not been produced yet). The response
+ * carries `Cache-Control: no-store` so a private cache cannot mask the
+ * conflict.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.37.0
+ */
+export declare class ConflictError extends HttpError {
+    constructor(detail?: string);
+}
 /**
  * `401 Unauthorized` — authentication is required and missing or invalid.
  * Pair with a `WWW-Authenticate` header on the response when issuing a
@@ -279,6 +299,29 @@ export declare class MethodNotAllowedError extends HttpError {
 export declare class PayloadTooLargeError extends HttpError {
     constructor(limit: number);
 }
+/**
+ * `431 Request Header Fields Too Large` — thrown when an incoming request
+ * carries more distinct header fields than {@link AppOptions.maxHeaderCount}.
+ *
+ * This is the portable, JS-layer counterpart to the native "max header
+ * count" caps that web servers and proxies expose (e.g. NGINX's
+ * `max_headers`, Node's `server.maxHeadersCount`). It is defence-in-depth
+ * against header-*count* amplification — the dimension abused by the
+ * "HTTP/2 Bomb" (Calif, 2026), where per-header server-side bookkeeping is
+ * the amplifier rather than header size. A flood of nearly-empty headers
+ * never reaches the router because the count cap fires first.
+ *
+ * The native HPACK session-memory pinning that the bomb relies on must
+ * still be mitigated at the runtime/proxy that terminates HTTP/2 (apply the
+ * vendor fix and cap the header count there); this guard protects the
+ * application tier on every runtime regardless of upstream configuration.
+ *
+ * @param limit - The configured maximum header count that was exceeded.
+ * @since 0.38.0
+ */
+export declare class RequestHeaderFieldsTooLargeError extends HttpError {
+    constructor(limit: number);
+}
 /**
  * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
  * not in {@link AppOptions.allowedContentTypes} for a route that declares a

package/dist/errors.js

@@ -143,6 +143,11 @@ export function httpError(opts) {
  * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
  * avoid information disclosure.
  *
+ * **Security note:** only **5xx** `detail` is scrubbed in production. A `4xx`
+ * `detail` is always returned to the client (it is assumed to be
+ * client-actionable), so never place secrets or internal diagnostics in the
+ * `detail` of a 4xx error.
+ *
  * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
  * for common statuses; instantiate `HttpError` directly only for unusual
  * status codes or fully-custom problem documents.
@@ -290,6 +295,28 @@ export class NotFoundError extends HttpError {
         this.name = "NotFoundError";
     }
 }
+/**
+ * `409 Conflict` — the request could not be completed because it conflicts
+ * with the current state of the target resource. The built-in
+ * {@link idempotency} middleware throws this when a second request arrives
+ * with an `Idempotency-Key` that is still being processed by an in-flight
+ * request (the original response has not been produced yet). The response
+ * carries `Cache-Control: no-store` so a private cache cannot mask the
+ * conflict.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.37.0
+ */
+export class ConflictError extends HttpError {
+    constructor(detail) {
+        super(409, {
+            type: "https://daloyjs.dev/errors/conflict",
+            title: "Conflict",
+            ...(detail ? { detail } : {}),
+        }, { "cache-control": "no-store" });
+        this.name = "ConflictError";
+    }
+}
 /**
  * `401 Unauthorized` — authentication is required and missing or invalid.
  * Pair with a `WWW-Authenticate` header on the response when issuing a
@@ -368,6 +395,36 @@ export class PayloadTooLargeError extends HttpError {
         this.name = "PayloadTooLargeError";
     }
 }
+/**
+ * `431 Request Header Fields Too Large` — thrown when an incoming request
+ * carries more distinct header fields than {@link AppOptions.maxHeaderCount}.
+ *
+ * This is the portable, JS-layer counterpart to the native "max header
+ * count" caps that web servers and proxies expose (e.g. NGINX's
+ * `max_headers`, Node's `server.maxHeadersCount`). It is defence-in-depth
+ * against header-*count* amplification — the dimension abused by the
+ * "HTTP/2 Bomb" (Calif, 2026), where per-header server-side bookkeeping is
+ * the amplifier rather than header size. A flood of nearly-empty headers
+ * never reaches the router because the count cap fires first.
+ *
+ * The native HPACK session-memory pinning that the bomb relies on must
+ * still be mitigated at the runtime/proxy that terminates HTTP/2 (apply the
+ * vendor fix and cap the header count there); this guard protects the
+ * application tier on every runtime regardless of upstream configuration.
+ *
+ * @param limit - The configured maximum header count that was exceeded.
+ * @since 0.38.0
+ */
+export class RequestHeaderFieldsTooLargeError extends HttpError {
+    constructor(limit) {
+        super(431, {
+            type: "https://daloyjs.dev/errors/request-header-fields-too-large",
+            title: "Request Header Fields Too Large",
+            detail: `Request carries more than ${limit} header fields`,
+        });
+        this.name = "RequestHeaderFieldsTooLargeError";
+    }
+}
 /**
  * `415 Unsupported Media Type` — thrown when the request `Content-Type` is
  * not in {@link AppOptions.allowedContentTypes} for a route that declares a

package/dist/fetch-guard.js

@@ -286,6 +286,10 @@ export function fetchGuard(options = {}) {
             const method = request.method.toUpperCase();
             const shouldDowngrade = res.status === 303 ||
                 ((res.status === 301 || res.status === 302) && method !== "GET" && method !== "HEAD");
+            // Committed to following this hop. Drain the intermediate 3xx body so
+            // the underlying socket isn't pinned until GC (Node/undici keep the
+            // connection open while an un-consumed body stream is outstanding).
+            void res.body?.cancel();
             request = shouldDowngrade
                 ? new Request(next, {
                     method: "GET",

package/dist/fetch-resilience.d.ts

@@ -0,0 +1,295 @@
+/**
+ * `resilientFetch()` — circuit breaker, retry-with-backoff, and per-call
+ * timeout for outbound `fetch`, designed to layer **on top of**
+ * {@link fetchGuard} (which only covers SSRF on egress).
+ *
+ * `fetchGuard()` answers "is this outbound address safe?". This module
+ * answers "is this upstream healthy, and how do we behave when it is
+ * not?" — the operational half of a mature outbound HTTP client
+ * (timeouts that prevent a hung upstream from exhausting your event
+ * loop, bounded retries that ride out a blip without amplifying an
+ * outage, and a circuit breaker that fails fast when an upstream is
+ * clearly down). The two compose: wrap an SSRF-guarded fetch in a
+ * resilient one and you get both safety and resilience with zero runtime
+ * dependencies.
+ *
+ * ```ts
+ * import { fetchGuard, resilientFetch } from "@daloyjs/core";
+ *
+ * const safeFetch = resilientFetch({
+ *   fetch: fetchGuard(),       // SSRF floor underneath
+ *   timeoutMs: 2_000,          // abort any call that stalls past 2s
+ *   retries: 2,                // up to 2 retries on transient failures
+ *   circuitBreaker: { failureThreshold: 5, resetTimeoutMs: 30_000 },
+ * });
+ *
+ * const res = await safeFetch("https://api.example.com/things");
+ * ```
+ *
+ * ## Design notes
+ *
+ * - **Per-call timeout** is enforced with an `AbortController` that is
+ *   combined with any caller-supplied `signal`, so cancellation works in
+ *   both directions. A timeout surfaces as {@link FetchTimeoutError}; a
+ *   caller-initiated abort surfaces as the caller's own `AbortError` and
+ *   is **never** retried or counted as an upstream failure.
+ * - **Retry-with-backoff** only retries idempotent methods
+ *   (`GET`/`HEAD`/`OPTIONS`/`PUT`/`DELETE`) and a conservative set of
+ *   transient statuses (`408`, `429`, `500`, `502`, `503`, `504`) plus
+ *   network errors and timeouts. Backoff is exponential with full
+ *   jitter and honours a `Retry-After` header when present. A
+ *   {@link SsrfBlockedError} is treated as a hard refusal — never
+ *   retried, never trips the breaker.
+ * - **Circuit breaker** is a classic three-state machine
+ *   (`closed → open → half-open`). Consecutive failures past the
+ *   threshold open the circuit; while open every call fails fast with
+ *   {@link CircuitOpenError} until `resetTimeoutMs` elapses, after which
+ *   a limited number of trial requests probe the upstream. The breaker
+ *   is shared across every call made through the returned function, so a
+ *   single hot upstream is protected process-wide.
+ *
+ * @module
+ * @since 0.37.0
+ */
+/**
+ * The three states of a {@link CircuitBreaker}.
+ *
+ * - `closed` — normal operation; calls pass through and failures are
+ *   counted.
+ * - `open` — the upstream is considered down; calls fail fast with
+ *   {@link CircuitOpenError} without touching the network.
+ * - `half-open` — a recovery probe window; a limited number of trial
+ *   calls are allowed through to test whether the upstream has healed.
+ *
+ * @since 0.37.0
+ */
+export type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Thrown by {@link resilientFetch} (and {@link CircuitBreaker.execute})
+ * when the circuit is open and the call is refused without hitting the
+ * network. Distinct from a network failure so callers can render a
+ * dedicated "service temporarily unavailable" path.
+ *
+ * @since 0.37.0
+ */
+export declare class CircuitOpenError extends Error {
+    /** Milliseconds until the breaker will next allow a trial request. */
+    readonly retryAfterMs: number;
+    constructor(retryAfterMs: number);
+}
+/**
+ * Thrown by {@link resilientFetch} when a single attempt exceeds the
+ * configured `timeoutMs`. A caller-initiated abort (via a `signal`
+ * passed in the request init) surfaces as the caller's own `AbortError`
+ * instead and is never retried.
+ *
+ * @since 0.37.0
+ */
+export declare class FetchTimeoutError extends Error {
+    /** The timeout that was exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Tuning for the {@link CircuitBreaker}. All fields are optional and
+ * default to a conservative posture suited to a single upstream.
+ *
+ * @since 0.37.0
+ */
+export interface CircuitBreakerOptions {
+    /**
+     * Number of consecutive failures that trips the breaker from `closed`
+     * to `open`. Default `5`.
+     */
+    failureThreshold?: number;
+    /**
+     * Time the breaker stays `open` before allowing trial requests
+     * (transition to `half-open`), in milliseconds. Default `30_000`.
+     */
+    resetTimeoutMs?: number;
+    /**
+     * Number of concurrent trial requests permitted while `half-open`.
+     * Extra calls during the probe window fail fast with
+     * {@link CircuitOpenError}. Default `1`.
+     */
+    halfOpenMaxAttempts?: number;
+    /**
+     * Number of consecutive trial successes required to close the breaker
+     * again. Default `1`.
+     */
+    successThreshold?: number;
+    /**
+     * Observe state transitions (e.g. to emit a metric or log). Called
+     * synchronously with the previous and next state.
+     */
+    onStateChange?: (next: CircuitState, previous: CircuitState) => void;
+    /**
+     * Monotonic clock, primarily for deterministic tests. Defaults to
+     * `Date.now`.
+     */
+    now?: () => number;
+}
+/**
+ * A standalone three-state circuit breaker. {@link resilientFetch}
+ * builds on this, but it is exported for callers who want to protect a
+ * non-`fetch` dependency (a database driver, a gRPC client, …) with the
+ * same semantics.
+ *
+ * @example
+ * ```ts
+ * const breaker = new CircuitBreaker({ failureThreshold: 3 });
+ * const rows = await breaker.execute(() => db.query("SELECT 1"));
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare class CircuitBreaker {
+    #private;
+    constructor(options?: CircuitBreakerOptions);
+    /** The breaker's current state, after applying any pending timeout. */
+    get state(): CircuitState;
+    /** Milliseconds until the breaker will next admit a trial request. */
+    get retryAfterMs(): number;
+    /**
+     * Run `fn` under breaker supervision. Throws {@link CircuitOpenError}
+     * immediately when the circuit is open. A thrown error (other than
+     * `CircuitOpenError`) counts as a failure; a returned value counts as
+     * a success. Use {@link recordOutcome} from {@link resilientFetch}
+     * when an HTTP *response* (not a thrown error) should count as a
+     * failure.
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Record an externally-determined outcome. Lets a caller treat a
+     * non-throwing result (e.g. an HTTP 503 response) as a failure while
+     * still flowing the value back. Returns nothing; pair with an explicit
+     * {@link admit}/{@link release} when you need full manual control.
+     */
+    recordOutcome(success: boolean): void;
+    /**
+     * Reserve a breaker slot for a manually-supervised call. Throws
+     * {@link CircuitOpenError} if the circuit will not admit the call.
+     * Must be paired with exactly one {@link recordOutcome} or
+     * {@link release}.
+     */
+    admit(): void;
+    /**
+     * Release a slot reserved by {@link admit} without recording a success
+     * or failure. Use for outcomes that are not an upstream health signal
+     * (a caller-initiated abort, an SSRF refusal). Counts and state are
+     * left untouched aside from freeing a half-open probe slot.
+     */
+    release(): void;
+}
+/**
+ * Context passed to the {@link ResilientFetchOptions.onRetry} hook and
+ * the {@link ResilientFetchOptions.isRetryable} predicate.
+ *
+ * @since 0.37.0
+ */
+export interface RetryContext {
+    /** 1-based attempt number that just failed. */
+    readonly attempt: number;
+    /** The request that was attempted. */
+    readonly request: Request;
+    /** The response received, when the failure was a retryable status. */
+    readonly response?: Response;
+    /** The error thrown, when the failure was a network error or timeout. */
+    readonly error?: unknown;
+}
+/**
+ * Options for {@link resilientFetch}. Every field is optional; the
+ * defaults bias toward safe, low-amplification behaviour.
+ *
+ * @since 0.37.0
+ */
+export interface ResilientFetchOptions {
+    /**
+     * Underlying fetch implementation. Defaults to `globalThis.fetch`.
+     * Pass a {@link fetchGuard} result to keep the SSRF floor underneath
+     * the resilience layer.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Per-attempt timeout in milliseconds. Each retry gets a fresh
+     * timeout. Set `0` to disable. Default `10_000`.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of retries **after** the first attempt. `0` disables
+     * retrying. Default `2` (so up to 3 total attempts).
+     */
+    retries?: number;
+    /**
+     * Base backoff delay in milliseconds for the first retry. Default
+     * `100`.
+     */
+    retryDelayMs?: number;
+    /** Upper bound on any single backoff delay. Default `2_000`. */
+    maxRetryDelayMs?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    backoffFactor?: number;
+    /**
+     * Apply full jitter (`delay * random()`) to backoff to avoid
+     * thundering-herd retries. Default `true`.
+     */
+    jitter?: boolean;
+    /**
+     * HTTP methods that are safe to retry. Default the idempotent set:
+     * `GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`. Non-idempotent methods
+     * (`POST`, `PATCH`) are never retried unless added here.
+     */
+    retryableMethods?: readonly string[];
+    /**
+     * Response statuses that should be retried. Default
+     * `[408, 429, 500, 502, 503, 504]`.
+     */
+    retryableStatuses?: readonly number[];
+    /**
+     * Honour a `Retry-After` header on a retryable response (seconds or
+     * HTTP-date), capped by `maxRetryDelayMs`. Default `true`.
+     */
+    respectRetryAfter?: boolean;
+    /**
+     * Override the retry decision entirely. Return `true` to retry the
+     * given outcome. When provided, replaces the method/status defaults.
+     */
+    isRetryable?: (context: RetryContext) => boolean;
+    /**
+     * Observe each retry, e.g. to emit a metric. Called with the failed
+     * attempt's context and the delay before the next attempt.
+     */
+    onRetry?: (context: RetryContext, delayMs: number) => void;
+    /**
+     * Circuit breaker configuration, an existing {@link CircuitBreaker}
+     * instance to share across clients, or `false` to disable. Default
+     * enabled with {@link CircuitBreakerOptions} defaults.
+     */
+    circuitBreaker?: CircuitBreakerOptions | CircuitBreaker | false;
+    /**
+     * Response statuses that count as an upstream failure for the circuit
+     * breaker. Default `[500, 502, 503, 504]`. A failing status still
+     * flows back to the caller after retries are exhausted.
+     */
+    circuitBreakerFailureStatuses?: readonly number[];
+    /**
+     * Sleep implementation, primarily for deterministic tests. Receives
+     * the delay and an `AbortSignal` that fires if the caller cancels.
+     * Defaults to a `setTimeout`-based abortable sleep.
+     */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Wrap a `fetch` with per-call timeout, retry-with-backoff, and a shared
+ * circuit breaker. The returned function has the same call signature as
+ * the global `fetch`.
+ *
+ * Layer it over {@link fetchGuard} to keep SSRF protection underneath:
+ *
+ * ```ts
+ * const safeFetch = resilientFetch({ fetch: fetchGuard(), timeoutMs: 2_000 });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare function resilientFetch(options?: ResilientFetchOptions): typeof fetch;