@gusnips/react 0.5.2 → 0.6.0

package/README.md

@@ -152,7 +152,32 @@ the prop shape _is_ the rule: `problem`, `cause`, `fix`, and `action`. **`fix` a
 required.** A required prop is the only version of "always offer a way out" that a caller in a
 hurry cannot skip.
 
-`createErrorDescriber` turns a thrown `ApiError` into the `cause` and `fix` to put in it.
+`createErrorDescriber` turns a thrown `ApiError` into the `cause` and `fix` to put in it — plus
+which control to offer, and the request id to print under it:
+
+```ts
+const { cause, fix, recover, reference } = describeError(error);
+// recover: "retry" | "signin" | "wait" | "none"
+```
+
+The field is `fix`, the same word as the prop above. It was `hint` until 0.6.0, which left every
+adopter writing `fix={hint}` at every error surface.
+
+`recover` is derived from `shouldRetry` — the same rule react-query retries on — so the button a
+reader sees and the retry that actually happens cannot disagree. Give it the same
+`durableLimitCodes` list you give `queryDefaults`, and a spent quota offers no button instead of
+one that cannot work.
+
+You also say how a stated wait becomes words:
+
+```ts
+formatWait: (secs) => humanizeWait(t, secs, "errors."); // three ICU plural keys
+formatWait: (secs) => formatIn(secs, locale); // or your own Intl formatter
+```
+
+It is required because the default hid its price: `humanizeWait` reads `waitSeconds`,
+`waitMinutes` and `waitHours` out of your catalog, so an app that already formats relative time
+with `Intl` had to add six entries per language before it would compile.
 
 ## Also here
 

package/dist/describe-error.d.ts

@@ -8,20 +8,55 @@ import { ApiError } from "./api-error.ts";
  * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
  * that could just say what to do next.
  *
- * `cause` is what happened. `hint` is what to do about it. **A surface that shows only the first
+ * `cause` is what happened. `fix` is what to do about it. **A surface that shows only the first
  * half is the dead end this exists to prevent** — which is why the type has two fields and not
- * one, and why `hint` being absent should be a deliberate choice at each call site rather than
+ * one, and why `fix` being absent should be a deliberate choice at each call site rather than
  * the default nobody noticed.
  *
+ * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps` — the contract this same
+ * package ships for the component that renders this — has always called it `fix`, so every
+ * adopter wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an
+ * API we got wrong. It also clears a collision, because in at least one adopter a form field's
+ * `hint` is the requirement text under the input, which is a different thing entirely.
+ *
  * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
  * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
  * which is the part that was written twice and got subtly different both times.
  */
-export interface DescribedError {
+/**
+ * Which control to offer beside the words.
+ *
+ * The fourth adopter had this and the package did not, which left every adopter re-deriving
+ * "can a second attempt fix this" from its own switch — beside a `shouldRetry` already deciding
+ * exactly that for react-query. Two answers to one question drift, and the drift is visible: a
+ * screen offering "try again" for a refusal the query layer refuses to retry, so the button does
+ * nothing and the reader presses it twice.
+ *
+ * So this is DERIVED from `shouldRetry`, not switched on separately. One rule, two consumers.
+ */
+export type RecoveryKind = 
+/** A second attempt can work. Offer the button. */
+"retry"
+/** Auth said no. Offer a way back to sign-in, never a retry. */
+ | "signin"
+/** It stated its own expiry. Offer the button, disabled, with the countdown. */
+ | "wait"
+/** Waiting cannot fix it and neither can pressing anything. Offer no control. */
+ | "none";
+/** The copy an arm writes. Everything it leaves out, {@link createErrorDescriber} fills in. */
+export interface ErrorCopy {
     /** What happened, in the reader's words. */
     cause: string;
     /** What to do about it. Its absence should be a decision, not an oversight. */
-    hint?: string;
+    fix?: string;
+    /** Override the derived kind — a 429 whose code means a spent quota is `"none"`, not `"wait"`. */
+    recover?: RecoveryKind;
+    /** Override the request id. Rarely wanted; the envelope's is used by default. */
+    reference?: string;
+}
+export interface DescribedError extends ErrorCopy {
+    /** Always present on the way out, whether an arm set it or the rule derived it. */
+    recover: RecoveryKind;
 }
 /**
  * The subset of i18next's `t` this module needs — typed here so `i18next` stays optional.
@@ -36,8 +71,16 @@ export interface DescribedError {
 export type Translate<Key extends string = string> = (key: Key, params?: Record<string, unknown>) => string;
 /** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
 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";
+/**
+ * Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them.
+ *
+ * The three wait names are deliberately NOT here, which is the other half of 0.6.0. This module
+ * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours` — each with
+ * an ICU plural — landed in the key union of every adopter's `t` whether or not a wait was ever
+ * rendered. An app that formats waits with `Intl.RelativeTimeFormat` needs none of them and was
+ * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
+ */
+type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -45,6 +88,11 @@ type CopyName = WaitName | "network" | "networkHint" | "unexpected" | "retrySoon
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export declare function humanizeWait<Prefix extends string>(t: Translate<`${Prefix}${WaitName}`>, secs: number, prefix: Prefix): string;
 export interface ErrorContext {
@@ -54,11 +102,28 @@ export interface ErrorContext {
     /** Seconds until it clears, already humanized. Null when the envelope did not say. */
     wait: string | null;
     waitSecs: number | null;
+    /**
+     * What the rule decided before this arm ran. Read it to agree, return your own to override.
+     *
+     * Exposed so an arm can narrow rather than restate: a quota arm that already knows the limit is
+     * durable returns `"none"`, and every other arm can leave it alone and stay right by default.
+     */
+    recover: RecoveryKind;
 }
 export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
     t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
     /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
     copyPrefix: Prefix;
+    /**
+     * How a stated wait becomes words, for the `wait` an arm reads off its context.
+     *
+     * Required rather than defaulted, because there is no answer that is right for everyone and a
+     * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog,
+     * and an app that already formats relative time with `Intl` would have had to add them to
+     * compile. Say which you want — `(secs) => humanizeWait(t, secs, "errors.")`, or your own
+     * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
+     */
+    formatWait: (secs: number) => string;
     /**
      * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
      * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -91,9 +156,17 @@ export interface ErrorDescriberOptions<Prefix extends string, ServerPrefix exten
      * code that does not exist is a compile error at the arm rather than a branch that never runs.
      */
     codes?: Partial<Record<string, ErrorArm>>;
+    /**
+     * The codes that mean "this limit does not clear by waiting" — **the same list you hand
+     * `queryDefaults`**, because it answers the same question and a second copy is a second
+     * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
+     */
+    durableLimitCodes?: readonly string[];
+    /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
+    maxRetryWaitSecs?: number;
 }
-export type ErrorArm = (ctx: ErrorContext) => DescribedError;
+export type ErrorArm = (ctx: ErrorContext) => ErrorCopy;
 /** Build the describer. */
