@remit/web-client 0.0.12 → 0.0.14

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/useComposeTarget.ts

@@ -0,0 +1,92 @@
+/**
+ * Where a global compose has to land.
+ *
+ * The compose surface (`FullCompose`) is mounted by the mailbox route only, so
+ * compose started from anywhere else — the daily brief, flagged, outbox — has
+ * to carry the user to a mailbox first. The target is the first account's
+ * inbox, falling back to its first mailbox.
+ *
+ * Both compose entry points use this: the top bar's button on desktop and the
+ * mobile `ComposeFab`. One resolver, so the two surfaces cannot disagree about
+ * which routes host the compose surface.
+ */
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { startTransition, useCallback } from "react";
+import { useCompose } from "@/components/compose/ComposeProvider";
+import { hostsComposeSurface } from "@/lib/compose-routes";
+import { buildMailboxRoleMap } from "@/lib/folder-roles";
+
+/**
+ * The mailbox id a global compose should navigate to, or undefined if none is
+ * known yet.
+ *
+ * Accounts resolve in order and an account whose mailbox query is still in
+ * flight blocks rather than being skipped: skipping hands back a later
+ * account's inbox and then silently swaps the target once the earlier query
+ * settles.
+ */
+export function useComposeTargetMailboxId(
+	accounts: RemitImapAccountResponse[],
+): string | undefined {
+	const mailboxQueries = useQueries({
+		queries: accounts.map((account) => ({
+			...mailboxOperationsListMailboxesOptions({
+				path: { accountId: account.accountId },
+			}),
+			staleTime: Infinity,
+		})),
+	});
+
+	for (const [index, account] of accounts.entries()) {
+		const query = mailboxQueries[index];
+		if (!query || query.isPending) return undefined;
+		const mailboxes = query.data?.items ?? [];
+		if (mailboxes.length === 0) continue;
+		const roleMap = buildMailboxRoleMap(account.folderAppointments);
+		const inbox = mailboxes.find(
+			(mailbox) => roleMap.get(mailbox.mailboxId) === "inbox",
+		);
+		return (inbox ?? mailboxes[0])?.mailboxId;
+	}
+	return undefined;
+}
+
+/**
+ * A compose action that works from every view: opens compose in place when the
+ * current route already hosts the surface, otherwise navigates to the target
+ * mailbox — compose state lives in `ComposeProvider` (mounted at the root), so
+ * it survives the transition and the destination mounts straight into it.
+ *
+ * With no target resolved yet — a cold load whose mailbox queries have not
+ * settled, or accounts with no mailboxes — the action does nothing. Opening
+ * compose state first would leave it open with nothing rendering it, and it
+ * would then pop up unprompted on the next navigation.
+ */
+export function useGlobalCompose(
+	accounts: RemitImapAccountResponse[],
+): () => void {
+	const { openCompose } = useCompose();
+	const navigate = useNavigate();
+	const location = useLocation();
+	const targetMailboxId = useComposeTargetMailboxId(accounts);
+
+	return useCallback(() => {
+		if (hostsComposeSurface(location.pathname)) {
+			startTransition(() => {
+				openCompose({ mode: "new" });
+			});
+			return;
+		}
+		if (!targetMailboxId) return;
+		startTransition(() => {
+			openCompose({ mode: "new" });
+		});
+		navigate({
+			to: "/mail/$mailboxId",
+			params: { mailboxId: targetMailboxId },
+		});
+	}, [openCompose, navigate, location.pathname, targetMailboxId]);
+}

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/useLayoutTier.test.ts

@@ -45,3 +45,29 @@ describe("isSinglePaneTier — compose surface must mount below desktop", () =>
 		assert.equal(isSinglePaneTier(resolveLayoutTier(1024)), false);
 	});
 });
+
+describe("exactly one search field is mounted at every width", () => {
+	// Two call sites decide this from the same tier: `mail.tsx` mounts the top
+	// bar's field when the layout is not single-pane, and `MailListHeader`
+	// passes `showSearch` to keep the header's field otherwise. Both read
+	// `isSinglePaneTier`, so they are each other's complement by construction —
+	// if either is rewritten to its own expression this fails. Two mounted
+	// fields compete for "/" and for focus (#59); zero leaves no way to search.
+	const mountsTopBarField = (width: number): boolean =>
+		!isSinglePaneTier(resolveLayoutTier(width));
+	const mountsHeaderField = (width: number): boolean =>
+		isSinglePaneTier(resolveLayoutTier(width));
+
+	for (const width of [0, 390, 767, 768, 1023, 1024, 1440]) {
+		it(`mounts one field at ${width}px`, () => {
+			const fields =
+				Number(mountsTopBarField(width)) + Number(mountsHeaderField(width));
+			assert.equal(fields, 1, `${width}px mounts ${fields} search fields`);
+		});
+	}
+
+	it("puts the field in the top bar only from desktop up", () => {
+		assert.equal(mountsTopBarField(1023), false);
+		assert.equal(mountsTopBarField(1024), true);
+	});
+});

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

package/src/hooks/useToggleStar.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { patchThreadListCache } from "../lib/thread-cache.js";
 import {
 	resolveMailboxForMessage,
 	toggleStarsInItems,
@@ -93,3 +94,33 @@ describe("resolveMailboxForMessage", () => {
 		);
 	});
 });
+
+describe("starring across the unified-threads cache shapes", () => {
+	// The Flagged view runs an infinite query on `listAllThreads({ starred:
+	// true })`, which shares its query-key prefix with the single-shot readers.
+	// A `setQueriesData` on that prefix therefore sees both shapes, and the
+	// optimistic patch has to survive whichever it is handed — patching the
+	// infinite entry as a plain `{ items }` threw and failed the star before it
+	// was sent.
+	const patch = (old: unknown) =>
+		patchThreadListCache(old, (items) => toggleStarsInItems(items, "m1", true));
+
+	test("patches the single-shot readers", () => {
+		const patched = patch({
+			items: [make("m1", false), make("m2", false)],
+		}) as {
+			items: RemitImapThreadMessageResponse[];
+		};
+		assert.equal(patched.items[0].hasStars, true);
+		assert.equal(patched.items[1].hasStars, false);
+	});
+
+	test("patches the Flagged view's infinite query instead of throwing", () => {
+		const patched = patch({
+			pages: [{ items: [make("m1", false)] }, { items: [make("m2", false)] }],
+			pageParams: [undefined, "next"],
+		}) as { pages: Array<{ items: RemitImapThreadMessageResponse[] }> };
+		assert.equal(patched.pages[0].items[0].hasStars, true);
+		assert.equal(patched.pages[1].items[0].hasStars, false);
+	});
+});