@remit/web-client 0.0.70 → 0.0.72

package/src/hooks/useDeleteFolder.ts

@@ -0,0 +1,267 @@
+import {
+	configOperationsGetConfigQueryKey,
+	mailboxOperationsListMailboxesQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import {
+	mailboxDetailOperationsDeleteMailbox,
+	mailboxOperationsListMailboxes,
+	messageBulkOperationsMoveMessages,
+	threadOperationsListThreads,
+} from "@remit/api-http-client/sdk.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import {
+	advanceMove,
+	beginMove,
+	failMove,
+	MOVE_BATCH_SIZE,
+	type MoveProgress,
+} from "@/lib/delete-folder";
+
+const PAGE_CAP = 50;
+
+type Outcome<T> = { ok: true; value: T } | { ok: false; error: string };
+
+const errorText = (error: unknown): string =>
+	error instanceof Error ? error.message : "Something went wrong.";
+
+/**
+ * Run a network call to a branchable result instead of a thrown exception, so
+ * the caller can surface a failed batch to the UI without a block catch (the
+ * fail-fast lint rule reserves those for rethrows).
+ */
+const attempt = <T>(work: Promise<T>): Promise<Outcome<T>> =>
+	work.then(
+		(value) => ({ ok: true as const, value }),
+		(error) => ({ ok: false as const, error: errorText(error) }),
+	);
+
+/**
+ * Collect up to `limit` message ids still living in the mailbox, skipping ones
+ * already moved this run and anything flagged deleted. Reads fresh from the
+ * server every call so a resumed or interrupted move enumerates what is
+ * actually left, never a stale snapshot.
+ */
+const collectMovableIds = async (
+	mailboxId: string,
+	alreadyMoved: ReadonlySet<string>,
+	limit: number,
+	signal: AbortSignal,
+): Promise<string[]> => {
+	const ids: string[] = [];
+	let continuationToken: string | undefined;
+	for (let page = 0; page < PAGE_CAP; page += 1) {
+		if (signal.aborted) return ids;
+		const { data } = await threadOperationsListThreads({
+			path: { mailboxId },
+			query: { order: "desc", continuationToken },
+			throwOnError: true,
+		});
+		for (const item of data.items) {
+			if (item.isDeleted) continue;
+			if (alreadyMoved.has(item.messageId)) continue;
+			if (ids.includes(item.messageId)) continue;
+			ids.push(item.messageId);
+			if (ids.length >= limit) return ids;
+		}
+		if (!data.continuationToken) break;
+		continuationToken = data.continuationToken;
+	}
+	return ids;
+};
+
+/**
+ * Count live messages still listed in the mailbox with no `moved`-set filtering,
+ * an independent read the move loop cannot fool. The delete gates on this: if any
+ * message still shows here — including one that lags in the source listing after a
+ * move — the folder is not emptied yet and must not be deleted.
+ */
+const liveMessageCount = async (
+	mailboxId: string,
+	signal: AbortSignal,
+): Promise<number> => {
+	let count = 0;
+	let continuationToken: string | undefined;
+	for (let page = 0; page < PAGE_CAP; page += 1) {
+		if (signal.aborted) return count;
+		const { data } = await threadOperationsListThreads({
+			path: { mailboxId },
+			query: { order: "desc", continuationToken },
+			throwOnError: true,
+		});
+		for (const item of data.items) {
+			if (item.isDeleted) continue;
+			count += 1;
+		}
+		if (!data.continuationToken) break;
+		continuationToken = data.continuationToken;
+	}
+	return count;
+};
+
+export type DeleteFolderPhase =
+	| "idle"
+	| "moving"
+	| "deleting"
+	| "done"
+	| "error";
+
+interface UseDeleteFolderOptions {
+	accountId: string;
+	mailboxId: string;
+	onDeleted: () => void;
+}
+
+export function useDeleteFolder({
+	accountId,
+	mailboxId,
+	onDeleted,
+}: UseDeleteFolderOptions) {
+	const queryClient = useQueryClient();
+	const [phase, setPhase] = useState<DeleteFolderPhase>("idle");
+	const [progress, setProgress] = useState<MoveProgress | null>(null);
+	const [errorMessage, setErrorMessage] = useState<string>();
+	const abortRef = useRef<AbortController | null>(null);
+
+	const invalidate = useCallback(() => {
+		queryClient.invalidateQueries({
+			queryKey: mailboxOperationsListMailboxesQueryKey({ path: { accountId } }),
+		});
+		queryClient.invalidateQueries({
+			queryKey: configOperationsGetConfigQueryKey(),
+		});
+	}, [queryClient, accountId]);
+
+	const deleteMailbox = useCallback(async () => {
+		setPhase("deleting");
+		const outcome = await attempt(
+			mailboxDetailOperationsDeleteMailbox({
+				path: { accountId, mailboxId },
+				throwOnError: true,
+			}),
+		);
+		if (!outcome.ok) {
+			setErrorMessage(outcome.error);
+			setPhase("error");
+			return;
+		}
+		invalidate();
+		setPhase("done");
+		onDeleted();
+	}, [accountId, mailboxId, invalidate, onDeleted]);
+
+	const remainingCount = useCallback(
+		(): Promise<number> =>
+			mailboxOperationsListMailboxes({
+				path: { accountId },
+				throwOnError: true,
+			}).then(
+				({ data }) =>
+					data.items.find((box) => box.mailboxId === mailboxId)?.messageCount ??
+					0,
+			),
+		[accountId, mailboxId],
+	);
+
+	const cancel = useCallback(() => {
+		abortRef.current?.abort();
+	}, []);
+
+	const moveThenDelete = useCallback(
+		async (destinationMailboxId: string) => {
+			const controller = new AbortController();
+			abortRef.current = controller;
+			const { signal } = controller;
+			setPhase("moving");
+			setErrorMessage(undefined);
+
+			const counted = await attempt(remainingCount());
+			if (signal.aborted) return;
+			if (!counted.ok) {
+				setErrorMessage(counted.error);
+				setPhase("error");
+				return;
+			}
+			let current = beginMove(counted.value);
+			setProgress(current);
+
+			const moved = new Set<string>();
+			while (true) {
+				if (signal.aborted) return;
+				const collected = await attempt(
+					collectMovableIds(mailboxId, moved, MOVE_BATCH_SIZE, signal),
+				);
+				if (signal.aborted) return;
+				if (!collected.ok) {
+					current = failMove(current, collected.error);
+					setProgress(current);
+					setErrorMessage(collected.error);
+					setPhase("error");
+					return;
+				}
+				const batch = collected.value;
+				if (batch.length === 0) break;
+
+				const movedBatch = await attempt(
+					messageBulkOperationsMoveMessages({
+						body: { messageIds: batch, destinationMailboxId },
+						throwOnError: true,
+					}),
+				);
+				if (signal.aborted) return;
+				if (!movedBatch.ok) {
+					current = failMove(current, movedBatch.error);
+					setProgress(current);
+					setErrorMessage(movedBatch.error);
+					setPhase("error");
+					return;
+				}
+				for (const id of batch) moved.add(id);
+				current = advanceMove(current, batch.length);
+				setProgress(current);
+			}
+
+			const remaining = await attempt(liveMessageCount(mailboxId, signal));
+			if (signal.aborted) return;
+			if (!remaining.ok) {
+				current = failMove(current, remaining.error);
+				setProgress(current);
+				setErrorMessage(remaining.error);
+				setPhase("error");
+				return;
+			}
+			if (remaining.value > 0) {
+				const message = `${remaining.value} ${
+					remaining.value === 1 ? "email is" : "emails are"
+				} still syncing. Re-open delete to finish removing this folder.`;
+				current = failMove(current, message);
+				setProgress(current);
+				setErrorMessage(message);
+				setPhase("error");
+				invalidate();
+				return;
+			}
+
+			await deleteMailbox();
+		},
+		[mailboxId, remainingCount, deleteMailbox, invalidate],
+	);
+
+	const reset = useCallback(() => {
+		abortRef.current?.abort();
+		abortRef.current = null;
+		setPhase("idle");
+		setProgress(null);
+		setErrorMessage(undefined);
+	}, []);
+
+	return {
+		phase,
+		progress,
+		errorMessage,
+		deleteMailbox,
+		moveThenDelete,
+		cancel,
+		reset,
+	};
+}