-export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
+export declare function createErrorDescriber<Prefix extends string, ServerPrefix extends string, ServerName extends string>({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, codes, durableLimitCodes, maxRetryWaitSecs, }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError;
 export {};
 //# sourceMappingURL=describe-error.d.ts.map

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

package/dist/describe-error.js

@@ -1,4 +1,5 @@
 import { ApiError, retryAfterSecs } from "./api-error.js";
+import { shouldRetry } from "./query.js";
 /**
  * "in 4 minutes" / "in 2 hours" — a wait nobody has to convert from seconds.
  *
@@ -6,6 +7,11 @@ import { ApiError, retryAfterSecs } from "./api-error.js";
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export function humanizeWait(t, secs, prefix) {
     if (secs < 90)
@@ -15,7 +21,7 @@ export function humanizeWait(t, secs, prefix) {
     return t(`${prefix}waitHours`, { count: Math.round(secs / 3600) });
 }
 /** Build the describer. */
-export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMessageKeys, codes = {}, }) {
+export function createErrorDescriber({ t, copyPrefix, formatWait, messageKeyPrefix, knownMessageKeys, codes = {}, durableLimitCodes = [], maxRetryWaitSecs, }) {
     const known = new Set(Object.keys(knownMessageKeys));
     // Sound, and the reason nothing here needs a cast: the set was built from the keys of
     // `knownMessageKeys`, so membership really does establish the claim. `Object.keys` and not
@@ -34,22 +40,48 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
         return (lookup(error.messageKey) ??
             (error.code === undefined ? null : lookup(`${messageKeyPrefix}${error.code}`)));
     }
+    /**
+     * Which control to offer, decided once and never switched on separately.
+     *
+     * Everything below the last line defers to `shouldRetry` — the rule invariant 8 already owns —
+     * so the button a reader sees and the retry react-query performs cannot disagree.
+     */
+    function recoveryFor(error, waitSecs) {
+        // The client raised this one itself, to stop a caller while a dead session was already being
+        // handled. Nothing is broken and the person is already on their way to sign-in, so asking
+        // them to try again would be the surface contradicting the thing it is reporting.
+        if (error.expected)
+            return "none";
+        // 401 is "we do not know who you are", which no number of attempts answers. 403 is NOT this:
+        // the session is fine and it is a different account that would help, so it falls through.
+        if (error.status === 401)
+            return "signin";
+        // It named its own expiry, so there is a real number to count down beside a disabled button.
+        if (waitSecs !== null)
+            return "wait";
+        return shouldRetry(error, durableLimitCodes, maxRetryWaitSecs) ? "retry" : "none";
+    }
     return function describeError(error) {
         if (!(error instanceof ApiError)) {
             // Not a response at all — the request never landed. Almost always the network, and almost
-            // never worth showing a stack trace for.
-            return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
+            // never worth showing a stack trace for. `shouldRetry` answers a non-response the same way,
+            // so these two agree here without either being told about the other.
+            return {
+                cause: t(`${copyPrefix}network`),
+                // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
+                // every adopter a JSON edit in every language, for a string no caller ever types.
+                fix: t(`${copyPrefix}networkHint`),
+                recover: "retry",
+            };
         }
         const waitSecs = retryAfterSecs(error);
         const ctx = {
             error,
             says: serverSentence(error),
-            wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
+            wait: waitSecs === null ? null : formatWait(waitSecs),
             waitSecs,
+            recover: recoveryFor(error, waitSecs),
         };
-        const arm = error.code === undefined ? undefined : codes[error.code];
-        if (arm)
-            return arm(ctx);
         // Anything unmapped: the server's own sentence is still the most specific thing we have,
         // and support can act on it. A 5xx additionally gets "try again shortly", because that one
         // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
@@ -59,10 +91,22 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
         // own `Request failed (502)`, written for a log. A gateway answering with HTML while the API
         // restarts is exactly when that happens, so it reached screens — until the second migration,
         // whose three apps each guarded against that one string by hand.
-        const serverWords = error.code === undefined ? "" : error.message;
+        const arm = error.code === undefined ? undefined : codes[error.code];
+        const copy = arm
+            ? arm(ctx)
+            : {
+                cause: ctx.says ??
+                    ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
+                fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+            };
+        // The arm wins where it spoke, the rule fills the rest. `requestId` is the one thing every
+        // error surface asks for and nothing was producing — `ErrorStateProps` has reserved a
+        // `reference` slot for it since the contract was written.
+        const reference = copy.reference ?? error.requestId;
         return {
-            cause: ctx.says ?? (serverWords || t(`${copyPrefix}unexpected`)),
-            hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+            ...copy,
+            recover: copy.recover ?? ctx.recover,
+            ...(reference !== undefined && { reference }),
         };
     };
 }

package/dist/describe-error.js.map

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

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { createApiClient, type ApiClient, type ApiClientOptions, type RefreshRes
 export { createSseParser, readSseStream, type SseFrame } from "./sse.ts";
 export { queryDefaults, retryDelayMs, shouldRetry, type QueryDefaultsOptions } from "./query.ts";
 export { ErrorBoundary, type ErrorBoundaryFallbackProps, type ErrorBoundaryProps, } from "./error-boundary.tsx";
-export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorDescriberOptions, type Translate, } from "./describe-error.ts";
+export { createErrorDescriber, humanizeWait, type DescribedError, type ErrorArm, type ErrorContext, type ErrorCopy, type ErrorDescriberOptions, type RecoveryKind, type Translate, } from "./describe-error.ts";
 export { installPreloadErrorHandler, isChunkLoadError, isPreloadHintFailure, isStaleBuild, RELOAD_GUARD_KEY, reloadOnce, } from "./deploy-recovery.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,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,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,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,SAAS,EACd,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAK9B,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.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,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,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,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,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,2FAA2F;AAC3F,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,4EAA4E;AAC5E,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,GAQb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,gBAAgB,EAChB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,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/package.json

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

