@remit/web-client 0.0.1

package/src/hooks/useOrganizeJob.ts

@@ -0,0 +1,90 @@
+import {
+	organizeJobDetailOperationsGetOrganizeJobOptions,
+	organizeOperationsCreateOrganizeJobMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapOrganizeJobResponse } from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { useCallback, useState } from "react";
+import {
+	buildOrganizeInput,
+	type OrganizeDraft,
+} from "@/lib/organize/organize-model";
+import {
+	isTerminalJobState,
+	nextPollDelayMs,
+} from "@/lib/organize/organize-poll";
+
+export interface OrganizeJobProgress {
+	state: RemitImapOrganizeJobResponse["state"] | undefined;
+	matchedCount: number;
+	appliedCount: number;
+	failedCount: number;
+	errorMessage: string;
+}
+
+/**
+ * "All like these" — start a one-time retroactive back-apply (POST /organize)
+ * and poll its status to completion (GET /organize/{organizeJobId}). Polling
+ * backs off exponentially and stops the instant the job reaches a terminal
+ * state (Complete / Failed), surfacing matched / applied / failed counts. The
+ * back-apply itself scans the corpus server-side; the client only reads a
+ * single job row per poll.
+ */
+export const useOrganizeJob = (accountId: string | undefined) => {
+	const [organizeJobId, setOrganizeJobId] = useState<string | undefined>();
+
+	const createMutation = useMutation({
+		...organizeOperationsCreateOrganizeJobMutation(),
+		onSuccess: (data) => setOrganizeJobId(data.organizeJobId),
+	});
+	const { mutate: createJob } = createMutation;
+
+	const jobQuery = useQuery({
+		...organizeJobDetailOperationsGetOrganizeJobOptions({
+			path: {
+				accountId: accountId ?? "",
+				organizeJobId: organizeJobId ?? "",
+			},
+		}),
+		enabled: !!accountId && !!organizeJobId,
+		refetchInterval: (query) => {
+			const state = query.state.data?.state;
+			if (isTerminalJobState(state)) return false;
+			return nextPollDelayMs(query.state.dataUpdateCount);
+		},
+	});
+
+	const start = useCallback(
+		(draft: OrganizeDraft) => {
+			if (!accountId) return;
+			setOrganizeJobId(undefined);
+			createJob({
+				path: { accountId },
+				body: buildOrganizeInput(draft),
+			});
+		},
+		[accountId, createJob],
+	);
+
+	const job = jobQuery.data;
+	const state = job?.state ?? createMutation.data?.state;
+	const isDone = isTerminalJobState(job?.state);
+
+	const progress: OrganizeJobProgress = {
+		state,
+		matchedCount: job?.matchedCount ?? 0,
+		appliedCount: job?.appliedCount ?? 0,
+		failedCount: job?.failedCount ?? 0,
+		errorMessage: job?.errorMessage ?? "",
+	};
+
+	return {
+		start,
+		progress,
+		isStarting: createMutation.isPending,
+		isRunning: !!organizeJobId && !isDone,
+		isDone,
+		isError: createMutation.isError || jobQuery.isError,
+		error: createMutation.error ?? jobQuery.error,
+	};
+};

package/src/hooks/useOrganizePreview.ts

@@ -0,0 +1,40 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation } from "@tanstack/react-query";
+import { useCallback } from "react";
+import {
+	buildOrganizeInput,
+	type OrganizeDraft,
+} from "@/lib/organize/organize-model";
+
+/**
+ * "Select similar messages" (the widen step). Runs the read-only matcher once
+ * server-side (POST /organize/preview) and returns the messages the same
+ * predicate would apply an action to — the previewed set equals the set a job
+ * with the same input would apply to. This is the only corpus-wide query the
+ * flow makes; there is no client-side pagination over messages.
+ */
+export const useOrganizePreview = (accountId: string | undefined) => {
+	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
+	const { mutate } = mutation;
+
+	const preview = useCallback(
+		(draft: OrganizeDraft) => {
+			if (!accountId) return;
+			mutate({
+				path: { accountId },
+				body: buildOrganizeInput(draft),
+			});
+		},
+		[accountId, mutate],
+	);
+
+	return {
+		preview,
+		reset: mutation.reset,
+		matchedCount: mutation.data?.matchedCount,
+		messageIds: mutation.data?.messageIds,
+		isPending: mutation.isPending,
+		isError: mutation.isError,
+		error: mutation.error,
+	};
+};

