@remit/web-client 0.0.173 → 0.0.175

package/src/hooks/useStaleAccountSync.test.ts

@@ -221,6 +221,21 @@ describe("handleBackgroundSyncFailure", () => {
 		assert.equal(escalated, false);
 	});
 
+	test("a 401 on the background probe does NOT escalate", () => {
+		silenceWarn();
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+
+		// The probe fires on mount and nobody is waiting on it. Escalating its
+		// 401 would put the full-screen page up on load for a lapsed session,
+		// ahead of the sign-in the shell is already about to ask for.
+		handleBackgroundSyncFailure("a-1", new ApiError("signed out", 401));
+
+		assert.equal(escalated, false);
+	});
+
 	test("a network blip on the background probe does NOT escalate", () => {
 		silenceWarn();
 		let escalated = false;

package/src/hooks/useStaleAccountSync.ts

@@ -140,13 +140,17 @@ export const __peekStaleAccountSyncGuard = (): ReadonlySet<string> =>
  * per-account guard so a later remount can retry, then log and move on. But a
  * 5xx is OUR API broken, and per the contract (#1059) that always escalates to
  * the full-screen overlay — even from a background trigger.
+ *
+ * Nobody is waiting on this one. It fires on mount, so escalating its 401 would
+ * put the full-screen page up on load for anyone whose session had lapsed,
+ * ahead of the sign-in the shell is already about to ask for.
  */
 export const handleBackgroundSyncFailure = (
 	accountId: string,
 	error: unknown,
 ): void => {
 	triggeredAccountIds.delete(accountId);
-	if (shouldEscalate(error, { softError: true })) {
+	if (shouldEscalate(error, { softError: true }, "nobody")) {
 		reportFatalError(error);
 		return;
 	}

package/src/lib/error-classifier.test.ts

@@ -278,4 +278,50 @@ describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
 		assert.equal(shouldEscalate(bug), true);
 		assert.equal(shouldEscalate(bug, { softError: true }), true);
 	});
+
+	it("escalates a 401 on a write EVEN when the call site marked it soft (rule 4 wins)", () => {
+		assert.equal(
+			shouldEscalate(
+				new ApiError("signed out", 401),
+				{ softError: true },
+				"user",
+			),
+			true,
+			"a dismissible banner leaves the user signed out with no way back in",
+		);
+	});
+
+	it("leaves a soft 401 soft when nobody is waiting on the answer", () => {
+		assert.equal(
+			shouldEscalate(
+				new ApiError("signed out", 401),
+				{ softError: true },
+				"nobody",
+			),
+			false,
+			"a background poll's 401 must not put the fatal page over the whole app",
+		);
+	});
+
+	it("defaults to nobody waiting, so an unstated call site keeps a soft 401 soft", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("signed out", 401), { softError: true }),
+			false,
+		);
+	});
+
+	it("escalates a 401 on a read that never opted out", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("signed out", 401), undefined, "nobody"),
+			true,
+			"a read with no softError escalates on the default, waiting or not",
+		);
+	});
+
+	it("leaves a soft 403 soft — the call site can state that refusal in place", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("not yours", 403), { softError: true }),
+			false,
+		);
+	});
 });

package/src/lib/error-classifier.ts

@@ -101,6 +101,37 @@ export const isClientBug = (error: unknown): boolean =>
 export const isAlwaysFatal = (error: unknown): boolean =>
 	isServerError(error) || isClientBug(error);
 
+/**
+ * The session is gone. Not 403: a handler answers 403 for a resource belonging
+ * to another account config, which is a refusal a call site can state where it
+ * stands. A 401 is the user signed out from under whatever they were doing.
+ */
+export const isUnauthenticated = (error: unknown): boolean =>
+	getErrorStatus(error) === 401;
+
+/**
+ * Who is waiting on this request's answer. One decision turns on it, and only
+ * one: whether a 401 overrides the call site's own `meta.softError`.
+ *
+ * "user" — the user did something and the app owes them the outcome. Every
+ * mutation is this, the debounced autosave included: it carries text that is on
+ * screen, and if it is refused for want of a session then so is the send behind
+ * it. No banner a call site can render signs anyone back in, so this is the one
+ * 4xx a call site may not keep to itself.
+ *
+ * "nobody" — a poll, a prefetch, a best-effort background trigger, an inline
+ * sub-resource with an error surface of its own. A 401 there is not news the
+ * app may take the whole screen for, and `meta.softError` decides as usual.
+ *
+ * Reads are "nobody" as a class, which is not the same as saying no read
+ * matters: a read the screen is actually waiting on has no `meta.softError` on
+ * it, so rule 1 escalates it anyway. The only reads this spares are the ones
+ * that already declared they own their failures — the update poll mounted at
+ * the app root, the message body with its own inline banner. Escalating those
+ * put the full-screen page over every screen in the app.
+ */
+export type Awaiting = "user" | "nobody";
+
 const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 	meta?.softError === true;
 