package/src/describe-error.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { ApiError } from "./api-error.ts";
 import { createErrorDescriber, humanizeWait } from "./describe-error.ts";
+import { shouldRetry } from "./query.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,25 +23,68 @@ describe("humanizeWait", () => {
   });
 });
 
+/**
+ * The seam 0.6.0 added, and why it is required rather than defaulted: this module used to
+ * humanize the wait itself, which put `waitSeconds`/`waitMinutes`/`waitHours` into the key union
+ * of every adopter's `t` — six ICU entries per language — even for an app that formats relative
+ * time with `Intl` and would never render one of them.
+ */
+describe("formatWait", () => {
+  const describeError = createErrorDescriber({
+    t,
+    copyPrefix: "errors.",
+    // What an adopter on `Intl.RelativeTimeFormat` passes. Its catalog has no wait keys at all,
+    // and it gets correct plurals in every language without writing one.
+    formatWait: (secs) =>
+      new Intl.RelativeTimeFormat("en", { numeric: "auto" }).format(
+        Math.round(secs / 60),
+        "minute",
+      ),
+    messageKeyPrefix: "serverErrors.",
+    knownMessageKeys: {},
+    codes: {
+      RATE_LIMIT_EXCEEDED: ({ wait }) => ({
+        cause: "errors.rateLimit",
+        fix: `wait:${String(wait)}`,
+      }),
+    },
+  });
+
+  it("hands an arm the wait in the app's own words, not the package's", () => {
+    const error = new ApiError(
+      429,
+      { code: "RATE_LIMIT_EXCEEDED", message: "slow down" },
+      { retryAfterSecs: 120 },
+    );
+    expect(describeError(error).fix).toBe("wait:in 2 minutes");
+  });
+
+  it("leaves the wait null when the refusal never stated one", () => {
+    const error = new ApiError(429, { code: "RATE_LIMIT_EXCEEDED", message: "slow down" });
+    expect(describeError(error).fix).toBe("wait:null");
+  });
+});
+
 describe("createErrorDescriber", () => {
   const describeError = createErrorDescriber({
     t,
     copyPrefix: "errors.",
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
     messageKeyPrefix: "serverErrors.",
     knownMessageKeys: { quotaDay: "", suspended: "" },
     codes: {
       QUOTA_EXCEEDED: ({ says, wait }) => ({
         cause: says ?? "errors.quota",
-        hint: wait ? `errors.retryIn(${wait})` : undefined,
+        fix: wait ? `errors.retryIn(${wait})` : undefined,
       }),
     },
   });
 
   it("reads a thrown non-response as the network, with a way forward", () => {
-    const { cause, hint } = describeError(new TypeError("Failed to fetch"));
+    const { cause, fix } = describeError(new TypeError("Failed to fetch"));
     expect(cause).toBe("errors.network");
-    // The hint is the point. A cause with no hint is the dead end this module exists to stop.
-    expect(hint).toBe("errors.networkHint");
+    // The fix is the point. A cause with no fix is the dead end this module exists to stop.
+    expect(fix).toBe("errors.networkHint");
   });
 
   it("resolves a messageKey this build carries, with its params", () => {
@@ -81,16 +125,98 @@ describe("createErrorDescriber", () => {
   it("offers a retry on a 5xx and withholds it on a 4xx", () => {
     // A 5xx genuinely clears on its own. A 4xx does not, and saying so would cost the reader
     // another attempt for nothing.
-    expect(describeError(new ApiError(503, null)).hint).toBe("errors.retrySoon");
-    expect(describeError(new ApiError(403, null)).hint).toBeUndefined();
+    expect(describeError(new ApiError(503, null)).fix).toBe("errors.retrySoon");
+    expect(describeError(new ApiError(403, null)).fix).toBeUndefined();
   });
 
   it("never puts the client's own log line on screen", () => {
     // A gateway answers with HTML, so there is no envelope and `message` is the client's
     // `Request failed (502)` — English, and written for a log.
-    const { cause, hint } = describeError(new ApiError(502, null));
+    const { cause, fix } = describeError(new ApiError(502, null));
     expect(cause).toBe("errors.unexpected");
-    expect(hint).toBe("errors.retrySoon");
+    expect(fix).toBe("errors.retrySoon");
+  });
+});
+
+/**
+ * The control to offer beside the words. The fourth adopter had this and the package did not, so
+ * every adopter re-derived "can a second attempt fix this" from its own switch — beside a
+ * `shouldRetry` already answering exactly that for react-query.
+ */
+describe("the recovery kind", () => {
+  const describeError = createErrorDescriber({
+    t,
+    copyPrefix: "errors.",
+    messageKeyPrefix: "serverErrors.",
+    knownMessageKeys: { quotaDay: "" },
+    durableLimitCodes: ["QUOTA_EXCEEDED"],
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
+  });
+
+  it("sends a 401 to sign-in and leaves a 403 alone", () => {
+    expect(describeError(new ApiError(401, null)).recover).toBe("signin");
+    // 403 is not a dead session: the session is fine and a different account is the fix, so
+    // signing someone out would be the wrong cause AND the wrong remedy.
+    expect(describeError(new ApiError(403, null)).recover).toBe("none");
+  });
+
+  it("offers a retry for a request that never landed", () => {
+    expect(describeError(new TypeError("Failed to fetch")).recover).toBe("retry");
+  });
+
+  it("counts down when the refusal stated its own expiry", () => {
+    const error = new ApiError(
+      429,
+      { code: "RATE_LIMIT_EXCEEDED", message: "slow down" },
+      { retryAfterSecs: 30 },
+    );
+    expect(describeError(error).recover).toBe("wait");
+  });
+
+  it("offers no control for a limit that buying clears rather than waiting", () => {
+    // The same 429 as above. Only the CODE separates a burst limit from a spent quota, which is
+    // why the caller names them — from the same list it hands `queryDefaults`.
+    const spent = new ApiError(429, { code: "QUOTA_EXCEEDED", message: "spent" });
+    expect(describeError(spent).recover).toBe("none");
+  });
+
+  it("never asks anyone to retry the 401 the client raised itself", () => {
+    // `expected` is the sign-out path: nothing is broken and the person is already on their way
+    // to the door. A retry button here is the surface contradicting what it reports.
+    expect(describeError(new ApiError(401, null, { expected: true })).recover).toBe("none");
+  });
+
+  it("agrees with the retry rule instead of deciding the same thing twice", () => {
+    // The whole reason this derives rather than switches: if the two ever disagree, a reader
+    // presses a button the query layer has already refused to honour.
+    const error = new ApiError(503, null);
+    expect(shouldRetry(error)).toBe(true);
+    expect(describeError(error).recover).toBe("retry");
+  });
+
+  it("carries the request id the error contract reserves a slot for", () => {
+    const error = new ApiError(500, null, { requestId: "req_123" });
+    expect(describeError(error).reference).toBe("req_123");
+  });
+
+  it("lets an arm narrow the derived kind without restating it", () => {
+    const describe503 = createErrorDescriber({
+      t,
+      copyPrefix: "errors.",
+      formatWait: (secs) => humanizeWait(t, secs, "errors."),
+      messageKeyPrefix: "serverErrors.",
+      knownMessageKeys: {},
+      codes: {
+        MAINTENANCE: (ctx) => {
+          // The arm reads what the rule decided, so an arm that agrees can stay silent.
+          expect(ctx.recover).toBe("retry");
+          return { cause: "errors.maintenance", recover: "none" };
+        },
+      },
+    });
+    const out = describe503(new ApiError(503, { code: "MAINTENANCE", message: "back soon" }));
+    expect(out.recover).toBe("none");
+    expect(out.cause).toBe("errors.maintenance");
   });
 });
 
@@ -104,6 +230,7 @@ describe("createErrorDescriber, when the code names the sentence", () => {
   const describeError = createErrorDescriber({
     t,
     copyPrefix: "errors.",
+    formatWait: (secs) => humanizeWait(t, secs, "errors."),
     messageKeyPrefix: "errors.",
     knownMessageKeys: { FORECAST_NOT_FOUND: "", network: "" },
   });

package/src/describe-error.ts

@@ -1,4 +1,5 @@
 import { ApiError, retryAfterSecs } from "./api-error.ts";
+import { shouldRetry } from "./query.ts";
 
 /**
  * Turning anything thrown into copy a person can act on.
@@ -9,21 +10,58 @@ import { ApiError, retryAfterSecs } from "./api-error.ts";
  * "Monthly quota spent, upgrade or buy a pack" is right in a JSON body and wrong under a button
  * that could just say what to do next.
  *
- * `cause` is what happened. `hint` is what to do about it. **A surface that shows only the first
+ * `cause` is what happened. `fix` is what to do about it. **A surface that shows only the first
  * half is the dead end this exists to prevent** — which is why the type has two fields and not
- * one, and why `hint` being absent should be a deliberate choice at each call site rather than
+ * one, and why `fix` being absent should be a deliberate choice at each call site rather than
  * the default nobody noticed.
  *
+ * `fix`, and not the `hint` this returned until 0.6.0. `ErrorStateProps` — the contract this same
+ * package ships for the component that renders this — has always called it `fix`, so every
+ * adopter wrote `fix={hint}` at every error surface: a rename adapter, which is the shape of an
+ * API we got wrong. It also clears a collision, because in at least one adopter a form field's
+ * `hint` is the requirement text under the input, which is a different thing entirely.
+ *
  * The per-code switch stays in the product: two donors' switches shared their SHAPE and almost
  * no arms, because the arms are that API's vocabulary. What ships is the scaffolding around it,
  * which is the part that was written twice and got subtly different both times.
  */
 
-export interface DescribedError {
+/**
+ * Which control to offer beside the words.
+ *
+ * The fourth adopter had this and the package did not, which left every adopter re-deriving
+ * "can a second attempt fix this" from its own switch — beside a `shouldRetry` already deciding
+ * exactly that for react-query. Two answers to one question drift, and the drift is visible: a
+ * screen offering "try again" for a refusal the query layer refuses to retry, so the button does
+ * nothing and the reader presses it twice.
+ *
+ * So this is DERIVED from `shouldRetry`, not switched on separately. One rule, two consumers.
+ */
+export type RecoveryKind =
+  /** A second attempt can work. Offer the button. */
+  | "retry"
+  /** Auth said no. Offer a way back to sign-in, never a retry. */
+  | "signin"
+  /** It stated its own expiry. Offer the button, disabled, with the countdown. */
+  | "wait"
+  /** Waiting cannot fix it and neither can pressing anything. Offer no control. */
+  | "none";
+
+/** The copy an arm writes. Everything it leaves out, {@link createErrorDescriber} fills in. */
+export interface ErrorCopy {
   /** What happened, in the reader's words. */
   cause: string;
   /** What to do about it. Its absence should be a decision, not an oversight. */
-  hint?: string;
+  fix?: string;
+  /** Override the derived kind — a 429 whose code means a spent quota is `"none"`, not `"wait"`. */
+  recover?: RecoveryKind;
+  /** Override the request id. Rarely wanted; the envelope's is used by default. */
+  reference?: string;
+}
+
+export interface DescribedError extends ErrorCopy {
+  /** Always present on the way out, whether an arm set it or the rule derived it. */
+  recover: RecoveryKind;
 }
 
 /**
@@ -44,8 +82,16 @@ export type Translate<Key extends string = string> = (
 /** The three names {@link humanizeWait} looks up, under whatever prefix you pass it. */
 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";
+/**
+ * Every name {@link createErrorDescriber} looks up itself. Your catalog carries all of them.
+ *
+ * The three wait names are deliberately NOT here, which is the other half of 0.6.0. This module
+ * used to humanize a stated wait itself, so `waitSeconds`/`waitMinutes`/`waitHours` — each with
+ * an ICU plural — landed in the key union of every adopter's `t` whether or not a wait was ever
+ * rendered. An app that formats waits with `Intl.RelativeTimeFormat` needs none of them and was
+ * left adding six entries per language to satisfy a compiler. `formatWait` owns that now.
+ */
+type CopyName = "network" | "networkHint" | "unexpected" | "retrySoon";
 
 /**
  * The paragraph above, pinned so it cannot quietly stop being true.
@@ -62,9 +108,6 @@ type ClosedCatalog = (
     | "errors.networkHint"
     | "errors.unexpected"
     | "errors.retrySoon"
-    | "errors.waitSeconds"
-    | "errors.waitMinutes"
-    | "errors.waitHours"
     | "serverErrors.quotaDay"
     | "billing.plan",
   params?: Record<string, unknown>,
@@ -82,6 +125,11 @@ type _TypedCatalogNeedsNoCast = Satisfied<
  * not become the less precise "in 1 minute", and 90 minutes rather than 60 for the same reason
  * one rung up. Needs `waitSeconds` / `waitMinutes` / `waitHours` under `prefix`, each with a
  * `count` plural.
+ *
+ * This is what you pass as `formatWait` when your catalog carries those three:
+ * `formatWait: (secs) => humanizeWait(t, secs, "errors.")`. An app that formats a wait with
+ * `Intl.RelativeTimeFormat` passes its own one-liner instead and needs no wait keys at all —
+ * which also gets it correct plurals in languages with more than two forms, for free.
  */
 export function humanizeWait<Prefix extends string>(
   t: Translate<`${Prefix}${WaitName}`>,
@@ -100,6 +148,13 @@ export interface ErrorContext {
   /** Seconds until it clears, already humanized. Null when the envelope did not say. */
   wait: string | null;
   waitSecs: number | null;
+  /**
+   * What the rule decided before this arm ran. Read it to agree, return your own to override.
+   *
+   * Exposed so an arm can narrow rather than restate: a quota arm that already knows the limit is
+   * durable returns `"none"`, and every other arm can leave it alone and stay right by default.
+   */
+  recover: RecoveryKind;
 }
 
 export interface ErrorDescriberOptions<
@@ -110,6 +165,16 @@ export interface ErrorDescriberOptions<
   t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
   /** Catalog namespace for this module's own copy, e.g. `"errors."`. */
   copyPrefix: Prefix;
+  /**
+   * How a stated wait becomes words, for the `wait` an arm reads off its context.
+   *
+   * Required rather than defaulted, because there is no answer that is right for everyone and a
+   * default hid the cost: {@link humanizeWait} reads three ICU plural keys out of your catalog,
+   * and an app that already formats relative time with `Intl` would have had to add them to
+   * compile. Say which you want — `(secs) => humanizeWait(t, secs, "errors.")`, or your own
+   * `(secs) => formatIn(secs, locale)` — and the catalog you need is the one you can see.
+   */
+  formatWait: (secs: number) => string;
   /**
    * The server's own catalog namespace, e.g. `"serverErrors."`. A `messageKey` outside it is
    * ignored — the server names a sentence, it does not get to name any key in the app.
@@ -142,9 +207,17 @@ export interface ErrorDescriberOptions<
    * code that does not exist is a compile error at the arm rather than a branch that never runs.
    */
   codes?: Partial<Record<string, ErrorArm>>;
+  /**
+   * The codes that mean "this limit does not clear by waiting" — **the same list you hand
+   * `queryDefaults`**, because it answers the same question and a second copy is a second
+   * chance to disagree with the retry rule. Declare it once in the app and pass it twice.
+   */
+  durableLimitCodes?: readonly string[];
+  /** Longest stated wait still worth a retry rather than a countdown. Matches `queryDefaults`. */
+  maxRetryWaitSecs?: number;
 }
 
-export type ErrorArm = (ctx: ErrorContext) => DescribedError;
+export type ErrorArm = (ctx: ErrorContext) => ErrorCopy;
 
 /** Build the describer. */
 export function createErrorDescriber<
@@ -154,9 +227,12 @@ export function createErrorDescriber<
 >({
   t,
   copyPrefix,
+  formatWait,
   messageKeyPrefix,
   knownMessageKeys,
   codes = {},
+  durableLimitCodes = [],
+  maxRetryWaitSecs,
 }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
   const known = new Set<string>(Object.keys(knownMessageKeys));
 
@@ -180,24 +256,48 @@ export function createErrorDescriber<
     );
   }
 
+  /**
+   * Which control to offer, decided once and never switched on separately.
+   *
+   * Everything below the last line defers to `shouldRetry` — the rule invariant 8 already owns —
+   * so the button a reader sees and the retry react-query performs cannot disagree.
+   */
+  function recoveryFor(error: ApiError, waitSecs: number | null): RecoveryKind {
+    // The client raised this one itself, to stop a caller while a dead session was already being
+    // handled. Nothing is broken and the person is already on their way to sign-in, so asking
+    // them to try again would be the surface contradicting the thing it is reporting.
+    if (error.expected) return "none";
+    // 401 is "we do not know who you are", which no number of attempts answers. 403 is NOT this:
+    // the session is fine and it is a different account that would help, so it falls through.
+    if (error.status === 401) return "signin";
+    // It named its own expiry, so there is a real number to count down beside a disabled button.
+    if (waitSecs !== null) return "wait";
+    return shouldRetry(error, durableLimitCodes, maxRetryWaitSecs) ? "retry" : "none";
+  }
+
   return function describeError(error: unknown): DescribedError {
     if (!(error instanceof ApiError)) {
       // Not a response at all — the request never landed. Almost always the network, and almost
-      // never worth showing a stack trace for.
-      return { cause: t(`${copyPrefix}network`), hint: t(`${copyPrefix}networkHint`) };
+      // never worth showing a stack trace for. `shouldRetry` answers a non-response the same way,
+      // so these two agree here without either being told about the other.
+      return {
+        cause: t(`${copyPrefix}network`),
+        // The catalog KEY keeps its name while the field becomes `fix`: renaming it would cost
+        // every adopter a JSON edit in every language, for a string no caller ever types.
+        fix: t(`${copyPrefix}networkHint`),
+        recover: "retry",
+      };
     }
 
     const waitSecs = retryAfterSecs(error);
     const ctx: ErrorContext = {
       error,
       says: serverSentence(error),
-      wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
+      wait: waitSecs === null ? null : formatWait(waitSecs),
       waitSecs,
+      recover: recoveryFor(error, waitSecs),
     };
 
-    const arm = error.code === undefined ? undefined : codes[error.code];
-    if (arm) return arm(ctx);
-
     // Anything unmapped: the server's own sentence is still the most specific thing we have,
     // and support can act on it. A 5xx additionally gets "try again shortly", because that one
     // genuinely does clear on its own — a 4xx does not, and saying so would be a lie that costs
@@ -207,10 +307,24 @@ export function createErrorDescriber<
     // own `Request failed (502)`, written for a log. A gateway answering with HTML while the API
     // restarts is exactly when that happens, so it reached screens — until the second migration,
     // whose three apps each guarded against that one string by hand.
-    const serverWords = error.code === undefined ? "" : error.message;
+    const arm = error.code === undefined ? undefined : codes[error.code];
+    const copy: ErrorCopy = arm
+      ? arm(ctx)
+      : {
+          cause:
+            ctx.says ??
+            ((error.code === undefined ? "" : error.message) || t(`${copyPrefix}unexpected`)),
+          fix: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+        };
+
+    // The arm wins where it spoke, the rule fills the rest. `requestId` is the one thing every
+    // error surface asks for and nothing was producing — `ErrorStateProps` has reserved a
+    // `reference` slot for it since the contract was written.
+    const reference = copy.reference ?? error.requestId;
     return {
-      cause: ctx.says ?? (serverWords || t(`${copyPrefix}unexpected`)),
-      hint: error.status >= 500 ? t(`${copyPrefix}retrySoon`) : undefined,
+      ...copy,
+      recover: copy.recover ?? ctx.recover,
+      ...(reference !== undefined && { reference }),
     };
   };
 }

package/src/index.ts

@@ -53,7 +53,9 @@ export {
   type DescribedError,
   type ErrorArm,
   type ErrorContext,
+  type ErrorCopy,
   type ErrorDescriberOptions,
+  type RecoveryKind,
   type Translate,
 } from "./describe-error.ts";