package/src/lib/delete-folder.test.ts

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	advanceMove,
+	appointedRole,
+	beginMove,
+	excludeFolder,
+	type FolderNode,
+	failMove,
+	guardFolderDeletion,
+	hasChildFolders,
+	initialStage,
+	moveProgressLabel,
+} from "./delete-folder.js";
+
+const folder = (
+	over: Partial<FolderNode> & { mailboxId: string },
+): FolderNode => ({
+	fullPath: over.mailboxId,
+	hierarchyDelimiter: "/",
+	messageCount: 0,
+	...over,
+});
+
+describe("guardFolderDeletion", () => {
+	it("blocks the inbox by its reserved path, case-insensitively", () => {
+		const target = folder({ mailboxId: "a", fullPath: "InBoX" });
+		const guard = guardFolderDeletion(target, [target], []);
+		assert.equal(guard.deletable, false);
+		assert.equal(guard.reason, "inbox");
+		assert.match(guard.message ?? "", /inbox can't be deleted/i);
+	});
+
+	it("blocks a folder appointed to a canonical role and names the role", () => {
+		const target = folder({ mailboxId: "arch", fullPath: "Archive" });
+		const guard = guardFolderDeletion(
+			target,
+			[target],
+			[{ role: "Archive", mailboxId: "arch" }],
+		);
+		assert.equal(guard.deletable, false);
+		assert.equal(guard.reason, "role");
+		assert.match(guard.message ?? "", /Archive/);
+	});
+
+	it("blocks a folder that has subfolders", () => {
+		const target = folder({ mailboxId: "work", fullPath: "Work" });
+		const child = folder({ mailboxId: "sub", fullPath: "Work/Shop" });
+		const guard = guardFolderDeletion(target, [target, child], []);
+		assert.equal(guard.deletable, false);
+		assert.equal(guard.reason, "children");
+		assert.match(guard.message ?? "", /subfolders/i);
+	});
+
+	it("allows a plain leaf folder with no role and no children", () => {
+		const target = folder({
+			mailboxId: "r",
+			fullPath: "Receipts",
+			messageCount: 4,
+		});
+		const other = folder({ mailboxId: "n", fullPath: "News" });
+		const guard = guardFolderDeletion(
+			target,
+			[target, other],
+			[{ role: "Archive", mailboxId: "other-box" }],
+		);
+		assert.deepEqual(guard, { deletable: true });
+	});
+
+	it("ignores an unfilled role appointment with no mailbox", () => {
+		const target = folder({ mailboxId: "r", fullPath: "Receipts" });
+		const guard = guardFolderDeletion(target, [target], [{ role: "Junk" }]);
+		assert.equal(guard.deletable, true);
+	});
+});
+
+describe("hasChildFolders", () => {
+	it("treats a delimiter-separated nested path as a child", () => {
+		const parent = {
+			mailboxId: "p",
+			fullPath: "Work",
+			hierarchyDelimiter: "/",
+		};
+		const kids = [{ mailboxId: "c", fullPath: "Work/Q3" }];
+		assert.equal(hasChildFolders(parent, [...kids, parent]), true);
+	});
+
+	it("does not treat a shared string prefix without a delimiter as a child", () => {
+		const parent = {
+			mailboxId: "p",
+			fullPath: "Work",
+			hierarchyDelimiter: "/",
+		};
+		const lookalike = [{ mailboxId: "w", fullPath: "Workshop" }];
+		assert.equal(hasChildFolders(parent, [...lookalike, parent]), false);
+	});
+
+	it("honours a non-slash delimiter", () => {
+		const parent = {
+			mailboxId: "p",
+			fullPath: "INBOX",
+			hierarchyDelimiter: ".",
+		};
+		const kids = [{ mailboxId: "c", fullPath: "INBOX.Sub" }];
+		assert.equal(hasChildFolders(parent, [...kids, parent]), true);
+	});
+});
+
+describe("appointedRole", () => {
+	it("returns the role a mailbox fills", () => {
+		assert.equal(
+			appointedRole("a", [{ role: "Trash", mailboxId: "a" }]),
+			"Trash",
+		);
+	});
+
+	it("returns undefined when the mailbox fills no role", () => {
+		assert.equal(
+			appointedRole("a", [{ role: "Trash", mailboxId: "b" }]),
+			undefined,
+		);
+	});
+});
+
+describe("excludeFolder", () => {
+	it("drops the folder being deleted from the destination list", () => {
+		const targets = [
+			{ mailboxId: "a" },
+			{ mailboxId: "b" },
+			{ mailboxId: "c" },
+		];
+		assert.deepEqual(excludeFolder(targets, "b"), [
+			{ mailboxId: "a" },
+			{ mailboxId: "c" },
+		]);
+	});
+});
+
+describe("move progress", () => {
+	it("begins at zero and moving for a non-empty set", () => {
+		assert.deepEqual(beginMove(120), { total: 120, moved: 0, phase: "moving" });
+	});
+
+	it("begins already moved for an empty set", () => {
+		assert.deepEqual(beginMove(0), { total: 0, moved: 0, phase: "moved" });
+	});
+
+	it("advances by the batch size and finishes at the total", () => {
+		let progress = beginMove(150);
+		progress = advanceMove(progress, 100);
+		assert.deepEqual(progress, { total: 150, moved: 100, phase: "moving" });
+		progress = advanceMove(progress, 50);
+		assert.deepEqual(progress, { total: 150, moved: 150, phase: "moved" });
+	});
+
+	it("clamps moved to the total if the folder shrank underneath the count", () => {
+		const progress = advanceMove(beginMove(80), 100);
+		assert.equal(progress.moved, 80);
+		assert.equal(progress.phase, "moved");
+	});
+
+	it("stops progress on failure and does not advance afterwards", () => {
+		const failed = failMove(beginMove(150), "boom");
+		assert.equal(failed.phase, "failed");
+		assert.equal(failed.moved, 0);
+		const after = advanceMove(failed, 100);
+		assert.deepEqual(after, failed);
+	});
+
+	it("labels progress as moved-of-total", () => {
+		assert.equal(
+			moveProgressLabel({ total: 150, moved: 100, phase: "moving" }),
+			"Moved 100 of 150",
+		);
+	});
+});
+
+describe("initialStage", () => {
+	it("opens on the empty confirm for a folder with no mail", () => {
+		assert.equal(initialStage(0), "confirm-empty");
+	});
+
+	it("opens on the fate choice for a folder holding mail", () => {
+		assert.equal(initialStage(3), "choose-fate");
+	});
+});

package/src/lib/delete-folder.ts

@@ -0,0 +1,151 @@
+export const MOVE_BATCH_SIZE = 100;
+
+export interface FolderNode {
+	mailboxId: string;
+	fullPath: string;
+	hierarchyDelimiter: string;
+	messageCount: number;
+}
+
+export interface RoleAppointment {
+	role: string;
+	mailboxId?: string | null;
+}
+
+export type DeleteBlockReason = "inbox" | "role" | "children";
+
+export interface DeleteGuard {
+	deletable: boolean;
+	reason?: DeleteBlockReason;
+	message?: string;
+}
+
+const isInboxPath = (fullPath: string): boolean =>
+	fullPath.trim().toLowerCase() === "inbox";
+
+/**
+ * A folder has children when another mailbox's path is nested under it — the
+ * folder's own path followed by the hierarchy delimiter. The delimiter matters:
+ * `Work` is not a parent of `Workshop`, only of `Work/Shop`.
+ */
+export const hasChildFolders = (
+	folder: Pick<FolderNode, "mailboxId" | "fullPath" | "hierarchyDelimiter">,
+	all: readonly Pick<FolderNode, "mailboxId" | "fullPath">[],
+): boolean => {
+	const prefix = `${folder.fullPath}${folder.hierarchyDelimiter}`;
+	return all.some(
+		(other) =>
+			other.mailboxId !== folder.mailboxId && other.fullPath.startsWith(prefix),
+	);
+};
+
+/** The canonical role a mailbox is appointed to, or `undefined` when unfilled. */
+export const appointedRole = (
+	mailboxId: string,
+	appointments: readonly RoleAppointment[],
+): string | undefined =>
+	appointments.find((a) => a.mailboxId != null && a.mailboxId === mailboxId)
+		?.role;
+
+/**
+ * Why a folder can't be deleted, or `{ deletable: true }` when it can. The
+ * inbox is reserved, a folder that fills a canonical role must be released
+ * first, and a folder with subfolders must have them handled before it goes.
+ */
+export function guardFolderDeletion(
+	folder: FolderNode,
+	all: readonly FolderNode[],
+	appointments: readonly RoleAppointment[],
+): DeleteGuard {
+	if (isInboxPath(folder.fullPath))
+		return {
+			deletable: false,
+			reason: "inbox",
+			message: "The inbox can't be deleted.",
+		};
+
+	const role = appointedRole(folder.mailboxId, appointments);
+	if (role)
+		return {
+			deletable: false,
+			reason: "role",
+			message: `This folder is your ${role} folder. Reassign that role before deleting it.`,
+		};
+
+	if (hasChildFolders(folder, all))
+		return {
+			deletable: false,
+			reason: "children",
+			message: "This folder has subfolders. Delete them first.",
+		};
+
+	return { deletable: true };
+}
+
+/** Destinations with the folder being deleted removed. */
+export function excludeFolder<T extends { mailboxId: string }>(
+	targets: readonly T[],
+	excludeMailboxId: string,
+): T[] {
+	return targets.filter((target) => target.mailboxId !== excludeMailboxId);
+}
+
+export type MovePhase = "moving" | "moved" | "failed";
+
+export interface MoveProgress {
+	total: number;
+	moved: number;
+	phase: MovePhase;
+	error?: string;
+}
+
+/** Progress at the start of a move; an empty set is already `moved`. */
+export function beginMove(total: number): MoveProgress {
+	return { total, moved: 0, phase: total === 0 ? "moved" : "moving" };
+}
+
+/**
+ * Count a successful batch. Clamps to `total` so a folder that grew mid-move
+ * never shows more moved than started, and only a still-`moving` progress
+ * advances — a failed or finished move stays put.
+ */
+export function advanceMove(
+	progress: MoveProgress,
+	batchSize: number,
+): MoveProgress {
+	if (progress.phase !== "moving") return progress;
+	const moved = Math.min(
+		progress.total,
+		progress.moved + Math.max(0, batchSize),
+	);
+	return {
+		...progress,
+		moved,
+		phase: moved >= progress.total ? "moved" : "moving",
+	};
+}
+
+/** A failed batch stops progress and surfaces the error; nothing advances after. */
+export function failMove(progress: MoveProgress, error: string): MoveProgress {
+	return { ...progress, phase: "failed", error };
+}
+
+export function moveProgressLabel(progress: MoveProgress): string {
+	return `Moved ${progress.moved} of ${progress.total}`;
+}
+
+export type DeleteStage =
+	| "confirm-empty"
+	| "choose-fate"
+	| "confirm-delete-all"
+	| "pick-destination"
+	| "moving"
+	| "deleting"
+	| "error";
+
+/** Where the wizard opens: a straight confirm for an empty folder, otherwise the fate step. */
+export function initialStage(
+	messageCount: number,
+): "confirm-empty" | "choose-fate" {
+	return messageCount > 0 ? "choose-fate" : "confirm-empty";
+}

package/src/lib/new-folder.test.ts

@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	composeFolderPath,
+	type FolderTarget,
+	validateNewFolderName,
+} from "./new-folder.js";
+
+const parent: FolderTarget = { fullPath: "INBOX", hierarchyDelimiter: "/" };
+
+describe("composeFolderPath", () => {
+	it("returns the trimmed name for a root folder", () => {
+		assert.equal(composeFolderPath("  Receipts  "), "Receipts");
+	});
+
+	it("joins the parent path by the parent's delimiter", () => {
+		assert.equal(composeFolderPath("Receipts", parent), "INBOX/Receipts");
+	});
+
+	it("honours a non-slash delimiter", () => {
+		assert.equal(
+			composeFolderPath("Receipts", {
+				fullPath: "INBOX",
+				hierarchyDelimiter: ".",
+			}),
+			"INBOX.Receipts",
+		);
+	});
+});
+
+describe("validateNewFolderName", () => {
+	const base = { delimiter: "/", existingPaths: ["INBOX", "INBOX/Archive"] };
+
+	it("rejects an empty or whitespace name", () => {
+		assert.match(
+			validateNewFolderName({ ...base, name: "   " }) ?? "",
+			/Enter a folder name/,
+		);
+	});
+
+	it("rejects a name containing the hierarchy delimiter", () => {
+		assert.match(
+			validateNewFolderName({ ...base, name: "a/b" }) ?? "",
+			/can't contain/,
+		);
+	});
+
+	it("rejects a name that would contain a non-slash delimiter", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: ".",
+				existingPaths: [],
+				name: "a.b",
+			}) ?? "",
+			/can't contain/,
+		);
+	});
+
+	it("rejects an exact collision with an existing path", () => {
+		assert.match(
+			validateNewFolderName({
+				...base,
+				name: "Archive",
+				parent,
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("rejects a root name that collides with an existing top-level fullPath", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["Work"],
+				name: "Work",
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("treats INBOX case-insensitively for collisions", () => {
+		assert.match(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["INBOX"],
+				name: "inbox",
+			}) ?? "",
+			/already exists/,
+		);
+	});
+
+	it("compares non-INBOX segments case-sensitively", () => {
+		assert.equal(
+			validateNewFolderName({
+				delimiter: "/",
+				existingPaths: ["Work"],
+				name: "work",
+			}),
+			undefined,
+		);
+	});
+
+	it("accepts a valid new nested folder", () => {
+		assert.equal(
+			validateNewFolderName({ ...base, name: "Receipts", parent }),
+			undefined,
+		);
+	});
+});