@remit/web-client 0.0.1

package/src/lib/bug-report.test.ts

@@ -0,0 +1,213 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { BugReportContext } from "./bug-report";
+import { buildBugReportDetails, buildGitHubIssueUrl } from "./bug-report";
+
+const baseCtx: BugReportContext = {
+	appSha: "abcdef1234567890abcdef1234567890abcdef12",
+	appShortSha: "abcdef1",
+	appBuildTime: "2024-01-15T10:30:00.000Z",
+	userAgent: "Mozilla/5.0 (Test Browser)",
+	viewport: "1440×900",
+	timestamp: "2024-06-12T08:00:00.000Z",
+	timezone: "Europe/Amsterdam",
+	href: "https://app.example.com/mail/inbox?q=test",
+	recentErrors: [],
+};
+
+/**
+ * URLSearchParams encodes spaces as `+`, but decodeURIComponent does not
+ * decode `+` back to space. Replace `+` first so assertions on
+ * human-readable strings work as expected.
+ */
+function decode(url: string): string {
+	return decodeURIComponent(url.replaceAll("+", " "));
+}
+
+describe("buildGitHubIssueUrl", () => {
+	it("returns a URL pointing at the GitHub new-issue endpoint", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		assert.ok(
+			url.startsWith("https://github.com/remit-mail/remit/issues/new?"),
+			`Expected GitHub issues URL, got: ${url}`,
+		);
+	});
+
+	it("prefills a title param", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		assert.ok(url.includes("title="), "Expected a title param");
+	});
+
+	it("includes the short SHA in the body", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(decoded.includes("abcdef1"), "Expected short SHA in body");
+	});
+
+	it("includes the full SHA commit link in the body", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("abcdef1234567890abcdef1234567890abcdef12"),
+			"Expected full SHA in commit link",
+		);
+	});
+
+	it("includes build time in the body", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("2024-01-15T10:30:00.000Z"),
+			"Expected build time in body",
+		);
+	});
+
+	it("includes the user agent", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("Mozilla/5.0 (Test Browser)"),
+			"Expected userAgent in body",
+		);
+	});
+
+	it("includes the viewport", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(decoded.includes("1440×900"), "Expected viewport in body");
+	});
+
+	it("includes the timestamp", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("2024-06-12T08:00:00.000Z"),
+			"Expected timestamp in body",
+		);
+	});
+
+	it("includes the timezone", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("Europe/Amsterdam"),
+			"Expected timezone in body",
+		);
+	});
+
+	it("includes the page URL", () => {
+		const url = buildGitHubIssueUrl(baseCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("https://app.example.com/mail/inbox"),
+			"Expected page href in body",
+		);
+	});
+
+	it("shows (none) when there are no recent errors", () => {
+		const url = buildGitHubIssueUrl({ ...baseCtx, recentErrors: [] });
+		const decoded = decode(url);
+		assert.ok(decoded.includes("(none)"), "Expected (none) for empty errors");
+	});
+
+	it("includes recent console errors when present", () => {
+		const ctx: BugReportContext = {
+			...baseCtx,
+			recentErrors: [
+				"TypeError: Cannot read property x of undefined",
+				"Network error: 503",
+			],
+		};
+		const url = buildGitHubIssueUrl(ctx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("TypeError: Cannot read property"),
+			"Expected first error in body",
+		);
+		assert.ok(
+			decoded.includes("Network error: 503"),
+			"Expected second error in body",
+		);
+	});
+
+	it("keeps the URL parseable after encoding", () => {
+		const ctx: BugReportContext = {
+			...baseCtx,
+			recentErrors: ["Error: something & weird <happened>"],
+		};
+		const url = buildGitHubIssueUrl(ctx);
+		assert.doesNotThrow(() => new URL(url), "URL must be valid");
+	});
+});
+
+describe("buildGitHubIssueUrl — seeded from a caught error", () => {
+	const seededCtx: BugReportContext = {
+		...baseCtx,
+		errorMessage: "date value is not finite in DateTimeFormat format()",
+		stack: "Error: date value is not finite\n    at format (util.ts:12)",
+		componentStack: "\n    at AccountsSettings\n    at Route",
+	};
+
+	it("puts the error message in the title", () => {
+		const url = buildGitHubIssueUrl(seededCtx);
+		const decoded = decode(url);
+		assert.ok(
+			decoded.includes("title=Bug: date value is not finite"),
+			"Expected the error message in the issue title",
+		);
+	});
+
+	it("includes the stacktrace and component stack in the body", () => {
+		const decoded = decode(buildGitHubIssueUrl(seededCtx));
+		assert.ok(
+			decoded.includes("## Stacktrace"),
+			"Expected a stacktrace section",
+		);
+		assert.ok(
+			decoded.includes("at format (util.ts:12)"),
+			"Expected the stack frame in the body",
+		);
+		assert.ok(
+			decoded.includes("## Component stack"),
+			"Expected a component-stack section",
+		);
+	});
+});
+
+describe("buildGitHubIssueUrl — truncation to fit the URL budget", () => {
+	const hugeStack = `Error: boom\n${"    at frame (file.ts:1)\n".repeat(2000)}`;
+	const hugeCtx: BugReportContext = {
+		...baseCtx,
+		errorMessage: "boom",
+		stack: hugeStack,
+	};
+
+	it("keeps the truncated URL under the GitHub length limit", () => {
+		const url = buildGitHubIssueUrl(hugeCtx);
+		assert.ok(
+			url.length <= 8000,
+			`Expected a URL under 8000 chars, got ${url.length}`,
+		);
+	});
+
+	it("marks the body as truncated and stays a valid URL", () => {
+		const url = buildGitHubIssueUrl(hugeCtx);
+		assert.ok(
+			decode(url).includes("truncated"),
+			"Expected a truncation marker",
+		);
+		assert.doesNotThrow(() => new URL(url), "Truncated URL must be valid");
+	});
+
+	it("Copy full details keeps the whole stacktrace (nothing lost)", () => {
+		const details = buildBugReportDetails(hugeCtx);
+		assert.ok(
+			details.includes(hugeStack),
+			"Expected the full untruncated stack in the copy-details report",
+		);
+		assert.ok(
+			details.length > buildGitHubIssueUrl(hugeCtx).length,
+			"Full details should be longer than the truncated URL body",
+		);
+	});
+});