package/src/hooks/useRescueCandidates.test.ts

@@ -0,0 +1,217 @@
+/**
+ * useRescueCandidates — exercises the real hook.
+ *
+ * Strategy: pre-seed a QueryClient cache with a mocked
+ * threadOperationsSearchThreads response (same key the hook generates), then
+ * render the hook synchronously via renderToString + QueryClientProvider. The
+ * hook reads from the cache, so the queryFn never fires; mapping drift in the
+ * hook source will break these assertions.
+ */
+
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { threadOperationsSearchThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapSenderTrust,
+	RemitImapThreadMessageResponse,
+	RemitImapThreadSearchResponse,
+} from "@remit/api-http-client/types.gen.ts";
+import type { RescueCandidate } from "@remit/ui";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { useRescueCandidates } from "./useRescueCandidates.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const JUNK_MAILBOX_ID = "mb-junk";
+
+/** Query options the hook passes — must stay in sync with useRescueCandidates.ts */
+const HOOK_QUERY_OPTIONS = {
+	path: { mailboxId: JUNK_MAILBOX_ID },
+	query: {
+		senderTrust: ["vip", "wellknown"] as RemitImapSenderTrust[],
+		dkimMismatch: false,
+		results: true,
+		limit: 500,
+	},
+};
+
+function makeThread(
+	overrides: Partial<RemitImapThreadMessageResponse> &
+		Pick<RemitImapThreadMessageResponse, "messageId" | "senderTrust">,
+): RemitImapThreadMessageResponse {
+	return {
+		threadMessageId: `tm-${overrides.messageId}`,
+		threadId: `t-${overrides.messageId}`,
+		accountConfigId: "acc",
+		mailboxId: JUNK_MAILBOX_ID,
+		sentDate: 1_000_000,
+		isRead: false,
+		hasAttachment: false,
+		hasStars: false,
+		isDeleted: false,
+		createdAt: 1_000_000,
+		updatedAt: 1_000_000,
+		fromName: "Anna de Vries",
+		fromEmail: "anna@example.nl",
+		subject: "Re: invoice",
+		snippet: "See attached.",
+		...overrides,
+	} as RemitImapThreadMessageResponse;
+}
+
+/**
+ * Pre-seeds a QueryClient with `response` under the key the hook generates,
+ * renders the hook synchronously inside a QueryClientProvider, and returns
+ * whatever the hook returned.
+ */
+function renderHookWithResponse(response: RemitImapThreadSearchResponse): {
+	candidates: RescueCandidate[];
+} {
+	const client = new QueryClient({
+		defaultOptions: { queries: { retry: false } },
+	});
+	client.setQueryData(
+		threadOperationsSearchThreadsQueryKey(HOOK_QUERY_OPTIONS),
+		response,
+	);
+
+	let captured: { candidates: RescueCandidate[] } = { candidates: [] };
+
+	function Capture() {
+		captured = useRescueCandidates(JUNK_MAILBOX_ID);
+		return null;
+	}
+
+	renderToString(
+		createElement(
+			QueryClientProvider,
+			{ client },
+			createElement(Capture),
+		) as never,
+	);
+
+	return captured;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useRescueCandidates: empty / disabled states", () => {
+	test("returns empty candidates when the response has no items", () => {
+		const { candidates } = renderHookWithResponse({ items: [] });
+		assert.deepEqual(candidates, []);
+	});
+
+	test("returns empty candidates and does not fire when junkMailboxId is undefined", () => {
+		const client = new QueryClient({
+			defaultOptions: { queries: { retry: false } },
+		});
+
+		// Prove the query was never seeded — so if enabled fired, it would hang
+		let captured: { candidates: RescueCandidate[] } = { candidates: [] };
+
+		function Capture() {
+			captured = useRescueCandidates(undefined);
+			return null;
+		}
+
+		renderToString(
+			createElement(
+				QueryClientProvider,
+				{ client },
+				createElement(Capture),
+			) as never,
+		);
+
+		assert.deepEqual(captured.candidates, []);
+	});
+});
+
+describe("useRescueCandidates: candidate mapping from real hook output", () => {
+	const vipThread = makeThread({ messageId: "m1", senderTrust: "vip" });
+	const wellknownThread = makeThread({
+		messageId: "m2",
+		senderTrust: "wellknown",
+	});
+
+	test("maps messageId to candidate id", () => {
+		const { candidates } = renderHookWithResponse({ items: [vipThread] });
+		assert.equal(candidates[0].id, "m1");
+	});
+
+	test("maps fromName as senderName", () => {
+		const { candidates } = renderHookWithResponse({ items: [vipThread] });
+		assert.equal(candidates[0].senderName, "Anna de Vries");
+	});
+
+	test("falls back to fromEmail when fromName is absent", () => {
+		const thread = makeThread({
+			messageId: "m3",
+			senderTrust: "vip",
+			fromName: undefined,
+		});
+		const { candidates } = renderHookWithResponse({ items: [thread] });
+		assert.equal(candidates[0].senderName, "anna@example.nl");
+	});
+
+	test("falls back to 'Unknown sender' when both name and email are absent", () => {
+		const thread = makeThread({
+			messageId: "m4",
+			senderTrust: "vip",
+			fromName: undefined,
+			fromEmail: undefined,
+		});
+		const { candidates } = renderHookWithResponse({ items: [thread] });
+		assert.equal(candidates[0].senderName, "Unknown sender");
+		assert.equal(candidates[0].senderAddress, "");
+	});
+
+	test("falls back to '(no subject)' when subject is absent", () => {
+		const thread = makeThread({
+			messageId: "m5",
+			senderTrust: "vip",
+			subject: undefined,
+		});
+		const { candidates } = renderHookWithResponse({ items: [thread] });
+		assert.equal(candidates[0].subject, "(no subject)");
+	});
+
+	test("sets vip trustSubReason via rescueCandidateReason", () => {
+		const { candidates } = renderHookWithResponse({ items: [vipThread] });
+		assert.equal(candidates[0].trustSubReason, "A sender you know");
+	});
+
+	test("sets wellknown trustSubReason via rescueCandidateReason", () => {
+		const { candidates } = renderHookWithResponse({
+			items: [wellknownThread],
+		});
+		assert.equal(candidates[0].trustSubReason, "You've emailed them before");
+	});
+
+	test("sets the constant trustReason headline", () => {
+		const { candidates } = renderHookWithResponse({ items: [vipThread] });
+		assert.equal(candidates[0].trustReason, "We can verify this sender");
+	});
+
+	test("preserves senderTrust on the candidate", () => {
+		const { candidates } = renderHookWithResponse({
+			items: [vipThread, wellknownThread],
+		});
+		assert.equal(candidates[0].senderTrust, "vip");
+		assert.equal(candidates[1].senderTrust, "wellknown");
+	});
+
+	test("maps all response items to candidates in order", () => {
+		const { candidates } = renderHookWithResponse({
+			items: [vipThread, wellknownThread],
+		});
+		assert.equal(candidates.length, 2);
+		assert.equal(candidates[0].id, "m1");
+		assert.equal(candidates[1].id, "m2");
+	});
+});

