@gusnips/react 0.4.0 → 0.4.1

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-client.js

@@ -1,6 +1,62 @@
 import { isApiError } from "@gusnips/http";
-import { ApiError } from "./api-error.js";
+import { ApiError, parseRetryAfter } from "./api-error.js";
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * One signal that fires on the caller's abort or on the deadline, whichever comes first.
+ *
+ * `AbortSignal.timeout` plus `AbortSignal.any` is the obvious way to write this, and it is
+ * not portable: React Native replaces the global `AbortSignal` with abort-controller@3, which
+ * has neither static — so the phone got `AbortSignal.timeout is not a function` on its very
+ * first request. This is the same two rules with an `AbortController`, which every runtime
+ * this package targets does have, and it is the ONLY path rather than a fallback: one branch
+ * cannot drift from the other.
+ *
+ * Three details that are the whole reason this is not three lines:
+ *
+ * - **The already-aborted race.** A caller whose signal fired before we attached would never
+ *   fire the listener, so the request would go out and run to full term. Checked first.
+ * - **A timeout must not look like a cancellation.** `isAbortError` exists so a request nobody
+ *   is waiting for stays silent; a request that ran out of time is a real failure somebody
+ *   should see. A bare `controller.abort()` raises an `AbortError` and would be swallowed, so
+ *   the deadline aborts with a plain `Error` — not a `DOMException`, which `isAbortError` is
+ *   the one thing that checks for.
+ * - **The timer is cleared.** Otherwise every completed request leaves a pending timeout for
+ *   the rest of its budget, which on a phone is a wake-up nobody asked for.
+ */
+function withDeadline(ms, caller) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        // Named, not typed: callers identify a deadline by `name === "TimeoutError"`, the same
+        // way `AbortSignal.timeout` reports it. A `DOMException` would be the faithful copy and is
+        // not constructible everywhere this runs.
+        const expired = new Error(`Request timed out after ${String(ms)}ms`);
+        expired.name = "TimeoutError";
+        controller.abort(expired);
+    }, ms);
+    let detach = () => { };
+    if (caller) {
+        if (caller.aborted) {
+            clearTimeout(timer);
+            controller.abort(caller.reason);
+        }
+        else {
+            const onAbort = () => {
+                controller.abort(caller.reason);
+            };
+            caller.addEventListener("abort", onAbort, { once: true });
+            detach = () => {
+                caller.removeEventListener("abort", onAbort);
+            };
+        }
+    }
+    return {
+        signal: controller.signal,
+        clear: () => {
+            clearTimeout(timer);
+            detach();
+        },
+    };
+}
 export function createApiClient({ baseUrl, session, headers: extraHeaders, onSessionDead, onError, timeoutMs = 30_000, maxRefreshAttempts = 2, refreshRetryDelayMs = 500, signOutTimeoutMs = 3_000, requestIdHeader = "x-request-id", }) {
     /**
      * Single-flight refresh.
@@ -51,15 +107,17 @@ export function createApiClient({ baseUrl, session, headers: extraHeaders, onSes
         const budget = perCall === undefined ? timeoutMs : perCall;
         if (budget === null)
             return fetch(`${baseUrl}${path}`, { ...init, signal, headers: buildHeaders(token, headers) });
-        // `AbortSignal.any` rather than a listener: it also catches the already-aborted race, where
-        // a caller's signal fired before we ever attached. It keeps the caller's abort and our
-        // timeout distinguishable at the source, which is what lets `isAbortError` stay honest.
-        const timeout = AbortSignal.timeout(budget);
-        return fetch(`${baseUrl}${path}`, {
-            ...init,
-            signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-            headers: buildHeaders(token, headers),
-        });
+        const deadline = withDeadline(budget, signal);
+        try {
+            return await fetch(`${baseUrl}${path}`, {
+                ...init,
+                signal: deadline.signal,
+                headers: buildHeaders(token, headers),
+            });
+        }
+        finally {
+            deadline.clear();
+        }
     }
     async function request(path, options = {}) {
         let res = await send(path, await session.getToken(), options);
@@ -86,6 +144,7 @@ export function createApiClient({ baseUrl, session, headers: extraHeaders, onSes
             const body = await res.json().catch(() => null);
             const error = new ApiError(res.status, isApiError(body) ? body.error : null, {
                 requestId: res.headers.get(requestIdHeader) ?? undefined,
+                retryAfterSecs: parseRetryAfter(res.headers.get("retry-after")),
             });
             // A listener that throws must not become the error the caller sees: the API failure is
             // the real news, and swallowing it for a bug in a side effect would send everyone

package/dist/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}

package/dist/api-error.d.ts

@@ -17,6 +17,17 @@ export declare class ApiError extends Error {
     readonly params: Record<string, string | number> | undefined;
     readonly details: unknown;
     readonly requestId: string | undefined;
+    /**
+     * Seconds until this refusal clears, when the answer said so.
+     *
+     * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
+     * written by anyone puts it. The second migration is why this exists: that API sends
+     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
+     * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
+     * both the copy and the retry rule were flying blind on the one refusal that states its own
+     * expiry. Two conventions, same fact; {@link retryAfterSecs} reads either.
+     */
+    readonly retryAfterSecs: number | undefined;
     /**
      * The client raised this itself to stop a caller while it was already handling the
      * situation — today, the 401 thrown after a dead session, where the person is already on
@@ -31,8 +42,25 @@ export declare class ApiError extends Error {
         requestId?: string;
         expected?: boolean;
         message?: string;
+        retryAfterSecs?: number;
     });
 }
+/**
+ * Seconds until a refusal clears, from whichever place the API put them.
+ *
+ * The header first, because it is the standard one and it is what a limiter emits without being
+ * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
+ * caller asking "how long" should not have to know which server it is talking to.
+ */
+export declare function retryAfterSecs(error: ApiError): number | null;
+/**
+ * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
+ *
+ * Both forms are real — RFC 9110 allows either and different servers pick differently — and the
+ * date one is the half that gets skipped, which turns a stated wait into no wait at all. Clamped
+ * at zero: a date already in the past means "now", not a negative delay.
+ */
+export declare function parseRetryAfter(value: string | null | undefined): number | undefined;
 /**
  * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
  * component waiting on it.

package/dist/api-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAEvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;gBAGzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;CAY1E;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD"}
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IAE5C;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;gBAGzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,EAClC,IAAI,GAAE;QACJ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,CAAC;KACpB;CAaT;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAM7D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAepF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpD"}

package/dist/api-error.js

@@ -16,6 +16,17 @@ export class ApiError extends Error {
     params;
     details;
     requestId;
+    /**
+     * Seconds until this refusal clears, when the answer said so.
+     *
+     * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
+     * written by anyone puts it. The second migration is why this exists: that API sends
+     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
+     * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
+     * both the copy and the retry rule were flying blind on the one refusal that states its own
+     * expiry. Two conventions, same fact; {@link retryAfterSecs} reads either.
+     */
+    retryAfterSecs;
     /**
      * The client raised this itself to stop a caller while it was already handling the
      * situation — today, the 401 thrown after a dead session, where the person is already on
@@ -35,9 +46,49 @@ export class ApiError extends Error {
         this.params = body?.params;
         this.details = body?.details;
         this.requestId = opts.requestId;
+        this.retryAfterSecs = opts.retryAfterSecs;
         this.expected = opts.expected ?? false;
     }
 }
+/**
+ * Seconds until a refusal clears, from whichever place the API put them.
+ *
+ * The header first, because it is the standard one and it is what a limiter emits without being
+ * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
+ * caller asking "how long" should not have to know which server it is talking to.
+ */
+export function retryAfterSecs(error) {
+    if (error.retryAfterSecs !== undefined)
+        return error.retryAfterSecs;
+    const details = error.details;
+    if (typeof details !== "object" || details === null)
+        return null;
+    const value = details.retryAfterSecs;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+/**
+ * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
+ *
+ * Both forms are real — RFC 9110 allows either and different servers pick differently — and the
+ * date one is the half that gets skipped, which turns a stated wait into no wait at all. Clamped
+ * at zero: a date already in the past means "now", not a negative delay.
+ */
+export function parseRetryAfter(value) {
+    const raw = value?.trim();
+    if (!raw)
+        return undefined;
+    // A bare integer is the delay-seconds form, malformed included: `Date.parse` accepts some of
+    // them as years, so falling through would read "-5" as a date long past and answer 0 — a
+    // wait invented out of a header that never stated one.
+    if (/^[+-]?\d+$/.test(raw)) {
+        const secs = Number(raw);
+        return Number.isSafeInteger(secs) && secs >= 0 ? secs : undefined;
+    }
+    const at = Date.parse(raw);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.round((at - Date.now()) / 1000));
+}
 /**
  * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
  * component waiting on it.

package/dist/api-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,IAAI,CAAqB;IACzB,UAAU,CAAqB;IAC/B,MAAM,CAA8C;IACpD,OAAO,CAAU;IACjB,SAAS,CAAqB;IAEvC;;;;;;;;OAQG;IACM,QAAQ,CAAU;IAE3B,YACE,MAAc,EACd,IAAkC,EAClC,OAAqE,EAAE;QAEvE,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,mBAAmB,MAAM,GAAG,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACtE,CAAC"}
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../src/api-error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,IAAI,CAAqB;IACzB,UAAU,CAAqB;IAC/B,MAAM,CAA8C;IACpD,OAAO,CAAU;IACjB,SAAS,CAAqB;IACvC;;;;;;;;;OASG;IACM,cAAc,CAAqB;IAE5C;;;;;;;;OAQG;IACM,QAAQ,CAAU;IAE3B,YACE,MAAc,EACd,IAAkC,EAClC,OAKI,EAAE;QAEN,KAAK,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,IAAI,mBAAmB,MAAM,GAAG,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC;QACvB,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,UAAU,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,OAAO,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAC;QAC1C,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,KAAK,CAAC;IACzC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC;IACpE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,KAAK,GAAI,OAAwC,CAAC,cAAc,CAAC;IACvE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC;IAC9D,MAAM,GAAG,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1B,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,6FAA6F;IAC7F,yFAAyF;IACzF,uDAAuD;IACvD,IAAI,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,CAAC;IAED,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,YAAY,YAAY,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AACtE,CAAC"}

package/dist/describe-error.d.ts

@@ -38,8 +38,6 @@ export type Translate<Key extends string = string> = (key: Key, params?: Record<
 type WaitName = "waitSeconds" | "waitMinutes" | "waitHours";
 /** Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them. */
 type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon";
-/** Seconds until a refusal clears, when the envelope carries them. */
-export declare function retryAfterSecs(error: ApiError): number | null;
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *

package/dist/describe-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,IAAI,CACnD,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,wFAAwF;AACxF,KAAK,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D,iGAAiG;AACjG,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AA8BlF,sEAAsE;AACtE,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAK7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,EAChD,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAIR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB,CACpC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM;IAEzB,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC,CAAC;IACtE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,gBAAgB,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC;AAE7D,2BAA2B;AAC3B,wBAAgB,oBAAoB,CAClC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM,EACzB,EACA,CAAC,EACD,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,KAAU,GACX,EAAE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAkD9F"}
+{"version":3,"file":"describe-error.d.ts","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAkB,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,IAAI,CACnD,GAAG,EAAE,GAAG,EACR,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC;AAEZ,wFAAwF;AACxF,KAAK,QAAQ,GAAG,aAAa,GAAG,aAAa,GAAG,WAAW,CAAC;AAE5D,iGAAiG;AACjG,KAAK,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,YAAY,GAAG,WAAW,CAAC;AA8BlF;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,MAAM,EAChD,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,MAAM,CAIR;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB,CACpC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM;IAEzB,CAAC,EAAE,SAAS,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,GAAG,GAAG,YAAY,GAAG,UAAU,EAAE,CAAC,CAAC;IACtE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,gBAAgB,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;OASG;IACH,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;CAC3C;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,cAAc,CAAC;AAE7D,2BAA2B;AAC3B,wBAAgB,oBAAoB,CAClC,MAAM,SAAS,MAAM,EACrB,YAAY,SAAS,MAAM,EAC3B,UAAU,SAAS,MAAM,EACzB,EACA,CAAC,EACD,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,KAAU,GACX,EAAE,qBAAqB,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAkD9F"}

package/dist/describe-error.js

@@ -1,12 +1,4 @@
-import { ApiError } from "./api-error.js";
-/** Seconds until a refusal clears, when the envelope carries them. */
-export function retryAfterSecs(error) {
-    const details = error.details;
-    if (typeof details !== "object" || details === null)
-        return null;
-    const value = details.retryAfterSecs;
-    return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
+import { ApiError, retryAfterSecs } from "./api-error.js";
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *

package/dist/describe-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AA6E1C,sEAAsE;AACtE,MAAM,UAAU,cAAc,CAAC,KAAe;IAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC9B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,KAAK,GAAI,OAAwC,CAAC,cAAc,CAAC;IACvE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,CAAoC,EACpC,IAAY,EACZ,MAAc;IAEd,IAAI,IAAI,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC,GAAG,MAAM,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,IAAI,IAAI,GAAG,EAAE,GAAG,EAAE;QAAE,OAAO,CAAC,CAAC,GAAG,MAAM,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IACvF,OAAO,CAAC,CAAC,GAAG,MAAM,WAAW,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAuDD,2BAA2B;AAC3B,MAAM,UAAU,oBAAoB,CAIlC,EACA,CAAC,EACD,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,GAAG,EAAE,GAC8C;IACxD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAE7D,sFAAsF;IACtF,2FAA2F;IAC3F,8CAA8C;IAC9C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAsB,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAElE,SAAS,cAAc,CAAC,KAAe;QACrC,MAAM,MAAM,GAAG,CAAC,KAAyB,EAAiB,EAAE;YAC1D,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,gBAAgB,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC5E,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;YAClD,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,gBAAgB,GAAG,IAAI,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC1E,CAAC,CAAC;QACF,wFAAwF;QACxF,4FAA4F;QAC5F,kDAAkD;QAClD,OAAO,CACL,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;YACxB,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,gBAAgB,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAC/E,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,aAAa,CAAC,KAAc;QAC1C,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC,EAAE,CAAC;YACjC,0FAA0F;YAC1F,yCAAyC;YACzC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,UAAU,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,UAAU,aAAa,CAAC,EAAE,CAAC;QACnF,CAAC;QAED,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACvC,MAAM,GAAG,GAAiB;YACxB,KAAK;YACL,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC;YAC3B,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC;YACtE,QAAQ;SACT,CAAC;QAEF,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACrE,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;QAEzB,yFAAyF;QACzF,2FAA2F;QAC3F,4FAA4F;QAC5F,8BAA8B;QAC9B,OAAO;YACL,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,UAAU,YAAY,CAAC,CAAC;YAClE,IAAI,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,UAAU,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;SACpE,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"describe-error.js","sourceRoot":"","sources":["../src/describe-error.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { cn } from "./cn.ts";
-export { ApiError, isAbortError } from "./api-error.ts";
+export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshResult, type RequestOptions, type SessionAdapter, } from "./api-client.ts";
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
-export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
+export { queryDefaults, retryDelayMs, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
-export { createErrorDescriber, humanizeWait, retryAfterSecs, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
+export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.ts";
 export { PRERENDERED_ROUTE_ATTR, SHELL_ROUTE } from "./prerender-contract.ts";
 export { applyBrandVars, i18nInitOptions, type I18nInitOptions } from "./i18n.ts";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA6BA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,EACb,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAElF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -27,12 +27,12 @@
 // Check that claim against `dist/`, never against this file: a type-only re-export looks
 // identical in source.
 export { cn } from "./cn.js";
-export { ApiError, isAbortError } from "./api-error.js";
+export { ApiError, isAbortError, retryAfterSecs } from "./api-error.js";
 export { createApiClient, } from "./api-client.js";
 export { createSseParser, readSseStream } from "./sse.js";
-export { queryDefaults, shouldRetry } from "./query.js";
+export { queryDefaults, retryDelayMs, shouldRetry } from "./query.js";
 export { ErrorBoundary, } from "./error-boundary.js";
-export { createErrorDescriber, humanizeWait, retryAfterSecs, } from "./describe-error.js";
+export { createErrorDescriber, humanizeWait, } from "./describe-error.js";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, reloadOnceForChunkError, } from "./chunk-reload.js";
 // The two constants, but NOT `hydrateOrMount` — that one is at `@gusnips/react/hydrate`, because
 // it is the package's only `react-dom` import. These come from the contract module, which imports

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,uEAAuE;AACvE,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEnF,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,EACZ,cAAc,GAMf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2CAA2C;AAC3C,EAAE;AACF,+FAA+F;AAC/F,gGAAgG;AAChG,+FAA+F;AAC/F,iGAAiG;AACjG,0BAA0B;AAC1B,EAAE;AACF,oEAAoE;AACpE,6DAA6D;AAC7D,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,6FAA6F;AAC7F,+FAA+F;AAC/F,+FAA+F;AAC/F,+FAA+F;AAC/F,uEAAuE;AACvE,EAAE;AACF,2FAA2F;AAC3F,iGAAiG;AACjG,qFAAqF;AACrF,6FAA6F;AAC7F,iGAAiG;AACjG,yFAAyF;AACzF,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EACL,eAAe,GAMhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,UAAU,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAA6B,MAAM,YAAY,CAAC;AAEjG,OAAO,EACL,aAAa,GAGd,MAAM,qBAAsB,CAAC;AAC9B,OAAO,EACL,oBAAoB,EACpB,YAAY,GAMb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,iGAAiG;AACjG,kGAAkG;AAClG,6FAA6F;AAC7F,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE9E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAwB,MAAM,WAAW,CAAC"}

package/dist/query.d.ts

@@ -8,6 +8,15 @@ export interface QueryDefaultsOptions {
     durableLimitCodes?: readonly string[];
     /** How many times to retry a transient failure. Two donors used 2, one used 1. */
     maxRetries?: number;
+    /**
+     * Longest stated wait still worth retrying. Default 10 seconds.
+     *
+     * Only applies when the refusal named its own expiry (`Retry-After`, or `retryAfterSecs` in
+     * the body). A burst limit that clears in two seconds is worth sitting out; a monthly ceiling
+     * that clears in an hour is an answer, and holding a spinner for it helps nobody — show the
+     * wait instead, which is what `humanizeWait` is for.
+     */
+    maxRetryWaitSecs?: number;
     staleTime?: number;
     gcTime?: number;
     /**
@@ -23,6 +32,12 @@ export interface QueryDefaultsOptions {
  * Exported on its own because an app with its own QueryClient config still wants this rule, and
  * because it is the part worth testing.
  */
-export declare function shouldRetry(error: unknown, durableLimitCodes?: readonly string[]): boolean;
-export declare function queryDefaults({ durableLimitCodes, maxRetries, staleTime, gcTime, refetchOnWindowFocus, }?: QueryDefaultsOptions): DefaultOptions;
+export declare function shouldRetry(error: unknown, durableLimitCodes?: readonly string[], maxRetryWaitSecs?: number): boolean;
+/**
+ * How long before the next attempt: the server's stated wait when there is one, react-query's
+ * exponential backoff otherwise, and never less than the backoff — a `Retry-After: 0` is a
+ * server saying "immediately", which for a client that just got refused is still too soon.
+ */
+export declare function retryDelayMs(attemptIndex: number, error: unknown): number;
+export declare function queryDefaults({ durableLimitCodes, maxRetries, maxRetryWaitSecs, staleTime, gcTime, refetchOnWindowFocus, }?: QueryDefaultsOptions): DefaultOptions;
 //# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAuB5D,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,iBAAiB,GAAE,SAAS,MAAM,EAAO,GAAG,OAAO,CAQ9F;AAED,wBAAgB,aAAa,CAAC,EAC5B,iBAAsB,EACtB,UAAc,EACd,SAAyB,EACzB,MAAuB,EACvB,oBAA4B,GAC7B,GAAE,oBAAyB,GAAG,cAAc,CAc5C"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AA+B5D,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,iBAAiB,GAAE,SAAS,MAAM,EAAO,EACzC,gBAAgB,SAA8B,GAC7C,OAAO,CAcT;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAKzE;AAED,wBAAgB,aAAa,CAAC,EAC5B,iBAAsB,EACtB,UAAc,EACd,gBAA8C,EAC9C,SAAyB,EACzB,MAAuB,EACvB,oBAA4B,GAC7B,GAAE,oBAAyB,GAAG,cAAc,CAe5C"}

package/dist/query.js

@@ -1,4 +1,4 @@
-import { ApiError } from "./api-error.js";
+import { ApiError, retryAfterSecs } from "./api-error.js";
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
  *
@@ -13,33 +13,58 @@ import { ApiError } from "./api-error.js";
  * - one set **`refetchOnReconnect`**, which none of the others had, and which is the single
  *   most useful refetch there is: coming back from a tunnel is exactly when the screen is stale.
  *
+ * The second migration added the fourth rule, which no donor had: **when a 429 says how long,
+ * believe it.** Its limiter answers `Retry-After: 60` on a per-minute window, and the default
+ * backoff retries at 1s and 2s — two more requests that cannot succeed, both charged against the
+ * same limiter, and three seconds added before the screen says anything. So a stated wait is
+ * waited out when it is short, and is an ANSWER when it is not.
+ *
  * This is invariant 8.
  */
 /** 4xx statuses a second attempt can fix. Everything else in the 4xx family is an answer. */
 const RETRYABLE_CLIENT_STATUS = new Set([408, 429]);
+const DEFAULT_MAX_RETRY_WAIT_SECS = 10;
 /**
  * Should this failure be retried?
  *
  * Exported on its own because an app with its own QueryClient config still wants this rule, and
  * because it is the part worth testing.
  */
-export function shouldRetry(error, durableLimitCodes = []) {
+export function shouldRetry(error, durableLimitCodes = [], maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS) {
     // No response at all — offline, DNS, a dropped connection. The request never landed, so
     // nothing about it is an answer, and a second attempt is exactly right.
     if (!(error instanceof ApiError))
         return true;
     if (error.code !== undefined && durableLimitCodes.includes(error.code))
         return false;
+    // It told us when it clears. A wait we are not willing to hold is a refusal, not a hiccup —
+    // and it is the same judgement `durableLimitCodes` makes, except the server did the naming.
+    const wait = retryAfterSecs(error);
+    if (wait !== null && wait > maxRetryWaitSecs)
+        return false;
     if (error.status >= 500)
         return true;
     return RETRYABLE_CLIENT_STATUS.has(error.status);
 }
-export function queryDefaults({ durableLimitCodes = [], maxRetries = 2, staleTime = 2 * 60 * 1000, gcTime = 10 * 60 * 1000, refetchOnWindowFocus = false, } = {}) {
+/**
+ * How long before the next attempt: the server's stated wait when there is one, react-query's
+ * exponential backoff otherwise, and never less than the backoff — a `Retry-After: 0` is a
+ * server saying "immediately", which for a client that just got refused is still too soon.
+ */
+export function retryDelayMs(attemptIndex, error) {
+    const backoff = Math.min(1000 * 2 ** attemptIndex, 30_000);
+    if (!(error instanceof ApiError))
+        return backoff;
+    const wait = retryAfterSecs(error);
+    return wait === null ? backoff : Math.max(backoff, wait * 1000);
+}
+export function queryDefaults({ durableLimitCodes = [], maxRetries = 2, maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS, staleTime = 2 * 60 * 1000, gcTime = 10 * 60 * 1000, refetchOnWindowFocus = false, } = {}) {
     return {
         queries: {
             staleTime,
             gcTime,
-            retry: (failureCount, error) => failureCount < maxRetries && shouldRetry(error, durableLimitCodes),
+            retry: (failureCount, error) => failureCount < maxRetries && shouldRetry(error, durableLimitCodes, maxRetryWaitSecs),
+            retryDelay: retryDelayMs,
             refetchOnWindowFocus,
             refetchOnReconnect: true,
         },

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AAEH,6FAA6F;AAC7F,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAqBpD;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,oBAAuC,EAAE;IACnF,wFAAwF;IACxF,wEAAwE;IACxE,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrF,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAC5B,iBAAiB,GAAG,EAAE,EACtB,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,EACzB,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EACvB,oBAAoB,GAAG,KAAK,MACJ,EAAE;IAC1B,OAAO;QACL,OAAO,EAAE;YACP,SAAS;YACT,MAAM;YACN,KAAK,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,CAC7B,YAAY,GAAG,UAAU,IAAI,WAAW,CAAC,KAAK,EAAE,iBAAiB,CAAC;YACpE,oBAAoB;YACpB,kBAAkB,EAAE,IAAI;SACzB;QACD,2FAA2F;QAC3F,yFAAyF;QACzF,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,6FAA6F;AAC7F,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEpD,MAAM,2BAA2B,GAAG,EAAE,CAAC;AA8BvC;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACzB,KAAc,EACd,oBAAuC,EAAE,EACzC,gBAAgB,GAAG,2BAA2B;IAE9C,wFAAwF;IACxF,wEAAwE;IACxE,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,iBAAiB,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAErF,4FAA4F;IAC5F,4FAA4F;IAC5F,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,GAAG,gBAAgB;QAAE,OAAO,KAAK,CAAC;IAE3D,IAAI,KAAK,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,YAAoB,EAAE,KAAc;IAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,YAAY,EAAE,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,KAAK,YAAY,QAAQ,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAC5B,iBAAiB,GAAG,EAAE,EACtB,UAAU,GAAG,CAAC,EACd,gBAAgB,GAAG,2BAA2B,EAC9C,SAAS,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,EACzB,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,EACvB,oBAAoB,GAAG,KAAK,MACJ,EAAE;IAC1B,OAAO;QACL,OAAO,EAAE;YACP,SAAS;YACT,MAAM;YACN,KAAK,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,CAC7B,YAAY,GAAG,UAAU,IAAI,WAAW,CAAC,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,CAAC;YACtF,UAAU,EAAE,YAAY;YACxB,oBAAoB;YACpB,kBAAkB,EAAE,IAAI;SACzB;QACD,2FAA2F;QAC3F,yFAAyF;QACzF,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;KAC5B,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gusnips/react",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "The headless runtime under a Vite + React SPA: typed fetch client with single-flight refresh, auth store, query defaults, route guards, error boundary, chunk-reload recovery, i18n bootstrap.",
   "type": "module",
   "license": "MIT",

package/src/api-client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { ApiError, isAbortError } from "./api-error.ts";
+import { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 import { createApiClient, type RefreshResult, type SessionAdapter } from "./api-client.ts";
 
 function stubFetch(handler: (url: string, init: RequestInit) => Response | Promise<Response>) {
@@ -65,6 +65,43 @@ describe("createApiClient", () => {
     });
   });
 
+  /**
+   * The second migration's API states the wait in the HEADER and puts nothing in the body — the
+   * standard place, and the one this package did not read. `retryAfterSecs` now answers for
+   * either convention, which is what lets one retry rule and one piece of copy serve both.
+   */
+  it("reads the wait off the Retry-After header", async () => {
+    stubFetch(
+      () =>
+        new Response(JSON.stringify({ error: { code: "RATE_LIMIT_EXCEEDED", message: "slow" } }), {
+          status: 429,
+          headers: { "Retry-After": "60" },
+        }),
+    );
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    const error = await api.get("/x").catch((e: unknown) => e);
+    expect(error).toMatchObject({ status: 429, retryAfterSecs: 60 });
+    expect(retryAfterSecs(error as ApiError)).toBe(60);
+  });
+
+  it("leaves the wait unset when the answer did not state one", async () => {
+    stubFetch(() => new Response("{}", { status: 500 }));
+    const api = createApiClient({
+      baseUrl: "https://api.test",
+      session: session(),
+      onSessionDead: () => {},
+    });
+
+    const error = await api.get("/x").catch((e: unknown) => e);
+    expect((error as ApiError).retryAfterSecs).toBeUndefined();
+    expect(retryAfterSecs(error as ApiError)).toBeNull();
+  });
+
   /**
    * The single-flight rule, and the reason all three donors found it the hard way: the auth
    * server rotates the refresh token on use, so six parallel 401s sending six refreshes means
@@ -150,15 +187,15 @@ describe("createApiClient", () => {
 
   /**
    * providerkit's invariant 2, on the web side: a caller's Stop and our deadline must stay
-   * distinguishable. `AbortSignal.timeout` rejects with a **TimeoutError**, not an AbortError,
-   * so `isAbortError` stays false for it — which is what lets a timeout be retried and reported
+   * distinguishable. The deadline aborts with a **TimeoutError**, not an AbortError, so
+   * `isAbortError` stays false for it — which is what lets a timeout be retried and reported
    * while a navigation-cancelled request is silently dropped.
    */
   it("distinguishes its own timeout from the caller's abort", async () => {
     // Note the `aborted` check before the listener. A signal that fired before fetch was ever
     // called never emits the event, so a listener alone hangs forever — real `fetch` checks the
-    // flag first, and so must anything standing in for it. That already-aborted race is exactly
-    // what `AbortSignal.any` in the client exists to cover.
+    // flag first, and so must anything standing in for it. That already-aborted race is one of
+    // the three things `withDeadline` exists to get right.
     stubFetch(
       (_url, init) =>
         new Promise<Response>((_resolve, reject) => {
@@ -175,13 +212,44 @@ describe("createApiClient", () => {
     });
 
     const timedOut = await api.get("/slow").catch((e: unknown) => e);
-    expect((timedOut as DOMException).name).toBe("TimeoutError");
+    expect((timedOut as Error).name).toBe("TimeoutError");
     expect(isAbortError(timedOut)).toBe(false);
 
     const controller = new AbortController();
     const cancelled = api.get("/slow", { signal: controller.signal }).catch((e: unknown) => e);
     controller.abort();
     expect(isAbortError(await cancelled)).toBe(true);
+
+    // The already-aborted race: a signal that fired BEFORE the call. A listener alone never
+    // hears it, so the request would go out and run to full term with nobody waiting.
+    const already = new AbortController();
+    already.abort();
+    const dead = await api.get("/slow", { signal: already.signal }).catch((e: unknown) => e);
+    expect(isAbortError(dead)).toBe(true);
+  });
+
+  /**
+   * React Native replaces the global `AbortSignal` with abort-controller@3, which has neither
+   * `timeout` nor `any`. The client used both, so `createApiClient` threw
+   * `AbortSignal.timeout is not a function` on the phone's first request — in the main entry,
+   * the one this package promises works there. Deleting the statics is the cheapest honest
+   * stand-in for that runtime.
+   */
+  it("works where AbortSignal has no static helpers, as on a phone", async () => {
+    const { timeout, any } = AbortSignal as unknown as Record<string, unknown>;
+    delete (AbortSignal as unknown as Record<string, unknown>).timeout;
+    delete (AbortSignal as unknown as Record<string, unknown>).any;
+    try {
+      stubFetch(() => ok({ id: "1" }));
+      const api = createApiClient({
+        baseUrl: "https://api.test",
+        session: session(),
+        onSessionDead: () => {},
+      });
+      await expect(api.get("/me")).resolves.toEqual({ id: "1" });
+    } finally {
+      Object.assign(AbortSignal, { timeout, any });
+    }
   });
 
   // A 204 has no body, so `res.json()` on one throws `Unexpected end of JSON input` — which

package/src/api-client.ts

@@ -1,5 +1,5 @@
 import { isApiError, type ApiSuccess } from "@gusnips/http";
-import { ApiError } from "./api-error.ts";
+import { ApiError, parseRetryAfter } from "./api-error.ts";
 
 /**
  * The app's one door to the API. Nothing else should call `fetch`.
@@ -144,6 +144,67 @@ export interface ApiClient {
 
 const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
 
+/**
+ * One signal that fires on the caller's abort or on the deadline, whichever comes first.
+ *
+ * `AbortSignal.timeout` plus `AbortSignal.any` is the obvious way to write this, and it is
+ * not portable: React Native replaces the global `AbortSignal` with abort-controller@3, which
+ * has neither static — so the phone got `AbortSignal.timeout is not a function` on its very
+ * first request. This is the same two rules with an `AbortController`, which every runtime
+ * this package targets does have, and it is the ONLY path rather than a fallback: one branch
+ * cannot drift from the other.
+ *
+ * Three details that are the whole reason this is not three lines:
+ *
+ * - **The already-aborted race.** A caller whose signal fired before we attached would never
+ *   fire the listener, so the request would go out and run to full term. Checked first.
+ * - **A timeout must not look like a cancellation.** `isAbortError` exists so a request nobody
+ *   is waiting for stays silent; a request that ran out of time is a real failure somebody
+ *   should see. A bare `controller.abort()` raises an `AbortError` and would be swallowed, so
+ *   the deadline aborts with a plain `Error` — not a `DOMException`, which `isAbortError` is
+ *   the one thing that checks for.
+ * - **The timer is cleared.** Otherwise every completed request leaves a pending timeout for
+ *   the rest of its budget, which on a phone is a wake-up nobody asked for.
+ */
+function withDeadline(
+  ms: number,
+  caller: AbortSignal | null | undefined,
+): { signal: AbortSignal; clear: () => void } {
+  const controller = new AbortController();
+  const timer = setTimeout(() => {
+    // Named, not typed: callers identify a deadline by `name === "TimeoutError"`, the same
+    // way `AbortSignal.timeout` reports it. A `DOMException` would be the faithful copy and is
+    // not constructible everywhere this runs.
+    const expired = new Error(`Request timed out after ${String(ms)}ms`);
+    expired.name = "TimeoutError";
+    controller.abort(expired);
+  }, ms);
+
+  let detach = (): void => {};
+  if (caller) {
+    if (caller.aborted) {
+      clearTimeout(timer);
+      controller.abort(caller.reason);
+    } else {
+      const onAbort = (): void => {
+        controller.abort(caller.reason);
+      };
+      caller.addEventListener("abort", onAbort, { once: true });
+      detach = () => {
+        caller.removeEventListener("abort", onAbort);
+      };
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    clear: () => {
+      clearTimeout(timer);
+      detach();
+    },
+  };
+}
+
 export function createApiClient({
   baseUrl,
   session,
@@ -215,15 +276,16 @@ export function createApiClient({
     if (budget === null)
       return fetch(`${baseUrl}${path}`, { ...init, signal, headers: buildHeaders(token, headers) });
 
-    // `AbortSignal.any` rather than a listener: it also catches the already-aborted race, where
-    // a caller's signal fired before we ever attached. It keeps the caller's abort and our
-    // timeout distinguishable at the source, which is what lets `isAbortError` stay honest.
-    const timeout = AbortSignal.timeout(budget);
-    return fetch(`${baseUrl}${path}`, {
-      ...init,
-      signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
-      headers: buildHeaders(token, headers),
-    });
+    const deadline = withDeadline(budget, signal);
+    try {
+      return await fetch(`${baseUrl}${path}`, {
+        ...init,
+        signal: deadline.signal,
+        headers: buildHeaders(token, headers),
+      });
+    } finally {
+      deadline.clear();
+    }
   }
 
   async function request(path: string, options: RequestOptions = {}): Promise<Response> {
@@ -249,6 +311,7 @@ export function createApiClient({
       const body: unknown = await res.json().catch(() => null);
       const error = new ApiError(res.status, isApiError(body) ? body.error : null, {
         requestId: res.headers.get(requestIdHeader) ?? undefined,
+        retryAfterSecs: parseRetryAfter(res.headers.get("retry-after")),
       });
       // A listener that throws must not become the error the caller sees: the API failure is
       // the real news, and swallowing it for a bug in a side effect would send everyone

package/src/api-error.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { ApiError, parseRetryAfter, retryAfterSecs } from "./api-error.ts";
+
+/**
+ * Two APIs, two places for the same fact: one states the wait in the `Retry-After` header (the
+ * standard one), the other in `details.retryAfterSecs`. A caller asking "how long" should not
+ * have to know which server answered.
+ */
+describe("retryAfterSecs", () => {
+  it("reads the header the client captured", () => {
+    expect(retryAfterSecs(new ApiError(429, null, { retryAfterSecs: 60 }))).toBe(60);
+    // Zero is a real answer — "now" — and must not read as "did not say".
+    expect(retryAfterSecs(new ApiError(429, null, { retryAfterSecs: 0 }))).toBe(0);
+  });
+
+  it("prefers the header to the body", () => {
+    const both = new ApiError(
+      429,
+      { code: "X", message: "", details: { retryAfterSecs: 30 } },
+      {
+        retryAfterSecs: 60,
+      },
+    );
+    expect(retryAfterSecs(both)).toBe(60);
+  });
+
+  it("reads the number out of details, and refuses anything else", () => {
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: 30 } }),
+      ),
+    ).toBe(30);
+    expect(
+      retryAfterSecs(
+        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: "30" } }),
+      ),
+    ).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
+    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
+  });
+});
+
+/**
+ * Both spec forms are real — RFC 9110 allows delay-seconds or an HTTP-date, and servers pick
+ * differently. The date half is the one that gets skipped, which silently turns a stated wait
+ * into no wait at all.
+ */
+describe("parseRetryAfter", () => {
+  it("reads delay-seconds", () => {
+    expect(parseRetryAfter("60")).toBe(60);
+    expect(parseRetryAfter("  60  ")).toBe(60);
+    expect(parseRetryAfter("0")).toBe(0);
+  });
+
+  it("reads an HTTP-date", () => {
+    const at = new Date(Date.now() + 120_000).toUTCString();
+    expect(parseRetryAfter(at)).toBeGreaterThanOrEqual(119);
+    expect(parseRetryAfter(at)).toBeLessThanOrEqual(120);
+  });
+
+  // A date already gone means "now", not a negative delay that would run the backoff backwards.
+  it("clamps a date in the past to zero", () => {
+    expect(parseRetryAfter(new Date(Date.now() - 60_000).toUTCString())).toBe(0);
+  });
+
+  it("answers nothing for a header that is missing or not a wait", () => {
+    expect(parseRetryAfter(null)).toBeUndefined();
+    expect(parseRetryAfter("")).toBeUndefined();
+    expect(parseRetryAfter("   ")).toBeUndefined();
+    expect(parseRetryAfter("soon")).toBeUndefined();
+    expect(parseRetryAfter("-5")).toBeUndefined();
+    expect(parseRetryAfter("9007199254740993")).toBeUndefined();
+  });
+});

package/src/api-error.ts

@@ -18,6 +18,17 @@ export class ApiError extends Error {
   readonly params: Record<string, string | number> | undefined;
   readonly details: unknown;
   readonly requestId: string | undefined;
+  /**
+   * Seconds until this refusal clears, when the answer said so.
+   *
+   * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
+   * written by anyone puts it. The second migration is why this exists: that API sends
+   * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
+   * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
+   * both the copy and the retry rule were flying blind on the one refusal that states its own
+   * expiry. Two conventions, same fact; {@link retryAfterSecs} reads either.
+   */
+  readonly retryAfterSecs: number | undefined;
 
   /**
    * The client raised this itself to stop a caller while it was already handling the
@@ -33,7 +44,12 @@ export class ApiError extends Error {
   constructor(
     status: number,
     body: ApiErrorBody["error"] | null,
-    opts: { requestId?: string; expected?: boolean; message?: string } = {},
+    opts: {
+      requestId?: string;
+      expected?: boolean;
+      message?: string;
+      retryAfterSecs?: number;
+    } = {},
   ) {
     super(opts.message ?? body?.message ?? `Request failed (${status})`);
     this.name = "ApiError";
@@ -43,10 +59,50 @@ export class ApiError extends Error {
     this.params = body?.params;
     this.details = body?.details;
     this.requestId = opts.requestId;
+    this.retryAfterSecs = opts.retryAfterSecs;
     this.expected = opts.expected ?? false;
   }
 }
 
+/**
+ * Seconds until a refusal clears, from whichever place the API put them.
+ *
+ * The header first, because it is the standard one and it is what a limiter emits without being
+ * asked; then `details.retryAfterSecs`, which one donor's API sends in the body instead. A
+ * caller asking "how long" should not have to know which server it is talking to.
+ */
+export function retryAfterSecs(error: ApiError): number | null {
+  if (error.retryAfterSecs !== undefined) return error.retryAfterSecs;
+  const details = error.details;
+  if (typeof details !== "object" || details === null) return null;
+  const value = (details as { retryAfterSecs?: unknown }).retryAfterSecs;
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * `Retry-After` in either spec form: delay-seconds, or an HTTP-date.
+ *
+ * Both forms are real — RFC 9110 allows either and different servers pick differently — and the
+ * date one is the half that gets skipped, which turns a stated wait into no wait at all. Clamped
+ * at zero: a date already in the past means "now", not a negative delay.
+ */
+export function parseRetryAfter(value: string | null | undefined): number | undefined {
+  const raw = value?.trim();
+  if (!raw) return undefined;
+
+  // A bare integer is the delay-seconds form, malformed included: `Date.parse` accepts some of
+  // them as years, so falling through would read "-5" as a date long past and answer 0 — a
+  // wait invented out of a header that never stated one.
+  if (/^[+-]?\d+$/.test(raw)) {
+    const secs = Number(raw);
+    return Number.isSafeInteger(secs) && secs >= 0 ? secs : undefined;
+  }
+
+  const at = Date.parse(raw);
+  if (Number.isNaN(at)) return undefined;
+  return Math.max(0, Math.round((at - Date.now()) / 1000));
+}
+
 /**
  * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
  * component waiting on it.

package/src/describe-error.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { ApiError } from "./api-error.ts";
-import { createErrorDescriber, humanizeWait, retryAfterSecs } from "./describe-error.ts";
+import { createErrorDescriber, humanizeWait } from "./describe-error.ts";
 
 /** A translator that echoes the key, so a test can see exactly which one was asked for. */
 const t = (key: string, params?: Record<string, unknown>) =>
@@ -22,23 +22,6 @@ describe("humanizeWait", () => {
   });
 });
 
-describe("retryAfterSecs", () => {
-  it("reads the number out of details, and refuses anything else", () => {
-    expect(
-      retryAfterSecs(
-        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: 30 } }),
-      ),
-    ).toBe(30);
-    expect(
-      retryAfterSecs(
-        new ApiError(429, { code: "X", message: "", details: { retryAfterSecs: "30" } }),
-      ),
-    ).toBeNull();
-    expect(retryAfterSecs(new ApiError(429, { code: "X", message: "", details: null }))).toBeNull();
-    expect(retryAfterSecs(new ApiError(429, null))).toBeNull();
-  });
-});
-
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,

package/src/describe-error.ts

@@ -1,4 +1,4 @@
-import { ApiError } from "./api-error.ts";
+import { ApiError, retryAfterSecs } from "./api-error.ts";
 
 /**
  * Turning anything thrown into copy a person can act on.
@@ -75,14 +75,6 @@ type _TypedCatalogNeedsNoCast = Satisfied<
     : false
 >;
 
-/** Seconds until a refusal clears, when the envelope carries them. */
-export function retryAfterSecs(error: ApiError): number | null {
-  const details = error.details;
-  if (typeof details !== "object" || details === null) return null;
-  const value = (details as { retryAfterSecs?: unknown }).retryAfterSecs;
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *

package/src/index.ts

@@ -29,7 +29,7 @@
 
 export { cn } from "./cn.ts";
 
-export { ApiError, isAbortError } from "./api-error.ts";
+export { ApiError, isAbortError, retryAfterSecs } from "./api-error.ts";
 export {
   createApiClient,
   type ApiClient,
@@ -40,7 +40,7 @@ export {
 } from "./api-client.ts";
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 
-export { queryDefaults, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
+export { queryDefaults, retryDelayMs, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 
 export {
   ErrorBoundary,
@@ -50,7 +50,6 @@ export {
 export {
   createErrorDescriber,
   humanizeWait,
-  retryAfterSecs,
   type DescribedError,
   type ErrorArm,
   type ErrorContext,

package/src/query.test.ts

@@ -1,10 +1,14 @@
 import { describe, expect, it } from "vitest";
 import { ApiError } from "./api-error.ts";
-import { shouldRetry } from "./query.ts";
+import { retryDelayMs, shouldRetry } from "./query.ts";
 
 const refusal = (status: number, code?: string) =>
   new ApiError(status, code ? { code, message: code } : null);
 
+/** A refusal that named its own expiry, the way a `Retry-After` header does. */
+const waited = (status: number, secs: number) =>
+  new ApiError(status, null, { retryAfterSecs: secs });
+
 // Invariant 8, and the reason this module exists: three donors wrote three retry rules and
 // each was right about something the other two got wrong. Every case below is one of those.
 describe("shouldRetry", () => {
@@ -51,4 +55,52 @@ describe("shouldRetry", () => {
   it("lets a durable code override the status", () => {
     expect(shouldRetry(refusal(503, "QUOTA_EXCEEDED"), ["QUOTA_EXCEEDED"])).toBe(false);
   });
+
+  // The second migration's rule. Its limiter answers `Retry-After: 60` on a per-minute window,
+  // so retrying at 1s and 2s spends two more requests that cannot possibly succeed.
+  it("does not retry a stated wait longer than we will hold", () => {
+    expect(shouldRetry(waited(429, 60))).toBe(false);
+    expect(shouldRetry(waited(429, 2))).toBe(true);
+    // The boundary is inclusive: exactly the ceiling is still worth waiting out.
+    expect(shouldRetry(waited(429, 10))).toBe(true);
+    expect(shouldRetry(waited(429, 11))).toBe(false);
+  });
+
+  it("takes the ceiling from the caller", () => {
+    expect(shouldRetry(waited(429, 60), [], 90)).toBe(true);
+    expect(shouldRetry(waited(429, 3), [], 1)).toBe(false);
+  });
+
+  // A long wait is an answer whatever the status says — the same judgement `durableLimitCodes`
+  // makes, except here the server named it and the app did not have to.
+  it("lets a stated wait override a 5xx", () => {
+    expect(shouldRetry(waited(503, 300))).toBe(false);
+  });
+
+  it("still retries when nothing said how long", () => {
+    expect(shouldRetry(refusal(429))).toBe(true);
+  });
+});
+
+describe("retryDelayMs", () => {
+  it("backs off exponentially when nothing said how long", () => {
+    expect(retryDelayMs(0, refusal(500))).toBe(1000);
+    expect(retryDelayMs(1, refusal(500))).toBe(2000);
+    // …and caps, so a long-lived query does not schedule a retry for next week.
+    expect(retryDelayMs(20, refusal(500))).toBe(30_000);
+  });
+
+  it("waits what the server asked for", () => {
+    expect(retryDelayMs(0, waited(429, 5))).toBe(5000);
+  });
+
+  // `Retry-After: 0` is a server saying "immediately", which for a client that was just refused
+  // is still too soon — the backoff is the floor.
+  it("never goes below the backoff", () => {
+    expect(retryDelayMs(1, waited(429, 0))).toBe(2000);
+  });
+
+  it("backs off for a failure that is not an API answer at all", () => {
+    expect(retryDelayMs(0, new TypeError("Failed to fetch"))).toBe(1000);
+  });
 });

package/src/query.ts

@@ -1,5 +1,5 @@
 import type { DefaultOptions } from "@tanstack/react-query";
-import { ApiError } from "./api-error.ts";
+import { ApiError, retryAfterSecs } from "./api-error.ts";
 
 /**
  * react-query defaults — the merge of three repos that each got part of this right.
@@ -15,12 +15,20 @@ import { ApiError } from "./api-error.ts";
  * - one set **`refetchOnReconnect`**, which none of the others had, and which is the single
  *   most useful refetch there is: coming back from a tunnel is exactly when the screen is stale.
  *
+ * The second migration added the fourth rule, which no donor had: **when a 429 says how long,
+ * believe it.** Its limiter answers `Retry-After: 60` on a per-minute window, and the default
+ * backoff retries at 1s and 2s — two more requests that cannot succeed, both charged against the
+ * same limiter, and three seconds added before the screen says anything. So a stated wait is
+ * waited out when it is short, and is an ANSWER when it is not.
+ *
  * This is invariant 8.
  */
 
 /** 4xx statuses a second attempt can fix. Everything else in the 4xx family is an answer. */
 const RETRYABLE_CLIENT_STATUS = new Set([408, 429]);
 
+const DEFAULT_MAX_RETRY_WAIT_SECS = 10;
+
 export interface QueryDefaultsOptions {
   /**
    * Error codes that mean "this limit does not clear by waiting" — a spent monthly quota, a
@@ -30,6 +38,15 @@ export interface QueryDefaultsOptions {
   durableLimitCodes?: readonly string[];
   /** How many times to retry a transient failure. Two donors used 2, one used 1. */
   maxRetries?: number;
+  /**
+   * Longest stated wait still worth retrying. Default 10 seconds.
+   *
+   * Only applies when the refusal named its own expiry (`Retry-After`, or `retryAfterSecs` in
+   * the body). A burst limit that clears in two seconds is worth sitting out; a monthly ceiling
+   * that clears in an hour is an answer, and holding a spinner for it helps nobody — show the
+   * wait instead, which is what `humanizeWait` is for.
+   */
+  maxRetryWaitSecs?: number;
   staleTime?: number;
   gcTime?: number;
   /**
@@ -46,19 +63,42 @@ export interface QueryDefaultsOptions {
  * Exported on its own because an app with its own QueryClient config still wants this rule, and
  * because it is the part worth testing.
  */
-export function shouldRetry(error: unknown, durableLimitCodes: readonly string[] = []): boolean {
+export function shouldRetry(
+  error: unknown,
+  durableLimitCodes: readonly string[] = [],
+  maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS,
+): boolean {
   // No response at all — offline, DNS, a dropped connection. The request never landed, so
   // nothing about it is an answer, and a second attempt is exactly right.
   if (!(error instanceof ApiError)) return true;
 
   if (error.code !== undefined && durableLimitCodes.includes(error.code)) return false;
+
+  // It told us when it clears. A wait we are not willing to hold is a refusal, not a hiccup —
+  // and it is the same judgement `durableLimitCodes` makes, except the server did the naming.
+  const wait = retryAfterSecs(error);
+  if (wait !== null && wait > maxRetryWaitSecs) return false;
+
   if (error.status >= 500) return true;
   return RETRYABLE_CLIENT_STATUS.has(error.status);
 }
 
+/**
+ * How long before the next attempt: the server's stated wait when there is one, react-query's
+ * exponential backoff otherwise, and never less than the backoff — a `Retry-After: 0` is a
+ * server saying "immediately", which for a client that just got refused is still too soon.
+ */
+export function retryDelayMs(attemptIndex: number, error: unknown): number {
+  const backoff = Math.min(1000 * 2 ** attemptIndex, 30_000);
+  if (!(error instanceof ApiError)) return backoff;
+  const wait = retryAfterSecs(error);
+  return wait === null ? backoff : Math.max(backoff, wait * 1000);
+}
+
 export function queryDefaults({
   durableLimitCodes = [],
   maxRetries = 2,
+  maxRetryWaitSecs = DEFAULT_MAX_RETRY_WAIT_SECS,
   staleTime = 2 * 60 * 1000,
   gcTime = 10 * 60 * 1000,
   refetchOnWindowFocus = false,
@@ -68,7 +108,8 @@ export function queryDefaults({
       staleTime,
       gcTime,
       retry: (failureCount, error) =>
-        failureCount < maxRetries && shouldRetry(error, durableLimitCodes),
+        failureCount < maxRetries && shouldRetry(error, durableLimitCodes, maxRetryWaitSecs),
+      retryDelay: retryDelayMs,
       refetchOnWindowFocus,
       refetchOnReconnect: true,
     },