@remit/web-client 0.0.1

package/src/lib/rescue-telemetry.ts

@@ -0,0 +1,55 @@
+import type { RemitImapSenderTrust } from "@remit/api-http-client/types.gen.ts";
+import type { Telemetry } from "@/lib/telemetry";
+
+/**
+ * Rescue-from-Spam telemetry. Shapes the small, privacy-safe payloads (counts,
+ * folder roles, booleans — never bodies or addresses) and emits them through the
+ * shared `recordEvent` channel, matching the `domain.action` event-name
+ * convention used across the client.
+ */
+
+export function recordRescueCandidatesSurfaced(
+	telemetry: Telemetry,
+	count: number,
+): void {
+	telemetry.recordEvent("rescue.candidates_surfaced", { count: String(count) });
+}
+
+export function recordRescueFlowOpened(
+	telemetry: Telemetry,
+	count: number,
+): void {
+	telemetry.recordEvent("rescue.flow_opened", { count: String(count) });
+}
+
+export function recordRescueCommitted(
+	telemetry: Telemetry,
+	input: { selected: number; total: number; toInbox: boolean },
+): void {
+	telemetry.recordEvent("rescue.committed", {
+		selected: String(input.selected),
+		total: String(input.total),
+		destination: input.toInbox ? "inbox" : "other",
+	});
+}
+
+/**
+ * The reverse signal: a message moved back into Junk. `wasRescuable` is the best
+ * cheaply-available prior-rescue proxy — the sender is one we can verify, so the
+ * user is overriding our trust. There is no per-message "was previously rescued"
+ * flag in the client, so we do not claim one.
+ */
+export function recordRescueSentToJunk(
+	telemetry: Telemetry,
+	input: {
+		count: number;
+		senderTrust: RemitImapSenderTrust;
+		wasRescuable: boolean;
+	},
+): void {
+	telemetry.recordEvent("rescue.sent_to_junk", {
+		count: String(input.count),
+		senderTrust: input.senderTrust,
+		wasRescuable: String(input.wasRescuable),
+	});
+}

package/src/lib/rum-adapter.test.ts