package/src/lib/bug-report.ts

@@ -0,0 +1,176 @@
+import {
+	APP_BUILD_TIME,
+	APP_SHA,
+	APP_SHORT_SHA,
+	GITHUB_NEW_ISSUE_URL,
+} from "./app-info";
+import { getRecentErrors } from "./console-errors";
+
+/**
+ * A GitHub new-issue URL is capped (~8 KB). We budget below that so the stack
+ * is truncated to fit rather than producing a URL GitHub silently rejects. The
+ * untruncated report is always available via `buildBugReportDetails` (the
+ * overlay's "Copy full details" action).
+ */
+const MAX_ISSUE_URL_LENGTH = 7500;
+
+const TRUNCATION_MARKER =
+	"\n… (truncated — use “Copy full details” for the full stacktrace)";
+
+export interface BugReportContext {
+	appSha: string;
+	appShortSha: string;
+	appBuildTime: string;
+	userAgent: string;
+	viewport: string;
+	timestamp: string;
+	timezone: string;
+	href: string;
+	recentErrors: readonly string[];
+	/** The message of the error that triggered the report, when seeded from one. */
+	errorMessage?: string;
+	/** The error's stacktrace, when available. */
+	stack?: string;
+	/** React component stack from the error boundary, when available. */
+	componentStack?: string;
+}
+
+/** Fields callers can seed from a caught error. */
+export interface BugReportSeed {
+	errorMessage?: string;
+	stack?: string;
+	componentStack?: string;
+}
+
+export function buildBugReportContext(seed?: BugReportSeed): BugReportContext {
+	return {
+		appSha: APP_SHA,
+		appShortSha: APP_SHORT_SHA,
+		appBuildTime: APP_BUILD_TIME,
+		userAgent: navigator.userAgent,
+		viewport: `${window.innerWidth}×${window.innerHeight}`,
+		timestamp: new Date().toISOString(),
+		timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+		href: window.location.href,
+		recentErrors: getRecentErrors(),
+		errorMessage: seed?.errorMessage,
+		stack: seed?.stack,
+		componentStack: seed?.componentStack,
+	};
+}
+
+function fencedBlock(content: string): string {
+	return ["```", content, "```"].join("\n");
+}
+
+function buildIssueBody(ctx: BugReportContext, stack?: string): string {
+	const errorSection =
+		ctx.recentErrors.length > 0
+			? ctx.recentErrors.map((e) => `  - ${e}`).join("\n")
+			: "  (none)";
+
+	const lines: string[] = [
+		"## Environment",
+		`- **Version**: [\`${ctx.appShortSha}\`](https://github.com/remit-mail/remit/commit/${ctx.appSha}) built ${ctx.appBuildTime}`,
+		`- **Browser**: ${ctx.userAgent}`,
+		`- **Viewport**: ${ctx.viewport}`,
+		`- **Time**: ${ctx.timestamp} (${ctx.timezone})`,
+		"",
+		"## URL",
+		ctx.href,
+		"",
+	];
+
+	if (ctx.errorMessage) {
+		lines.push("## Error", ctx.errorMessage, "");
+	}
+
+	const resolvedStack = stack ?? ctx.stack;
+	if (resolvedStack) {
+		lines.push("## Stacktrace", fencedBlock(resolvedStack), "");
+	}
+
+	if (ctx.componentStack) {
+		lines.push("## Component stack", fencedBlock(ctx.componentStack), "");
+	}
+
+	lines.push(
+		"## Recent console errors",
+		errorSection,
+		"",
+		"## Steps to reproduce",
+		"1. ",
+		"",
+		"## Expected behaviour",
+		"",
+		"## Actual behaviour",
+		"",
+	);
+
+	return lines.join("\n");
+}
+
+function buildIssueTitle(ctx: BugReportContext): string {
+	if (!ctx.errorMessage) return "Bug: ";
+	const firstLine = ctx.errorMessage.split("\n")[0].trim();
+	const clipped =
+		firstLine.length > 120 ? `${firstLine.slice(0, 117)}…` : firstLine;
+	return `Bug: ${clipped}`;
+}
+
+function issueUrl(ctx: BugReportContext, stack?: string): string {
+	const params = new URLSearchParams({
+		title: buildIssueTitle(ctx),
+		body: buildIssueBody(ctx, stack),
+	});
+	return `${GITHUB_NEW_ISSUE_URL}?${params.toString()}`;
+}
+
+/**
+ * The full, untruncated report — every field including the complete stacktrace
+ * and component stack. Backs the overlay's "Copy full details" action so
+ * nothing is lost when the URL-bound report has to truncate the stack.
+ */
+export function buildBugReportDetails(ctx: BugReportContext): string {
+	return buildIssueBody(ctx);
+}
+
+/**
+ * Build a prefilled GitHub new-issue URL. When the full body would exceed the
+ * URL budget, the stacktrace is truncated (binary-searched to the longest
+ * prefix that fits) and marked; everything else is preserved. The component
+ * stack is dropped from the URL when truncation kicks in — it survives in the
+ * "Copy full details" report.
+ */
+export function buildGitHubIssueUrl(ctx: BugReportContext): string {
+	const full = issueUrl(ctx);
+	if (full.length <= MAX_ISSUE_URL_LENGTH) return full;
+
+	const stack = ctx.stack ?? "";
+	const withoutComponentStack: BugReportContext = {
+		...ctx,
+		componentStack: undefined,
+	};
+
+	let lo = 0;
+	let hi = stack.length;
+	let best = 0;
+	while (lo <= hi) {
+		const mid = (lo + hi) >> 1;
+		const candidate = issueUrl(
+			withoutComponentStack,
+			stack.slice(0, mid) + TRUNCATION_MARKER,
+		);
+		if (candidate.length <= MAX_ISSUE_URL_LENGTH) {
+			best = mid;
+			lo = mid + 1;
+		} else {
+			hi = mid - 1;
+		}
+	}
+
+	return issueUrl(
+		withoutComponentStack,
+		stack.slice(0, best) + TRUNCATION_MARKER,
+	);
+}