package/src/hooks/useRescueCandidates.ts

@@ -0,0 +1,48 @@
+import { threadOperationsSearchThreadsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RescueCandidate } from "@remit/ui";
+import { useQuery } from "@tanstack/react-query";
+import { rescueCandidateReason } from "@/lib/rescue-candidates";
+
+const TRUST_REASON = "We can verify this sender";
+
+/**
+ * Fetch rescue candidates from the backend for the given Junk mailbox.
+ *
+ * Filters by senderTrust=[vip,wellknown] and dkimMismatch=false. The
+ * dkimMismatch=false filter excludes senders with no authenticity signal
+ * (undefined), not just confirmed mismatches — this is intentional: it closes
+ * the impersonation path where a spoofed trusted-sender From with no DKIM
+ * would otherwise surface as a rescue candidate.
+ *
+ * Only fires when junkMailboxId is provided.
+ */
+export function useRescueCandidates(junkMailboxId: string | undefined): {
+	candidates: RescueCandidate[];
+} {
+	const { data } = useQuery({
+		...threadOperationsSearchThreadsOptions({
+			path: { mailboxId: junkMailboxId ?? "" },
+			query: {
+				senderTrust: ["vip", "wellknown"],
+				dkimMismatch: false,
+				results: true,
+				limit: 500,
+			},
+		}),
+		enabled: !!junkMailboxId,
+		staleTime: 60_000,
+	});
+
+	const candidates: RescueCandidate[] = (data?.items ?? []).map((thread) => ({
+		id: thread.messageId,
+		senderName: thread.fromName || thread.fromEmail || "Unknown sender",
+		senderAddress: thread.fromEmail ?? "",
+		subject: thread.subject || "(no subject)",
+		snippet: thread.snippet ?? "",
+		trustReason: TRUST_REASON,
+		trustSubReason: rescueCandidateReason(thread.senderTrust),
+		senderTrust: thread.senderTrust,
+	}));
+
+	return { candidates };
+}

