@remit/web-client 0.0.1

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

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { ApiError } from "./api";
+import { getRecentErrors } from "./console-errors";
+import {
+	__resetFatalError,
+	getCurrentFatalError,
+	reportFatalError,
+	setFatalErrorTelemetry,
+	subscribeFatalError,
+} from "./fatal-error";
+
+afterEach(() => {
+	__resetFatalError();
+});
+
+describe("reportFatalError", () => {
+	it("notifies subscribers with the classified fatal", () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+
+		reportFatalError(new Error("server exploded"));
+
+		assert.deepEqual(seen, ["server exploded"]);
+	});
+
+	it("records the fatal into the recent-errors ring (bug-report flow reads it)", () => {
+		reportFatalError(new Error("ring me"));
+		const recent = getRecentErrors();
+		assert.ok(
+			recent.some((line) => line.includes("Fatal: ring me")),
+			"expected the fatal to land in the console-errors ring",
+		);
+	});
+
+	it("assigns a correlation id and exposes the current fatal", () => {
+		const fatal = reportFatalError(new Error("with id"));
+		assert.ok(fatal.correlationId.length > 0);
+		assert.equal(getCurrentFatalError(), fatal);
+	});
+
+	it("emits a telemetry fatal-error event through the registered sink", () => {
+		const recorded: Array<{ message: string; ctx?: Record<string, string> }> =
+			[];
+		setFatalErrorTelemetry({
+			recordPageView: () => {},
+			recordError: (error, ctx) =>
+				recorded.push({ message: error.message, ctx }),
+			recordEvent: () => {},
+			recordTiming: () => {},
+		});
+
+		reportFatalError(new Error("telemetry please"));
+
+		assert.equal(recorded.length, 1);
+		assert.equal(recorded[0].message, "telemetry please");
+		assert.equal(recorded[0].ctx?.fatal, "true");
+	});
+
+	it("unsubscribe stops further notifications", () => {
+		let count = 0;
+		const unsubscribe = subscribeFatalError(() => {
+			count += 1;
+		});
+		reportFatalError(new Error("one"));
+		unsubscribe();
+		reportFatalError(new Error("two"));
+		assert.equal(count, 1);
+	});
+});
+
+describe("reportFatalError — recoverable classification", () => {
+	it("classifies a 5xx as recoverable (Retry may succeed)", () => {
+		const fatal = reportFatalError(new ApiError("boom", 503));
+		assert.equal(fatal.recoverable, true);
+	});
+
+	it("classifies a hard 4xx as not recoverable (deterministic)", () => {
+		const fatal = reportFatalError(new ApiError("bad request", 400));
+		assert.equal(fatal.recoverable, false);
+	});
+
+	it("honours an explicit recoverable=false for a caught render exception", () => {
+		const fatal = reportFatalError(new Error("date value is not finite"), {
+			recoverable: false,
+			componentStack: "\n    at Accounts\n    at Route",
+		});
+		assert.equal(fatal.recoverable, false);
+		assert.equal(fatal.componentStack, "\n    at Accounts\n    at Route");
+	});
+
+	it("carries the error stack so the bug report can seed from it", () => {
+		const error = new Error("with stack");
+		const fatal = reportFatalError(error);
+		assert.equal(fatal.stack, error.stack);
+	});
+});

package/src/lib/fatal-error.ts

