@remit/web-client 0.0.13 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/auth/better-auth-config.ts

@@ -1,4 +1,5 @@
 import { createAuthClient } from "better-auth/react";
+import { taggedFetch } from "../lib/network-error";
 import { getRuntimeConfig } from "../runtime-config";
 
 /**
@@ -51,7 +52,9 @@ const decodeExp = (token: string): number => {
 };
 
 const requestToken = async (): Promise<string | null> => {
-	const res = await fetch("/api/auth/token", { credentials: "include" });
+	const res = await taggedFetch("/api/auth/token", {
+		credentials: "include",
+	});
 	if (!res.ok) return null;
 	const body: unknown = await res.json();
 	if (

package/src/components/compose/ComposeForm.tsx

@@ -419,6 +419,7 @@ export const ComposeForm = ({
 		pushError({
 			title: "Couldn't save draft",
 			detail: formatErrorDetail(saveError) ?? "Saving the draft failed.",
+			error: saveError,
 		});
 	}, [saveError, pushError]);
 
@@ -541,6 +542,7 @@ export const ComposeForm = ({
 					pushError({
 						title: "Couldn't send message",
 						detail: formatErrorDetail(error) ?? "Saving the draft failed.",
+						error,
 					});
 					return null;
 				});
@@ -562,6 +564,7 @@ export const ComposeForm = ({
 						(createdThisAttempt
 							? "The draft was saved but the send request failed. Try again from the Outbox."
 							: "The send request failed. Try again."),
+					error,
 				});
 				return null;
 			});

package/src/components/mail/IntelligencePane.tsx

@@ -313,15 +313,17 @@ function WiredPanel({
 		[updateFlags],
 	);
 
-	// Per-sender flag toggles are always wired. They stay active even before the
-	// address record resolves: `updateFlags` surfaces feedback when `addressId`
-	// is missing rather than letting the button look active but do nothing.
+	// Every per-sender flag toggle PATCHes the sender's address row, so none of
+	// them can be serviced until that row resolves. Leave them unwired until it
+	// does: the panel renders an unwired quick action as disabled, so the flow is
+	// never reachable in a state where a click can only fail (issue #51).
+	const canUpdateFlags = addressId !== undefined;
 	const actions: IntelligenceQuickActions = {
-		onToggleVip: handleToggleVip,
-		onToggleMute: handleToggleMute,
-		onToggleBlock: handleToggleBlock,
-		onToggleUnsubscribe: handleToggleUnsubscribe,
-		onReclassify: () => setReclassifyOpen(true),
+		onToggleVip: canUpdateFlags ? handleToggleVip : undefined,
+		onToggleMute: canUpdateFlags ? handleToggleMute : undefined,
+		onToggleBlock: canUpdateFlags ? handleToggleBlock : undefined,
+		onToggleUnsubscribe: canUpdateFlags ? handleToggleUnsubscribe : undefined,
+		onReclassify: canUpdateFlags ? () => setReclassifyOpen(true) : undefined,
 		onNotSpam: spamAction === "notSpam" ? handleNotSpam : undefined,
 		onMarkSpam: spamAction === "markSpam" ? handleMarkSpam : undefined,
 	};

package/src/components/mail/MessageActionMenu.tsx

@@ -27,6 +27,7 @@ import { formatErrorDetail } from "@/components/ui/error-banners";
 import { useDeleteMessages } from "@/hooks/useDeleteMessages";
 import { useMoveMessages } from "@/hooks/useMoveMessages";
 import { useToggleTrusted } from "@/hooks/useToggleTrusted";
+import { patchThreadListCache, type ThreadListCache } from "@/lib/thread-cache";
 import { MoveToTrigger } from "./MoveToTrigger";
 
 interface ThreadMessagesData {
@@ -34,15 +35,12 @@ interface ThreadMessagesData {
 	[key: string]: unknown;
 }
 
-interface ThreadsListPage {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface ThreadsListData {
-	pages: ThreadsListPage[];
-	pageParams: Array<string | undefined>;
-}
+/**
+ * Either shape a thread list/search query caches — the infinite mailbox list
+ * or a single-shot page. `setQueriesData` matches by key prefix, so the
+ * optimistic updater sees both.
+ */
+type ThreadsListData = ThreadListCache;
 
 interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
@@ -169,26 +167,20 @@ export const MessageActionMenu = ({
 				},
 			);
 