@@ -0,0 +1,299 @@
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { AwsRum } from "aws-rum-web";
+import { createRumTelemetry, initRum } from "./rum-adapter";
+
+interface RumStub {
+	appMonitorId: string;
+	calls: {
+		recordPageView: string[];
+		recordError: Error[];
+		recordEvent: { name: string; attributes: Record<string, unknown> }[];
+	};
+}
+
+function resetInstances(): void {
+	(
+		globalThis as unknown as { __AWS_RUM_MOCKS__: { instances: unknown[] } }
+	).__AWS_RUM_MOCKS__ = { instances: [] };
+}
+
+function getLastInstance(): RumStub {
+	const mocks = (
+		globalThis as unknown as {
+			__AWS_RUM_MOCKS__: { instances: RumStub[] };
+		}
+	).__AWS_RUM_MOCKS__;
+	const instance = mocks.instances.at(-1);
+	assert.ok(instance, "Expected an AwsRum instance to have been created");
+	return instance;
+}
+
+function makeRum(): AwsRum {
+	return new (
+		AwsRum as unknown as new (
+			id: string,
+			v: string,
+			r: string,
+			c: Record<string, unknown>,
+		) => AwsRum
+	)("monitor-id", "1.0.0", "eu-west-1", {});
+}
+
+function stubCalls(rum: AwsRum): RumStub["calls"] {
+	return (rum as unknown as RumStub).calls;
+}
+
+describe("createRumTelemetry", () => {
+	let rum: AwsRum;
+
+	beforeEach(() => {
+		resetInstances();
+		rum = makeRum();
+	});
+
+	it("recordPageView delegates to the RUM client", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/inbox");
+		assert.deepEqual(stubCalls(rum).recordPageView, ["/inbox"]);
+	});
+
+	it("recordPageView strips the entire query string", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/callback?token=secret&next=/inbox");
+		assert.equal(stubCalls(rum).recordPageView[0], "/callback");
+	});
+
+	it("recordPageView strips selectedMessageId query param", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/inbox?selectedMessageId=msg_abc123def456");
+		assert.equal(stubCalls(rum).recordPageView[0], "/inbox");
+	});
+
+	it("recordPageView strips search query param", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/inbox?q=sensitive+search+text");
+		assert.equal(stubCalls(rum).recordPageView[0], "/inbox");
+	});
+
+	it("recordPageView strips query string and fragment together", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/inbox?q=foo#section");
+		assert.equal(stubCalls(rum).recordPageView[0], "/inbox");
+	});
+
+	it("recordPageView strips fragment-only paths", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/inbox#fragment");
+		assert.equal(stubCalls(rum).recordPageView[0], "/inbox");
+	});
+
+	it("recordPageView strips message id path segments", () => {
+		const t = createRumTelemetry(rum);
+		t.recordPageView("/messages/msg_abc123def456");
+		assert.ok(
+			!stubCalls(rum).recordPageView[0]?.includes("msg_abc123def456"),
+			"message id must be redacted",
+		);
+	});
+
+	it("recordError delegates to the RUM client", () => {
+		const t = createRumTelemetry(rum);
+		const error = new Error("boom");
+		t.recordError(error);
+		assert.deepEqual(stubCalls(rum).recordError, [error]);
+	});
+
+	it("recordError scrubs message id tokens from error messages", () => {
+		const t = createRumTelemetry(rum);
+		const error = new Error("failed to load /messages/msg_abc123def456");
+		t.recordError(error);
+		const recorded = stubCalls(rum).recordError[0] as Error;
+		assert.ok(
+			!recorded.message.includes("msg_abc123def456"),
+			"message id must be scrubbed from error message",
+		);
+	});
+
+	it("recordError preserves error name on scrubbed errors", () => {
+		const t = createRumTelemetry(rum);
+		const error = new TypeError("token=secret leaked into /messages/msg_xyz");
+		t.recordError(error);
+		const recorded = stubCalls(rum).recordError[0] as Error;
+		assert.equal(recorded.name, "TypeError");
+	});
+
+	it("recordError with context emits an additional event", () => {
+		const t = createRumTelemetry(rum);
+		t.recordError(new Error("boom"), { component: "Inbox" });
+		const ctx = stubCalls(rum).recordEvent.find(
+			(e) => e.name === "telemetry.error_context",
+		);
+		assert.ok(ctx, "Expected a telemetry.error_context event");
+		assert.deepEqual(ctx.attributes, { component: "Inbox" });
+	});
+
+	it("recordEvent delegates to the RUM client", () => {
+		const t = createRumTelemetry(rum);
+		t.recordEvent("thread.open", { mailboxId: "inbox" });
+		assert.ok(
+			stubCalls(rum).recordEvent.some((e) => e.name === "thread.open"),
+			"Expected thread.open event",
+		);
+	});
+
+	it("recordEvent with no attributes passes an empty object", () => {
+		const t = createRumTelemetry(rum);
+		t.recordEvent("app.load");
+		const ev = stubCalls(rum).recordEvent.find((e) => e.name === "app.load");
+		assert.ok(ev, "Expected app.load event");
+		assert.deepEqual(ev.attributes, {});
+	});
+
+	it("recordTiming emits a telemetry.timing event with name and duration", () => {
+		const t = createRumTelemetry(rum);
+		t.recordTiming("api.latency", 123);
+		const ev = stubCalls(rum).recordEvent.find(
+			(e) => e.name === "telemetry.timing",
+		);
+		assert.ok(ev, "Expected telemetry.timing event");
+		assert.equal((ev.attributes as Record<string, string>).name, "api.latency");
+		assert.equal((ev.attributes as Record<string, string>).durationMs, "123");
+	});
+
+	it("recordTiming merges extra attributes", () => {
+		const t = createRumTelemetry(rum);
+		t.recordTiming("api.latency", 50, { route: "/inbox" });
+		const ev = stubCalls(rum).recordEvent.find(
+			(e) => e.name === "telemetry.timing",
+		);
+		assert.ok(ev, "Expected telemetry.timing event");
+		assert.equal((ev.attributes as Record<string, string>).route, "/inbox");
+	});
+});
+
+type WindowListener = (event: unknown) => void;
+
+interface WindowStub {
+	listeners: Map<string, WindowListener>;
+	addEventListener(type: string, listener: WindowListener): void;
+}
+
+function installWindowStub(): WindowStub {
+	const stub: WindowStub = {
+		listeners: new Map(),
+		addEventListener(type, listener): void {
+			this.listeners.set(type, listener);
+		},
+	};
+	(globalThis as unknown as { window: WindowStub }).window = stub;
+	return stub;
+}
+
+function getRumConfig(
+	instance: RumStub,
+): { telemetries: string[] } & Record<string, unknown> {
+	return (instance as unknown as { config: { telemetries: string[] } }).config;
+}
+
+describe("initRum", () => {
+	afterEach(() => {
+		delete globalThis.__REMIT_CONFIG__;
+		delete (globalThis as unknown as { window?: unknown }).window;
+	});
+
+	it("returns a no-op telemetry when VITE_RUM_APP_MONITOR_ID is unset", () => {
+		globalThis.__REMIT_CONFIG__ = {};
+		const t = initRum();
+		assert.doesNotThrow(() => t.recordPageView("/"));
+		assert.doesNotThrow(() => t.recordError(new Error("x")));
+		assert.doesNotThrow(() => t.recordEvent("e"));
+		assert.doesNotThrow(() => t.recordTiming("t", 1));
+	});
+
+	it("creates a RumTelemetry when VITE_RUM_APP_MONITOR_ID is set", () => {
+		resetInstances();
+		installWindowStub();
+		globalThis.__REMIT_CONFIG__ = {
+			rum: {
+				appMonitorId: "test-monitor-id",
+				identityPoolId: "eu-west-1:test-pool",
+				region: "eu-west-1",
+			},
+		};
+		const t = initRum();
+		const instance = getLastInstance();
+		assert.equal(instance.appMonitorId, "test-monitor-id");
+		assert.doesNotThrow(() => t.recordPageView("/inbox"));
+	});
+
+	it("does not enable leaky auto-telemetries", () => {
+		resetInstances();
+		installWindowStub();
+		globalThis.__REMIT_CONFIG__ = {
+			rum: { appMonitorId: "test-monitor-id" },
+		};
+		initRum();
+		const config = getRumConfig(getLastInstance());
+		assert.ok(
+			!config.telemetries.includes("errors"),
+			"errors auto-capture must be disabled",
+		);
+		assert.ok(
+			!config.telemetries.includes("http"),
+			"http auto-capture must be disabled",
+		);
+	});
+
+	it("disables auto page view so paths are recorded via the sanitizing adapter", () => {
+		resetInstances();
+		installWindowStub();
+		globalThis.__REMIT_CONFIG__ = {
+			rum: { appMonitorId: "test-monitor-id" },
+		};
+		initRum();
+		const config = getRumConfig(getLastInstance());
+		assert.equal(config.disableAutoPageView, true);
+	});
+
+	it("scrubs uncaught errors before recording them through RUM", () => {
+		resetInstances();
+		const win = installWindowStub();
+		globalThis.__REMIT_CONFIG__ = {
+			rum: { appMonitorId: "test-monitor-id" },
+		};
+		initRum();
+		const handler = win.listeners.get("error");
+		assert.ok(handler, "Expected a global error handler");
+		handler({
+			error: new Error("failed to load /messages/msg_abc123def456"),
+			message: "failed to load /messages/msg_abc123def456",
+		});
+		const recorded = stubCalls(getLastInstance() as unknown as AwsRum)
+			.recordError[0] as Error;
+		assert.ok(
+			!recorded.message.includes("msg_abc123def456"),
+			"uncaught error message must be scrubbed",
+		);
+	});
+
+	it("scrubs unhandled rejections before recording them through RUM", () => {
+		resetInstances();
+		const win = installWindowStub();
+		globalThis.__REMIT_CONFIG__ = {
+			rum: { appMonitorId: "test-monitor-id" },
+		};
+		initRum();
+		const handler = win.listeners.get("unhandledrejection");
+		assert.ok(handler, "Expected a global unhandledrejection handler");
+		handler({
+			reason: new Error("rejected loading /messages/msg_xyz789"),
+		});
+		const recorded = stubCalls(getLastInstance() as unknown as AwsRum)
+			.recordError[0] as Error;
+		assert.ok(
+			!recorded.message.includes("msg_xyz789"),
+			"rejection reason must be scrubbed",
+		);
+	});
+});