package/src/lib/client.ts

@@ -0,0 +1,36 @@
+import { client } from "@remit/api-http-client/client.gen.ts";
+import { getRuntimeConfig } from "../runtime-config";
+import { ApiError } from "./api";
+
+// In production, the config.js apiUrl points at the deployed API Gateway.
+// In local dev, the Vite proxy forwards /api -> localhost:4321 (see vite.config.ts).
+const baseUrl = getRuntimeConfig().apiUrl;
+
+client.setConfig({
+	baseUrl,
+});
+
+/**
+ * The hey-api client throws the parsed JSON error *body* on a non-ok response —
+ * a shape with no HTTP status. That makes it impossible to tell a 404 (expected)
+ * from a 500 (fatal) at the call site, which is the whole point of the fail-fast
+ * classifier. This error interceptor re-wraps every HTTP error as an `ApiError`
+ * carrying `response.status`, so `shouldEscalate` / `getErrorStatus` work
+ * uniformly across both clients. The body's `message` is preserved on the
+ * `ApiError` so existing message-prefix checks (e.g. `isMessageNotFoundError`)
+ * keep working.
+ */
+client.interceptors.error.use((error, response) => {
+	if (error instanceof ApiError) return error;
+	if (!response) return error;
+
+	const body = error;
+	const message =
+		body && typeof body === "object" && "message" in body
+			? String((body as { message: unknown }).message)
+			: `Request failed with status ${response.status}`;
+
+	return new ApiError(message, response.status, body);
+});
+
+export { client };

