@remit/web-client 0.0.1

package/src/lib/organize/organize-model.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	buildCreateFilterInput,
+	buildOrganizeInput,
+	hasCommittableAction,
+	NO_ACTION,
+	type OrganizeDraft,
+} from "./organize-model";
+
+const baseDraft = (overrides: Partial<OrganizeDraft> = {}): OrganizeDraft => ({
+	matchOperator: "And",
+	literalClauses: [],
+	...overrides,
+});
+
+describe("hasCommittableAction", () => {
+	it("is false when no move target is chosen — labeling has no backend yet, so a keep-in-place draft has nothing to commit", () => {
+		assert.equal(hasCommittableAction(baseDraft()), false);
+	});
+
+	it("is false for the None sentinel", () => {
+		assert.equal(
+			hasCommittableAction(baseDraft({ moveMailboxId: NO_ACTION })),
+			false,
+		);
+	});
+
+	it("is true once a real destination mailbox is chosen", () => {
+		assert.equal(
+			hasCommittableAction(baseDraft({ moveMailboxId: "mbx-1" })),
+			true,
+		);
+	});
+});
+
+describe("buildOrganizeInput", () => {
+	it("carries the anchor and defaults the action to None when no move is set", () => {
+		const input = buildOrganizeInput(baseDraft({ anchorMessageId: "msg-1" }));
+		assert.equal(input.anchorMessageId, "msg-1");
+		assert.equal(input.actionMailboxId, NO_ACTION);
+		assert.equal(input.actionLabelId, NO_ACTION);
+		assert.equal(input.matchOperator, "And");
+		assert.deepEqual(input.literalClauses, []);
+	});
+
+	it("omits anchorMessageId entirely for a purely-literal input", () => {
+		const input = buildOrganizeInput(
+			baseDraft({
+				literalClauses: [{ field: "From", value: "airbnb.com" }],
+			}),
+		);
+		assert.equal("anchorMessageId" in input, false);
+	});
+
+	it("labels the label action None even when a move target is set — label writes have no endpoint", () => {
+		const input = buildOrganizeInput(
+			baseDraft({ anchorMessageId: "msg-1", moveMailboxId: "mbx-9" }),
+		);
+		assert.equal(input.actionMailboxId, "mbx-9");
+		assert.equal(input.actionLabelId, NO_ACTION);
+	});
+});
+
+describe("buildCreateFilterInput", () => {
+	it("builds a Standing filter with no expiresAt", () => {
+		const input = buildCreateFilterInput(
+			baseDraft({ anchorMessageId: "msg-1", moveMailboxId: "mbx-2" }),
+			"standing",
+			"Travel",
+		);
+		assert.equal(input.scope, "Standing");
+		assert.equal("expiresAt" in input, false);
+		assert.equal(input.name, "Travel");
+		assert.equal(input.actionMailboxId, "mbx-2");
+		assert.equal(input.actionLabelId, NO_ACTION);
+		assert.equal(input.anchorMessageId, "msg-1");
+	});
+
+	it("builds a Temporary filter that carries expiresAt", () => {
+		const input = buildCreateFilterInput(
+			baseDraft({
+				moveMailboxId: "mbx-2",
+				expiresAt: "2026-07-16T23:59:59+02:00",
+			}),
+			"temporary",
+			"Trip",
+		);
+		assert.equal(input.scope, "Temporary");
+		assert.equal(input.expiresAt, "2026-07-16T23:59:59+02:00");
+	});
+
+	it("never sends a client-side ttl — the server derives it from expiresAt", () => {
+		const input = buildCreateFilterInput(
+			baseDraft({
+				moveMailboxId: "mbx-2",
+				expiresAt: "2026-07-16T23:59:59+02:00",
+			}),
+			"temporary",
+			"Trip",
+		);
+		assert.equal("ttl" in input, false);
+	});
+});

package/src/lib/organize/organize-model.ts