-			const patchListData = (old: ThreadsListData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					pages: old.pages.map((page) => ({
-						...page,
-						items: page.items.map((item) =>
-							targetIds.has(item.messageId)
-								? { ...item, isRead: isReadNext }
-								: item,
-						),
-					})),
-				};
-			};
+			const patchListData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					items.map((item) =>
+						targetIds.has(item.messageId)
+							? { ...item, isRead: isReadNext }
+							: item,
+					),
+				);
 
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsListPrefix },
 				patchListData,
 			);
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsSearchPrefix },
 				patchListData,
 			);
@@ -214,6 +206,7 @@ export const MessageActionMenu = ({
 			pushError({
 				title: isReadNext ? "Couldn't mark as read" : "Couldn't mark as unread",
 				detail: formatErrorDetail(err),
+				error: err,
 			});
 		},
 		onSettled: (_data, _err, _vars, context) => {

package/src/components/mail/MessageDetail.tsx

@@ -74,6 +74,7 @@ export const MessageDetail = ({ messageId }: MessageDetailProps) => {
 			pushError({
 				title: "Couldn't mark message as read",
 				detail: formatErrorDetail(error),
+				error,
 			});
 		},
 	});

package/src/components/ui/ErrorBanner.tsx

@@ -15,12 +15,12 @@ const SEVERITY_STYLES: Record<
 	{ container: string; icon: string; title: string }
 > = {
 	error: {
-		container: "border-danger/50 bg-danger/10 dark:bg-danger/20",
+		container: "border-danger/50 bg-danger-soft",
 		icon: "text-danger",
 		title: "text-danger",
 	},
 	warning: {
-		container: "border-warning/50 bg-warning/10",
+		container: "border-warning/50 bg-warning-soft",
 		icon: "text-warning",
 		title: "text-warning",
 	},
@@ -61,7 +61,10 @@ export const ErrorBanner = ({
 			role={severity === "error" ? "alert" : "status"}
 			aria-live={severity === "error" ? "assertive" : "polite"}
 			className={cn(
-				"pointer-events-auto flex items-start gap-3 rounded-md border bg-canvas/80 px-3 py-2 shadow-md backdrop-blur",
+				// Opaque, not translucent: a banner overlaps the toolbar and the
+				// message list, and see-through text on top of see-through text is
+				// unreadable (issue #55).
+				"pointer-events-auto flex items-start gap-3 rounded-md border bg-canvas px-3 py-2 shadow-lg",
 				styles.container,
 			)}
 		>

package/src/components/ui/ErrorBannerProvider.render.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ApiError } from "@/lib/api";
+import { __resetFatalError, getCurrentFatalError } from "@/lib/fatal-error";
+import { ErrorBannerProvider, useErrorBanners } from "./ErrorBannerProvider";
+import type { PushErrorInput } from "./error-banners";
+
+/**
+ * Push one error through the real provider and report where it went. The
+ * routing decision happens inside `pushError`, so a single render is enough:
+ * either a fatal was recorded, or the error stayed a soft banner.
+ */
+const push = (input: PushErrorInput): { escalated: boolean } => {
+	const Pusher = () => {
+		useErrorBanners().pushError(input);
+		return null;
+	};
+	renderToString(
+		createElement(ErrorBannerProvider, null, createElement(Pusher)) as never,
+	);
+	return { escalated: getCurrentFatalError() !== null };
+};
+
+afterEach(() => {
+	__resetFatalError();
+});
+
+describe("pushError — a banner is a soft surface only", () => {
+	it("keeps a soft failure with no error attached in a banner", () => {
+		assert.equal(push({ title: "Couldn't save draft" }).escalated, false);
+	});
+
+	it("treats an absent error as absent, not as a bug", () => {
+		// A caller forwarding an optional error it does not have passes
+		// `undefined`. That is "nothing went wrong that we can classify", not a
+		// client-side exception, and must not take over the screen.
+		assert.equal(
+			push({ title: "Couldn't save draft", error: undefined }).escalated,
+			false,
+		);
+		assert.equal(
+			push({ title: "Couldn't save draft", error: null }).escalated,
+			false,
+		);
+	});
+
+	it("keeps a 4xx the call site owns in a banner", () => {
+		assert.equal(
+			push({
+				title: "Couldn't move this message",
+				error: new ApiError("Not found", 404),
+			}).escalated,
+			false,
+		);
+	});
+
+	it("escalates a 5xx to the fatal page instead of a toast", () => {
+		assert.equal(
+			push({
+				title: "Couldn't move 339 messages",
+				error: new ApiError("Internal error", 500),
+			}).escalated,
+			true,
+		);
+		assert.equal(getCurrentFatalError()?.message, "Internal error");
+	});
+
+	it("escalates an exception thrown by our own code (issue #55)", () => {
+		const bug = new TypeError(
+			'can\'t access property "map", N.pages is undefined',
+		);
+		assert.equal(
+			push({ title: "Couldn't move 339 messages", error: bug }).escalated,
+			true,
+		);
+		assert.equal(getCurrentFatalError()?.message, bug.message);
+		assert.equal(
+			getCurrentFatalError()?.recoverable,
+			false,
+			"a bug is not something the user can retry away",
+		);
+	});
+});

package/src/components/ui/ErrorBannerProvider.tsx

@@ -6,6 +6,8 @@ import {
 	useMemo,
 	useState,
 } from "react";
+import { isAlwaysFatal } from "@/lib/error-classifier";
+import { reportFatalError } from "@/lib/fatal-error";
 import { ErrorBannerStack } from "./ErrorBannerStack.js";
 import {
 	appendBanner,
@@ -39,7 +41,23 @@ const generateId = (): string => {
 export const ErrorBannerProvider = ({ children }: { children: ReactNode }) => {
 	const [errors, setErrors] = useState<ErrorBannerEntry[]>([]);
 
+	/**
+	 * Show a soft, dismissible banner — and only that. A fatal error is not a
+	 * notification: when the caller hands us a 5xx or an exception from our own
+	 * code, it goes to the fatal seam instead, so the user gets the full-screen
+	 * page with a way forward and a bug report rather than a toast they can only
+	 * dismiss (issue #55). Those two classes are fatal with no opt-out; anything
+	 * a call site can legitimately own — a 404 empty state, a 4xx the user can
+	 * act on — still banners here.
+	 *
+	 * The guard is on the error being present, not on the key being present:
+	 * `error` is optional, so a caller forwarding one it does not have passes
+	 * `undefined`, and "no error at all" must not be classified as a bug.
+	 */
 	const pushError = useCallback((input: PushErrorInput): string => {
+		if (input.error != null && isAlwaysFatal(input.error)) {
+			return reportFatalError(input.error).correlationId;
+		}
 		const entry = buildEntry(input, generateId(), Date.now());
 		setErrors((current) => appendBanner(current, entry));
 		return entry.id;

package/src/components/ui/error-banners.ts

@@ -12,6 +12,14 @@ export interface PushErrorInput {
 	severity?: ErrorBannerSeverity;
 	title: string;
 	detail?: string;
+	/**
+	 * The error being reported, when there is one. Pass it: a banner is a soft
+	 * surface, and `pushError` uses this to refuse errors that are not soft —
+	 * a 5xx or a client-side exception is escalated to the full-screen fatal
+	 * page (which offers Retry, a way out, and a bug report) instead of being
+	 * reduced to a dismissible toast.
+	 */
+	error?: unknown;
 }
 
 const MAX_BANNERS = 5;
@@ -30,6 +38,7 @@ export const buildMutationErrorBanner = (
 ): PushErrorInput => ({
 	title,
 	detail: formatErrorDetail(error) ?? fallback,
+	error,
 });
 
 export const formatErrorDetail = (error: unknown): string | undefined => {

package/src/hooks/useDeleteMessages.ts

@@ -10,6 +10,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
+import { patchThreadListCache, type ThreadListCache } from "@/lib/thread-cache";
 
 interface UseDeleteMessagesOptions {
 	mailboxId: string;
@@ -28,15 +29,12 @@ interface ThreadMessagesData {
 	[key: string]: unknown;
 }
 
-interface ThreadsListPage {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface ThreadsListData {
-	pages: ThreadsListPage[];
-	pageParams: Array<string | undefined>;
-}
+/**
+ * Either shape a thread list/search query caches — the infinite mailbox list
+ * or a single-shot page. `setQueriesData` matches by key prefix, so the
+ * optimistic updater sees both.
+ */
+type ThreadsListData = ThreadListCache;
 
 interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
@@ -147,22 +145,16 @@ export const useDeleteMessages = ({
 				);
 			}
 
-			const patchListData = (old: ThreadsListData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					pages: old.pages.map((page) => ({
-						...page,
-						items: removeMessagesFromItems(page.items, messageIds),
-					})),
-				};
-			};
+			const patchListData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					removeMessagesFromItems(items, messageIds),
+				);
 
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsListPrefix },
 				patchListData,
 			);
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsSearchPrefix },
 				patchListData,
 			);
@@ -193,6 +185,7 @@ export const useDeleteMessages = ({
 						? `Couldn't delete ${count} messages`
 						: "Couldn't delete this message",
 				detail: formatErrorDetail(err),
+				error: err,
 			});
 		},
 		onSettled: (_data, _err, _vars, context) => {

package/src/hooks/useIntelligenceData.ts

@@ -18,6 +18,10 @@ import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
 import { isServerError } from "@/lib/error-classifier";
 import { formatDate, formatEmailDate } from "@/lib/format";
+import {
+	pickSenderAddress,
+	senderAddressSearchQuery,
+} from "@/lib/sender-address";
 
 /**
  * Format a creation timestamp as a human-readable "first seen" label.
@@ -180,7 +184,11 @@ export interface UseIntelligenceDataResult {
 	 * that misrepresents the sender's real state. Escalation covers it.
 	 */
 	addressErrorIsFatal: boolean;
-	/** Address id for the sender — needed for PATCH /addresses/{id} mutations. */
+	/**
+	 * Address id for the sender — needed for PATCH /addresses/{id} mutations.
+	 * `undefined` until the lookup resolves the row for exactly this address;
+	 * quick actions that PATCH it must stay unwired until then.
+	 */
 	addressId: string | undefined;
 	/**
 	 * Raw address response for the sender — forwarded to the quick-action
@@ -209,13 +217,16 @@ export function useIntelligenceData(
 	// --- Address lookup: flags + first-seen timestamp ---
 	const { data: addressSearchResult, error: addressError } = useQuery({
 		...addressOperationsSearchAddressesOptions({
-			query: { q: senderEmail ?? "", limit: 1 },
+			query: senderAddressSearchQuery(senderEmail ?? undefined),
 		}),
 		enabled: Boolean(senderEmail),
 		staleTime: 30_000,
 	});
 
-	const address = addressSearchResult?.items?.[0];
+	const address = pickSenderAddress(
+		addressSearchResult?.items,
+		senderEmail ?? undefined,
+	);
 
 	// --- Semantic search: similar messages ---
 	const semanticQuery = [subject, senderEmail].filter(Boolean).join(" ");

package/src/hooks/useMarkAsRead.ts

@@ -10,6 +10,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
+import { patchThreadListCache, type ThreadListCache } from "@/lib/thread-cache";
 
 interface UseMarkAsReadOptions {
 	messages: RemitImapThreadMessageResponse[];
@@ -24,15 +25,12 @@ interface ThreadMessagesData {
 	[key: string]: unknown;
 }
 
-interface ThreadsListPage {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface ThreadsListData {
-	pages: ThreadsListPage[];
-	pageParams: Array<string | undefined>;
-}
+/**
+ * Either shape a thread list/search query caches — the infinite mailbox list
+ * or a single-shot page. `setQueriesData` matches by key prefix, so the
+ * optimistic updater sees both.
+ */
+type ThreadsListData = ThreadListCache;
 
 interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
@@ -178,25 +176,16 @@ export const useMarkAsRead = ({
 				},
 			);
 
-			const patchListData = (old: ThreadsListData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					pages: old.pages.map((page) => ({
-						...page,
-						items: setReadOnItems(page.items, messageIds, isRead),
-					})),
-				};
-			};
+			const patchListData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					setReadOnItems(items, messageIds, isRead),
+				);
 
 			for (const queryKey of [
 				...threadsListPrefixes,
 				...threadsSearchPrefixes,
 			]) {
-				queryClient.setQueriesData<ThreadsListData>(
-					{ queryKey },
-					patchListData,
-				);
+				queryClient.setQueriesData({ queryKey }, patchListData);
 			}
 
 			return {
@@ -231,6 +220,7 @@ export const useMarkAsRead = ({
 			pushError({
 				title: isRead ? "Couldn't mark as read" : "Couldn't mark as unread",
 				detail: formatErrorDetail(error),
+				error,
 			});
 		},
 		onSettled: (_data, _err, _vars, context) => {
@@ -321,6 +311,7 @@ export const useToggleReadFor = (options: {
 			pushError({
 				title: isRead ? "Couldn't mark as read" : "Couldn't mark as unread",
 				detail: formatErrorDetail(error),
+				error,
 			});
 		},
 		onSettled: () => {

package/src/hooks/useMessageBodyContent.ts

@@ -7,6 +7,7 @@ import {
 	pickRenderablePart,
 	type RenderableBodyPart,
 } from "@/lib/message-body-source";
+import { taggedFetch } from "@/lib/network-error";
 import { useTelemetry } from "@/lib/telemetry-context";
 import { messageKeys } from "./queries/keys";
 
@@ -186,7 +187,7 @@ export const fetchBodyContent = async (
 	const headers: Record<string, string> = {};
 	const token = await getToken();
 	if (token) headers.Authorization = `Bearer ${token}`;
-	const response = await fetch(url, { headers });
+	const response = await taggedFetch(url, { headers });
 	// 202 = the body is not synced yet. The content route has re-armed the sync
 	// cue; retry after `Retry-After` seconds rather than rendering the placeholder
 	// body (a 202 is `ok`, so this must be caught before the success path).

package/src/hooks/useMoveMessages.ts

@@ -10,6 +10,7 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback } from "react";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
+import { patchThreadListCache, type ThreadListCache } from "@/lib/thread-cache";
 
 interface UseMoveMessagesOptions {
 	mailboxId: string;
@@ -28,15 +29,12 @@ interface ThreadMessagesData {
 	[key: string]: unknown;
 }
 
-interface ThreadsListPage {
-	items: RemitImapThreadMessageResponse[];
-	[key: string]: unknown;
-}
-
-interface ThreadsListData {
-	pages: ThreadsListPage[];
-	pageParams: Array<string | undefined>;
-}
+/**
+ * Either shape a thread list/search query caches — the infinite mailbox list
+ * or a single-shot page. `setQueriesData` matches by key prefix, so the
+ * optimistic updater sees both.
+ */
+type ThreadsListData = ThreadListCache;
 
 interface SnapshotEntry<T> {
 	queryKey: readonly unknown[];
@@ -142,22 +140,16 @@ export const useMoveMessages = ({
 				);
 			}
 
-			const patchListData = (old: ThreadsListData | undefined) => {
-				if (!old) return old;
-				return {
-					...old,
-					pages: old.pages.map((page) => ({
-						...page,
-						items: removeMovedMessagesFromItems(page.items, messageIds),
-					})),
-				};
-			};
+			const patchListData = (old: unknown) =>
+				patchThreadListCache(old, (items) =>
+					removeMovedMessagesFromItems(items, messageIds),
+				);
 
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsListPrefix },
 				patchListData,
 			);
-			queryClient.setQueriesData<ThreadsListData>(
+			queryClient.setQueriesData(
 				{ queryKey: threadsSearchPrefix },
 				patchListData,
 			);
@@ -188,6 +180,7 @@ export const useMoveMessages = ({
 						? `Couldn't move ${count} messages`
 						: "Couldn't move this message",
 				detail: formatErrorDetail(err),
+				error: err,
 			});
 		},
 		onSettled: (_data, _err, _vars, context) => {

package/src/hooks/useStaleAccountSync.test.ts

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { afterEach, describe, test } from "node:test";
 import { ApiError } from "../lib/api.js";
 import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error.js";
+import { NetworkError } from "../lib/network-error.js";
 import {
 	__peekStaleAccountSyncGuard,
 	__resetStaleAccountSyncGuard,
@@ -227,11 +228,31 @@ describe("handleBackgroundSyncFailure", () => {
 			escalated = true;
 		});
 
-		handleBackgroundSyncFailure("a-1", new TypeError("Failed to fetch"));
+		// The probe goes through the generated client, so a real transport
+		// failure arrives tagged by the fetch boundary.
+		handleBackgroundSyncFailure(
+			"a-1",
+			new NetworkError(new TypeError("Failed to fetch")),
+		);
 
 		assert.equal(escalated, false);
 	});
 
+	test("an exception from our own code on the probe DOES escalate", () => {
+		silenceWarn();
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+
+		// Untagged and statusless: nothing said this came off the wire, so it is
+		// our bug, and a silent background probe is exactly where one would
+		// otherwise go unnoticed.
+		handleBackgroundSyncFailure("a-1", new TypeError("x is not a function"));
+
+		assert.equal(escalated, true);
+	});
+
 	test("drops the per-account guard so a later remount can retry", () => {
 		silenceWarn();
 		__peekStaleAccountSyncGuard(); // touch to ensure import is used