@remit/web-client 0.0.1

package/src/lib/provider-presets.ts

@@ -0,0 +1,81 @@
+import type { ServerSettings } from "./autodiscovery.js";
+
+export interface ProviderPreset {
+	id: string;
+	label: string;
+	username: "full-email";
+	imap: ServerSettings;
+	smtp: ServerSettings;
+	passwordHelp: { text: string; url: string };
+}
+
+export const PROVIDER_PRESETS: ProviderPreset[] = [
+	{
+		id: "icloud",
+		label: "iCloud",
+		username: "full-email",
+		imap: { host: "imap.mail.me.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.mail.me.com", port: 587, security: "starttls" },
+		passwordHelp: {
+			text: "iCloud requires an app-specific password, not your Apple ID password. Generate one under Sign-In & Security → App-Specific Passwords.",
+			url: "https://support.apple.com/en-us/102654",
+		},
+	},
+	{
+		id: "yahoo",
+		label: "Yahoo",
+		username: "full-email",
+		imap: { host: "imap.mail.yahoo.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.mail.yahoo.com", port: 465, security: "tls" },
+		passwordHelp: {
+			text: "Yahoo requires an app password, not your login password. Generate one under Account Security.",
+			url: "https://help.yahoo.com/kb/generate-manage-third-party-passwords-sln15241.html",
+		},
+	},
+	{
+		id: "aol",
+		label: "AOL",
+		username: "full-email",
+		imap: { host: "imap.aol.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.aol.com", port: 465, security: "tls" },
+		passwordHelp: {
+			text: "AOL requires an app password, not your login password. Generate one under Account Security.",
+			url: "https://login.aol.com/account/security",
+		},
+	},
+	{
+		id: "fastmail",
+		label: "Fastmail",
+		username: "full-email",
+		imap: { host: "imap.fastmail.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.fastmail.com", port: 465, security: "tls" },
+		passwordHelp: {
+			text: "Fastmail requires an app password, not your login password. Create one under Settings → Privacy & Security → App passwords.",
+			url: "https://www.fastmail.help/hc/en-us/articles/360058752854",
+		},
+	},
+];
+
+export function getPresetById(id: string): ProviderPreset | undefined {
+	return PROVIDER_PRESETS.find((preset) => preset.id === id);
+}
+
+const DOMAIN_TO_PRESET: Record<string, string> = {
+	"icloud.com": "icloud",
+	"me.com": "icloud",
+	"mac.com": "icloud",
+	"yahoo.com": "yahoo",
+	"yahoo.co.uk": "yahoo",
+	"ymail.com": "yahoo",
+	"aol.com": "aol",
+	"fastmail.com": "fastmail",
+	"fastmail.fm": "fastmail",
+};
+
+/** Pre-select a provider preset from a known email domain; "" for Custom. */
+export function presetIdForEmail(email: string): string {
+	const atIdx = email.indexOf("@");
+	if (atIdx === -1) return "";
+	const domain = email.slice(atIdx + 1).toLowerCase();
+	return DOMAIN_TO_PRESET[domain] ?? "";
+}

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

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { Mutation, Query } from "@tanstack/react-query";
+import { ApiError } from "./api";
+import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "./query-error-handler";
+
+const fakeQuery = (
+	meta?: Record<string, unknown>,
+	dataUpdatedAt = 0,
+): Query<unknown, unknown, unknown> =>
+	({ meta, state: { dataUpdatedAt } }) as unknown as Query<
+		unknown,
+		unknown,
+		unknown
+	>;
+
+const fakeMutation = (
+	meta?: Record<string, unknown>,
+): Mutation<unknown, unknown, unknown> =>
+	({ meta }) as unknown as Mutation<unknown, unknown, unknown>;
+
+const abortError = (): Error => {
+	const error = new Error("aborted");
+	error.name = "AbortError";
+	return error;
+};
+
+const escalations = (): string[] => {
+	const seen: string[] = [];
+	subscribeFatalError((fatal) => seen.push(fatal.message));
+	return seen;
+};
+
+afterEach(() => {
+	__resetFatalError();
+});
+
+describe("handleQueryCacheError (fail-fast contract #1059)", () => {
+	it("escalates a 5xx that breaks the INITIAL load", () => {
+		const seen = escalations();
+		handleQueryCacheError(
+			new ApiError("internal", 500),
+			fakeQuery(undefined, 0),
+		);
+		assert.deepEqual(seen, ["internal"]);
+	});
+
+	it("escalates a 5xx on a background REFETCH (the deleted dataUpdatedAt guard — the headline bug)", () => {
+		const seen = escalations();
+		// dataUpdatedAt !== 0 used to swallow this (PR #758). It must now escalate.
+		handleQueryCacheError(
+			new ApiError("internal", 500),
+			fakeQuery(undefined, 123456),
+		);
+		assert.deepEqual(seen, ["internal"]);
+	});
+
+	it("escalates a 5xx EVEN when the query is marked meta.softError (rule 2 wins)", () => {
+		const seen = escalations();
+		handleQueryCacheError(
+			new ApiError("internal", 500),
+			fakeQuery({ softError: true }, 123456),
+		);
+		assert.deepEqual(seen, ["internal"]);
+	});
+
+	it("escalates a 4xx by DEFAULT (no opt-out)", () => {
+		const seen = escalations();
+		handleQueryCacheError(new ApiError("not found", 404), fakeQuery());
+		assert.deepEqual(seen, ["not found"]);
+	});
+
+	it("does NOT escalate a 4xx the query opted out of via meta.softError", () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		handleQueryCacheError(
+			new ApiError("not found", 404),
+			fakeQuery({ softError: true }),
+		);
+		assert.equal(escalated, false);
+	});
+
+	it("does NOT escalate an aborted request", () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		handleQueryCacheError(abortError(), fakeQuery());
+		assert.equal(escalated, false);
+	});
+
+	it("does NOT escalate a statusless network blip", () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		handleQueryCacheError(new TypeError("Failed to fetch"), fakeQuery());
+		assert.equal(escalated, false);
+	});
+});
+
+describe("handleMutationCacheError (fail-fast contract #1059)", () => {
+	it("escalates a mutation 5xx", () => {
+		const seen = escalations();
+		handleMutationCacheError(
+			new ApiError("mutation blew up", 503),
+			undefined,
+			undefined,
+			fakeMutation(),
+		);
+		assert.deepEqual(seen, ["mutation blew up"]);
+	});
+
+	it("escalates a mutation 4xx by DEFAULT", () => {
+		const seen = escalations();
+		handleMutationCacheError(
+			new ApiError("conflict", 409),
+			undefined,
+			undefined,
+			fakeMutation(),
+		);
+		assert.deepEqual(seen, ["conflict"]);
+	});
+
+	it("does NOT escalate a mutation 4xx marked meta.softError", () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		handleMutationCacheError(
+			new ApiError("conflict", 409),
+			undefined,
+			undefined,
+			fakeMutation({ softError: true }),
+		);
+		assert.equal(escalated, false);
+	});
+});

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