@@ -0,0 +1,105 @@
+import type {
+	RemitImapCreateFilterInput,
+	RemitImapFilterClause,
+	RemitImapFilterMatchOperator,
+	RemitImapFilterScope,
+	RemitImapOrganizeInput,
+} from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * The four commit scopes the smart-organize sentence offers (RFC 034 recap):
+ *
+ * - `just-these` — a one-time action on the current selection. Existing
+ *   message-action API, nothing persisted.
+ * - `all-like-these` — a one-time retroactive back-apply across the matching
+ *   corpus (POST /organize job). Nothing standing persisted.
+ * - `standing` — "these and new mail like this": a permanent `Filter`.
+ * - `temporary` — "until <date>": a `Filter` that expires on its own.
+ */
+export type OrganizeScope =
+	| "just-these"
+	| "all-like-these"
+	| "standing"
+	| "temporary";
+
+/** The `"None"` sentinel the API uses for an absent label / move action. */
+export const NO_ACTION = "None";
+
+/**
+ * The user's in-progress organize decision, independent of which scope they
+ * land on. The anchor and predicate drive the match set; `moveMailboxId` is the
+ * one committable action today (labeling has no backend yet — see
+ * `labelPlaceholder`).
+ */
+export interface OrganizeDraft {
+	/** Semantic anchor — "mail like this one". The first selected message. */
+	anchorMessageId?: string;
+	/** How `literalClauses` combine. Ignored when there are none. */
+	matchOperator: RemitImapFilterMatchOperator;
+	/** Literal from/subject/has-words clauses (RFC 031). */
+	literalClauses: RemitImapFilterClause[];
+	/**
+	 * Destination the match set is moved into — the exclusive action (RFC 034
+	 * Decision 3.1). Absent means "keep where they are": no move action.
+	 */
+	moveMailboxId?: string;
+	/**
+	 * ISO 8601 date-time with zone offset. Present only for the `temporary`
+	 * scope; a plain picked date (RFC 034 non-goal: no event-based expiry).
+	 */
+	expiresAt?: string;
+}
+
+/**
+ * Whether the draft carries a committable action. Labeling is not wired yet
+ * (no Label API — RFC 030's `Label`/`MessageLabel` entities exist in TypeSpec
+ * but have no CRUD endpoint), so a move target is the only real action. A draft
+ * with no move target has nothing to commit; the caller disables the CTA and
+ * says why (ux.md).
+ */
+export const hasCommittableAction = (draft: OrganizeDraft): boolean =>
+	draft.moveMailboxId !== undefined && draft.moveMailboxId !== NO_ACTION;
+
+/**
+ * Build the read-only preview / back-apply matcher input. The action fields do
+ * not affect which messages match — the preview returns exactly the set a job
+ * with the same predicate would apply to — so a widen preview can pass this
+ * before the user has chosen a folder.
+ */
+export const buildOrganizeInput = (
+	draft: OrganizeDraft,
+): RemitImapOrganizeInput => ({
+	...(draft.anchorMessageId ? { anchorMessageId: draft.anchorMessageId } : {}),
+	matchOperator: draft.matchOperator,
+	literalClauses: draft.literalClauses,
+	actionLabelId: NO_ACTION,
+	actionMailboxId: draft.moveMailboxId ?? NO_ACTION,
+});
+
+/**
+ * Build the `createFilter` body for a standing or temporary filter. `ttl` is
+ * derived server-side from `expiresAt`; `expiresAt` is sent only for the
+ * temporary scope (RFC 034 Decision 1.3).
+ */
+export const buildCreateFilterInput = (
+	draft: OrganizeDraft,
+	scope: Extract<OrganizeScope, "standing" | "temporary">,
+	name: string,
+): RemitImapCreateFilterInput => {
+	const filterScope: RemitImapFilterScope =
+		scope === "standing" ? "Standing" : "Temporary";
+	return {
+		name,
+		scope: filterScope,
+		...(scope === "temporary" && draft.expiresAt
+			? { expiresAt: draft.expiresAt }
+			: {}),
+		matchOperator: draft.matchOperator,
+		literalClauses: draft.literalClauses,
+		actionLabelId: NO_ACTION,
+		actionMailboxId: draft.moveMailboxId ?? NO_ACTION,
+		...(draft.anchorMessageId
+			? { anchorMessageId: draft.anchorMessageId }
+			: {}),
+	};
+};

