@remit/web-client 0.0.190 → 0.0.191

package/src/components/ui/folder-role-refusal.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	isFolderRoleRefusal,
+	isMailboxNotSettledRefusal,
+} from "./folder-role-refusal.js";
+
+const refusal = {
+	code: "folder_role_unresolved",
+	message: "No folder is appointed as Trash",
+	details: { role: "Trash", reason: "none", accountId: "acct-1" },
+};
+
+describe("isFolderRoleRefusal", () => {
+	it("carries the account and the reason the prompt needs", () => {
+		assert.deepEqual(isFolderRoleRefusal(refusal), {
+			reason: "none",
+			role: "Trash",
+			accountId: "acct-1",
+		});
+	});
+
+	it("reads every reason the API declares", () => {
+		for (const reason of ["none", "stale", "unconfirmed"]) {
+			assert.equal(
+				isFolderRoleRefusal({
+					...refusal,
+					details: { ...refusal.details, reason },
+				})?.reason,
+				reason,
+			);
+		}
+	});
+
+	it("does not open the prompt for a 409 without the code", () => {
+		assert.equal(
+			isFolderRoleRefusal({
+				message: "No folder is appointed as Trash",
+				details: refusal.details,
+			}),
+			undefined,
+		);
+		assert.equal(
+			isFolderRoleRefusal({ ...refusal, code: "mailbox_not_settled" }),
+			undefined,
+		);
+	});
+
+	it("never guesses at a message string", () => {
+		assert.equal(
+			isFolderRoleRefusal(new Error("folder_role_unresolved: Trash")),
+			undefined,
+		);
+	});
+
+	it("refuses a body missing anything the prompt has to have", () => {
+		assert.equal(isFolderRoleRefusal({ ...refusal, details: {} }), undefined);
+		assert.equal(
+			isFolderRoleRefusal({
+				...refusal,
+				details: { role: "Trash", reason: "sideways", accountId: "acct-1" },
+			}),
+			undefined,
+		);
+		assert.equal(
+			isFolderRoleRefusal({
+				...refusal,
+				details: { role: "Trash", reason: "none" },
+			}),
+			undefined,
+		);
+	});
+
+	it("survives anything a network layer might throw", () => {
+		for (const value of [undefined, null, "boom", 409, []]) {
+			assert.equal(isFolderRoleRefusal(value), undefined);
+		}
+	});
+});
+
+describe("isMailboxNotSettledRefusal", () => {
+	it("matches only the appointment write's own refusal", () => {
+		assert.equal(
+			isMailboxNotSettledRefusal({
+				code: "mailbox_not_settled",
+				message: "Mailbox is still being created",
+				details: { mailboxId: "mbx-1", syncStatus: "pending" },
+			}),
+			true,
+		);
+		assert.equal(isMailboxNotSettledRefusal(refusal), false);
+		assert.equal(isMailboxNotSettledRefusal(new Error("pending")), false);
+	});
+});

package/src/components/ui/folder-role-refusal.ts