package/src/lib/rum-adapter.ts

@@ -0,0 +1,107 @@
+import { AwsRum } from "aws-rum-web";
+import { getRuntimeConfig } from "../runtime-config";
+import type { Telemetry } from "./telemetry";
+import { noopTelemetry } from "./telemetry";
+
+const ID_TOKEN_PATTERN =
+	/([?&](token|access_token|id_token|authorization)=[^&]*)|\/messages\/[a-z0-9_-]+/gi;
+
+function scrubIds(value: string): string {
+	return value.replace(ID_TOKEN_PATTERN, "[redacted]");
+}
+
+function sanitizePath(path: string): string {
+	const qIndex = path.indexOf("?");
+	const hIndex = path.indexOf("#");
+	const cutAt =
+		qIndex === -1 && hIndex === -1
+			? path.length
+			: qIndex === -1
+				? hIndex
+				: hIndex === -1
+					? qIndex
+					: Math.min(qIndex, hIndex);
+	return scrubIds(path.slice(0, cutAt));
+}
+
+function scrubErrorMessage(error: Error): Error {
+	const scrubbed = scrubIds(error.message);
+	if (scrubbed === error.message) {
+		return error;
+	}
+	const next = new Error(scrubbed);
+	next.name = error.name;
+	next.stack = error.stack;
+	return next;
+}
+
+export function createRumTelemetry(rum: AwsRum): Telemetry {
+	return {
+		recordPageView(path: string): void {
+			rum.recordPageView(sanitizePath(path));
+		},
+
+		recordError(error: Error, context?: Record<string, string>): void {
+			rum.recordError(scrubErrorMessage(error));
+			if (context) {
+				rum.recordEvent("telemetry.error_context", context);
+			}
+		},
+
+		recordEvent(name: string, attributes?: Record<string, string>): void {
+			rum.recordEvent(name, attributes ?? {});
+		},
+
+		recordTiming(
+			name: string,
+			durationMs: number,
+			attributes?: Record<string, string>,
+		): void {
+			rum.recordEvent("telemetry.timing", {
+				...attributes,
+				name,
+				durationMs: String(durationMs),
+			});
+		},
+	};
+}
+
+function toError(reason: unknown): Error {
+	if (reason instanceof Error) {
+		return reason;
+	}
+	return new Error(String(reason));
+}
+
+function installGlobalErrorHandlers(telemetry: Telemetry): void {
+	window.addEventListener("error", (event: ErrorEvent): void => {
+		telemetry.recordError(toError(event.error ?? event.message));
+	});
+	window.addEventListener(
+		"unhandledrejection",
+		(event: PromiseRejectionEvent): void => {
+			telemetry.recordError(toError(event.reason));
+		},
+	);
+}
+
+export function initRum(): Telemetry {
+	const { appMonitorId, identityPoolId, region } = getRuntimeConfig().rum;
+	if (!appMonitorId) {
+		return noopTelemetry;
+	}
+
+	const rum = new AwsRum(appMonitorId, "1.0.0", region, {
+		sessionSampleRate: 1,
+		identityPoolId,
+		endpoint: `https://dataplane.rum.${region}.amazonaws.com`,
+		telemetries: ["performance"],
+		disableAutoPageView: true,
+		allowCookies: false,
+		enableXRay: false,
+	});
+
+	const telemetry = createRumTelemetry(rum);
+	installGlobalErrorHandlers(telemetry);
+	return telemetry;
+}

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