package/src/lib/console-errors.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { install } from "./console-errors";
+import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+
+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 emitWindowError(stub: WindowStub, message: string): void {
+	const handler = stub.listeners.get("error");
+	assert.ok(handler, "install() should register a window error handler");
+	handler({ message, error: null, filename: "app.js", lineno: 0 });
+}
+
+describe("console-errors window error handling", () => {
+	const originalConsoleError = console.error;
+
+	afterEach(() => {
+		__resetFatalError();
+		console.error = originalConsoleError;
+		delete (globalThis as unknown as { window?: unknown }).window;
+	});
+
+	it("does not escalate benign ResizeObserver noise", () => {
+		const stub = installWindowStub();
+		const escalated: string[] = [];
+		subscribeFatalError((fatal) => escalated.push(fatal.message));
+		install();
+
+		emitWindowError(stub, "ResizeObserver loop limit exceeded");
+		emitWindowError(
+			stub,
+			"ResizeObserver loop completed with undelivered notifications.",
+		);
+
+		assert.deepEqual(escalated, []);
+	});
+
+	it("escalates an arbitrary uncaught error", () => {
+		const stub = installWindowStub();
+		const escalated: string[] = [];
+		subscribeFatalError((fatal) => escalated.push(fatal.message));
+		install();
+
+		emitWindowError(stub, "TypeError: boom");
+
+		assert.equal(escalated.length, 1);
+	});
+});