@@ -0,0 +1,81 @@
+/**
+ * The coded 409 a destructive action is refused with when the folder role it
+ * needs is unsettled (#887). Read the `code`, never the message: the copy is
+ * free to change and a message-string match would silently start opening the
+ * appointment prompt over an unrelated conflict. A 409 without one of these
+ * codes is somebody else's error and keeps today's banner.
+ */
+import type {
+	ApiError,
+	RemitImapCanonicalMailboxRole,
+} from "@remit/api-http-client/types.gen.ts";
+import { CanonicalMailboxRole } from "@remit/domain-enums";
+
+/** Why the role is unresolved, as the API's `details.reason` spells it. */
+export type FolderRoleRefusalReason = "none" | "stale" | "unconfirmed";
+
+/** `FolderRoleConflict`'s `details`, narrowed to the values the prompt needs. */
+export interface FolderRoleRefusal {
+	reason: FolderRoleRefusalReason;
+	role: RemitImapCanonicalMailboxRole;
+	accountId: string;
+}
+
+const REASONS: ReadonlySet<string> = new Set<FolderRoleRefusalReason>([
+	"none",
+	"stale",
+	"unconfirmed",
+]);
+
+const ROLES: ReadonlySet<string> = new Set(Object.values(CanonicalMailboxRole));
+
+/**
+ * The wire body as `handleError` emits it — flat, so `code` and `details` sit
+ * at the top level. Everything is re-checked at runtime: this is a network
+ * boundary, and the type only says what the contract promises.
+ */
+const bodyOf = (error: unknown): Partial<ApiError> | undefined =>
+	typeof error === "object" && error !== null
+		? (error as Partial<ApiError>)
+		: undefined;
+
+const stringAt = (
+	details: ApiError["details"],
+	key: string,
+): string | undefined => {
+	const value = details?.[key];
+	return typeof value === "string" ? value : undefined;
+};
+
+/**
+ * The refusal, or `undefined` for every other failure. Every fact the prompt
+ * needs travels with it: the account to appoint on (the delete endpoint's body
+ * carries none), the role, and the reason, which decides the framing.
+ */
+export const isFolderRoleRefusal = (
+	error: unknown,
+): FolderRoleRefusal | undefined => {
+	const body = bodyOf(error);
+	if (body?.code !== "folder_role_unresolved") return undefined;
+	const { details } = body;
+	if (typeof details !== "object" || details === null) return undefined;
+	const reason = stringAt(details, "reason");
+	const role = stringAt(details, "role");
+	const accountId = stringAt(details, "accountId");
+	if (!reason || !REASONS.has(reason)) return undefined;
+	if (!role || !ROLES.has(role) || !accountId) return undefined;
+	return {
+		reason: reason as FolderRoleRefusalReason,
+		role: role as RemitImapCanonicalMailboxRole,
+		accountId,
+	};
+};
+
+/**
+ * The appointment write's own refusal: the mailbox is still being created or
+ * deleted on the mail server, so it cannot hold a role yet. A different
+ * sentence with a different remedy from a network failure — waiting fixes this
+ * one, retrying does not.
+ */
+export const isMailboxNotSettledRefusal = (error: unknown): boolean =>
+	bodyOf(error)?.code === "mailbox_not_settled";

package/src/hooks/useArchiveMailbox.ts

@@ -5,6 +5,7 @@ import type {
 } from "@remit/api-http-client/types.gen.ts";
 import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
