@gusnips/react 0.5.2 → 0.5.3

package/README.md

@@ -152,7 +152,18 @@ 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, hint, recover, reference } = describeError(error);
+// recover: "retry" | "signin" | "wait" | "none"
+```
+
+`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.
 
 ## Also here
 

package/dist/describe-error.d.ts

@@ -17,11 +17,40 @@ import { ApiError } from "./api-error.ts";
  * 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;
+    /** 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.
@@ -54,6 +83,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<Prefix extends string, ServerPrefix extends string, ServerName extends string> {
     t: Translate<`${Prefix}${CopyName}` | `${ServerPrefix}${ServerName}`>;
@@ -91,9 +127,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, 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.
  *
@@ -15,7 +16,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, 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,11 +35,37 @@ 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`),
+                hint: t(`${copyPrefix}networkHint`),
+                recover: "retry",
+            };
         }
         const waitSecs = retryAfterSecs(error);
         const ctx = {
@@ -46,10 +73,8 @@ export function createErrorDescriber({ t, copyPrefix, messageKeyPrefix, knownMes
             says: serverSentence(error),
             wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
             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 +84,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`)),
+                hint: 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.5.3",
   "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>) =>
@@ -94,6 +95,86 @@ describe("createErrorDescriber", () => {
   });
 });
 
+/**
+ * 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"],
+  });
+
+  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.",
+      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");
+  });
+});
+
 /**
  * The second convention in the fleet: an API with no `messageKey` field at all, whose CODE
  * names the sentence. One repo has 98 of them — `errors.FORECAST_NOT_FOUND` and its siblings —

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.
@@ -19,11 +20,42 @@ import { ApiError, retryAfterSecs } from "./api-error.ts";
  * 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;
+  /** 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;
 }
 
 /**
@@ -100,6 +132,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<
@@ -142,9 +181,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<
@@ -157,6 +204,8 @@ export function createErrorDescriber<
   messageKeyPrefix,
   knownMessageKeys,
   codes = {},
+  durableLimitCodes = [],
+  maxRetryWaitSecs,
 }: ErrorDescriberOptions<Prefix, ServerPrefix, ServerName>): (error: unknown) => DescribedError {
   const known = new Set<string>(Object.keys(knownMessageKeys));
 
@@ -180,11 +229,35 @@ 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`),
+        hint: t(`${copyPrefix}networkHint`),
+        recover: "retry",
+      };
     }
 
     const waitSecs = retryAfterSecs(error);
@@ -193,11 +266,9 @@ export function createErrorDescriber<
       says: serverSentence(error),
       wait: waitSecs === null ? null : humanizeWait(t, waitSecs, copyPrefix),
       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 +278,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`)),
+          hint: 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";