package/src/lib/console-errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Tiny ring-buffer that captures the last N console errors, uncaught
+ * exceptions, and unhandled promise rejections. Install once at app
+ * startup; consumers call getRecentErrors() to read the buffer.
+ *
+ * Dependency-free and side-effect-free until install() is called.
+ */
+
+import { reportFatalError } from "./fatal-error";
+
+const MAX_ENTRIES = 20;
+
+const ring: string[] = [];
+
+// Browser-spec noise, not app errors: the ResizeObserver spec fires these when
+// observation callbacks don't settle within a frame. They surface as window
+// `error` events with a null `error` and are safe to ignore. The live message
+// carries a trailing period, so strip it before matching this canonical set.
+const BENIGN_RESIZE_OBSERVER_MESSAGES = new Set([
+	"ResizeObserver loop limit exceeded",
+	"ResizeObserver loop completed with undelivered notifications",
+]);
+
+function isBenignResizeObserverError(message: unknown): boolean {
+	if (typeof message !== "string") return false;
+	return BENIGN_RESIZE_OBSERVER_MESSAGES.has(message.replace(/\.\s*$/, ""));
+}
+
+function push(entry: string): void {
+	ring.push(entry);
+	if (ring.length > MAX_ENTRIES) ring.shift();
+}
+
+/**
+ * Record a single line into the recent-errors ring. Exposed so the global
+ * `reportFatalError` seam (lib/fatal-error.ts) can land fatal errors in the
+ * same buffer the bug-report flow reads, without re-implementing the ring.
+ */
+export function recordError(entry: string): void {
+	push(entry);
+}
+
+function formatArgs(args: unknown[]): string {
+	return args
+		.map((a) => {
+			if (typeof a === "string") return a;
+			if (a instanceof Error) return `${a.name}: ${a.message}`;
+			try {
+				return JSON.stringify(a);
+			} catch {
+				return String(a);
+			}
+		})
+		.join(" ");
+}
+
+export function install(): void {
+	const originalError = console.error.bind(console);
+	console.error = (...args: unknown[]) => {
+		push(formatArgs(args));
+		originalError(...args);
+	};
+
+	window.addEventListener("error", (event: ErrorEvent) => {
+		if (isBenignResizeObserverError(event.message)) return;
+		push(
+			`Uncaught ${event.error instanceof Error ? `${event.error.name}: ${event.error.message}` : String(event.message)} (${event.filename}:${event.lineno})`,
+		);
+		// An uncaught exception is, by definition, unhandled — escalate it.
+		reportFatalError(event.error ?? event.message);
+	});
+
+	window.addEventListener(
+		"unhandledrejection",
+		(event: PromiseRejectionEvent) => {
+			const reason = event.reason;
+			const detail =
+				reason instanceof Error
+					? `${reason.name}: ${reason.message}`
+					: String(reason);
+			push(`Unhandled rejection: ${detail}`);
+			// A rejection that bubbles to the window was never handled by any
+			// caller — route it through the same fatal seam.
+			reportFatalError(reason);
+		},
+	);
+}
+
+/** Returns a copy of the captured entries (oldest first, up to 20). */
+export function getRecentErrors(): readonly string[] {
+	return ring.slice();
+}

package/src/lib/conversation-target.test.ts

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { buildConversationTarget } from "./conversation-target.js";
+
+function thread(
+	overrides: Partial<RemitImapThreadMessageResponse> = {},
+): RemitImapThreadMessageResponse {
+	return {
+		messageId: "m1",
+		threadId: "t1",
+		mailboxId: "mb1",
+		subject: "Loaded subject",
+		isRead: false,
+		...overrides,
+	} as RemitImapThreadMessageResponse;
+}
+
+describe("buildConversationTarget", () => {
+	test("prefers the loaded thread, carrying its display fields", () => {
+		const authenticity = { dkimMismatch: true, fromDomain: "example.com" };
+		const target = buildConversationTarget(thread({ authenticity }), {
+			messageId: "m1",
+			threadId: "ignored",
+			mailboxId: "ignored",
+		});
+		assert.deepEqual(target, {
+			threadId: "t1",
+			mailboxId: "mb1",
+			subject: "Loaded subject",
+			messageId: "m1",
+			authenticity,
+		});
+	});
+
+	// The bug: a tapped semantic "Related" hit's message isn't in the loaded list,
+	// so there is no thread to resolve — it must still open from the URL hints.
+	test("falls back to the URL thread + mailbox when no thread is loaded", () => {
+		const target = buildConversationTarget(undefined, {
+			messageId: "m9",
+			threadId: "t9",
+			mailboxId: "mb9",
+		});
+		assert.deepEqual(target, {
+			threadId: "t9",
+			mailboxId: "mb9",
+			messageId: "m9",
+		});
+	});
+
+	test("returns undefined when the message is cleared (Back pressed)", () => {
+		const target = buildConversationTarget(undefined, {
+			messageId: undefined,
+			threadId: "t9",
+			mailboxId: "mb9",
+		});
+		assert.equal(target, undefined);
+	});
+
+	test("returns undefined without a threadId to open", () => {
+		const target = buildConversationTarget(undefined, {
+			messageId: "m9",
+			threadId: undefined,
+			mailboxId: "mb9",
+		});
+		assert.equal(target, undefined);
+	});
+});