package/src/lib/organize/organize-poll.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isTerminalJobState, nextPollDelayMs } from "./organize-poll";
+
+describe("isTerminalJobState", () => {
+	it("stops on Complete and Failed", () => {
+		assert.equal(isTerminalJobState("Complete"), true);
+		assert.equal(isTerminalJobState("Failed"), true);
+	});
+
+	it("keeps polling on Pending and Running", () => {
+		assert.equal(isTerminalJobState("Pending"), false);
+		assert.equal(isTerminalJobState("Running"), false);
+	});
+
+	it("keeps polling while the state is unknown", () => {
+		assert.equal(isTerminalJobState(undefined), false);
+	});
+});
+
+describe("nextPollDelayMs", () => {
+	it("backs off exponentially from 1s", () => {
+		assert.equal(nextPollDelayMs(0), 1_000);
+		assert.equal(nextPollDelayMs(1), 2_000);
+		assert.equal(nextPollDelayMs(2), 4_000);
+		assert.equal(nextPollDelayMs(3), 8_000);
+	});
+
+	it("caps the delay at 15s", () => {
+		assert.equal(nextPollDelayMs(10), 15_000);
+		assert.equal(nextPollDelayMs(100), 15_000);
+	});
+
+	it("treats a negative attempt as the first delay", () => {
+		assert.equal(nextPollDelayMs(-5), 1_000);
+	});
+});

package/src/lib/organize/organize-poll.ts

@@ -0,0 +1,28 @@
+import type { RemitImapOrganizeJobState } from "@remit/api-http-client/types.gen.ts";
+
+/** States a back-apply job stops at — polling ends here (RFC 034, #1278). */
+const TERMINAL_STATES: ReadonlySet<RemitImapOrganizeJobState> = new Set([
+	"Complete",
+	"Failed",
+]);
+
+export const isTerminalJobState = (
+	state: RemitImapOrganizeJobState | undefined,
+): boolean => state !== undefined && TERMINAL_STATES.has(state);
+
+const BASE_POLL_MS = 1_000;
+const MAX_POLL_MS = 15_000;
+
+/**
+ * Exponential backoff for job polling: 1s, 2s, 4s, 8s, capped at 15s. `attempt`
+ * is the number of polls already made (0 for the first delay). Backoff keeps a
+ * long-running back-apply from hammering the job endpoint while staying
+ * responsive for the common fast case — and there is never a client-side loop
+ * over message pages (remit is data-heavy; the corpus is queried once, server
+ * side, by the job itself).
+ */
+export const nextPollDelayMs = (attempt: number): number => {
+	const clampedAttempt = Math.max(0, attempt);
+	const delay = BASE_POLL_MS * 2 ** clampedAttempt;
+	return Math.min(delay, MAX_POLL_MS);
+};

package/src/lib/outbox-status.test.ts

@@ -0,0 +1,64 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	describeOutboxStatus,
+	isOutboxListRow,
+	isUnsendableStatus,
+} from "./outbox-status.js";
+
+describe("describeOutboxStatus", () => {
+	test("returns null for draft", () => {
+		assert.equal(describeOutboxStatus("draft"), null);
+	});
+
+	test("blocked is rendered with a warning tone, not success", () => {
+		const desc = describeOutboxStatus("blocked");
+		assert.ok(desc);
+		assert.equal(desc.tone, "warning");
+		assert.equal(desc.label, "Blocked");
+	});
+
+	test("sent is success tone", () => {
+		const desc = describeOutboxStatus("sent");
+		assert.ok(desc);
+		assert.equal(desc.tone, "success");
+		assert.equal(desc.label, "Sent");
+	});
+
+	test("failed is error tone (distinct from blocked)", () => {
+		const desc = describeOutboxStatus("failed");
+		assert.ok(desc);
+		assert.equal(desc.tone, "error");
+		assert.notEqual(desc.tone, describeOutboxStatus("blocked")?.tone);
+	});
+});
+
+describe("isUnsendableStatus", () => {
+	test("sent must NOT be flagged as unsendable — never show error subtitle on success (issue #192)", () => {
+		assert.equal(isUnsendableStatus("sent"), false);
+	});
+
+	test("failed and blocked are unsendable", () => {
+		assert.equal(isUnsendableStatus("failed"), true);
+		assert.equal(isUnsendableStatus("blocked"), true);
+	});
+
+	test("queued and sending are not unsendable", () => {
+		assert.equal(isUnsendableStatus("queued"), false);
+		assert.equal(isUnsendableStatus("sending"), false);
+	});
+});
+
+describe("isOutboxListRow", () => {
+	test("hides draft and sent rows", () => {
+		assert.equal(isOutboxListRow("draft"), false);
+		assert.equal(isOutboxListRow("sent"), false);
+	});
+
+	test("shows queued, sending, failed, blocked", () => {
+		assert.equal(isOutboxListRow("queued"), true);
+		assert.equal(isOutboxListRow("sending"), true);
+		assert.equal(isOutboxListRow("failed"), true);
+		assert.equal(isOutboxListRow("blocked"), true);
+	});
+});