@@ -0,0 +1,34 @@
+import type { Mutation, Query } from "@tanstack/react-query";
+import { shouldEscalate } from "./error-classifier";
+import { reportFatalError } from "./fatal-error";
+
+/**
+ * Global React Query error sink. Every query and mutation error flows through
+ * here (wired on the `QueryCache`/`MutationCache` in main.tsx). The fail-fast
+ * contract (#1059) lives in `shouldEscalate`: a non-2xx escalates to the
+ * full-screen red overlay by default; a 5xx ALWAYS escalates; only aborts,
+ * statusless network blips, and non-5xx errors a call site opted out of via
+ * `meta.softError` stay soft.
+ *
+ * This is the v5 equivalent of `defaultOptions.queries.onError` /
+ * `.mutations.onError` — v5 moved the global error hook onto the caches.
+ */
+export const handleQueryCacheError = (
+	error: Error,
+	query: Query<unknown, unknown, unknown>,
+): void => {
+	if (shouldEscalate(error, query.meta)) {
+		reportFatalError(error);
+	}
+};
+
+export const handleMutationCacheError = (
+	error: unknown,
+	_variables: unknown,
+	_onMutateResult: unknown,
+	mutation: Mutation<unknown, unknown, unknown>,
+): void => {
+	if (shouldEscalate(error, mutation.meta)) {
+		reportFatalError(error);
+	}
+};

