@remit/web-client 0.0.1

package/src/lib/conversation-target.ts

@@ -0,0 +1,59 @@
+/**
+ * The minimal data needed to open a conversation. A list view normally opens the
+ * thread it already has loaded, but a semantic "Related" search hit can point at a
+ * message that isn't in the loaded list at all. Such a hit still carries its
+ * `threadId` and `mailboxId`, and `ConversationView` fetches by `threadId`, so we
+ * can open it directly from those alone — no dependency on the loaded list.
+ */
+import type {
+	RemitImapMessageAuthenticity,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+
+export interface ConversationTarget {
+	threadId: string;
+	mailboxId: string;
+	subject?: string;
+	messageId?: string;
+	authenticity?: RemitImapMessageAuthenticity;
+}
+
+function threadToConversationTarget(
+	thread: RemitImapThreadMessageResponse,
+): ConversationTarget {
+	return {
+		threadId: thread.threadId,
+		mailboxId: thread.mailboxId,
+		subject: thread.subject,
+		messageId: thread.messageId,
+		authenticity: thread.authenticity,
+	};
+}
+
+/**
+ * Resolve the conversation to open. Prefer the fully loaded thread (it carries
+ * the subject, authenticity and read state the reading pane wants); otherwise
+ * fall back to the `threadId` + `mailboxId` carried in the URL by a tapped
+ * "Related" hit so a message outside the loaded list still opens.
+ */
+export function buildConversationTarget(
+	selectedThread: RemitImapThreadMessageResponse | undefined,
+	fallback: {
+		messageId?: string;
+		threadId?: string;
+		mailboxId?: string;
+	},
+): ConversationTarget | undefined {
+	if (selectedThread) return threadToConversationTarget(selectedThread);
+	// Require the messageId too: it's always set alongside the threadId when a
+	// result is tapped, and gating on it means clearing `selectedMessageId` (e.g.
+	// pressing Back) closes the conversation even if a stale threadId lingers.
+	if (fallback.messageId && fallback.threadId && fallback.mailboxId) {
+		return {
+			threadId: fallback.threadId,
+			mailboxId: fallback.mailboxId,
+			messageId: fallback.messageId,
+		};
+	}
+	return undefined;
+}

package/src/lib/display-category.ts

@@ -0,0 +1,20 @@
+import type { RemitImapMessageCategory } from "@remit/api-http-client/types.gen.ts";
+import type { ThreadCategory } from "@remit/ui";
+
+/**
+ * Map an API message category to a kit display category.
+ *
+ * The API category is total (RFC 032 Tier 2) and carries `uncategorized` for
+ * messages that are metadata-synced but not yet body-classified. The kit's
+ * display unions (`ThreadCategory`, `EmailRenderCategory`, badge `MessageCategory`)
+ * have no `uncategorized` member — there is nothing to show for "not yet
+ * classified", so it collapses to `personal`, the classifier's own fallback and
+ * the display default that never renders a badge. Pre-migration rows that still
+ * read `undefined` collapse the same way.
+ */
+export function toDisplayCategory(
+	category: RemitImapMessageCategory | undefined,
+): ThreadCategory {
+	if (category === undefined || category === "uncategorized") return "personal";
+	return category;
+}

package/src/lib/drafts.test.ts

@@ -0,0 +1,241 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import type {
+	RemitImapOutboxMessageResponse,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import { groupDraftSections } from "./drafts.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function outboxMessage(
+	overrides: Partial<RemitImapOutboxMessageResponse> &
+		Pick<RemitImapOutboxMessageResponse, "outboxMessageId" | "accountId">,
+): RemitImapOutboxMessageResponse {
+	return {
+		fromAddress: "me@example.com",
+		toAddresses: ["alice@example.com"],
+		status: "draft",
+		createdAt: 1_000_000,
+		updatedAt: 1_000_000,
+		...overrides,
+	} as RemitImapOutboxMessageResponse;
+}
+
+function threadMessage(
+	overrides: Partial<RemitImapThreadMessageResponse> &
+		Pick<
+			RemitImapThreadMessageResponse,
+			"threadMessageId" | "threadId" | "messageId" | "accountConfigId"
+		>,
+): RemitImapThreadMessageResponse {
+	return {
+		mailboxId: "mb-drafts",
+		sentDate: 1_000_000,
+		isRead: false,
+		hasAttachment: false,
+		hasStars: false,
+		isDeleted: false,
+		...overrides,
+	} as RemitImapThreadMessageResponse;
+}
+
+// ---------------------------------------------------------------------------
+// groupDraftSections
+// ---------------------------------------------------------------------------
+
+describe("groupDraftSections", () => {
+	test("returns empty array when both sources are empty", () => {
+		const sections = groupDraftSections({
+			outboxMessages: [],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.deepStrictEqual(sections, []);
+	});
+
+	test("returns only Remit-drafts section when there are no IMAP threads", () => {
+		const draft = outboxMessage({
+			outboxMessageId: "d1",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draft],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.strictEqual(sections.length, 1);
+		assert.strictEqual(sections[0].id, "remit-drafts");
+		assert.strictEqual(sections[0].threads.length, 1);
+		assert.strictEqual(sections[0].threads[0].id, "d1");
+	});
+
+	test("returns only IMAP-drafts section when there are no Remit drafts", () => {
+		const thread = threadMessage({
+			threadMessageId: "tm1",
+			threadId: "t1",
+			messageId: "m1",
+			accountConfigId: "acc-1",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [],
+			accountId: "acc-1",
+			imapThreads: [thread],
+		});
+		assert.strictEqual(sections.length, 1);
+		assert.strictEqual(sections[0].id, "imap-drafts");
+		assert.strictEqual(sections[0].threads.length, 1);
+		assert.strictEqual(sections[0].threads[0].id, "m1");
+	});
+
+	test("returns both sections when both sources have rows", () => {
+		const draft = outboxMessage({
+			outboxMessageId: "d1",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const thread = threadMessage({
+			threadMessageId: "tm1",
+			threadId: "t1",
+			messageId: "m1",
+			accountConfigId: "acc-1",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draft],
+			accountId: "acc-1",
+			imapThreads: [thread],
+		});
+		assert.strictEqual(sections.length, 2);
+		assert.deepStrictEqual(
+			sections.map((s) => s.id),
+			["remit-drafts", "imap-drafts"],
+		);
+	});
+
+	test("per-account filter: only drafts for the given accountId appear", () => {
+		const draftOwner = outboxMessage({
+			outboxMessageId: "d1",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const draftOther = outboxMessage({
+			outboxMessageId: "d2",
+			accountId: "acc-2",
+			status: "draft",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draftOwner, draftOther],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.strictEqual(sections.length, 1);
+		assert.strictEqual(sections[0].threads.length, 1);
+		assert.strictEqual(sections[0].threads[0].id, "d1");
+	});
+
+	test("status filter: non-draft statuses are excluded from Remit section", () => {
+		const draft = outboxMessage({
+			outboxMessageId: "d1",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const queued = outboxMessage({
+			outboxMessageId: "q1",
+			accountId: "acc-1",
+			status: "queued",
+		});
+		const failed = outboxMessage({
+			outboxMessageId: "f1",
+			accountId: "acc-1",
+			status: "failed",
+		});
+		const blocked = outboxMessage({
+			outboxMessageId: "b1",
+			accountId: "acc-1",
+			status: "blocked",
+		});
+		const sending = outboxMessage({
+			outboxMessageId: "s1",
+			accountId: "acc-1",
+			status: "sending",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draft, queued, failed, blocked, sending],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.strictEqual(sections.length, 1);
+		// Only the draft should appear
+		assert.strictEqual(sections[0].threads.length, 1);
+		assert.strictEqual(sections[0].threads[0].id, "d1");
+	});
+
+	test("empty sections are omitted when status filter removes all drafts", () => {
+		const queued = outboxMessage({
+			outboxMessageId: "q1",
+			accountId: "acc-1",
+			status: "queued",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [queued],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.deepStrictEqual(sections, []);
+	});
+
+	test("section labels match spec", () => {
+		const draft = outboxMessage({
+			outboxMessageId: "d1",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const thread = threadMessage({
+			threadMessageId: "tm1",
+			threadId: "t1",
+			messageId: "m1",
+			accountConfigId: "acc-1",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draft],
+			accountId: "acc-1",
+			imapThreads: [thread],
+		});
+		assert.deepStrictEqual(
+			sections.map((s) => s.label),
+			["Not yet sent (Remit)", "On the server"],
+		);
+	});
+
+	test("Remit-drafts section row id equals outboxMessageId", () => {
+		const draft = outboxMessage({
+			outboxMessageId: "outbox-abc",
+			accountId: "acc-1",
+			status: "draft",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [draft],
+			accountId: "acc-1",
+			imapThreads: [],
+		});
+		assert.strictEqual(sections[0].threads[0].id, "outbox-abc");
+	});
+
+	test("IMAP-drafts section row id equals messageId", () => {
+		const thread = threadMessage({
+			threadMessageId: "tm1",
+			threadId: "t1",
+			messageId: "msg-xyz",
+			accountConfigId: "acc-1",
+		});
+		const sections = groupDraftSections({
+			outboxMessages: [],
+			accountId: "acc-1",
+			imapThreads: [thread],
+		});
+		assert.strictEqual(sections[0].threads[0].id, "msg-xyz");
+	});
+});

package/src/lib/drafts.ts

@@ -0,0 +1,121 @@
+/**
+ * Drafts view grouping logic.
+ *
+ * Pure function: takes Remit outbox drafts and IMAP thread rows and returns
+ * two labeled sections:
+ *
+ *  1. Not yet sent (Remit) — outbox rows with status === "draft" belonging to
+ *     the account that owns the open \Drafts mailbox.
+ *  2. On the server — IMAP \Drafts thread rows already loaded for the mailbox.
+ *
+ * Sections with no rows are omitted entirely (mirrors groupBriefSections).
+ *
+ * --- Dedup note ---
+ * Remit draft rows and IMAP \Drafts messages are rendered in both sections
+ * without client-side dedup. There is currently no IMAP APPEND-as-draft path
+ * and no IMAP uid / Message-ID back-reference on the outbox model, so the two
+ * sets are distinct objects with no shared key. If a future change starts
+ * appending Remit drafts into IMAP \Drafts the dedup key would be the RFC822
+ * `Message-ID` header. Until that ships, rendering both sections faithfully is
+ * the correct behaviour (issue #505).
+ */
+
+import type {
+	RemitImapOutboxMessageResponse,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { ThreadRowData, ThreadSection } from "@remit/ui";
+import { formatEmailDate } from "./format.js";
+
+/**
+ * Map a Remit outbox draft to the ThreadRowData shape used by remit-ui row
+ * components.
+ */
+export function toDraftRowData(
+	draft: RemitImapOutboxMessageResponse,
+): ThreadRowData {
+	const recipients = draft.toAddresses.join(", ");
+	return {
+		id: draft.outboxMessageId,
+		accountId: draft.accountId,
+		fromName: draft.fromName ?? draft.fromAddress ?? "Me",
+		fromEmail: draft.fromAddress ?? "",
+		subject: draft.subject ?? "(No subject)",
+		snippet: recipients ? `To: ${recipients}` : "(No recipients)",
+		timeLabel: formatEmailDate(draft.updatedAt),
+		isRead: true,
+	};
+}
+
+/**
+ * Map a RemitImapThreadMessageResponse to the ThreadRowData shape used by
+ * remit-ui row body components.  Mirrors toThreadRowData in lib/brief.ts.
+ */
+export function toImapDraftRowData(
+	thread: RemitImapThreadMessageResponse,
+): ThreadRowData {
+	return {
+		id: thread.messageId,
+		accountId: thread.accountConfigId,
+		fromName: thread.fromName ?? thread.fromEmail ?? "Unknown",
+		fromEmail: thread.fromEmail ?? "",
+		subject: thread.subject ?? "(No subject)",
+		snippet: thread.snippet ?? "",
+		timeLabel: formatEmailDate(thread.sentDate),
+		isRead: thread.isRead,
+		hasAttachment: thread.hasAttachment,
+		starred:
+			thread.star != null && thread.star !== "none" && thread.hasStars === true,
+	};
+}
+
+export interface GroupDraftSectionsInput {
+	/** All outbox messages. Will be filtered to status === "draft" and accountId. */
+	outboxMessages: RemitImapOutboxMessageResponse[];
+	/** The accountId that owns the open \Drafts mailbox. */
+	accountId: string;
+	/** Thread rows already loaded for the \Drafts mailbox (IMAP). */
+	imapThreads: RemitImapThreadMessageResponse[];
+}
+
+/**
+ * Group outbox drafts and IMAP thread rows into the two-section Drafts view.
+ *
+ * @param input.outboxMessages  Full outbox list (will be filtered here).
+ * @param input.accountId       Owner account of the open \Drafts mailbox.
+ * @param input.imapThreads     IMAP \Drafts threads already loaded.
+ * @returns                     Array of ThreadSection — empty sections omitted.
+ */
+export function groupDraftSections({
+	outboxMessages,
+	accountId,
+	imapThreads,
+}: GroupDraftSectionsInput): ThreadSection[] {
+	// Only outbox rows with status === "draft" for this account. failed/blocked
+	// rows live in the Outbox view and must never appear in Drafts (issue #505).
+	const remitDrafts = outboxMessages
+		.filter((m) => m.status === "draft" && m.accountId === accountId)
+		.map(toDraftRowData);
+
+	const imapDrafts = imapThreads.map(toImapDraftRowData);
+
+	const sections: ThreadSection[] = [];
+
+	if (remitDrafts.length > 0) {
+		sections.push({
+			id: "remit-drafts",
+			label: "Not yet sent (Remit)",
+			threads: remitDrafts,
+		});
+	}
+
+	if (imapDrafts.length > 0) {
+		sections.push({
+			id: "imap-drafts",
+			label: "On the server",
+			threads: imapDrafts,
+		});
+	}
+
+	return sections;
+}

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

@@ -0,0 +1,133 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ApiError } from "./api";
+import {
+	getErrorStatus,
+	hasHttpStatus,
+	isAbortError,
+	isNetworkError,
+	isServerError,
+	shouldEscalate,
+} from "./error-classifier";
+
+const abortError = (): Error => {
+	const error = new Error("aborted");
+	error.name = "AbortError";
+	return error;
+};
+
+describe("getErrorStatus", () => {
+	it("reads status off an ApiError", () => {
+		assert.equal(getErrorStatus(new ApiError("boom", 503)), 503);
+	});
+
+	it("reads a numeric status off a plain object", () => {
+		assert.equal(getErrorStatus({ status: 500 }), 500);
+		assert.equal(getErrorStatus({ statusCode: 404 }), 404);
+	});
+
+	it("returns undefined when no status is present", () => {
+		assert.equal(getErrorStatus(new Error("network")), undefined);
+		assert.equal(getErrorStatus("nope"), undefined);
+		assert.equal(getErrorStatus(null), undefined);
+	});
+});
+
+describe("isServerError", () => {
+	it("is true for any 5xx", () => {
+		assert.equal(isServerError(new ApiError("boom", 500)), true);
+		assert.equal(isServerError(new ApiError("boom", 502)), true);
+		assert.equal(isServerError({ status: 599 }), true);
+	});
+
+	it("is false for a 4xx", () => {
+		assert.equal(isServerError(new ApiError("not found", 404)), false);
+		assert.equal(isServerError(new ApiError("forbidden", 403)), false);
+	});
+
+	it("is false for a statusless error", () => {
+		assert.equal(isServerError(new TypeError("Failed to fetch")), false);
+		assert.equal(isServerError(undefined), false);
+	});
+});
+
+describe("hasHttpStatus", () => {
+	it("is true when the error carries a status", () => {
+		assert.equal(hasHttpStatus(new ApiError("boom", 500)), true);
+		assert.equal(hasHttpStatus({ statusCode: 404 }), true);
+	});
+
+	it("is false for a statusless error", () => {
+		assert.equal(hasHttpStatus(new TypeError("Failed to fetch")), false);
+		assert.equal(hasHttpStatus(null), false);
+	});
+});
+
+describe("isAbortError", () => {
+	it("is true for an AbortError", () => {
+		assert.equal(isAbortError(abortError()), true);
+	});
+
+	it("is false for anything else", () => {
+		assert.equal(isAbortError(new ApiError("boom", 500)), false);
+		assert.equal(isAbortError(new TypeError("Failed to fetch")), false);
+	});
+});
+
+describe("isNetworkError", () => {
+	it("is true for a statusless transport failure", () => {
+		assert.equal(isNetworkError(new TypeError("Failed to fetch")), true);
+		assert.equal(isNetworkError(new Error("network down")), true);
+	});
+
+	it("is false for an aborted request (its own category)", () => {
+		assert.equal(isNetworkError(abortError()), false);
+	});
+
+	it("is false when the error carries a status", () => {
+		assert.equal(isNetworkError(new ApiError("boom", 500)), false);
+		assert.equal(isNetworkError(new ApiError("not found", 404)), false);
+	});
+});
+
+describe("shouldEscalate (the fail-fast decision table — #1059)", () => {
+	it("escalates a 5xx by default", () => {
+		assert.equal(shouldEscalate(new ApiError("boom", 500)), true);
+		assert.equal(shouldEscalate(new ApiError("boom", 503)), true);
+	});
+
+	it("escalates a 5xx EVEN when the call site marked it soft (rule 2 wins)", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("boom", 500), { softError: true }),
+			true,
+		);
+	});
+
+	it("escalates a 4xx by DEFAULT (no opt-out)", () => {
+		assert.equal(shouldEscalate(new ApiError("not found", 404)), true);
+		assert.equal(shouldEscalate(new ApiError("forbidden", 403)), true);
+	});
+
+	it("does NOT escalate a 4xx the call site opted out of via meta.softError", () => {
+		assert.equal(
+			shouldEscalate(new ApiError("not found", 404), { softError: true }),
+			false,
+		);
+	});
+
+	it("does NOT escalate an aborted/cancelled request", () => {
+		assert.equal(shouldEscalate(abortError()), false);
+	});
+
+	it("does NOT escalate a statusless network/offline blip", () => {
+		assert.equal(shouldEscalate(new TypeError("Failed to fetch")), false);
+		assert.equal(shouldEscalate(new Error("network down")), false);
+	});
+
+	it("a statusless error is soft regardless of meta", () => {
+		assert.equal(
+			shouldEscalate(new TypeError("Failed to fetch"), { softError: false }),
+			false,
+		);
+	});
+});

package/src/lib/error-classifier.ts

@@ -0,0 +1,96 @@
+import { ApiError } from "./api";
+
+/**
+ * Extract an HTTP status code from a thrown error, regardless of which client
+ * raised it.
+ *
+ * Two client shapes coexist in the web client:
+ *  - the hand-written `api` wrapper throws `ApiError` (carries `.status`);
+ *  - the generated `@remit/api-http-client` (hey-api) throws the parsed JSON error
+ *    body. A response interceptor (see `lib/client.ts`) re-wraps those as
+ *    `ApiError` too, so in practice both paths carry `.status`. As a belt-and-
+ *    braces fallback we also read a numeric `status`/`statusCode` off a plain
+ *    object.
+ */
+export const getErrorStatus = (error: unknown): number | undefined => {
+	if (error instanceof ApiError) return error.status;
+	if (error && typeof error === "object") {
+		const candidate = error as { status?: unknown; statusCode?: unknown };
+		if (typeof candidate.status === "number") return candidate.status;
+		if (typeof candidate.statusCode === "number") return candidate.statusCode;
+	}
+	return undefined;
+};
+
+/** The error carries a real HTTP status — our API answered. */
+export const hasHttpStatus = (error: unknown): boolean =>
+	getErrorStatus(error) !== undefined;
+
+/** A genuine first-party server failure: an HTTP 5xx. */
+export const isServerError = (error: unknown): boolean => {
+	const status = getErrorStatus(error);
+	return status !== undefined && status >= 500 && status <= 599;
+};
+
+/**
+ * A deliberately cancelled request (route change, React Query cancellation).
+ * Never a failure.
+ */
+export const isAbortError = (error: unknown): boolean => {
+	if (
+		typeof DOMException !== "undefined" &&
+		error instanceof DOMException &&
+		error.name === "AbortError"
+	) {
+		return true;
+	}
+	if (
+		error &&
+		typeof error === "object" &&
+		"name" in error &&
+		(error as { name?: unknown }).name === "AbortError"
+	) {
+		return true;
+	}
+	return false;
+};
+
+/**
+ * A statusless transport/network failure (`TypeError: Failed to fetch` from a
+ * wifi drop, tab wake, captive portal, or a background refetch): the request
+ * never reached a server, so it is environmental, not a proven first-party
+ * failure. Excludes deliberate aborts (also statusless, but their own category).
+ */
+export const isNetworkError = (error: unknown): boolean =>
+	!isAbortError(error) && !hasHttpStatus(error);
+
+const isSoftErrorMeta = (meta: Record<string, unknown> | undefined): boolean =>
+	meta?.softError === true;
+
+/**
+ * The single fail-fast decision: should this error escalate to the full-screen
+ * fatal overlay? Default is YES — a non-2xx must never silently vanish.
+ *
+ * The contract (issue #1059):
+ *  1. DEFAULT = escalate.
+ *  2. A 5xx (500–599) ALWAYS escalates — no opt-out, even on a background
+ *     refetch, even when the call site marked `meta.softError`. Our API
+ *     answered "I'm broken"; that is never benign.
+ *  3. The ONLY soft (do-NOT-escalate) exemptions:
+ *     a. aborts / cancellations — never a failure;
+ *     b. statusless network/offline errors — environmental, recovered by React
+ *        Query's reconnect/retry;
+ *     c. a non-5xx error on a query/mutation that opted out via
+ *        `meta.softError === true` — the call site owns that error's UX
+ *        (e.g. a 404 empty state, a 4xx "Reconnect" banner).
+ */
+export const shouldEscalate = (
+	error: unknown,
+	meta?: Record<string, unknown>,
+): boolean => {
+	if (isServerError(error)) return true;
+	if (isAbortError(error)) return false;
+	if (isNetworkError(error)) return false;
+	if (isSoftErrorMeta(meta)) return false;
+	return true;
+};