@remit/web-client 0.0.52 → 0.0.54

package/src/components/ui/ErrorState.render.test.ts

@@ -0,0 +1,82 @@
+/**
+ * ErrorState is the shared "this didn't load" surface. Two things matter about
+ * it: the message it shows comes from whatever the caller caught (which is
+ * rarely an `Error`), and Retry only exists when there is something to retry.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ErrorState, formatErrorMessage } from "./ErrorState";
+
+(globalThis as { React?: typeof React }).React = React;
+
+const render = (props: Parameters<typeof ErrorState>[0]): string =>
+	renderToString(createElement(ErrorState, props) as never);
+
+describe("formatErrorMessage", () => {
+	it("uses an Error's message", () => {
+		assert.equal(
+			formatErrorMessage(new Error("imap timed out")),
+			"imap timed out",
+		);
+	});
+
+	it("passes a bare string through", () => {
+		assert.equal(formatErrorMessage("nope"), "nope");
+	});
+
+	it("reads `message` off a plain object — what a rejected fetch body looks like", () => {
+		assert.equal(formatErrorMessage({ message: "Bad Gateway" }), "Bad Gateway");
+	});
+
+	it("falls back for a shape it cannot read", () => {
+		assert.equal(
+			formatErrorMessage({ status: 500 }),
+			"An unexpected error occurred",
+		);
+		assert.equal(formatErrorMessage(null), "An unexpected error occurred");
+		assert.equal(
+			formatErrorMessage({ message: 42 }),
+			"An unexpected error occurred",
+		);
+	});
+});
+
+describe("ErrorState", () => {
+	it("announces itself as an alert and shows the caught message", () => {
+		const html = render({ error: new Error("mailbox unreachable") });
+		assert.match(html, /role="alert"/);
+		assert.match(html, /mailbox unreachable/);
+		assert.match(html, /Couldn&#x27;t load content/);
+	});
+
+	it("takes a caller-supplied title over the default", () => {
+		const html = render({ error: "x", title: "Couldn't load folders" });
+		assert.match(html, /Couldn&#x27;t load folders/);
+		assert.doesNotMatch(html, /load content/);
+	});
+
+	it("offers no Retry when the caller has no retry to give", () => {
+		assert.doesNotMatch(render({ error: "x" }), /Retry/);
+		assert.doesNotMatch(render({ error: "x", variant: "inline" }), /Retry/);
+	});
+
+	it("offers Retry in both variants when it can retry", () => {
+		const retry = () => undefined;
+		assert.match(render({ error: "x", onRetry: retry }), /Retry/);
+		assert.match(
+			render({ error: "x", onRetry: retry, variant: "inline" }),
+			/Retry/,
+		);
+	});
+
+	it("renders the inline variant as a single row, not the centred block", () => {
+		const inline = render({ error: "x", variant: "inline" });
+		const block = render({ error: "x" });
+		assert.match(inline, /items-start/);
+		assert.match(block, /justify-center/);
+		assert.doesNotMatch(inline, /justify-center/);
+	});
+});

package/src/hooks/mutation-optimism.test.ts

@@ -0,0 +1,278 @@
+/**
+ * The mutation hooks behind delete, move, star and mark-read all make the same
+ * promise: the list changes the moment the user acts, every listing that shows
+ * the row changes with it — including the unified one the daily brief reads
+ * (#140, #149) — and a server refusal puts the row back and says so.
+ *
+ * These mount the real hooks against a real QueryClient, so the optimistic
+ * patch, the rollback and the banner are exercised together rather than as
+ * three separate pure helpers.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import {
+	threadOperationsListThreadsQueryKey,
+	unifiedThreadOperationsListAllThreadsQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { makeThreadMessage } from "../test-support/fixtures";
+import { type HttpMock, httpError, mockFetch } from "../test-support/http";
+import { useDeleteMessages } from "./useDeleteMessages";
+import { useToggleReadFor } from "./useMarkAsRead";
+import { useMoveMessages } from "./useMoveMessages";
+import { useToggleStar } from "./useToggleStar";
+
+const INBOX = "mbx-inbox";
+const SENT = "mbx-sent";
+const ARCHIVE = "mbx-archive";
+
+const inboxRow = makeThreadMessage({ messageId: "msg-1", mailboxId: INBOX });
+const sentRow = makeThreadMessage({
+	messageId: "msg-2",
+	mailboxId: SENT,
+	threadMessageId: "tm-2",
+});
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+const inboxKey = threadOperationsListThreadsQueryKey({
+	path: { mailboxId: INBOX },
+});
+const sentKey = threadOperationsListThreadsQueryKey({
+	path: { mailboxId: SENT },
+});
+const briefKey = unifiedThreadOperationsListAllThreadsQueryKey();
+
+const seed = (dom: DomHarness): void => {
+	dom.queryClient.setQueryData(inboxKey, { items: [inboxRow] });
+	dom.queryClient.setQueryData(sentKey, { items: [sentRow] });
+	dom.queryClient.setQueryData(briefKey, { items: [inboxRow, sentRow] });
+};
+
+const rows = (
+	dom: DomHarness,
+	key: readonly unknown[],
+): RemitImapThreadMessageResponse[] =>
+	(
+		dom.queryClient.getQueryData(key) as
+			| { items: RemitImapThreadMessageResponse[] }
+			| undefined
+	)?.items ?? [];
+
+const ids = (dom: DomHarness, key: readonly unknown[]): string[] =>
+	rows(dom, key).map((row) => row.messageId);
+
+/** Mount a hook and hand its return value back to the test. */
+const mountHook = <T>(useHook: () => T): { current: () => T } => {
+	let value: T | undefined;
+	const Probe = () => {
+		value = useHook();
+		return null;
+	};
+	harness = createDomHarness();
+	seed(harness);
+	harness.renderApp(createElement(Probe));
+	return {
+		current: () => {
+			if (value === undefined) throw new Error("hook did not render");
+			return value;
+		},
+	};
+};
+
+const dom = (): DomHarness => {
+	if (!harness) throw new Error("nothing mounted");
+	return harness;
+};
+
+beforeEach(() => {
+	http = mockFetch(() => ({}));
+});
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+});
+
+describe("deleting from a listing", () => {
+	it("removes the row from its mailbox and from the brief at once", async () => {
+		const hook = mountHook(() => useDeleteMessages({ mailboxId: INBOX }));
+
+		hook.current().deleteMessages(["msg-1"]);
+		await dom().flush();
+
+		assert.deepEqual(ids(dom(), inboxKey), []);
+		assert.deepEqual(ids(dom(), briefKey), ["msg-2"]);
+	});
+
+	it("tells the caller the row is gone so it can leave the open thread", async () => {
+		const removed: string[][] = [];
+		const hook = mountHook(() =>
+			useDeleteMessages({
+				mailboxId: INBOX,
+				onAfterOptimisticRemove: (messageIds) => removed.push(messageIds),
+			}),
+		);
+
+		hook.current().deleteMessages(["msg-1"]);
+		await dom().flush();
+
+		assert.deepEqual(removed, [["msg-1"]]);
+	});
+
+	it("patches the mailbox the message is really in, not the one being browsed", async () => {
+		const hook = mountHook(() =>
+			useDeleteMessages({ mailboxId: INBOX, messages: [inboxRow, sentRow] }),
+		);
+
+		hook.current().deleteMessages(["msg-2"]);
+		await dom().flush();
+
+		assert.deepEqual(ids(dom(), sentKey), []);
+		assert.deepEqual(ids(dom(), inboxKey), ["msg-1"]);
+	});
+
+	it("does nothing at all for an empty selection", async () => {
+		const hook = mountHook(() => useDeleteMessages({ mailboxId: INBOX }));
+
+		hook.current().deleteMessages([]);
+		await dom().flush();
+
+		assert.deepEqual(http.calls, []);
+		assert.deepEqual(ids(dom(), inboxKey), ["msg-1"]);
+	});
+
+	it("puts the row back and says so when the server refuses", async () => {
+		http.restore();
+		http = mockFetch(() => httpError(409, "mailbox is locked"));
+		const hook = mountHook(() => useDeleteMessages({ mailboxId: INBOX }));
+
+		hook.current().deleteMessages(["msg-1"]);
+		await dom().flush();
+
+		assert.deepEqual(ids(dom(), inboxKey), ["msg-1"]);
+		assert.deepEqual(ids(dom(), briefKey), ["msg-1", "msg-2"]);
+		assert.match(dom().text(), /Couldn't delete this message/);
+	});
+
+	it("counts the messages in the failure it reports", async () => {
+		http.restore();
+		http = mockFetch(() => httpError(409));
+		const hook = mountHook(() => useDeleteMessages({ mailboxId: INBOX }));
+
+		hook.current().deleteMessages(["msg-1", "msg-2"]);
+		await dom().flush();
+
+		assert.match(dom().text(), /Couldn't delete 2 messages/);
+	});
+});
+
+describe("moving between folders", () => {
+	it("takes the row out of the source listing straight away", async () => {
+		const hook = mountHook(() => useMoveMessages({ mailboxId: INBOX }));
+
+		hook.current().moveMessages(["msg-1"], ARCHIVE);
+		await dom().flush();
+
+		assert.deepEqual(ids(dom(), inboxKey), []);
+		const [moved] = http.calls;
+		assert.equal(moved?.body?.destinationMailboxId, ARCHIVE);
+	});
+
+	it("restores the source listing when the move fails", async () => {
+		http.restore();
+		http = mockFetch(() => httpError(409));
+		const hook = mountHook(() => useMoveMessages({ mailboxId: INBOX }));
+
+		hook.current().moveMessages(["msg-1"], ARCHIVE);
+		await dom().flush();
+
+		assert.deepEqual(ids(dom(), inboxKey), ["msg-1"]);
+		assert.match(dom().text(), /Couldn't move/);
+	});
+});
+
+describe("starring a message", () => {
+	it("stars the row in the mailbox it lives in, not the browsed one (#46)", async () => {
+		const hook = mountHook(() =>
+			useToggleStar({
+				threadId: "thread-1",
+				mailboxId: INBOX,
+				messages: [inboxRow, sentRow],
+			}),
+		);
+
+		hook.current().toggleStar("msg-2", false);
+		await dom().flush();
+
+		assert.equal(rows(dom(), sentKey)[0].hasStars, true);
+		assert.equal(rows(dom(), inboxKey)[0].hasStars, false);
+	});
+
+	it("unstars a starred message", async () => {
+		const hook = mountHook(() =>
+			useToggleStar({ threadId: "thread-1", mailboxId: INBOX }),
+		);
+
+		hook.current().toggleStar("msg-1", false);
+		await dom().flush();
+		assert.equal(rows(dom(), inboxKey)[0].hasStars, true);
+
+		hook.current().toggleStar("msg-1", true);
+		await dom().flush();
+		assert.equal(rows(dom(), inboxKey)[0].hasStars, false);
+	});
+
+	it("rolls the star back and names the direction that failed", async () => {
+		http.restore();
+		http = mockFetch(() => httpError(409));
+		const hook = mountHook(() =>
+			useToggleStar({ threadId: "thread-1", mailboxId: INBOX }),
+		);
+
+		hook.current().toggleStar("msg-1", false);
+		await dom().flush();
+
+		assert.equal(rows(dom(), inboxKey)[0].hasStars, false);
+		assert.match(dom().text(), /Couldn't star message/);
+	});
+});
+
+describe("marking a selection read", () => {
+	it("sends the ids and the direction the caller asked for", async () => {
+		const hook = mountHook(() => useToggleReadFor({ mailboxId: INBOX }));
+
+		hook.current().toggleReadFor(["msg-1"], true);
+		await dom().flush();
+
+		const [call] = http.calls;
+		assert.equal(call?.path, "/messages/flags");
+		assert.deepEqual(call?.body?.messageIds, ["msg-1"]);
+		assert.equal(call?.body?.isRead, true);
+	});
+
+	it("stays quiet for an empty selection", async () => {
+		const hook = mountHook(() => useToggleReadFor({ mailboxId: INBOX }));
+
+		hook.current().toggleReadFor([], true);
+		await dom().flush();
+
+		assert.deepEqual(http.calls, []);
+	});
+
+	it("says which way it failed — read, not unread", async () => {
+		http.restore();
+		http = mockFetch(() => httpError(409));
+		const hook = mountHook(() => useToggleReadFor({ mailboxId: INBOX }));
+
+		hook.current().toggleReadFor(["msg-1"], false);
+		await dom().flush();
+
+		assert.match(dom().text(), /Couldn't mark as unread/);
+	});
+});

package/src/test-support/dom.ts

@@ -0,0 +1,180 @@
+/**
+ * Mount-and-poke harness over the jsdom globals `dom-env.mjs` installs.
+ *
+ * Excluded from coverage by `test:run`; it lives under `src/` only because the
+ * build's `rootDir` is `src/`. Node's test runner gives every test file its own
+ * process, so nothing here leaks between files.
+ */
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import React, { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+	DEFAULT_VIEWPORT_WIDTH,
+	setViewportWidth,
+} from "../../test-support/dom-env.mjs";
+import { ErrorBannerProvider } from "../components/ui/ErrorBannerProvider";
+
+export interface DomHarness {
+	window: Window & typeof globalThis;
+	document: Document;
+	container: HTMLElement;
+	/** The client behind `renderApp`; seed it with `setQueryData`. */
+	queryClient: QueryClient;
+	render: (element: React.ReactNode) => void;
+	/** Render under the providers every mail surface expects. */
+	renderApp: (element: React.ReactNode) => void;
+	renderAsync: (element: React.ReactNode) => Promise<void>;
+	unmount: () => void;
+	close: () => void;
+	html: () => string;
+	text: () => string;
+	query: <T extends Element = HTMLElement>(selector: string) => T | null;
+	queryAll: <T extends Element = HTMLElement>(selector: string) => T[];
+	byLabel: (label: string) => HTMLElement;
+	byText: (selector: string, text: string) => HTMLElement;
+	click: (element: Element) => void;
+	/** Pick an option by value and let React see the change. */
+	select: (element: Element, value: string) => void;
+	dispatch: (target: EventTarget, event: Event) => void;
+	type: (element: Element, value: string) => void;
+	flush: () => Promise<void>;
+	/** Let real timers fire — some flows stage their steps on a delay. */
+	wait: (ms: number) => Promise<void>;
+}
+
+export interface DomOptions {
+	/** Width `matchMedia` answers against — jsdom has no layout of its own. */
+	viewportWidth?: number;
+}
+
+export const createDomHarness = (options: DomOptions = {}): DomHarness => {
+	setViewportWidth(options.viewportWidth ?? DEFAULT_VIEWPORT_WIDTH);
+	// The test loader transpiles remit-ui's `.tsx` with the classic JSX runtime,
+	// which reads a global `React`. Vite uses the automatic runtime, so this
+	// shim exists only for the test harness.
+	(globalThis as { React?: typeof React }).React = React;
+
+	const container = document.createElement("div");
+	document.body.appendChild(container);
+	let root: Root | undefined = createRoot(container);
+	// No retries: a test asserting a failure should not have to wait out a
+	// backoff before it can see one.
+	const queryClient = new QueryClient({
+		defaultOptions: {
+			queries: { retry: false },
+			mutations: { retry: false },
+		},
+	});
+
+	const requireRoot = (): Root => {
+		if (!root) throw new Error("harness already unmounted");
+		return root;
+	};
+
+	const harness: DomHarness = {
+		window: globalThis.window,
+		document: globalThis.document,
+		container,
+		queryClient,
+		render: (element) => {
+			act(() => requireRoot().render(element as never));
+		},
+		renderApp: (element) => {
+			harness.render(
+				createElement(
+					QueryClientProvider,
+					{ client: queryClient },
+					createElement(ErrorBannerProvider, null, element),
+				),
+			);
+		},
+		renderAsync: async (element) => {
+			await act(async () => {
+				requireRoot().render(element as never);
+			});
+		},
+		unmount: () => {
+			if (!root) return;
+			const current = root;
+			root = undefined;
+			act(() => current.unmount());
+		},
+		close: () => {
+			harness.unmount();
+			// Drops every cached query along with its garbage-collection timer,
+			// which otherwise holds the test process open for its full gcTime.
+			queryClient.clear();
+			container.remove();
+			setViewportWidth(DEFAULT_VIEWPORT_WIDTH);
+		},
+		html: () => container.innerHTML,
+		text: () => container.textContent ?? "",
+		query: <T extends Element = HTMLElement>(selector: string) =>
+			container.querySelector(selector) as T | null,
+		queryAll: <T extends Element = HTMLElement>(selector: string) =>
+			[...container.querySelectorAll(selector)] as T[],
+		byLabel: (label) => {
+			const found = container.querySelector(`[aria-label="${label}"]`);
+			if (!found) throw new Error(`no element labelled "${label}"`);
+			return found as HTMLElement;
+		},
+		byText: (selector, text) => {
+			const found = [...container.querySelectorAll(selector)].find((node) =>
+				(node.textContent ?? "").includes(text),
+			);
+			if (!found) throw new Error(`no ${selector} containing "${text}"`);
+			return found as HTMLElement;
+		},
+		click: (element) => {
+			act(() => {
+				element.dispatchEvent(
+					new MouseEvent("click", { bubbles: true, cancelable: true }),
+				);
+			});
+		},
+		select: (element, value) => {
+			act(() => {
+				const node = element as HTMLSelectElement;
+				Object.getOwnPropertyDescriptor(
+					HTMLSelectElement.prototype,
+					"value",
+				)?.set?.call(node, value);
+				node.dispatchEvent(new Event("change", { bubbles: true }));
+			});
+		},
+		dispatch: (target, event) => {
+			act(() => {
+				target.dispatchEvent(event);
+			});
+		},
+		type: (element, value) => {
+			act(() => {
+				const input = element as HTMLInputElement | HTMLTextAreaElement;
+				const prototype =
+					input instanceof HTMLTextAreaElement
+						? HTMLTextAreaElement.prototype
+						: HTMLInputElement.prototype;
+				Object.getOwnPropertyDescriptor(prototype, "value")?.set?.call(
+					input,
+					value,
+				);
+				input.dispatchEvent(new Event("input", { bubbles: true }));
+			});
+		},
+		wait: async (ms) => {
+			await act(async () => {
+				await new Promise((resolve) => setTimeout(resolve, ms));
+			});
+		},
+		flush: async () => {
+			// Enough turns for a chain of awaits — form validation, then the
+			// mutation, then its `onSuccess` — to settle.
+			await act(async () => {
+				for (let turn = 0; turn < 8; turn += 1) await Promise.resolve();
+			});
+		},
+	};
+
+	return harness;
+};

package/src/test-support/fixtures.ts

@@ -0,0 +1,83 @@
+/**
+ * Fully-shaped API fixtures. Lives outside `src/` so it is not measured for
+ * coverage. Every builder returns a complete generated type — no casts at the
+ * call sites, so a contract change surfaces here once instead of in every test.
+ */
+
+import type {
+	RemitImapAccountResponse,
+	RemitImapMailboxResponse,
+	RemitImapThreadMessageResponse,
+} from "@remit/api-http-client/types.gen.ts";
+
+export const makeMailbox = (
+	overrides: Partial<RemitImapMailboxResponse> & {
+		mailboxId: string;
+		fullPath: string;
+	},
+): RemitImapMailboxResponse => ({
+	accountId: "acc-1",
+	namespaceType: "personal",
+	namespacePrefix: "",
+	hierarchyDelimiter: "/",
+	messageCount: 0,
+	unseenCount: 0,
+	deletedCount: 0,
+	lastSyncUid: 0,
+	highWaterMarkUid: 0,
+	lastMessageSyncAt: 0,
+	createdAt: 0,
+	updatedAt: 0,
+	...overrides,
+});
+
+export const makeAccount = (
+	overrides: Partial<RemitImapAccountResponse> & { accountId: string },
+): RemitImapAccountResponse => ({
+	accountConfigId: "cfg-1",
+	username: "alice@example.com",
+	email: "alice@example.com",
+	authType: "password",
+	imapHost: "imap.example.com",
+	imapPort: 993,
+	imapTls: true,
+	imapStartTls: false,
+	smtpEnabled: true,
+	smtpHost: "smtp.example.com",
+	smtpPort: 587,
+	smtpTls: false,
+	smtpStartTls: true,
+	smtpUsername: "alice@example.com",
+	isActive: true,
+	connectionState: "authenticated",
+	createdAt: 0,
+	updatedAt: 0,
+	folderAppointments: [],
+	...overrides,
+});
+
+export const makeThreadMessage = (
+	overrides: Partial<RemitImapThreadMessageResponse> & {
+		messageId: string;
+	},
+): RemitImapThreadMessageResponse => ({
+	threadId: "thread-1",
+	threadMessageId: `tm-${overrides.messageId}`,
+	accountConfigId: "cfg-1",
+	mailboxId: "mbx-inbox",
+	accountId: "acc-1",
+	subject: "Quarterly report",
+	fromName: "Alice",
+	fromEmail: "alice@example.com",
+	sentDate: 1_767_225_600_000,
+	snippet: "",
+	isRead: false,
+	hasAttachment: false,
+	star: "none",
+	hasStars: false,
+	isDeleted: false,
+	senderTrust: "unknown",
+	createdAt: 0,
+	updatedAt: 0,
+	...overrides,
+});

package/src/test-support/http.ts

@@ -0,0 +1,72 @@
+/**
+ * Fetch seam for the tests. The generated SDK talks to the network through
+ * `globalThis.fetch`, so intercepting it — rather than the client module —
+ * exercises the real request the app builds: method, path, and JSON body.
+ */
+
+export interface HttpCall {
+	method: string;
+	url: string;
+	path: string;
+	body: Record<string, unknown> | undefined;
+}
+
+export interface HttpMock {
+	calls: HttpCall[];
+	/** Calls whose path ends with `suffix`, in order. */
+	to: (suffix: string) => HttpCall[];
+	restore: () => void;
+}
+
+type Responder = (call: HttpCall) => unknown;
+
+/**
+ * Answer every request with `responder`'s return value as JSON. Throwing from
+ * the responder, or returning a `Response`, is how a test drives a failure.
+ */
+export const mockFetch = (responder: Responder = () => ({})): HttpMock => {
+	const original = globalThis.fetch;
+	const calls: HttpCall[] = [];
+
+	globalThis.fetch = (async (
+		input: RequestInfo | URL,
+		init?: RequestInit,
+	): Promise<Response> => {
+		const request = input instanceof Request ? input : undefined;
+		const url = request ? request.url : String(input);
+		const rawBody = request ? await request.clone().text() : undefined;
+		const call: HttpCall = {
+			method: (request?.method ?? init?.method ?? "GET").toUpperCase(),
+			url,
+			path: new URL(url, "http://localhost").pathname,
+			body: rawBody ? JSON.parse(rawBody) : undefined,
+		};
+		calls.push(call);
+
+		const result = responder(call);
+		if (result instanceof Response) return result;
+		return new Response(JSON.stringify(result ?? {}), {
+			status: 200,
+			headers: { "content-type": "application/json" },
+		});
+	}) as typeof globalThis.fetch;
+
+	return {
+		calls,
+		to: (suffix) => calls.filter((call) => call.path.endsWith(suffix)),
+		restore: () => {
+			globalThis.fetch = original;
+		},
+	};
+};
+
+/**
+ * A failed request. The status travels in the body as well as on the response:
+ * the generated client throws the parsed body, and the app's error classifier
+ * reads the status off it.
+ */
+export const httpError = (status: number, message = "boom"): Response =>
+	new Response(JSON.stringify({ status, message }), {
+		status,
+		headers: { "content-type": "application/json" },
+	});