package/src/lib/outbox-status.ts

@@ -0,0 +1,75 @@
+import type { RemitImapOutboxMessageStatus } from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * Visual states for outbox messages.
+ *
+ * `sent` is included for completeness (the detail view of a sent message
+ * uses it before the row gets purged) but the outbox list never renders
+ * `sent` rows — they are filtered out (issue #193).
+ */
+export type OutboxDisplayStatus = Exclude<
+	RemitImapOutboxMessageStatus,
+	"draft"
+>;
+
+export type OutboxStatusTone =
+	| "success"
+	| "info"
+	| "warning"
+	| "error"
+	| "neutral";
+
+export interface OutboxStatusDescriptor {
+	label: string;
+	tone: OutboxStatusTone;
+}
+
+const STATUS_DESCRIPTORS: Record<OutboxDisplayStatus, OutboxStatusDescriptor> =
+	{
+		queued: { label: "Queued", tone: "neutral" },
+		sending: { label: "Sending…", tone: "info" },
+		sent: { label: "Sent", tone: "success" },
+		failed: { label: "Failed", tone: "error" },
+		blocked: { label: "Blocked", tone: "warning" },
+	};
+
+/**
+ * Describe an outbox status for UI rendering.
+ *
+ * `failed` and `blocked` are both terminal non-success states but carry
+ * different remediation: `failed` may auto-retry on a transient error, and
+ * is the appropriate label for SMTP auth/connection errors. `blocked` means
+ * the account is misconfigured (e.g. no SMTP host) — the user must fix the
+ * account before any retry can succeed.
+ *
+ * Returns null for `draft` (drafts live in a separate view).
+ */
+export const describeOutboxStatus = (
+	status: RemitImapOutboxMessageStatus,
+): OutboxStatusDescriptor | null => {
+	if (status === "draft") return null;
+	return STATUS_DESCRIPTORS[status];
+};
+
+/**
+ * Whether a status carries a `lastError` worth surfacing in the UI.
+ *
+ * Critically: `sent` is NOT included. A successful send must never display
+ * a stale lastError — that is the contradictory "green check + 'SMTP not
+ * configured'" UI bug from issue #192.
+ */
+export const isUnsendableStatus = (
+	status: RemitImapOutboxMessageStatus,
+): boolean => status === "failed" || status === "blocked";
+
+/**
+ * Whether the outbox list view should render this row.
+ *
+ * `draft` belongs in the Drafts view. `sent` rows are deleted by the IMAP
+ * APPEND handler (issue #178) — but until that happens we hide them from
+ * the Outbox list so a successfully-sent message never appears in two
+ * places at once (issue #193).
+ */
+export const isOutboxListRow = (
+	status: RemitImapOutboxMessageStatus,
+): boolean => status !== "draft" && status !== "sent";

package/src/lib/plate-serializer.ts

@@ -0,0 +1,164 @@
+import type { TElement, TText, Value } from "platejs";
+
+type PlateNode = TElement | TText;
+
+const isText = (node: PlateNode): node is TText =>
+	"text" in node && !("children" in node);
+
+const escapeHtml = (text: string): string =>
+	text
+		.replace(/&/g, "&")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;");
+
+const serializeTextNode = (node: TText): string => {
+	let html = escapeHtml(node.text);
+	if (node.bold) html = `<strong>${html}</strong>`;
+	if (node.italic) html = `<em>${html}</em>`;
+	return html;
+};
+
+const serializeElement = (node: TElement): string => {
+	const children = node.children
+		.map((child) =>
+			isText(child as PlateNode)
+				? serializeTextNode(child as TText)
+				: serializeElement(child as TElement),
+		)
+		.join("");
+
+	switch (node.type) {
+		case "blockquote":
+			return `<blockquote>${children}</blockquote>`;
+		case "a": {
+			const url = (node as TElement & { url?: string }).url ?? "";
+			return `<a href="${escapeHtml(url)}">${children}</a>`;
+		}
+		default:
+			return `<p>${children}</p>`;
+	}
+};
+
+export const plateValueToHtml = (value: Value): string =>
+	value.map(serializeElement).join("");
+
+const extractText = (node: PlateNode): string => {
+	if (isText(node)) return node.text;
+	return (node.children as PlateNode[]).map(extractText).join("");
+};
+
+export const plateValueToText = (value: Value): string =>
+	value.map(extractText).join("\n");
+
+const parseTextWithMarks = (
+	textContent: string,
+	marks: Record<string, boolean>,
+): TText => ({
+	text: textContent,
+	...marks,
+});
+
+const getMarksFromElement = (el: Element): Record<string, boolean> => {
+	const marks: Record<string, boolean> = {};
+	const tag = el.tagName.toLowerCase();
+	if (tag === "strong" || tag === "b") marks.bold = true;
+	if (tag === "em" || tag === "i") marks.italic = true;
+	return marks;
+};
+
+const parseInlineChildren = (
+	node: Node,
+	inheritedMarks: Record<string, boolean> = {},
+): TText[] => {
+	const results: TText[] = [];
+
+	for (const child of Array.from(node.childNodes)) {
+		if (child.nodeType === Node.TEXT_NODE) {
+			results.push(parseTextWithMarks(child.textContent ?? "", inheritedMarks));
+			continue;
+		}
+
+		if (child.nodeType !== Node.ELEMENT_NODE) continue;
+
+		const el = child as Element;
+		const tag = el.tagName.toLowerCase();
+
+		if (tag === "a") {
+			const linkElement: TElement & { url: string } = {
+				type: "a",
+				url: el.getAttribute("href") ?? "",
+				children: parseInlineChildren(el, inheritedMarks),
+			};
+			results.push(linkElement as unknown as TText);
+			continue;
+		}
+
+		const marks = { ...inheritedMarks, ...getMarksFromElement(el) };
+		results.push(...parseInlineChildren(el, marks));
+	}
+
+	return results;
+};
+
+const parseBlockElement = (el: Element): TElement => {
+	const tag = el.tagName.toLowerCase();
+
+	if (tag === "blockquote") {
+		const children = Array.from(el.children);
+		if (children.length > 0) {
+			return {
+				type: "blockquote",
+				children: children.map(parseBlockElement),
+			};
+		}
+		const inlineChildren = parseInlineChildren(el);
+		return {
+			type: "blockquote",
+			children: inlineChildren.length > 0 ? inlineChildren : [{ text: "" }],
+		};
+	}
+
+	if (tag === "a") {
+		return {
+			type: "a",
+			url: el.getAttribute("href") ?? "",
+			children: parseInlineChildren(el),
+		} as TElement & { url: string };
+	}
+
+	const inlineChildren = parseInlineChildren(el);
+	return {
+		type: "p",
+		children: inlineChildren.length > 0 ? inlineChildren : [{ text: "" }],
+	};
+};
+
+export const htmlToPlateValue = (html: string): Value => {
+	const parser = new DOMParser();
+	const doc = parser.parseFromString(html, "text/html");
+	const body = doc.body;
+
+	const blockElements = Array.from(body.childNodes).reduce<TElement[]>(
+		(acc, node) => {
+			if (node.nodeType === Node.TEXT_NODE) {
+				const text = node.textContent ?? "";
+				if (text.trim()) {
+					acc.push({ type: "p", children: [{ text }] });
+				}
+				return acc;
+			}
+			if (node.nodeType === Node.ELEMENT_NODE) {
+				acc.push(parseBlockElement(node as Element));
+			}
+			return acc;
+		},
+		[],
+	);
+
+	if (blockElements.length === 0) {
+		return [{ type: "p", children: [{ text: "" }] }];
+	}
+
+	return blockElements;
+};

package/src/lib/provider-presets.test.ts

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	getPresetById,
+	PROVIDER_PRESETS,
+	type ProviderPreset,
+	presetIdForEmail,
+} from "./provider-presets.js";
+
+interface ExpectedSettings {
+	imap: { host: string; port: number; security: string };
+	smtp: { host: string; port: number; security: string };
+}
+
+const EXPECTED: Record<string, ExpectedSettings> = {
+	icloud: {
+		imap: { host: "imap.mail.me.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.mail.me.com", port: 587, security: "starttls" },
+	},
+	yahoo: {
+		imap: { host: "imap.mail.yahoo.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.mail.yahoo.com", port: 465, security: "tls" },
+	},
+	aol: {
+		imap: { host: "imap.aol.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.aol.com", port: 465, security: "tls" },
+	},
+	fastmail: {
+		imap: { host: "imap.fastmail.com", port: 993, security: "tls" },
+		smtp: { host: "smtp.fastmail.com", port: 465, security: "tls" },
+	},
+};
+
+describe("provider presets", () => {
+	it("exposes exactly the four documented providers", () => {
+		const ids = PROVIDER_PRESETS.map((p) => p.id).sort();
+		assert.deepEqual(ids, ["aol", "fastmail", "icloud", "yahoo"]);
+	});
+
+	for (const preset of PROVIDER_PRESETS) {
+		describe(preset.label, () => {
+			const expected = EXPECTED[preset.id];
+
+			it("matches the exact IMAP settings from the table", () => {
+				assert.deepEqual(preset.imap, expected.imap);
+			});
+
+			it("matches the exact SMTP settings from the table", () => {
+				assert.deepEqual(preset.smtp, expected.smtp);
+			});
+
+			it("uses the full email as username", () => {
+				assert.equal(preset.username, "full-email");
+			});
+
+			it("has password help text", () => {
+				assert.ok(preset.passwordHelp.text.length > 0);
+				assert.match(preset.passwordHelp.text, /app[\w-]* password/i);
+			});
+
+			it("has a valid https app-password url", () => {
+				const url = new URL(preset.passwordHelp.url);
+				assert.equal(url.protocol, "https:");
+			});
+		});
+	}
+
+	it("looks up a preset by id", () => {
+		const preset: ProviderPreset | undefined = getPresetById("icloud");
+		assert.ok(preset);
+		assert.equal(preset.label, "iCloud");
+	});
+
+	it("returns undefined for an unknown id", () => {
+		assert.equal(getPresetById("custom"), undefined);
+	});
+
+	describe("presetIdForEmail", () => {
+		it("pre-selects a preset for a known provider domain", () => {
+			assert.equal(presetIdForEmail("alice@icloud.com"), "icloud");
+			assert.equal(presetIdForEmail("bob@me.com"), "icloud");
+			assert.equal(presetIdForEmail("carol@yahoo.com"), "yahoo");
+			assert.equal(presetIdForEmail("dave@aol.com"), "aol");
+			assert.equal(presetIdForEmail("erin@fastmail.com"), "fastmail");
+		});
+
+		it("is case-insensitive on the domain", () => {
+			assert.equal(presetIdForEmail("Alice@iCloud.com"), "icloud");
+		});
+
+		it("returns Custom for unknown or malformed addresses", () => {
+			assert.equal(presetIdForEmail("self@example.com"), "");
+			assert.equal(presetIdForEmail("not-an-email"), "");
+		});
+	});
+});