package/src/lib/query-escalation.integration.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Integration: prove the global React Query caches route a first-party error
+ * through the fail-fast handlers → `reportFatalError`, which is what drives the
+ * full-screen escalation overlay. React Query's core runs headless (no DOM),
+ * so this exercises the real `QueryCache`/`MutationCache` wiring from main.tsx
+ * without rendering.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import { ApiError } from "./api";
+import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "./query-error-handler";
+
+afterEach(() => {
+	__resetFatalError();
+});
+
+const makeClient = () =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: { queries: { retry: false } },
+	});
+
+describe("global query/mutation escalation", () => {
+	it("a first-party 5xx from a query escalates to the fatal overlay seam", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+
+		await client
+			.fetchQuery({
+				queryKey: ["explode"],
+				queryFn: async () => {
+					throw new ApiError("internal server error", 500);
+				},
+			})
+			.catch(() => {});
+
+		assert.deepEqual(seen, ["internal server error"]);
+	});
+
+	it("a 5xx on a background REFETCH escalates — the exact #1059 bug (semantic-search-style query that 500s after first rendering data)", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+		const queryKey = ["semanticSearch"];
+		let calls = 0;
+		const queryFn = async () => {
+			calls += 1;
+			if (calls === 1) return { items: [] as string[] };
+			throw new ApiError("semantic search exploded", 500);
+		};
+
+		// First load succeeds → query now has data (dataUpdatedAt !== 0). Under the
+		// deleted guard this refetch 500 vanished into `data?.items ?? []`.
+		await client.fetchQuery({ queryKey, queryFn });
+		await client.refetchQueries({ queryKey }).catch(() => {});
+
+		assert.deepEqual(seen, ["semantic search exploded"]);
+	});
+
+	it("a first-party 5xx from a mutation escalates to the fatal overlay seam", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+
+		const mutation = client.getMutationCache().build(client, {
+			mutationFn: async () => {
+				throw new ApiError("mutation blew up", 503);
+			},
+		});
+		await mutation.execute(undefined).catch(() => {});
+
+		assert.deepEqual(seen, ["mutation blew up"]);
+	});
+
+	it("a 404 on a query marked meta.softError does NOT escalate (call site owns the empty state)", async () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		const client = makeClient();
+
+		await client
+			.fetchQuery({
+				queryKey: ["missing"],
+				queryFn: async () => {
+					throw new ApiError("not found", 404);
+				},
+				meta: { softError: true },
+			})
+			.catch(() => {});
+
+		assert.equal(escalated, false);
+	});
+
+	it("a 404 on a query that did NOT opt out escalates by default", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+
+		await client
+			.fetchQuery({
+				queryKey: ["unhandled-404"],
+				queryFn: async () => {
+					throw new ApiError("not found", 404);
+				},
+			})
+			.catch(() => {});
+
+		assert.deepEqual(seen, ["not found"]);
+	});
+
+	it("a statusless `Failed to fetch` (offline blip) from a query does NOT escalate", async () => {
+		let escalated = false;
+		subscribeFatalError(() => {
+			escalated = true;
+		});
+		const client = makeClient();
+
+		await client
+			.fetchQuery({
+				queryKey: ["offline"],
+				queryFn: async () => {
+					throw new TypeError("Failed to fetch");
+				},
+			})
+			.catch(() => {});
+
+		assert.equal(escalated, false);
+	});
+});

package/src/lib/recent-searches.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert";
+import { beforeEach, describe, test } from "node:test";
+import { loadRecentSearches, saveRecentSearch } from "./recent-searches.js";
+
+function installMemoryStorage(): void {
+	const store = new Map<string, string>();
+	globalThis.localStorage = {
+		getItem: (k: string) => store.get(k) ?? null,
+		setItem: (k: string, v: string) => void store.set(k, v),
+		removeItem: (k: string) => void store.delete(k),
+		clear: () => store.clear(),
+		key: () => null,
+		length: 0,
+	} as Storage;
+}
+
+describe("recent-searches", () => {
+	beforeEach(installMemoryStorage);
+
+	test("starts empty", () => {
+		assert.deepEqual(loadRecentSearches(), []);
+	});
+
+	test("saves and loads a query", () => {
+		assert.deepEqual(saveRecentSearch("alice"), ["alice"]);
+		assert.deepEqual(loadRecentSearches(), ["alice"]);
+	});
+
+	test("most recent first, deduplicated", () => {
+		saveRecentSearch("alice");
+		saveRecentSearch("bob");
+		assert.deepEqual(saveRecentSearch("alice"), ["alice", "bob"]);
+	});
+
+	test("caps at five entries", () => {
+		for (const q of ["a", "b", "c", "d", "e", "f"]) saveRecentSearch(q);
+		assert.deepEqual(loadRecentSearches(), ["f", "e", "d", "c", "b"]);
+	});
+
+	test("ignores blank queries", () => {
+		saveRecentSearch("alice");
+		assert.deepEqual(saveRecentSearch("   "), ["alice"]);
+	});
+
+	test("trims before storing", () => {
+		assert.deepEqual(saveRecentSearch("  bob  "), ["bob"]);
+	});
+
+	test("survives corrupt storage", () => {
+		globalThis.localStorage.setItem("remit.recentSearches", "{not json");
+		assert.deepEqual(loadRecentSearches(), []);
+	});
+});

