@squasher-ai/nextjs 0.3.0 → 0.4.0

package/dist/_vendor/sdk-runtime/errors/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Typed error hierarchy for Squasher SDKs. Status-specific subclasses retain
+ * `SquasherApiError` as their common parent.
+ */
+import { type HeaderSource } from "./headers.js";
+export type { HeaderLike } from "./headers.js";
+export interface ParsedErrorBody {
+    /** Squasher API convention: `{ error: "human readable message" }`. */
+    error?: string;
+    /** Optional structured message supplied by an API response. */
+    message?: string;
+    /** Optional structured error code supplied by an API response. */
+    code?: string;
+}
+/**
+ * Lookup that works for both the WHATWG `Headers` instance and a plain
+ * `Record<string, string>`. The api-client used to be Headers-only; SDK code
+ * sometimes hands us a plain object, so accept both.
+ */
+/** Root of every Squasher SDK error. Lets callers `catch (e: SquasherError)`. */
+export declare class SquasherError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for every error returned by the Squasher API. Status-specific
+ * subclasses extend this; checks against `SquasherApiError` continue to match
+ * any of them.
+ */
+export declare class SquasherApiError extends SquasherError {
+    readonly status: number;
+    readonly body: ParsedErrorBody | null;
+    readonly requestId: string | undefined;
+    constructor(status: number, body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+    /**
+     * Map an HTTP status to the most specific subclass. Falls back to the
+     * generic `SquasherApiError` for unrecognised statuses (e.g. 418).
+     * Network/abort failures throw `SquasherConnectionError` /
+     * `SquasherUserAbortError` instead — those never go through here.
+     */
+    static generate(status: number, body: ParsedErrorBody | null, fallbackMessage: string, headers?: HeaderSource): SquasherApiError;
+}
+export declare class BadRequestError extends SquasherApiError {
+    readonly status: 400;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class AuthenticationError extends SquasherApiError {
+    readonly status: 401;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class PermissionDeniedError extends SquasherApiError {
+    readonly status: 403;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class NotFoundError extends SquasherApiError {
+    readonly status: 404;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class ConflictError extends SquasherApiError {
+    readonly status: 409;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class UnprocessableEntityError extends SquasherApiError {
+    readonly status: 422;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class RateLimitError extends SquasherApiError {
+    readonly status: 429;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+/** 5xx — keeps the actual status because the spread is too wide for a const. */
+export declare class InternalServerError extends SquasherApiError {
+    constructor(status: number, body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+/** Network-level failure (DNS, connection refused, TLS). */
+export declare class SquasherConnectionError extends SquasherError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/** Specifically a connect-or-read timeout. Subclasses ConnectionError on purpose. */
+export declare class SquasherConnectionTimeoutError extends SquasherConnectionError {
+    constructor(message?: string);
+}
+/** AbortController.abort() raised; surfaced separately so retry loops skip it. */
+export declare class SquasherUserAbortError extends SquasherError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a Standard Webhooks payload fails signature verification —
+ * unknown or rotated secret, tampered body, replayed/expired timestamp,
+ * or malformed signature header. Extends SquasherError directly (not
+ * SquasherApiError) because webhook failures are not HTTP responses.
+ */
+export declare class InvalidWebhookSignatureError extends SquasherError {
+    constructor(message: string);
+}

package/dist/_vendor/sdk-runtime/errors/index.js

@@ -0,0 +1,157 @@
+/**
+ * Typed error hierarchy for Squasher SDKs. Status-specific subclasses retain
+ * `SquasherApiError` as their common parent.
+ */
+import { readHeader } from "./headers.js";
+/**
+ * Lookup that works for both the WHATWG `Headers` instance and a plain
+ * `Record<string, string>`. The api-client used to be Headers-only; SDK code
+ * sometimes hands us a plain object, so accept both.
+ */
+/** Root of every Squasher SDK error. Lets callers `catch (e: SquasherError)`. */
+export class SquasherError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SquasherError";
+    }
+}
+/**
+ * Base class for every error returned by the Squasher API. Status-specific
+ * subclasses extend this; checks against `SquasherApiError` continue to match
+ * any of them.
+ */
+export class SquasherApiError extends SquasherError {
+    status;
+    body;
+    requestId;
+    constructor(status, body, message, headers) {
+        super(buildMessage(body, message));
+        this.name = "SquasherApiError";
+        this.status = status;
+        this.body = body;
+        this.requestId = readHeader(headers, "x-request-id");
+    }
+    /**
+     * Map an HTTP status to the most specific subclass. Falls back to the
+     * generic `SquasherApiError` for unrecognised statuses (e.g. 418).
+     * Network/abort failures throw `SquasherConnectionError` /
+     * `SquasherUserAbortError` instead — those never go through here.
+     */
+    static generate(status, body, fallbackMessage, headers) {
+        if (status === 400)
+            return new BadRequestError(body, fallbackMessage, headers);
+        if (status === 401)
+            return new AuthenticationError(body, fallbackMessage, headers);
+        if (status === 403)
+            return new PermissionDeniedError(body, fallbackMessage, headers);
+        if (status === 404)
+            return new NotFoundError(body, fallbackMessage, headers);
+        if (status === 409)
+            return new ConflictError(body, fallbackMessage, headers);
+        if (status === 422)
+            return new UnprocessableEntityError(body, fallbackMessage, headers);
+        if (status === 429)
+            return new RateLimitError(body, fallbackMessage, headers);
+        if (status >= 500)
+            return new InternalServerError(status, body, fallbackMessage, headers);
+        return new SquasherApiError(status, body, fallbackMessage, headers);
+    }
+}
+function buildMessage(body, fallback) {
+    if (body?.error)
+        return body.error;
+    if (body?.message)
+        return body.message;
+    return fallback;
+}
+export class BadRequestError extends SquasherApiError {
+    status = 400;
+    constructor(body, message, headers) {
+        super(400, body, message, headers);
+        this.name = "BadRequestError";
+    }
+}
+export class AuthenticationError extends SquasherApiError {
+    status = 401;
+    constructor(body, message, headers) {
+        super(401, body, message, headers);
+        this.name = "AuthenticationError";
+    }
+}
+export class PermissionDeniedError extends SquasherApiError {
+    status = 403;
+    constructor(body, message, headers) {
+        super(403, body, message, headers);
+        this.name = "PermissionDeniedError";
+    }
+}
+export class NotFoundError extends SquasherApiError {
+    status = 404;
+    constructor(body, message, headers) {
+        super(404, body, message, headers);
+        this.name = "NotFoundError";
+    }
+}
+export class ConflictError extends SquasherApiError {
+    status = 409;
+    constructor(body, message, headers) {
+        super(409, body, message, headers);
+        this.name = "ConflictError";
+    }
+}
+export class UnprocessableEntityError extends SquasherApiError {
+    status = 422;
+    constructor(body, message, headers) {
+        super(422, body, message, headers);
+        this.name = "UnprocessableEntityError";
+    }
+}
+export class RateLimitError extends SquasherApiError {
+    status = 429;
+    constructor(body, message, headers) {
+        super(429, body, message, headers);
+        this.name = "RateLimitError";
+    }
+}
+/** 5xx — keeps the actual status because the spread is too wide for a const. */
+export class InternalServerError extends SquasherApiError {
+    constructor(status, body, message, headers) {
+        super(status, body, message, headers);
+        this.name = "InternalServerError";
+    }
+}
+/** Network-level failure (DNS, connection refused, TLS). */
+export class SquasherConnectionError extends SquasherError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "SquasherConnectionError";
+    }
+}
+/** Specifically a connect-or-read timeout. Subclasses ConnectionError on purpose. */
+export class SquasherConnectionTimeoutError extends SquasherConnectionError {
+    constructor(message = "Request timed out") {
+        super(message);
+        this.name = "SquasherConnectionTimeoutError";
+    }
+}
+/** AbortController.abort() raised; surfaced separately so retry loops skip it. */
+export class SquasherUserAbortError extends SquasherError {
+    constructor(message = "Request was aborted") {
+        super(message);
+        this.name = "SquasherUserAbortError";
+    }
+}
+/**
+ * Thrown when a Standard Webhooks payload fails signature verification —
+ * unknown or rotated secret, tampered body, replayed/expired timestamp,
+ * or malformed signature header. Extends SquasherError directly (not
+ * SquasherApiError) because webhook failures are not HTTP responses.
+ */
+export class InvalidWebhookSignatureError extends SquasherError {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidWebhookSignatureError";
+    }
+}

package/dist/_vendor/sdk-runtime/headers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Default telemetry headers attached to every SDK-originated HTTP request.
+ *
+ * Every request identifies the language, package, package version, OS,
+ * architecture, and runtime. Retry count and timeout are added per request.
+ */
+export interface DefaultHeadersOptions {
+    /** npm package name (e.g. "@squasher-ai/client", "@squasher-ai/node"). */
+    packageName: string;
+    /** Semver of the package shipping the request. */
+    packageVersion: string;
+}
+export interface RequestHeaderOptions {
+    /** Retry attempt count. Set to 0 on first attempt; incremented per retry. */
+    retryCount?: number;
+    /** Per-request timeout in milliseconds, surfaced as seconds in the header. */
+    timeoutMs?: number;
+}
+export interface TelemetryHeaders {
+    [name: string]: string;
+}
+/**
+ * Build the constant-per-process header set: lang, package, OS, arch, runtime.
+ * Cache the return value at the SDK-construction site rather than calling per
+ * request — platform detection is cached but header construction still
+ * allocates a fresh object.
+ */
+export declare function getDefaultHeaders(opts: DefaultHeadersOptions): TelemetryHeaders;
+/**
+ * Build the per-request header overlay: retry count and timeout. Returned as
+ * a separate object so callers can spread it on top of `getDefaultHeaders()`.
+ * Omits any field whose source is undefined so we don't ship empty headers.
+ */
+export declare function getRequestHeaders(opts: RequestHeaderOptions): TelemetryHeaders;
+/** Build the SDK User-Agent string used by standard HTTP access logs. */
+export declare function getUserAgent(opts: DefaultHeadersOptions): string;
+/** Header names used by SDK tests and request integrations. */
+export declare const HEADER_NAMES: {
+    readonly lang: "X-Squasher-Lang";
+    readonly package: "X-Squasher-Package";
+    readonly packageVersion: "X-Squasher-Package-Version";
+    readonly os: "X-Squasher-OS";
+    readonly arch: "X-Squasher-Arch";
+    readonly runtime: "X-Squasher-Runtime";
+    readonly runtimeVersion: "X-Squasher-Runtime-Version";
+    readonly retryCount: "X-Squasher-Retry-Count";
+    readonly timeout: "X-Squasher-Timeout";
+};

package/dist/_vendor/sdk-runtime/headers.js

@@ -0,0 +1,67 @@
+/**
+ * Default telemetry headers attached to every SDK-originated HTTP request.
+ *
+ * Every request identifies the language, package, package version, OS,
+ * architecture, and runtime. Retry count and timeout are added per request.
+ */
+import { getPlatform } from "./platform.js";
+const HEADER_LANG = "X-Squasher-Lang";
+const HEADER_PACKAGE = "X-Squasher-Package";
+const HEADER_PACKAGE_VERSION = "X-Squasher-Package-Version";
+const HEADER_OS = "X-Squasher-OS";
+const HEADER_ARCH = "X-Squasher-Arch";
+const HEADER_RUNTIME = "X-Squasher-Runtime";
+const HEADER_RUNTIME_VERSION = "X-Squasher-Runtime-Version";
+const HEADER_RETRY_COUNT = "X-Squasher-Retry-Count";
+const HEADER_TIMEOUT = "X-Squasher-Timeout";
+/**
+ * Build the constant-per-process header set: lang, package, OS, arch, runtime.
+ * Cache the return value at the SDK-construction site rather than calling per
+ * request — platform detection is cached but header construction still
+ * allocates a fresh object.
+ */
+export function getDefaultHeaders(opts) {
+    const platform = getPlatform();
+    return {
+        [HEADER_LANG]: platform.lang,
+        [HEADER_PACKAGE]: opts.packageName,
+        [HEADER_PACKAGE_VERSION]: opts.packageVersion,
+        [HEADER_OS]: platform.os,
+        [HEADER_ARCH]: platform.arch,
+        [HEADER_RUNTIME]: platform.runtime,
+        [HEADER_RUNTIME_VERSION]: platform.runtimeVersion,
+    };
+}
+/**
+ * Build the per-request header overlay: retry count and timeout. Returned as
+ * a separate object so callers can spread it on top of `getDefaultHeaders()`.
+ * Omits any field whose source is undefined so we don't ship empty headers.
+ */
+export function getRequestHeaders(opts) {
+    const out = {};
+    if (opts.retryCount !== undefined && opts.retryCount > 0) {
+        out[HEADER_RETRY_COUNT] = String(opts.retryCount);
+    }
+    if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+        // Express the timeout in seconds with millisecond precision.
+        out[HEADER_TIMEOUT] = (opts.timeoutMs / 1000).toString();
+    }
+    return out;
+}
+/** Build the SDK User-Agent string used by standard HTTP access logs. */
+export function getUserAgent(opts) {
+    const { runtime, runtimeVersion, os, arch } = getPlatform();
+    return `${opts.packageName}/${opts.packageVersion} (${runtime}/${runtimeVersion}; ${os} ${arch})`;
+}
+/** Header names used by SDK tests and request integrations. */
+export const HEADER_NAMES = {
+    lang: HEADER_LANG,
+    package: HEADER_PACKAGE,
+    packageVersion: HEADER_PACKAGE_VERSION,
+    os: HEADER_OS,
+    arch: HEADER_ARCH,
+    runtime: HEADER_RUNTIME,
+    runtimeVersion: HEADER_RUNTIME_VERSION,
+    retryCount: HEADER_RETRY_COUNT,
+    timeout: HEADER_TIMEOUT,
+};

package/dist/_vendor/sdk-runtime/platform.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Runtime, OS, and architecture detection used by SDK request headers.
+ *
+ * Probes are wrapped in try/catch because locked-down runtimes can throw when
+ * global properties are read. Unknown values remain explicit.
+ */
+export type PlatformRuntime = "node" | "deno" | "bun" | "edge" | "workerd" | `browser:${string}` | "unknown";
+export type PlatformOs = "MacOS" | "Linux" | "Windows" | "FreeBSD" | "OpenBSD" | "iOS" | "Android" | "Unknown";
+export type PlatformArch = "x32" | "x64" | "arm" | "arm64" | "Unknown";
+export interface PlatformProperties {
+    /** Language family. Always "js" for any TypeScript/JavaScript SDK. */
+    lang: "js";
+    /** Concrete runtime identifier. */
+    runtime: PlatformRuntime;
+    /** Best-effort runtime version string ("20.10.0", "1.0.30", etc.) or "unknown". */
+    runtimeVersion: string;
+    /** Operating system. */
+    os: PlatformOs;
+    /** CPU architecture. */
+    arch: PlatformArch;
+}
+/**
+ * Detect the runtime, OS, arch, and version of the host JS environment.
+ *
+ * Detection order: Deno → Bun → Cloudflare workerd → generic Edge → Node →
+ * Browser → unknown. Earlier checks take precedence because some runtimes
+ * (Bun, Deno) also expose a `process` global for compatibility — we want the
+ * native identifier to win.
+ */
+export declare function detectPlatform(): PlatformProperties;
+export declare function getPlatform(): PlatformProperties;
+/** Reset cached detection for deterministic tests. */
+export declare function resetPlatformCacheForTesting(): void;

package/dist/_vendor/sdk-runtime/platform.js

@@ -0,0 +1,173 @@
+/**
+ * Runtime, OS, and architecture detection used by SDK request headers.
+ *
+ * Probes are wrapped in try/catch because locked-down runtimes can throw when
+ * global properties are read. Unknown values remain explicit.
+ */
+import { readGlobalProperty, readRuntimeProperty, readRuntimeString, } from "./runtime/environment.js";
+function nestedString(value, ...path) {
+    let current = value;
+    for (const name of path)
+        current = readRuntimeProperty(current, name);
+    return readRuntimeString(current);
+}
+function normalizeOs(platform) {
+    if (!platform)
+        return "Unknown";
+    if (platform === "darwin")
+        return "MacOS";
+    if (platform === "linux")
+        return "Linux";
+    if (platform === "win32")
+        return "Windows";
+    if (platform === "freebsd")
+        return "FreeBSD";
+    if (platform === "openbsd")
+        return "OpenBSD";
+    if (platform === "android")
+        return "Android";
+    return "Unknown";
+}
+function normalizeArch(arch) {
+    if (!arch)
+        return "Unknown";
+    if (arch === "x32" || arch === "ia32")
+        return "x32";
+    if (arch === "x64" || arch === "amd64")
+        return "x64";
+    if (arch === "arm")
+        return "arm";
+    if (arch === "arm64" || arch === "aarch64")
+        return "arm64";
+    return "Unknown";
+}
+const BROWSER_UA_PATTERNS = [
+    { key: "edge", re: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)?)/ },
+    { key: "ie", re: /MSIE (\d+(?:\.\d+)?)/ },
+    { key: "ie", re: /Trident\/.*; rv:(\d+(?:\.\d+)?)/ },
+    { key: "chrome", re: /Chrome\/(\d+(?:\.\d+)?)/ },
+    { key: "firefox", re: /Firefox\/(\d+(?:\.\d+)?)/ },
+    { key: "safari", re: /Version\/(\d+(?:\.\d+)?).*Safari/ },
+];
+function detectBrowserFromUserAgent(ua) {
+    let os = "Unknown";
+    if (/Mac OS X/.test(ua))
+        os = "MacOS";
+    else if (/Windows/.test(ua))
+        os = "Windows";
+    else if (/Linux/.test(ua))
+        os = "Linux";
+    else if (/Android/.test(ua))
+        os = "Android";
+    else if (/iP(hone|ad|od)/.test(ua))
+        os = "iOS";
+    for (const { key, re } of BROWSER_UA_PATTERNS) {
+        const match = re.exec(ua);
+        if (match) {
+            return { runtime: `browser:${key}`, version: match[1] ?? "unknown", os };
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the runtime, OS, arch, and version of the host JS environment.
+ *
+ * Detection order: Deno → Bun → Cloudflare workerd → generic Edge → Node →
+ * Browser → unknown. Earlier checks take precedence because some runtimes
+ * (Bun, Deno) also expose a `process` global for compatibility — we want the
+ * native identifier to win.
+ */
+export function detectPlatform() {
+    // Deno
+    const deno = readGlobalProperty("Deno");
+    if (deno !== undefined && deno !== null) {
+        return {
+            lang: "js",
+            runtime: "deno",
+            runtimeVersion: nestedString(deno, "version", "deno") ?? "unknown",
+            os: normalizeOs(nestedString(deno, "build", "os")),
+            arch: normalizeArch(nestedString(deno, "build", "arch")),
+        };
+    }
+    // Bun
+    const bun = readGlobalProperty("Bun");
+    if (bun !== undefined && bun !== null) {
+        const process = readGlobalProperty("process");
+        return {
+            lang: "js",
+            runtime: "bun",
+            runtimeVersion: nestedString(bun, "version") ?? "unknown",
+            os: normalizeOs(nestedString(process, "platform")),
+            arch: normalizeArch(nestedString(process, "arch")),
+        };
+    }
+    // Cloudflare workerd (preferred over generic edge — gives us version when present)
+    const navigatorUserAgent = nestedString(readGlobalProperty("navigator"), "userAgent");
+    if (navigatorUserAgent && /Cloudflare-Workers/.test(navigatorUserAgent)) {
+        return {
+            lang: "js",
+            runtime: "workerd",
+            runtimeVersion: "unknown",
+            os: "Unknown",
+            arch: "Unknown",
+        };
+    }
+    // Generic edge (Vercel Edge, Next.js edge runtime, etc.)
+    const edgeRuntime = readGlobalProperty("EdgeRuntime");
+    if (edgeRuntime !== undefined) {
+        return {
+            lang: "js",
+            runtime: "edge",
+            runtimeVersion: readRuntimeString(edgeRuntime) ?? "unknown",
+            os: "Unknown",
+            arch: "Unknown",
+        };
+    }
+    // Node.js — duck-typed via release.name to avoid false positives on
+    // bundlers that polyfill `process` for browser code.
+    const process = readGlobalProperty("process");
+    if (nestedString(process, "release", "name") === "node") {
+        return {
+            lang: "js",
+            runtime: "node",
+            runtimeVersion: nestedString(process, "versions", "node") ?? nestedString(process, "version") ?? "unknown",
+            os: normalizeOs(nestedString(process, "platform")),
+            arch: normalizeArch(nestedString(process, "arch")),
+        };
+    }
+    // Browser
+    if (navigatorUserAgent) {
+        const match = detectBrowserFromUserAgent(navigatorUserAgent);
+        if (match) {
+            return {
+                lang: "js",
+                runtime: match.runtime,
+                runtimeVersion: match.version,
+                os: match.os,
+                arch: "Unknown",
+            };
+        }
+    }
+    return {
+        lang: "js",
+        runtime: "unknown",
+        runtimeVersion: "unknown",
+        os: "Unknown",
+        arch: "Unknown",
+    };
+}
+/**
+ * Cached platform properties — detection is stable across a process lifetime,
+ * so probing once and reusing the result keeps the per-request cost at zero.
+ * Tests that need a fresh probe can call `resetPlatformCacheForTesting()`.
+ */
+let cached;
+export function getPlatform() {
+    if (!cached)
+        cached = detectPlatform();
+    return cached;
+}
+/** Reset cached detection for deterministic tests. */
+export function resetPlatformCacheForTesting() {
+    cached = undefined;
+}

package/dist/_vendor/sdk-runtime/retry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Retry primitives shared across Squasher SDKs.
+ *
+ * Server retry hints take precedence over exponential backoff with downward
+ * jitter. Aborts are never retried; network failures, timeouts, 408, 429, and
+ * 5xx responses are retryable by default.
+ */
+import { type HeaderSource } from "./errors/headers.js";
+export interface RetryDecisionInput {
+    /** HTTP response status, if a response was received. */
+    status?: number;
+    /** Response headers — supports either a fetch `Headers` or plain object. */
+    headers?: HeaderSource;
+    /** Error thrown by `fetch` itself (network failure / abort). */
+    thrown?: Error;
+}
+export type HeadersLike = Headers;
+/**
+ * Decide whether a response (or thrown error) should trigger a retry.
+ *
+ * Aborts always opt out — `AbortController.abort()` is user intent, not a
+ * transient failure. Connection errors always opt in. Status-code logic
+ * mirrors Stainless: 408/409/429 plus any 5xx, with `X-Should-Retry`
+ * override.
+ */
+export declare function shouldRetry(input: RetryDecisionInput): boolean;
+export interface BackoffOptions {
+    /** Zero-indexed retry attempt number. The first retry uses attempt = 0. */
+    attempt: number;
+    /** Response headers, used to honor Retry-After / Retry-After-Ms. */
+    headers?: HeaderSource;
+    /** Random source — injected for deterministic tests. Defaults to Math.random. */
+    random?: () => number;
+    /** Max sleep in ms. Defaults to 8000 to match Stainless. */
+    maxSleepMs?: number;
+    /** Reference time used to interpret HTTP-date `Retry-After` values. Tests inject. */
+    now?: () => number;
+}
+/**
+ * Compute the delay in milliseconds before the next attempt. Server-supplied
+ * hints win when present, otherwise falls back to exponential backoff with
+ * downward jitter.
+ *
+ * Returned value is always non-negative. Capped at `maxSleepMs` (default 8s)
+ * even when the server requests a longer retry — long sleeps almost always
+ * indicate the caller should reach for queueing instead of in-process retries.
+ */
+export declare function nextBackoffMs(opts: BackoffOptions): number;
+/** Promise-friendly setTimeout. Resolves after `ms` milliseconds. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;