@@ -0,0 +1,80 @@
+import assert from "node:assert";
+import { beforeEach, describe, test } from "node:test";
+import {
+	isSearchSaved,
+	loadSavedSearches,
+	removeSavedSearch,
+	saveSearch,
+} from "./saved-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("saved-searches", () => {
+	beforeEach(installMemoryStorage);
+
+	test("starts empty", () => {
+		assert.deepEqual(loadSavedSearches(), []);
+	});
+
+	test("saves and loads a query", () => {
+		assert.deepEqual(saveSearch("from:alice has:attachment"), [
+			"from:alice has:attachment",
+		]);
+		assert.deepEqual(loadSavedSearches(), ["from:alice has:attachment"]);
+	});
+
+	test("most recent save first, deduplicated", () => {
+		saveSearch("alice");
+		saveSearch("bob");
+		assert.deepEqual(saveSearch("alice"), ["alice", "bob"]);
+	});
+
+	test("ignores blank queries", () => {
+		saveSearch("alice");
+		assert.deepEqual(saveSearch("   "), ["alice"]);
+	});
+
+	test("trims before storing", () => {
+		assert.deepEqual(saveSearch("  bob  "), ["bob"]);
+	});
+
+	test("survives corrupt storage", () => {
+		globalThis.localStorage.setItem("remit.savedSearches", "{not json");
+		assert.deepEqual(loadSavedSearches(), []);
+	});
+
+	test("removeSavedSearch drops the exact query", () => {
+		saveSearch("alice");
+		saveSearch("bob");
+		assert.deepEqual(removeSavedSearch("alice"), ["bob"]);
+		assert.deepEqual(loadSavedSearches(), ["bob"]);
+	});
+
+	test("removeSavedSearch is a no-op for a query that isn't saved", () => {
+		saveSearch("alice");
+		assert.deepEqual(removeSavedSearch("nonexistent"), ["alice"]);
+	});
+
+	test("isSearchSaved reflects the persisted set, trimmed", () => {
+		saveSearch("alice");
+		assert.equal(isSearchSaved("alice"), true);
+		assert.equal(isSearchSaved("  alice  "), true);
+		assert.equal(isSearchSaved("bob"), false);
+	});
+
+	test("caps at MAX_SAVED entries", () => {
+		for (let i = 0; i < 30; i++) saveSearch(`query-${i}`);
+		assert.equal(loadSavedSearches().length, 25);
+		assert.deepEqual(loadSavedSearches()[0], "query-29");
+	});
+});