@@ -0,0 +1,165 @@
+import { recordError } from "./console-errors";
+import { isServerError } from "./error-classifier";
+import type { Telemetry } from "./telemetry";
+
+/**
+ * The single escalation seam for first-party fatal errors.
+ *
+ * Calling `reportFatalError(error)` does three things, unconditionally:
+ *  1. records the error into the recent-errors ring (so the bug-report flow
+ *     picks it up),
+ *  2. emits a telemetry fatal-error event (when a telemetry sink is registered
+ *     via `setFatalErrorTelemetry` — `main.tsx` plugs the live RUM adapter in
+ *     here), and
+ *  3. notifies every subscriber — the `FatalErrorOverlay` subscribes here and
+ *     takes over the whole screen with the red escalation page.
+ *
+ * This is the one place telemetry plugs in: RUM wires in once, not per call
+ * site.
+ */
+
+export interface FatalError {
+	error: unknown;
+	/** Human-readable message extracted from the error. */
+	message: string;
+	/** Correlation id for support — distinguishes one fatal from the next. */
+	correlationId: string;
+	/** When the fatal was reported. */
+	at: number;
+	/**
+	 * Whether retrying the same action might succeed. A transient class — a 5xx,
+	 * an offline/network blip, an aborted request — is recoverable; the overlay
+	 * offers Retry. A deterministic render/exception (caught by the route error
+	 * boundary) is NOT recoverable — retry re-crashes, so the overlay offers a
+	 * way out (a safe route) instead.
+	 */
+	recoverable: boolean;
+	/** The error's stack, when it is an `Error`. Seeds the bug report. */
+	stack?: string;
+	/** React component stack from the error boundary, when available. */
+	componentStack?: string;
+}
+
+/** Options for `reportFatalError`. */
+export interface ReportFatalOptions {
+	/**
+	 * Force the recoverable classification. Omit to derive it from the error
+	 * (transient network/5xx/abort ⇒ recoverable). The route error boundary
+	 * passes `false` for a caught render exception — it is deterministic.
+	 */
+	recoverable?: boolean;
+	/** React component stack captured by the error boundary. */
+	componentStack?: string;
+}
+
+/**
+ * Default recoverable classification for an error with no explicit override.
+ * Only a 5xx is treated as recoverable — the one clearly transient class, where
+ * retrying the same action may succeed. Everything that reaches the fatal seam
+ * is otherwise deterministic: aborts and offline/network blips never escalate
+ * here (they are filtered upstream by `shouldEscalate`), so a statusless error
+ * arriving here is an uncaught/unhandled crash, not a benign network blip.
+ * A caught render exception is deterministic too — the error boundary reports
+ * it with an explicit `recoverable: false` for good measure.
+ */
+const defaultRecoverable = (error: unknown): boolean => isServerError(error);
+
+type FatalErrorListener = (fatal: FatalError) => void;
+
+const listeners = new Set<FatalErrorListener>();
+
+let current: FatalError | null = null;
+
+let telemetry: Telemetry | null = null;
+
+/**
+ * Register the telemetry sink the fatal seam emits to. Called once from
+ * `main.tsx` with the live RUM adapter (no-op telemetry when RUM is disabled).
+ */
+export const setFatalErrorTelemetry = (sink: Telemetry): void => {
+	telemetry = sink;
+};
+
+const toError = (error: unknown): Error =>
+	error instanceof Error ? error : new Error(messageOf(error));
+
+const messageOf = (error: unknown): string => {
+	if (error instanceof Error) return error.message || error.name;
+	if (typeof error === "string") return error;
+	if (
+		error &&
+		typeof error === "object" &&
+		"message" in error &&
+		typeof (error as { message: unknown }).message === "string"
+	) {
+		return (error as { message: string }).message;
+	}
+	return "An unexpected server error occurred.";
+};
+
+const newCorrelationId = (): string => {
+	if (
+		typeof globalThis.crypto !== "undefined" &&
+		typeof globalThis.crypto.randomUUID === "function"
+	) {
+		return globalThis.crypto.randomUUID();
+	}
+	return `fatal-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+};
+
+/**
+ * Report a fatal, first-party error. Idempotent in spirit: the overlay shows
+ * the first fatal and stays until the user reloads, so repeated calls only
+ * refresh the recorded entry and re-notify (a no-op for an already-mounted
+ * overlay).
+ */
+export const reportFatalError = (
+	error: unknown,
+	options?: ReportFatalOptions,
+): FatalError => {
+	const fatal: FatalError = {
+		error,
+		message: messageOf(error),
+		correlationId: newCorrelationId(),
+		at: Date.now(),
+		recoverable: options?.recoverable ?? defaultRecoverable(error),
+		stack: error instanceof Error ? error.stack : undefined,
+		componentStack: options?.componentStack,
+	};
+
+	current = fatal;
+	recordError(`Fatal: ${fatal.message} [${fatal.correlationId}]`);
+
+	// Single telemetry seam: emit the fatal through RUM (epic #658). Scrubbing
+	// of ids/tokens happens inside the RUM adapter.
+	telemetry?.recordError(toError(error), {
+		fatal: "true",
+		correlationId: fatal.correlationId,
+	});
+
+	for (const listener of listeners) {
+		listener(fatal);
+	}
+
+	return fatal;
+};
+
+/** Subscribe to fatal errors. Returns an unsubscribe function. */
+export const subscribeFatalError = (
+	listener: FatalErrorListener,
+): (() => void) => {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+};
+
+/** The most recent fatal error, if any — lets a late subscriber catch up. */
+export const getCurrentFatalError = (): FatalError | null => current;
+
+/** Test-only: clear the in-memory fatal state, listeners, and telemetry sink. */
+export const __resetFatalError = (): void => {
+	current = null;
+	listeners.clear();
+	telemetry = null;
+};

package/src/lib/folder-roles.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import type { RemitImapFolderAppointment } from "@remit/api-http-client/types.gen.ts";
+import {
+	buildMailboxRoleMap,
+	getMailboxDisplayName,
+	labelForMailbox,
+	shouldShowUnreadBadgeForRole,
+} from "./folder-roles.js";
+
+const appoint = (
+	role: RemitImapFolderAppointment["role"],
+	mailboxId: string | undefined,
+): RemitImapFolderAppointment => ({ role, mailboxId });
+
+describe("buildMailboxRoleMap", () => {
+	test("maps mailboxId to its appointed role", () => {
+		const map = buildMailboxRoleMap([
+			appoint("Inbox", "mb-inbox"),
+			appoint("Drafts", "mb-concepten"),
+		]);
+		assert.equal(map.get("mb-inbox"), "inbox");
+		assert.equal(map.get("mb-concepten"), "drafts");
+	});
+
+	test("an unfilled role (no mailboxId) contributes no entry", () => {
+		const map = buildMailboxRoleMap([appoint("Archive", undefined)]);
+		assert.equal(map.size, 0);
+	});
+
+	test("a mailbox appointed to two roles keeps the higher-priority one", () => {
+		// RFC 032: a folder may legitimately fill more than one role — the
+		// sidebar shows one row, so the map picks a single winner deterministically.
+		const map = buildMailboxRoleMap([
+			appoint("Trash", "mb-1"),
+			appoint("Inbox", "mb-1"),
+		]);
+		assert.equal(map.get("mb-1"), "inbox");
+	});
+
+	test("empty appointments produce an empty map", () => {
+		assert.equal(buildMailboxRoleMap([]).size, 0);
+	});
+});
+
+describe("getMailboxDisplayName", () => {
+	test("returns the leaf segment of a nested path", () => {
+		assert.equal(getMailboxDisplayName("INBOX/Sent Messages"), "Sent Messages");
+	});
+
+	test("returns the whole path when there is no delimiter", () => {
+		assert.equal(getMailboxDisplayName("INBOX"), "INBOX");
+	});
+});
+
+describe("labelForMailbox", () => {
+	const t = (key: string, fallback: string) =>
+		key === "sidebar.sent" ? "Verzonden" : fallback;
+
+	test("a trimmed displayNameOverride wins over everything", () => {
+		assert.equal(
+			labelForMailbox(
+				{ fullPath: "INBOX/Sent", displayNameOverride: "  My Sent  " },
+				"sent",
+				t,
+			),
+			"My Sent",
+		);
+	});
+
+	test("falls back to the translated canonical role label", () => {
+		assert.equal(
+			labelForMailbox({ fullPath: "INBOX/Verzonden" }, "sent", t),
+			"Verzonden",
+		);
+	});
+
+	test("falls back to the provider leaf when there is no role", () => {
+		assert.equal(
+			labelForMailbox({ fullPath: "INBOX/Nieuwsbrieven" }, undefined, t),
+			"Nieuwsbrieven",
+		);
+	});
+
+	test("falls back to the leaf when no translator is supplied", () => {
+		assert.equal(labelForMailbox({ fullPath: "INBOX/Sent" }, "sent"), "Sent");
+	});
+
+	test("a blank/whitespace override is ignored", () => {
+		assert.equal(
+			labelForMailbox(
+				{ fullPath: "INBOX/Sent", displayNameOverride: "   " },
+				"sent",
+				t,
+			),
+			"Verzonden",
+		);
+	});
+});
+
+describe("shouldShowUnreadBadgeForRole", () => {
+	test("hides the badge for Sent, Drafts, and Trash", () => {
+		assert.equal(shouldShowUnreadBadgeForRole("sent"), false);
+		assert.equal(shouldShowUnreadBadgeForRole("drafts"), false);
+		assert.equal(shouldShowUnreadBadgeForRole("trash"), false);
+	});
+
+	test("shows the badge for Inbox, Junk, and plain folders (no role)", () => {
+		assert.equal(shouldShowUnreadBadgeForRole("inbox"), true);
+		assert.equal(shouldShowUnreadBadgeForRole("junk"), true);
+		assert.equal(shouldShowUnreadBadgeForRole(undefined), true);
+	});
+});

package/src/lib/folder-roles.ts

@@ -0,0 +1,112 @@
+import type {
+	RemitImapCanonicalMailboxRole,
+	RemitImapFolderAppointment,
+} from "@remit/api-http-client/types.gen.ts";
+import type { NavMailboxRole } from "@remit/ui";
+
+/**
+ * RFC 032 exclusive-folder-appointment (#976): the sidebar, the move-to
+ * picker, and the per-role hooks all resolve a mailbox's role from the
+ * account's `folderAppointments` map — never by re-detecting it from the
+ * folder's name or IMAP flags. The map is server-computed (persisted choice,
+ * or a proposal for anything unfilled) and exclusive by construction: a role
+ * points at exactly one mailbox, so there is nothing left to dedupe or guess
+ * at client-side.
+ */
+
+/** `CanonicalMailboxRole` (PascalCase, wire) → kit `NavMailboxRole` (lowercase). */
+export const CANONICAL_TO_NAV_ROLE: Record<string, NavMailboxRole> = {
+	Inbox: "inbox",
+	Drafts: "drafts",
+	Sent: "sent",
+	Archive: "archive",
+	Junk: "junk",
+	Trash: "trash",
+	All: "all",
+	Flagged: "flagged",
+};
+
+/** Kit `NavMailboxRole`/`FolderRole` (lowercase) → wire `CanonicalMailboxRole`. */
+export const NAV_ROLE_TO_CANONICAL: Record<
+	NavMailboxRole,
+	RemitImapCanonicalMailboxRole
+> = {
+	inbox: "Inbox",
+	drafts: "Drafts",
+	sent: "Sent",
+	archive: "Archive",
+	junk: "Junk",
+	trash: "Trash",
+	all: "All",
+	flagged: "Flagged",
+};
+
+// Display/pin priority, matching the kit's own ROLE_ORDER (nav-sidebar.tsx).
+// Used to pick a single role when one mailbox is (unusually) appointed to more
+// than one — the RFC allows this, but a sidebar row shows one role — and to
+// order the move-to picker's system-folder rows.
+export const ROLE_PRIORITY: readonly NavMailboxRole[] = [
+	"inbox",
+	"flagged",
+	"drafts",
+	"sent",
+	"archive",
+	"all",
+	"junk",
+	"trash",
+];
+
+/**
+ * Reverse the role→mailboxId appointment map into mailboxId→role, so a
+ * mailbox row can look up its own role in O(1). When a mailbox is appointed to
+ * more than one role, the highest-priority role wins for display purposes.
+ */
+export function buildMailboxRoleMap(
+	appointments: readonly RemitImapFolderAppointment[],
+): Map<string, NavMailboxRole> {
+	const byMailbox = new Map<string, NavMailboxRole>();
+	const sorted = [...appointments].sort(
+		(a, b) =>
+			ROLE_PRIORITY.indexOf(CANONICAL_TO_NAV_ROLE[a.role]) -
+			ROLE_PRIORITY.indexOf(CANONICAL_TO_NAV_ROLE[b.role]),
+	);
+	for (const appointment of sorted) {
+		if (!appointment.mailboxId) continue;
+		if (byMailbox.has(appointment.mailboxId)) continue;
+		const role = CANONICAL_TO_NAV_ROLE[appointment.role];
+		if (role) byMailbox.set(appointment.mailboxId, role);
+	}
+	return byMailbox;
+}
+
+/** Leaf segment of a provider path (`INBOX/Spam` → `Spam`). */
+export const getMailboxDisplayName = (fullPath: string): string => {
+	const parts = fullPath.split("/");
+	return parts[parts.length - 1] || fullPath;
+};
+
+type Translator = (key: string, fallback: string) => string;
+
+/**
+ * Render-ready label: a trimmed `displayNameOverride` wins, else the
+ * canonical localized label for the appointed role, else the provider leaf.
+ */
+export function labelForMailbox(
+	mailbox: { fullPath: string; displayNameOverride?: string },
+	role: NavMailboxRole | undefined,
+	t?: Translator,
+): string {
+	const override = mailbox.displayNameOverride?.trim();
+	if (override) return override;
+	const leaf = getMailboxDisplayName(mailbox.fullPath);
+	if (!role || !t) return leaf;
+	return t(`sidebar.${role}`, leaf);
+}
+
+// Roles where a user-action-oriented unread badge isn't useful: Sent/Drafts
+// weren't sent TO the user, and Trash is deleted mail (issue #195).
+const COUNTLESS_ROLES = new Set<NavMailboxRole>(["sent", "drafts", "trash"]);
+
+export const shouldShowUnreadBadgeForRole = (
+	role: NavMailboxRole | undefined,
+): boolean => role === undefined || !COUNTLESS_ROLES.has(role);

package/src/lib/format.test.ts

@@ -0,0 +1,115 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import {
+	formatDate,
+	formatDatePreset,
+	formatDeleteToTrashTitle,
+	formatEmailDate,
+	formatRelativeTime,
+} from "./format.js";
+
+// null/undefined can arrive at runtime even though the type forbids them.
+const invalidInputs: Array<[string, unknown]> = [
+	["Invalid Date", new Date("nope")],
+	["null", null],
+	["undefined", undefined],
+	["empty string", ""],
+	["whitespace string", "   "],
+	["unparseable string", "not-a-date"],
+];
+
+describe("date formatters render invalid input as empty instead of throwing", () => {
+	for (const [label, value] of invalidInputs) {
+		test(`formatDate(${label})`, () => {
+			assert.strictEqual(
+				formatDate(value as Parameters<typeof formatDate>[0]),
+				"",
+			);
+		});
+		test(`formatDatePreset(${label})`, () => {
+			assert.strictEqual(
+				formatDatePreset(
+					value as Parameters<typeof formatDatePreset>[0],
+					"medium",
+				),
+				"",
+			);
+		});
+		test(`formatRelativeTime(${label})`, () => {
+			assert.strictEqual(
+				formatRelativeTime(value as Parameters<typeof formatRelativeTime>[0]),
+				"",
+			);
+		});
+		test(`formatEmailDate(${label})`, () => {
+			assert.strictEqual(
+				formatEmailDate(value as Parameters<typeof formatEmailDate>[0]),
+				"",
+			);
+		});
+	}
+});
+
+describe("date formatters render valid input", () => {
+	const epochMs = Date.UTC(2023, 0, 17, 12, 0, 0);
+
+	test("epoch 0 is a valid date, not a fallback", () => {
+		assert.notStrictEqual(formatDate(0), "");
+	});
+
+	test("a Date, an epoch number, and the same epoch as a string agree", () => {
+		const fromNumber = formatDate(epochMs, { year: "numeric" });
+		const fromDate = formatDate(new Date(epochMs), { year: "numeric" });
+		const fromString = formatDate(String(epochMs), { year: "numeric" });
+		assert.strictEqual(fromNumber, "2023");
+		assert.strictEqual(fromDate, "2023");
+		assert.strictEqual(fromString, "2023");
+	});
+
+	test("formatRelativeTime renders a non-empty label for a recent date", () => {
+		assert.notStrictEqual(formatRelativeTime(Date.now() - 60_000), "");
+	});
+
+	test("an ISO string with separators goes through the Date parser, not the epoch branch", () => {
+		// The /^-?\d+$/ guard only matches pure digits, so a real business date
+		// string (with "-", "T", ":", "+") is parsed as a date, never as an epoch.
+		assert.strictEqual(
+			formatDate("2026-07-07T12:34:56+02:00", {
+				year: "numeric",
+				timeZone: "UTC",
+			}),
+			"2026",
+		);
+	});
+
+	test("an all-digit string is read as epoch MILLISECONDS", () => {
+		// toDate does Number(msString); a 13-digit value is milliseconds.
+		// Seconds-based sources must pre-multiply by 1000 at the CALL SITE — a
+		// 10-digit seconds value is the caller's responsibility, not toDate's.
+		const msString = String(Date.UTC(2023, 0, 17));
+		assert.strictEqual(
+			formatDate(msString, { year: "numeric", timeZone: "UTC" }),
+			"2023",
+		);
+	});
+});
+
+describe("formatDeleteToTrashTitle", () => {
+	test("uses the singular noun for one message", () => {
+		assert.strictEqual(formatDeleteToTrashTitle(1), "Move 1 message to Trash?");
+	});
+
+	test("uses the plural noun and the count for many messages", () => {
+		assert.strictEqual(
+			formatDeleteToTrashTitle(3),
+			"Move 3 messages to Trash?",
+		);
+	});
+
+	test("treats zero as plural", () => {
+		assert.strictEqual(
+			formatDeleteToTrashTitle(0),
+			"Move 0 messages to Trash?",
+		);
+	});
+});