package/src/hooks/useSaveDraft.ts

@@ -0,0 +1,118 @@
+import {
+	outboxDetailOperationsUpdateOutboxMessageMutation,
+	outboxOperationsCreateOutboxMessageMutation,
+	outboxOperationsListOutboxMessagesOptions,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+
+export type SaveStatus = "idle" | "saving" | "saved" | "error";
+
+interface DraftData {
+	accountId: string;
+	toAddresses: string[];
+	ccAddresses?: string[];
+	bccAddresses?: string[];
+	subject?: string;
+	textBody?: string;
+	htmlBody?: string;
+	inReplyTo?: string;
+	references?: string[];
+}
+
+interface UseSaveDraftOptions {
+	outboxMessageId?: string;
+	onDraftCreated: (id: string) => void;
+}
+
+export const useSaveDraft = ({
+	outboxMessageId,
+	onDraftCreated,
+}: UseSaveDraftOptions) => {
+	const [saveStatus, setSaveStatus] = useState<SaveStatus>("idle");
+	const [saveError, setSaveError] = useState<unknown>(null);
+	const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+	const queryClient = useQueryClient();
+
+	const createMutation = useMutation(
+		outboxOperationsCreateOutboxMessageMutation(),
+	);
+	const updateMutation = useMutation(
+		outboxDetailOperationsUpdateOutboxMessageMutation(),
+	);
+
+	const executeSave = useCallback(
+		async (data: DraftData) => {
+			setSaveStatus("saving");
+			setSaveError(null);
+
+			if (outboxMessageId) {
+				const result = await updateMutation.mutateAsync({
+					path: { outboxMessageId },
+					body: {
+						toAddresses: data.toAddresses,
+						ccAddresses: data.ccAddresses,
+						bccAddresses: data.bccAddresses,
+						subject: data.subject,
+						textBody: data.textBody,
+						htmlBody: data.htmlBody,
+						inReplyTo: data.inReplyTo,
+						references: data.references,
+					},
+				});
+				setSaveStatus("saved");
+				return result;
+			}
+
+			const result = await createMutation.mutateAsync({
+				body: {
+					...data,
+					sendImmediately: false,
+				},
+			});
+			onDraftCreated(result.outboxMessageId);
+			setSaveStatus("saved");
+			queryClient.invalidateQueries({
+				queryKey: outboxOperationsListOutboxMessagesOptions().queryKey,
+			});
+			return result;
+		},
+		[
+			outboxMessageId,
+			createMutation,
+			updateMutation,
+			onDraftCreated,
+			queryClient,
+		],
+	);
+
+	const saveDraft = useCallback(
+		(data: DraftData) => {
+			if (timerRef.current) clearTimeout(timerRef.current);
+			timerRef.current = setTimeout(() => {
+				// Keep the real error, not just a vague "error" status — the caller
+				// surfaces its detail in a banner. A fatal 5xx additionally escalates
+				// through the global MutationCache.onError sink.
+				executeSave(data).catch((error: unknown) => {
+					setSaveError(error);
+					setSaveStatus("error");
+				});
+			}, 2000);
+		},
+		[executeSave],
+	);
+
+	const saveImmediately = useCallback(
+		(data: DraftData) => {
+			if (timerRef.current) clearTimeout(timerRef.current);
+			return executeSave(data);
+		},
+		[executeSave],
+	);
+
+	const cancelAutoSave = useCallback(() => {
+		if (timerRef.current) clearTimeout(timerRef.current);
+	}, []);
+
+	return { saveStatus, saveError, saveDraft, saveImmediately, cancelAutoSave };
+};

package/src/hooks/useSelection.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { computeRange, nextFocusId } from "./useSelection.js";
+
+const ids = ["a", "b", "c", "d", "e"];
+
+describe("computeRange", () => {
+	test("forward range: anchor above target selects the inclusive slice", () => {
+		assert.deepStrictEqual(computeRange(ids, "b", "d"), ["b", "c", "d"]);
+	});
+
+	test("backward range: target above anchor selects the same inclusive slice", () => {
+		assert.deepStrictEqual(computeRange(ids, "d", "b"), ["b", "c", "d"]);
+	});
+
+	test("anchor equals target selects just that one id", () => {
+		assert.deepStrictEqual(computeRange(ids, "c", "c"), ["c"]);
+	});
+
+	test("no anchor selects just the target", () => {
+		assert.deepStrictEqual(computeRange(ids, undefined, "c"), ["c"]);
+	});
+
+	test("anchor not present in the list selects just the target", () => {
+		assert.deepStrictEqual(computeRange(ids, "zzz", "c"), ["c"]);
+	});
+
+	test("full span from first to last includes every id in order", () => {
+		assert.deepStrictEqual(computeRange(ids, "a", "e"), [
+			"a",
+			"b",
+			"c",
+			"d",
+			"e",
+		]);
+	});
+
+	test("target not present in the list selects nothing", () => {
+		assert.deepStrictEqual(computeRange(ids, "b", "zzz"), []);
+	});
+});
+
+describe("nextFocusId", () => {
+	test("moves down one row", () => {
+		assert.strictEqual(nextFocusId(ids, "b", 1), "c");
+	});
+
+	test("moves up one row", () => {
+		assert.strictEqual(nextFocusId(ids, "c", -1), "b");
+	});
+
+	test("clamps at the bottom (no wrap)", () => {
+		assert.strictEqual(nextFocusId(ids, "e", 1), "e");
+	});
+
+	test("clamps at the top (no wrap)", () => {
+		assert.strictEqual(nextFocusId(ids, "a", -1), "a");
+	});
+
+	test("no focus + down starts at the first row", () => {
+		assert.strictEqual(nextFocusId(ids, undefined, 1), "a");
+	});
+
+	test("no focus + up starts at the last row", () => {
+		assert.strictEqual(nextFocusId(ids, undefined, -1), "e");
+	});
+
+	test("focus not in the list + down starts at the first row", () => {
+		assert.strictEqual(nextFocusId(ids, "zzz", 1), "a");
+	});
+
+	test("empty list returns undefined", () => {
+		assert.strictEqual(nextFocusId([], "a", 1), undefined);
+	});
+});