+import type { TrashResolution } from "@/lib/format";
 
 /**
  * RFC 032 exclusive-folder-appointment (#976): every "which mailbox plays
@@ -99,7 +100,7 @@ export const useJunkMailbox = (
  * move over an expunge that would replay on reconnect.
  */
 export const useTrashByAccount = (): {
-	trashByAccount: ReadonlyMap<string, string | undefined>;
+	trashByAccount: ReadonlyMap<string, TrashResolution>;
 	hasAppointments: boolean;
 	isError: boolean;
 } => {
@@ -109,12 +110,16 @@ export const useTrashByAccount = (): {
 	});
 
 	const trashByAccount = useMemo(() => {
-		const byAccount = new Map<string, string | undefined>();
+		const byAccount = new Map<string, TrashResolution>();
 		for (const account of config?.accounts ?? []) {
-			byAccount.set(
-				account.accountId,
-				account.folderAppointments.find((fa) => fa.role === "Trash")?.mailboxId,
+			const trash = account.folderAppointments.find(
+				(appointment) => appointment.role === "Trash",
 			);
+			byAccount.set(account.accountId, {
+				mailboxId: trash?.mailboxId,
+				source: trash?.source ?? "None",
+				staleFolderPath: trash?.staleAppointmentPath,
+			});
 		}
 		return byAccount;
 	}, [config]);

package/src/hooks/useDeleteMessages.ts

@@ -5,9 +5,11 @@ import {
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import { useRoleAppointmentPrompt } from "@/components/mail/RoleAppointmentPromptProvider";
 import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
 import { formatErrorDetail } from "@/components/ui/error-banners";
+import { isFolderRoleRefusal } from "@/components/ui/folder-role-refusal";
 import { resolveMailboxesForMessages } from "@/hooks/useMarkAsRead";
 import { runChunkedMutation } from "@/lib/bulk-actions";
 import {
@@ -75,6 +77,14 @@ export const useDeleteMessages = ({
 }: UseDeleteMessagesOptions) => {
 	const queryClient = useQueryClient();
 	const { pushError } = useErrorBanners();
+	const { requestAppointment } = useRoleAppointmentPrompt();
+
+	// The refused chunk is not what the user asked for. The whole selection is
+	// held here so the appointment's confirm replays all of it (#887).
+	const selectionRef = useRef<string[]>([]);
+	const runRef = useRef<(messageIds: string[]) => Promise<void>>(
+		async () => {},
+	);
 
 	const { mutateAsync, isPending } = useMutation({
 		...messageBulkOperationsDeleteMessagesMutation(),
@@ -149,6 +159,21 @@ export const useDeleteMessages = ({
 				}
 				restoreThreadListQueries(queryClient, context.previousThreadsList);
 			}
+			// A provenance refusal is answered by the prompt, not by a banner: the
+			// generic banner is suppressed for this one error, and every other
+			// failure keeps today's.
+			const refusal = isFolderRoleRefusal(err);
+			if (refusal) {
+				const replay = selectionRef.current;
+				requestAppointment({
+					accountId: refusal.accountId,
+					role: refusal.role,
+					reason: refusal.reason,
+					action: { kind: "delete", count: replay.length },
+					onAppointed: () => runRef.current(replay),
+				});
+				return;
+			}
 			const count = vars.body.messageIds?.length ?? 0;
 			pushError({
 				title:
@@ -177,14 +202,25 @@ export const useDeleteMessages = ({
 		},
 	});
 
+	const runSelection = useCallback(
+		(messageIds: string[]): Promise<void> =>
+			runChunkedMutation(messageIds, (chunk) =>
+				mutateAsync({ body: { messageIds: chunk } }),
+			),
+		[mutateAsync],
+	);
+
+	useEffect(() => {
+		runRef.current = runSelection;
+	}, [runSelection]);
+
 	const deleteMessages = useCallback(
 		(messageIds: string[]) => {
 			if (messageIds.length === 0) return;
-			void runChunkedMutation(messageIds, (chunk) =>
-				mutateAsync({ body: { messageIds: chunk } }),
-			);
+			selectionRef.current = messageIds;
+			void runSelection(messageIds);
 		},
-		[mutateAsync],
+		[runSelection],
 	);
 
 	return { deleteMessages, isPending };

package/src/hooks/useDeleteOutcome.ts

@@ -11,7 +11,9 @@
  * from several mailboxes and several accounts at once.
  *
  * The decision itself is `deleteOutcomeFor`, kept pure in `lib/format`; this is
- * only the read that feeds it.
+ * only the read that feeds it. The two facts beside it are what the copy needs
+ * to name a folder: whether the Trash it resolved is a name match nobody
+ * confirmed (D4a), and the folder a stale appointment lost.
  */
 import { useMemo } from "react";
 import {
@@ -21,15 +23,43 @@ import {
 } from "@/lib/format";
 import { useTrashByAccount } from "./useArchiveMailbox";
 
+export interface DeleteOutcomeResult {
+	outcome: DeleteOutcome;
+	/** The Trash these rows resolve to was matched by name, never confirmed. */
+	trashIsUnconfirmed: boolean;
+	/** The folder the user appointed, when it is gone from the mail server. */
+	staleFolderLabel?: string;
+}
+
 /** The outcome of deleting `targets`. */
 export const useDeleteOutcome = (
 	targets: readonly DeleteTarget[],
-): DeleteOutcome => {
+): DeleteOutcomeResult => {
 	const { trashByAccount, hasAppointments, isError } = useTrashByAccount();
 
-	return useMemo(
-		() =>
-			deleteOutcomeFor({ targets, trashByAccount, hasAppointments, isError }),
-		[targets, trashByAccount, hasAppointments, isError],
-	);
+	return useMemo(() => {
+		const outcome = deleteOutcomeFor({
+			targets,
+			trashByAccount,
+			hasAppointments,
+			isError,
+		});
+		const trashFor = (target: DeleteTarget) =>
+			target.accountId ? trashByAccount.get(target.accountId) : undefined;
+		return {
+			outcome,
+			// Only the rows the delete would actually expunge — a row filed
+			// somewhere else says nothing about the folder it is moving into.
+			trashIsUnconfirmed: targets.some((target) => {
+				const trash = trashFor(target);
+				return (
+					trash?.source === "Proposed" && trash.mailboxId === target.mailboxId
+				);
+			}),
+			// The account `deleteOutcomeFor` refused on, found the way it found it.
+			staleFolderLabel: targets
+				.map(trashFor)
+				.find((trash) => trash?.source === "Stale")?.staleFolderPath,
+		};
+	}, [targets, trashByAccount, hasAppointments, isError]);
 };

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"));
+	});
 });