package/src/lib/saved-searches.ts

@@ -0,0 +1,52 @@
+/**
+ * Saved searches for the mail search bar, persisted in localStorage (#428
+ * follow-up, local-only MVP — see doc/design/flows/06-search.md; no backend
+ * preference storage yet). Mirrors `recent-searches.ts`: a query already
+ * carries its filter chips (`parseSearchTokens` re-derives them), so saving
+ * the raw query text is enough to reproduce the full search. Best-effort:
+ * storage failures (private mode, quota) degrade to an empty list rather than
+ * crashing the search surface.
+ */
+const SAVED_SEARCHES_KEY = "remit.savedSearches";
+const MAX_SAVED = 25;
+
+export function loadSavedSearches(): string[] {
+	try {
+		const raw = localStorage.getItem(SAVED_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 saveSearch(query: string): string[] {
+	const trimmed = query.trim();
+	if (!trimmed) return loadSavedSearches();
+	const next = [
+		trimmed,
+		...loadSavedSearches().filter((q) => q !== trimmed),
+	].slice(0, MAX_SAVED);
+	try {
+		localStorage.setItem(SAVED_SEARCHES_KEY, JSON.stringify(next));
+	} catch {
+		return next;
+	}
+	return next;
+}
+
+export function removeSavedSearch(query: string): string[] {
+	const next = loadSavedSearches().filter((q) => q !== query);
+	try {
+		localStorage.setItem(SAVED_SEARCHES_KEY, JSON.stringify(next));
+	} catch {
+		return next;
+	}
+	return next;
+}
+
+export function isSearchSaved(query: string): boolean {
+	return loadSavedSearches().includes(query.trim());
+}

package/src/lib/search-pending.test.ts

@@ -0,0 +1,61 @@
+// Regression test for #623: search results must be openable once the query
+// settles. The route computes `isSearchPending = searchInput !== searchQuery`
+// to decide whether to suppress the reading pane, then resolves the selected
+// thread via `resolveSelectedThread`.
+//
+// - `searchInput` is the live (pre-debounce) value the user is typing.
+// - `searchQuery` is the debounced (committed) value sent to the API.
+// - The pane is suppressed only while the two differ (a debounce is in flight).
+// - Once settled, a selected result should be shown in the reading pane.
+
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { isSearchPending, resolveSelectedThread } from "./search-pending.ts";
+
+describe("isSearchPending (reading-pane suppression guard)", () => {
+	test("no search: both empty — not pending", () => {
+		assert.equal(isSearchPending("", ""), false);
+	});
+
+	test("settled search: input matches debounced query — not pending", () => {
+		assert.equal(isSearchPending("amazon", "amazon"), false);
+	});
+
+	test("user starts typing: input differs from query — pending", () => {
+		assert.equal(isSearchPending("ama", ""), true);
+	});
+
+	test("mid-debounce: partial input vs previous query — pending", () => {
+		assert.equal(isSearchPending("amaz", "amazon"), true);
+	});
+});
+
+describe("resolveSelectedThread (#623 reading-pane resolution)", () => {
+	const threads = [{ messageId: "msg-001" }, { messageId: "msg-002" }];
+
+	test("regression #623: settled query with a matching selection opens the thread", () => {
+		const pending = isSearchPending("amazon", "amazon");
+		assert.equal(pending, false);
+
+		const selectedThread = resolveSelectedThread(threads, "msg-001", pending);
+		assert.deepEqual(selectedThread, { messageId: "msg-001" });
+	});
+
+	test("pending search suppresses the reading pane even with a matching selection", () => {
+		const pending = isSearchPending("amaz", "amazon");
+		assert.equal(pending, true);
+
+		const selectedThread = resolveSelectedThread(threads, "msg-001", pending);
+		assert.equal(selectedThread, undefined);
+	});
+
+	test("settled query but selection absent from results — no thread", () => {
+		const selectedThread = resolveSelectedThread(threads, "msg-999", false);
+		assert.equal(selectedThread, undefined);
+	});
+
+	test("settled query with no selection — no thread", () => {
+		const selectedThread = resolveSelectedThread(threads, undefined, false);
+		assert.equal(selectedThread, undefined);
+	});
+});

package/src/lib/search-pending.ts

@@ -0,0 +1,24 @@
+// Reading-pane suppression guard for the mail search bar (#539, #623).
+//
+// `searchInput` is the live (pre-debounce) value the user is typing;
+// `searchQuery` is the debounced (committed) value sent to the API. A debounce
+// is in flight whenever the two differ — during that window the reading pane is
+// kept closed so it clears the instant a new search starts (#539). Once the
+// query settles, a selected result is honored so search results can be opened
+// (#623).
+export const isSearchPending = (
+	searchInput: string,
+	searchQuery: string,
+): boolean => searchInput !== searchQuery;
+
+// Resolve the thread to show in the reading pane. Returns `undefined` while a
+// search debounce is pending or when nothing is selected; otherwise looks the
+// selected message up in the loaded thread list.
+export const resolveSelectedThread = <T extends { messageId: string }>(
+	threads: T[],
+	selectedMessageId: string | undefined,
+	pending: boolean,
+): T | undefined => {
+	if (pending || !selectedMessageId) return undefined;
+	return threads.find((t) => t.messageId === selectedMessageId);
+};