@remit/web-client 0.0.190 → 0.0.192

package/src/hooks/useEmptyTrash.render.test.ts

@@ -0,0 +1,194 @@
+/**
+ * What a refusal and a report are *about* (#847). The mailbox pane never
+ * remounts on a route change, so both are scoped: account A's standing refusal
+ * must not render over account B's Trash, and a count from a folder that was
+ * emptied must not outlive the folder it counted. The empty is also issued
+ * against the Trash `/config` names at that moment, so the replay after a
+ * repair invalidates the folder it actually emptied.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { configOperationsGetConfigQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { act, createElement } from "react";
+import { RoleAppointmentPromptProvider } from "@/components/mail/RoleAppointmentPromptProvider";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { type EmptyTrashState, useEmptyTrash } from "./useEmptyTrash";
+
+const ACCOUNT_A = "acc-a";
+const ACCOUNT_B = "acc-b";
+const TRASH_A = "mbx-trash-a";
+const TRASH_B = "mbx-trash-b";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+let state: EmptyTrashState | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	state = undefined;
+});
+
+const CONFIG = {
+	accounts: [
+		{
+			accountId: ACCOUNT_A,
+			email: "a@example.com",
+			folderAppointments: [
+				{ role: "Trash", mailboxId: TRASH_A, source: "Proposed" },
+			],
+		},
+		{
+			accountId: ACCOUNT_B,
+			email: "b@example.com",
+			folderAppointments: [
+				{ role: "Trash", mailboxId: TRASH_B, source: "Appointed" },
+			],
+		},
+	],
+};
+
+/** Fresh every call — a `Response` body can only be read once. */
+const refusal = (): Response =>
+	new Response(
+		JSON.stringify({
+			status: 409,
+			message: "Trash is not confirmed",
+			code: "folder_role_unresolved",
+			details: { reason: "unconfirmed", role: "Trash", accountId: ACCOUNT_A },
+		}),
+		{ status: 409, headers: { "content-type": "application/json" } },
+	);
+
+/** Account A refuses the empty; account B allows it. */
+const respond = (path: string): unknown => {
+	if (path.endsWith("/config")) return CONFIG;
+	if (path.endsWith(`/accounts/${ACCOUNT_A}/trash/empty`)) return refusal();
+	if (path.endsWith(`/accounts/${ACCOUNT_B}/trash/empty`))
+		return { deletedCount: 7 };
+	return {};
+};
+
+const Probe = ({
+	accountId,
+	mailboxId,
+}: {
+	accountId: string;
+	mailboxId: string;
+}) => {
+	state = useEmptyTrash({ accountId, mailboxId });
+	return null;
+};
+
+const tree = (accountId: string, mailboxId: string) =>
+	createElement(
+		QueryClientProvider,
+		{ client: harness?.queryClient as never },
+		createElement(
+			ErrorBannerProvider,
+			null,
+			createElement(
+				RoleAppointmentPromptProvider,
+				null,
+				createElement(Probe, { accountId, mailboxId }),
+			),
+		),
+	);
+
+const settle = async (done: () => boolean = () => false): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	for (let round = 0; round < 40; round += 1) {
+		await harness.flush();
+		await harness.wait(0);
+		if (done()) return;
+	}
+};
+
+const mount = async (accountId: string, mailboxId: string): Promise<void> => {
+	http = mockFetch((call) => respond(call.path));
+	harness = createDomHarness();
+	await harness.renderAsync(tree(accountId, mailboxId));
+	await settle(() => state !== undefined);
+};
+
+/** The same mounted pane, now looking at another folder — never a remount. */
+const openInstead = async (
+	accountId: string,
+	mailboxId: string,
+): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	await harness.renderAsync(tree(accountId, mailboxId));
+	await settle();
+};
+
+const press = async (done: () => boolean): Promise<void> => {
+	await act(async () => {
+		state?.emptyTrash();
+	});
+	await settle(done);
+};
+
+describe("useEmptyTrash scope", () => {
+	it("drops a refusal raised on one mailbox when another is opened", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		assert.equal(state?.refusal?.reason, "unconfirmed");
+		assert.equal(state?.refusal?.accountId, ACCOUNT_A);
+
+		await openInstead(ACCOUNT_B, TRASH_B);
+		assert.equal(state?.refusal, undefined);
+	});
+
+	it("drops a report of what was emptied when another mailbox is opened", async () => {
+		await mount(ACCOUNT_B, TRASH_B);
+		await press(() => state?.deletedCount !== undefined);
+		assert.equal(state?.deletedCount, 7);
+
+		await openInstead(ACCOUNT_A, TRASH_A);
+		assert.equal(state?.deletedCount, undefined);
+	});
+
+	it("issues the empty against the account the pane is on", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		await openInstead(ACCOUNT_B, TRASH_B);
+		await press(() => state?.deletedCount !== undefined);
+
+		const empties = (http?.calls ?? []).filter((call) =>
+			call.path.endsWith("/trash/empty"),
+		);
+		assert.equal(empties.length, 2);
+		assert.ok(empties[0].path.endsWith(`/accounts/${ACCOUNT_A}/trash/empty`));
+		assert.ok(empties[1].path.endsWith(`/accounts/${ACCOUNT_B}/trash/empty`));
+	});
+
+	it("drops the refusal once the account's Trash resolution changes", async () => {
+		await mount(ACCOUNT_A, TRASH_A);
+		await press(() => state?.refusal !== undefined);
+		assert.ok(state?.refusal);
+
+		// A repair made anywhere else — the settings pane, another tab — lands
+		// here as a new `/config`, and the refusal it answered is spent.
+		await act(async () => {
+			harness?.queryClient.setQueryData(configOperationsGetConfigQueryKey(), {
+				accounts: [
+					{
+						...CONFIG.accounts[0],
+						folderAppointments: [
+							{ role: "Trash", mailboxId: TRASH_A, source: "Appointed" },
+						],
+					},
+					CONFIG.accounts[1],
+				],
+			});
+		});
+		await settle(() => state?.refusal === undefined);
+		assert.equal(state?.refusal, undefined);
+	});
+});