package/src/lib/recent-searches.ts

@@ -0,0 +1,34 @@
+/**
+ * Recent search queries for the mobile search takeover, persisted in
+ * localStorage. Best-effort: storage failures (private mode, quota) degrade to
+ * an empty list rather than crashing the search surface.
+ */
+const RECENT_SEARCHES_KEY = "remit.recentSearches";
+const MAX_RECENT = 5;
+
+export function loadRecentSearches(): string[] {
+	try {
+		const raw = localStorage.getItem(RECENT_SEARCHES_KEY);
+		if (!raw) return [];
+		const parsed: unknown = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+		return parsed.filter((q): q is string => typeof q === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function saveRecentSearch(query: string): string[] {
+	const trimmed = query.trim();
+	if (!trimmed) return loadRecentSearches();
+	const next = [
+		trimmed,
+		...loadRecentSearches().filter((q) => q !== trimmed),
+	].slice(0, MAX_RECENT);
+	try {
+		localStorage.setItem(RECENT_SEARCHES_KEY, JSON.stringify(next));
+	} catch {
+		return next;
+	}
+	return next;
+}

package/src/lib/rescue-candidates.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import {
+	isRescueCandidate,
+	rescueCandidateReason,
+} from "./rescue-candidates.js";
+
+function thread(
+	overrides: Partial<RemitImapThreadMessageResponse> &
+		Pick<RemitImapThreadMessageResponse, "messageId" | "senderTrust">,
+): RemitImapThreadMessageResponse {
+	return {
+		threadMessageId: `tm-${overrides.messageId}`,
+		threadId: `t-${overrides.messageId}`,
+		accountConfigId: "acc",
+		mailboxId: "mb-junk",
+		sentDate: 1_000_000,
+		isRead: false,
+		hasAttachment: false,
+		hasStars: false,
+		isDeleted: false,
+		createdAt: 1_000_000,
+		updatedAt: 1_000_000,
+		fromName: "Anna de Vries",
+		fromEmail: "anna@studio-noord.nl",
+		subject: "Re: invoice",
+		snippet: "Final files attached.",
+		...overrides,
+	} as RemitImapThreadMessageResponse;
+}
+
+describe("rescueCandidateReason", () => {
+	test("VIP senders read as someone you know", () => {
+		assert.equal(rescueCandidateReason("vip"), "A sender you know");
+	});
+
+	test("well-known senders read as previously emailed", () => {
+		assert.equal(
+			rescueCandidateReason("wellknown"),
+			"You've emailed them before",
+		);
+	});
+
+	test("anything else falls back to passed authentication", () => {
+		assert.equal(rescueCandidateReason("unknown"), "Passed authentication");
+	});
+
+	test("never leaks authentication jargon", () => {
+		for (const trust of ["vip", "wellknown", "unknown"] as const) {
+			assert.doesNotMatch(rescueCandidateReason(trust), /DKIM|SPF|DMARC/i);
+		}
+	});
+});
+
+describe("isRescueCandidate (telemetry predicate)", () => {
+	test("includes verified senders with no DKIM mismatch", () => {
+		assert.equal(
+			isRescueCandidate(thread({ messageId: "m1", senderTrust: "wellknown" })),
+			true,
+		);
+		assert.equal(
+			isRescueCandidate(thread({ messageId: "m2", senderTrust: "vip" })),
+			true,
+		);
+	});
+
+	test("excludes unknown senders", () => {
+		assert.equal(
+			isRescueCandidate(thread({ messageId: "m3", senderTrust: "unknown" })),
+			false,
+		);
+	});
+
+	test("excludes a verified sender that failed DKIM alignment", () => {
+		assert.equal(
+			isRescueCandidate(
+				thread({
+					messageId: "m4",
+					senderTrust: "vip",
+					authenticity: { fromDomain: "x.nl", dkimMismatch: true },
+				}),
+			),
+			false,
+		);
+	});
+
+	test("keeps a verified sender when authenticity is absent", () => {
+		assert.equal(
+			isRescueCandidate(thread({ messageId: "m5", senderTrust: "wellknown" })),
+			true,
+		);
+	});
+});

package/src/lib/rescue-candidates.ts

@@ -0,0 +1,35 @@
+import type {
+	RemitImapSenderTrust,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * Plain-language reason a message is safe to rescue, derived from the sender's
+ * trust tier. Never DKIM/SPF jargon — the user only sees why we trust them.
+ */
+export const rescueCandidateReason = (
+	senderTrust: RemitImapSenderTrust,
+): string => {
+	if (senderTrust === "vip") return "A sender you know";
+	if (senderTrust === "wellknown") return "You've emailed them before";
+	return "Passed authentication";
+};
+
+/**
+ * Returns true when a thread's sender is VIP or well-known with no confirmed
+ * DKIM mismatch. Used only for telemetry (wasRescuable) when marking a message
+ * as junk — it records whether the user moved a message that was previously
+ * eligible for rescue under the client-side rule.
+ *
+ * Note: the backend rescue query uses dkimMismatch=false which also excludes
+ * senders with no authenticity signal (undefined), unlike this predicate which
+ * treats absent authenticity as eligible. The backend is stricter by design.
+ */
+export const isRescueCandidate = (
+	thread: RemitImapThreadMessageResponse,
+): boolean => {
+	if (thread.senderTrust !== "vip" && thread.senderTrust !== "wellknown") {
+		return false;
+	}
+	return thread.authenticity?.dkimMismatch !== true;
+};

package/src/lib/rescue-telemetry.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Telemetry } from "@/lib/telemetry";
+import {
+	recordRescueCandidatesSurfaced,
+	recordRescueCommitted,
+	recordRescueFlowOpened,
+	recordRescueSentToJunk,
+} from "./rescue-telemetry";
+
+interface RecordedEvent {
+	name: string;
+	attributes?: Record<string, string>;
+}
+
+function stubTelemetry(): { telemetry: Telemetry; events: RecordedEvent[] } {
+	const events: RecordedEvent[] = [];
+	const telemetry: Telemetry = {
+		recordPageView: () => undefined,
+		recordError: () => undefined,
+		recordTiming: () => undefined,
+		recordEvent: (name, attributes) => events.push({ name, attributes }),
+	};
+	return { telemetry, events };
+}
+
+describe("rescue telemetry", () => {
+	it("emits candidates surfaced with the count", () => {
+		const { telemetry, events } = stubTelemetry();
+		recordRescueCandidatesSurfaced(telemetry, 7);
+		assert.deepEqual(events, [
+			{ name: "rescue.candidates_surfaced", attributes: { count: "7" } },
+		]);
+	});
+
+	it("emits flow opened with the count", () => {
+		const { telemetry, events } = stubTelemetry();
+		recordRescueFlowOpened(telemetry, 3);
+		assert.deepEqual(events, [
+			{ name: "rescue.flow_opened", attributes: { count: "3" } },
+		]);
+	});
+
+	it("emits committed with selected vs total and an inbox destination", () => {
+		const { telemetry, events } = stubTelemetry();
+		recordRescueCommitted(telemetry, { selected: 2, total: 5, toInbox: true });
+		assert.deepEqual(events, [
+			{
+				name: "rescue.committed",
+				attributes: { selected: "2", total: "5", destination: "inbox" },
+			},
+		]);
+	});
+
+	it("marks a non-inbox destination as other", () => {
+		const { telemetry, events } = stubTelemetry();
+		recordRescueCommitted(telemetry, { selected: 1, total: 1, toInbox: false });
+		assert.equal(events[0]?.attributes?.destination, "other");
+	});
+
+	it("emits the reverse signal with trust and rescuable flag", () => {
+		const { telemetry, events } = stubTelemetry();
+		recordRescueSentToJunk(telemetry, {
+			count: 1,
+			senderTrust: "vip",
+			wasRescuable: true,
+		});
+		assert.deepEqual(events, [
+			{
+				name: "rescue.sent_to_junk",
+				attributes: { count: "1", senderTrust: "vip", wasRescuable: "true" },
+			},
+		]);
+	});
+});