@@ -115,7 +146,12 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
  *     answered "I'm broken"; that is never benign.
  *  3. A client-side exception ALWAYS escalates, on the same terms. It is our
  *     bug; there is nothing for the user to retry and nothing to dismiss.
- *  4. The ONLY soft (do-NOT-escalate) exemptions:
+ *  4. A 401 on a request the user is waiting on ALWAYS escalates, on the same
+ *     terms. Dismissing it leaves them signed out with no way back in, and a
+ *     send that keeps failing becomes a loop with no exit — `BetterAuthShell`
+ *     re-gates only when `useSession()` revalidates, which a banner never makes
+ *     happen. See `Awaiting` for what nobody waiting on it means.
+ *  5. The ONLY soft (do-NOT-escalate) exemptions:
  *     a. aborts / cancellations — never a failure;
  *     b. network/offline errors — environmental, recovered by React Query's
  *        reconnect/retry;
@@ -126,11 +162,29 @@ const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
 export const shouldEscalate = (
 	error: unknown,
 	meta?: Record<string, unknown>,
+	awaiting: Awaiting = "nobody",
 ): boolean => {
 	if (isServerError(error)) return true;
 	if (isAbortError(error)) return false;
 	if (isNetworkError(error)) return false;
+	if (awaiting === "user" && isUnauthenticated(error)) return true;
 	if (isAlwaysFatal(error)) return true;
 	if (isSoftErrorMeta(meta)) return false;
 	return true;
 };
+
+/**
+ * The meta a call site sets to keep its own non-5xx failures off the
+ * full-screen fatal page, because it renders them itself — a banner, a retry,
+ * an empty state. Rules 2, 3 and 4 above still win: a 5xx, a client-side
+ * exception, and a 401 on something the user is waiting on, escalate regardless.
+ *
+ * Two classes of call site must always carry it. One is a request the user
+ * never asked for and is not waiting on — a debounced autosave, a
+ * dwell-triggered mark-as-read: a refusal there is not news worth stopping the
+ * app for. The other is any surface holding text the user has not finished
+ * writing. The fatal page unmounts the app, so escalating from a composer
+ * throws the message away and leaves nothing to retry, which is a worse outcome
+ * than the failure it reports.
+ */
+export const softErrorMeta: { softError: true } = { softError: true };

package/src/lib/query-error-handler.ts

@@ -10,6 +10,13 @@ import { reportFatalError } from "./fatal-error";
  * statusless network blips, and non-5xx errors a call site opted out of via
  * `meta.softError` stay soft.
  *
+ * The two caches differ on one thing, the `Awaiting` argument. A mutation is
+ * something the user did and is owed the outcome of, so a 401 there escalates
+ * over `meta.softError` — no banner signs anyone back in. A query is "nobody" as
+ * a class: the reads the screen is actually waiting on carry no `meta.softError`
+ * and escalate on the default anyway, so the only ones this spares are those
+ * that already declared they own their failures.
+ *
  * This is the v5 equivalent of `defaultOptions.queries.onError` /
  * `.mutations.onError` — v5 moved the global error hook onto the caches.
  */
@@ -17,7 +24,7 @@ export const handleQueryCacheError = (
 	error: Error,
 	query: Query<unknown, unknown, unknown>,
 ): void => {
-	if (shouldEscalate(error, query.meta)) {
+	if (shouldEscalate(error, query.meta, "nobody")) {
 		reportFatalError(error);
 	}
 };
@@ -28,7 +35,7 @@ export const handleMutationCacheError = (
 	_onMutateResult: unknown,
 	mutation: Mutation<unknown, unknown, unknown>,
 ): void => {
-	if (shouldEscalate(error, mutation.meta)) {
+	if (shouldEscalate(error, mutation.meta, "user")) {
 		reportFatalError(error);
 	}
 };