package/src/hooks/useEmptyTrash.ts

@@ -0,0 +1,187 @@
+/**
+ * Emptying an account's Trash, and the refusal the server answers it with.
+ *
+ * The press always reaches the server (#847): the client's `/config` is a read
+ * that can be stale, so a folder-role refusal is the server's to make, and the
+ * 409 is the only authority the surface listens to. On that refusal the strip
+ * states it in place and the repair opens the appointment prompt, which replays
+ * the empty once a folder is confirmed (#887 D16 item 1).
+ */
+import {
+	configOperationsGetConfigQueryKey,
+	mailboxOperationsListMailboxesQueryKey,
+	trashOperationsEmptyTrashMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { ConfigOperationsGetConfigResponse } from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { useRoleAppointmentPrompt } from "@/components/mail/RoleAppointmentPromptProvider";
+import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
+import { formatErrorDetail } from "@/components/ui/error-banners";
+import {
+	type FolderRoleRefusal,
+	isFolderRoleRefusal,
+} from "@/components/ui/folder-role-refusal";
+import {
+	invalidateThreadListQueries,
+	threadListCacheKeys,
+} from "@/lib/thread-list-cache";
+import { useTrashByAccount } from "./useArchiveMailbox";
+
+interface UseEmptyTrashOptions {
+	accountId: string | undefined;
+	/** The open mailbox the strip is mounted over. */
+	mailboxId: string;
+}
+
+export interface EmptyTrashState {
+	emptyTrash: () => void;
+	isEmptying: boolean;
+	/** What the last finished run reported, straight from the service. */
+	deletedCount: number | undefined;
+	refusal: FolderRoleRefusal | undefined;
+	repair: () => void;
+}
+
+/**
+ * What a report or a refusal is about. Both are facts about one account's
+ * Trash as it resolved at the time, so neither may survive the mailbox or the
+ * account changing under a pane that never remounts — nor a resolution
+ * repaired elsewhere, which is the "or the resolution changes" the refusal
+ * persists until.
+ */
+const scopeOf = (
+	accountId: string | undefined,
+	mailboxId: string,
+	trashMailboxId: string | undefined,
+	source: string | undefined,
+): string =>
+	`${accountId ?? ""}|${mailboxId}|${trashMailboxId ?? ""}|${source ?? ""}`;
+
+interface EmptyTrashRun {
+	scope: string;
+	deletedCount?: number;
+	refusal?: FolderRoleRefusal;
+}
+
+interface EmptyTrashContext {
+	scope: string;
+	/** The folder the empty was issued against, whose listing it invalidates. */
+	listMailboxId: string;
+}
+
+export const useEmptyTrash = ({
+	accountId,
+	mailboxId,
+}: UseEmptyTrashOptions): EmptyTrashState => {
+	const queryClient = useQueryClient();
+	const { pushError } = useErrorBanners();
+	const { requestAppointment } = useRoleAppointmentPrompt();
+	const { trashByAccount } = useTrashByAccount();
+
+	const trash = accountId ? trashByAccount.get(accountId) : undefined;
+	const scope = scopeOf(accountId, mailboxId, trash?.mailboxId, trash?.source);
+
+	const [run, setRun] = useState<EmptyTrashRun>({ scope });
+	if (run.scope !== scope) setRun({ scope });
+	const current = run.scope === scope ? run : undefined;
+
+	/**
+	 * The Trash as `/config` reads *now*, straight from the cache. After a
+	 * repair the appointment names a different folder, and the replay must
+	 * invalidate that folder's listing rather than the one this pane opened —
+	 * a render has not necessarily flushed by the time the replay is called.
+	 */
+	const listMailboxIdNow = useCallback((): string => {
+		const config = queryClient.getQueryData<ConfigOperationsGetConfigResponse>(
+			configOperationsGetConfigQueryKey(),
+		);
+		const account = config?.accounts.find((one) => one.accountId === accountId);
+		const appointed = account?.folderAppointments.find(
+			(one) => one.role === "Trash",
+		)?.mailboxId;
+		return appointed ?? mailboxId;
+	}, [queryClient, accountId, mailboxId]);
+
+	// What the run in flight is about, for the same reason: a press on one
+	// folder must not read as a press on the next one the pane opens.
+	const inFlight = useRef<string>(undefined);
+
+	const { mutateAsync, isPending } = useMutation({
+		...trashOperationsEmptyTrashMutation(),
+		onMutate: (): EmptyTrashContext => {
+			inFlight.current = scope;
+			return { scope, listMailboxId: listMailboxIdNow() };
+		},
+		onSuccess: (data, _variables, context) => {
+			if (context.scope !== scope) return;
+			// The service's count, never a local tally. A second press re-marks the
+			// same rows and reports N again — that is what the folder still holds,
+			// and reporting 0 over an expunge is the failure #887 is about.
+			setRun({ scope, deletedCount: data.deletedCount });
+		},
+		onError: (error, _variables, context) => {
+			const refused = isFolderRoleRefusal(error);
+			if (!refused) {
+				pushError({
+					title: "Couldn't empty Trash",
+					detail: formatErrorDetail(error),
+					error,
+				});
+				return;
+			}
+			// A refusal that outlived what it was about states somebody else's
+			// problem over this folder.
+			if (context?.scope !== scope) return;
+			setRun({ scope, refusal: refused });
+		},
+		onSettled: (_data, _error, _variables, context) => {
+			if (inFlight.current === context?.scope) inFlight.current = undefined;
+			invalidateThreadListQueries(
+				queryClient,
+				threadListCacheKeys([context?.listMailboxId ?? mailboxId]),
+			);
+			if (!accountId) return;
+			queryClient.invalidateQueries({
+				queryKey: mailboxOperationsListMailboxesQueryKey({
+					path: { accountId },
+				}),
+			});
+		},
+	});
+
+	// `onError` above has already stated the failure; the rejection reaching the
+	// caller would only report it a second time.
+	const issue = useCallback((): Promise<void> => {
+		if (!accountId) return Promise.resolve();
+		setRun({ scope });
+		return mutateAsync({ path: { accountId } }).then(
+			() => {},
+			() => {},
+		);
+	}, [accountId, scope, mutateAsync]);
+
+	const emptyTrash = useCallback(() => {
+		void issue();
+	}, [issue]);
+
+	const repair = useCallback(() => {
+		const refusal = current?.refusal;
+		if (!refusal) return;
+		requestAppointment({
+			accountId: refusal.accountId,
+			role: refusal.role,
+			reason: refusal.reason,
+			action: { kind: "emptyTrash" },
+			onAppointed: issue,
+		});
+	}, [current, requestAppointment, issue]);
+
+	return {
+		emptyTrash,
+		isEmptying: isPending && inFlight.current === scope,
+		deletedCount: current?.deletedCount,
+		refusal: current?.refusal,
+		repair,
+	};
+};

package/src/lib/format.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
-import type { DeleteTarget } from "./format.js";
+import type { DeleteTarget, TrashResolution } from "./format.js";
 import {
 	deleteConfirmationCopy,
 	deleteOutcomeFor,
@@ -166,9 +166,9 @@ describe("deleteConfirmationCopy", () => {
  * the error path.
  */
 describe("deleteOutcomeFor", () => {
-	const trashByAccount = new Map([
-		["acct-1", "mbx-trash"],
-		["acct-2", undefined],
+	const trashByAccount = new Map<string, TrashResolution>([
+		["acct-1", { mailboxId: "mbx-trash", source: "Appointed" }],
+		["acct-2", { mailboxId: undefined, source: "None" }],
 	]);
 	const settled = { trashByAccount, hasAppointments: true, isError: false };
 	// No default for the account: a default parameter is applied to an explicit
@@ -234,9 +234,9 @@ describe("deleteOutcomeFor", () => {
 		assert.strictEqual(
 			deleteOutcomeFor({
 				...settled,
-				trashByAccount: new Map([
-					["acct-1", "mbx-trash"],
-					["acct-2", "mbx-other-trash"],
+				trashByAccount: new Map<string, TrashResolution>([
+					["acct-1", { mailboxId: "mbx-trash", source: "Appointed" }],
+					["acct-2", { mailboxId: "mbx-other-trash", source: "Appointed" }],
 				]),
 				targets: [target("mbx-trash", "acct-2")],
 			}),
@@ -306,6 +306,67 @@ describe("deleteOutcomeFor", () => {
 			"unknown",
 		);
 	});
+
+	test("a Trash the account lost is a repair, not a missing appointment", () => {
+		assert.strictEqual(
+			deleteOutcomeFor({
+				...settled,
+				trashByAccount: new Map<string, TrashResolution>([
+					[
+						"acct-1",
+						{
+							mailboxId: "mbx-fallback",
+							source: "Stale",
+							staleFolderPath: "INBOX/Prullenbak",
+						},
+					],
+				]),
+				targets: [target("mbx-inbox", "acct-1")],
+			}),
+			"staleTrash",
+			"the folder the user chose is gone; a fallback is not their choice",
+		);
+	});
+
+	test("a Trash matched only by name still takes an ordinary delete", () => {
+		assert.strictEqual(
+			deleteOutcomeFor({
+				...settled,
+				trashByAccount: new Map<string, TrashResolution>([
+					["acct-1", { mailboxId: "mbx-trash", source: "Proposed" }],
+				]),
+				targets: [target("mbx-inbox", "acct-1")],
+			}),
+			"trash",
+			"only Empty Trash demands a confirmed appointment (D4)",
+		);
+	});
+
+	test("never answers `unconfirmed`, whatever the rows say", () => {
+		const sources: TrashResolution["source"][] = [
+			"Appointed",
+			"Flagged",
+			"Reserved",
+			"Proposed",
+			"Stale",
+			"None",
+		];
+		for (const source of sources) {
+			for (const mailboxId of ["mbx-trash", "mbx-inbox", undefined]) {
+				assert.notStrictEqual(
+					deleteOutcomeFor({
+						...settled,
+						trashByAccount: new Map<string, TrashResolution>([
+							["acct-1", { mailboxId, source }],
+						]),
+						targets: [target("mbx-inbox", "acct-1")],
+					}),
+					"unconfirmed",
+					"the targets of a delete say nothing about a whole folder",
+				);
+			}
+		}
+	});
 });
 
 describe("deleteConfirmationCopy — the refusal", () => {
@@ -324,11 +385,14 @@ describe("deleteConfirmationCopy — the refusal", () => {
 		assert.ok(!copy.description.includes("restore"));
 	});
 
-	test("sends an unappointed Trash to the screen that appoints one", () => {
+	test("answers a missing Trash where the refusal happened", () => {
 		const copy = deleteConfirmationCopy(3, "noTrash");
-		assert.strictEqual(copy.title, "Can't delete 3 messages");
-		assert.match(copy.description, /appointed as Trash/);
-		assert.strictEqual(copy.confirmLabel, "Open folder settings");
+		assert.strictEqual(copy.title, "Can't delete 3 messages yet");
+		assert.strictEqual(
+			copy.description,
+			"No folder on this account is set as Trash, so there is nowhere to move the mail. Nothing has been deleted.",
+		);
+		assert.strictEqual(copy.confirmLabel, "Pick a Trash folder");
 	});
 
 	test("never promises a restore when no Trash is appointed", () => {
@@ -336,4 +400,62 @@ describe("deleteConfirmationCopy — the refusal", () => {
 		assert.ok(!copy.title.includes("Move"));
 		assert.ok(!copy.description.includes("restore"));
 	});
+
+	test("names the folder that vanished, and drops the clause without one", () => {
+		const named = deleteConfirmationCopy(3, "staleTrash", {
+			staleFolderLabel: "INBOX/Prullenbak",
+		});
+		assert.strictEqual(named.title, "Can't delete 3 messages yet");
+		assert.strictEqual(
+			named.description,
+			"The folder you set as this account's Trash — INBOX/Prullenbak — is gone from the mail server. Nothing has been deleted.",
+		);
+		assert.strictEqual(named.confirmLabel, "Pick another folder");
+		assert.strictEqual(
+			deleteConfirmationCopy(3, "staleTrash").description,
+			"The folder you set as this account's Trash is gone from the mail server. Nothing has been deleted.",
+		);
+	});
+
+	test("names the guess and the irreversibility before an Empty Trash", () => {
+		const copy = deleteConfirmationCopy(0, "unconfirmed", {
+			trashFolderLabel: "Deleted Messages",
+		});
+		assert.strictEqual(copy.title, "Confirm this account's Trash folder");
+		assert.strictEqual(
+			copy.description,
+			"reader files this account's deleted mail in Deleted Messages because of its name — nobody confirmed it. Emptying a folder erases everything in it from the mail server, and that cannot be restored. Nothing has been emptied.",
+		);
+		assert.strictEqual(copy.confirmLabel, "Confirm the folder");
+	});
+
+	test("keeps today's words for an expunge inside a confirmed Trash", () => {
+		assert.deepStrictEqual(deleteConfirmationCopy(2, "permanent"), {
+			title: "Permanently delete 2 messages?",
+			description:
+				"They are erased from the mail server and cannot be restored.",
+			confirmLabel: "Delete permanently",
+		});
+	});
+
+	test("names the folder before an expunge inside a Trash nobody confirmed", () => {
+		const copy = deleteConfirmationCopy(2, "permanent", {
+			trashFolderLabel: "Deleted Messages",
+			trashIsUnconfirmed: true,
+		});
+		assert.strictEqual(copy.title, "Permanently delete 2 messages?");
+		assert.strictEqual(
+			copy.description,
+			"They are in Deleted Messages, which reader treats as this account's Trash because of its name — nobody confirmed it. They are erased from the mail server and cannot be restored.",
+		);
+		assert.strictEqual(copy.confirmLabel, "Delete permanently");
+	});
+
+	test("drops the name clause when the caller holds no folder name", () => {
+		const copy = deleteConfirmationCopy(2, "permanent", {
+			trashIsUnconfirmed: true,
+		});
+		assert.match(copy.description, /because of its name — nobody confirmed it/);
+		assert.ok(!copy.description.includes("undefined"));
+	});
 });