@remit/web-client 0.0.129 → 0.0.130

package/src/hooks/useAutoMovedBadge.ts

@@ -1,15 +1,20 @@
 import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapAutoMovedInfo } from "@remit/api-http-client/types.gen.ts";
+import type {
+	RemitImapAutoMovedInfo,
+	RemitImapMessageSpamReport,
+} from "@remit/api-http-client/types.gen.ts";
 import { useQuery } from "@tanstack/react-query";
 import { useCallback } from "react";
 import {
 	autoMovedLabel,
 	isAutoMoveInEffect,
 	resolveUndoTargetMailboxId,
+	spamReportLabel,
 } from "@/lib/auto-moved";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
 import { useInboxMailbox, useJunkMailbox } from "./useArchiveMailbox";
 import { useMoveMessages } from "./useMoveMessages";
+import { useReportSpam } from "./useReportSpam";
 
 interface UseAutoMovedBadgeOptions {
 	accountId: string | undefined;
@@ -18,6 +23,14 @@ interface UseAutoMovedBadgeOptions {
 	/** The message's current mailbox — the row/card it's rendered in. */
 	mailboxId: string;
 	autoMoved: RemitImapAutoMovedInfo | undefined;
+	/**
+	 * Present when the user reported this message as spam and the report has
+	 * not been undone (issue #648). Takes precedence over `autoMoved`: a
+	 * report can be a no-op move (the provider's own filter already placed the
+	 * message in Junk), so it carries its own badge independent of the
+	 * message's current folder, unlike a classifier/filter move.
+	 */
+	spamReport: RemitImapMessageSpamReport | undefined;
 }
 
 export interface AutoMovedBadgeState {
@@ -36,22 +49,27 @@ export interface AutoMovedBadgeState {
 }
 
 /**
- * Composes the account's mailboxes with the message's `autoMoved` projection
- * into everything the `AutoMovedBadge` kit component needs: the derived "still
- * in effect" gate, the plain-language label, and a one-click undo bound to the
- * existing `moveMessages` mutation (no new endpoint — moves back through the
- * same bulk move operation, the other direction).
+ * Composes the account's mailboxes with the message's `autoMoved` and
+ * `spamReport` projections into everything the `AutoMovedBadge` kit component
+ * needs: the derived "still in effect" gate, the plain-language label, and a
+ * one-click undo.
  *
- * Both auto-move shapes are handled. A classifier move resolves its
- * Inbox/Junk role mailboxes; a standing-filter move names an arbitrary source
- * folder, whose display name is resolved from the account's mailbox list, and
- * carries a Settings › Filters link so the filter that keeps moving mail is one
- * tap away — undo does not disable it.
+ * Three provenances are handled, `spamReport` taking priority when present:
+ * - A spam report (issue #648) undoes via `POST /messages/not-spam`, which
+ *   resolves its own restore target server-side — the client never needs an
+ *   Inbox/Junk lookup for it, and the badge shows regardless of the message's
+ *   current folder (a report can be a no-op move).
+ * - A classifier move resolves its Inbox/Junk role mailboxes and undoes via a
+ *   plain move back to the source role.
+ * - A standing-filter move names an arbitrary source folder, whose display
+ *   name is resolved from the account's mailbox list, and carries a
+ *   Settings › Filters link so the filter that keeps moving mail is one tap
+ *   away — undo does not disable it.
  *
- * `show` re-derives on every render from `mailboxId` — no local dismissed
- * flag. Once `moveMessages` settles, its query invalidation refetches the
- * thread row with its updated `mailboxId`, and the badge naturally stops
- * showing (doc/rules/data-flow.md).
+ * `show` re-derives on every render from `mailboxId` (or from `spamReport`'s
+ * presence) — no local dismissed flag. Once the undo mutation settles, its
+ * query invalidation refetches the thread row with its updated state, and the
+ * badge naturally stops showing (doc/rules/data-flow.md).
  */
 export const useAutoMovedBadge = ({
 	accountId,
@@ -59,10 +77,16 @@ export const useAutoMovedBadge = ({
 	threadId,
 	mailboxId,
 	autoMoved,
+	spamReport,
 }: UseAutoMovedBadgeOptions): AutoMovedBadgeState => {
 	const { inboxMailboxId } = useInboxMailbox(accountId);
 	const { junkMailboxId } = useJunkMailbox(accountId);
-	const { moveMessages, isPending } = useMoveMessages({
+	const { moveMessages, isPending: isMoveUndoing } = useMoveMessages({
+		mailboxId,
+		threadId,
+		accountId,
+	});
+	const { notSpam, isRestoring: isSpamUndoing } = useReportSpam({
 		mailboxId,
 		threadId,
 		accountId,
@@ -77,17 +101,30 @@ export const useAutoMovedBadge = ({
 	});
 
 	const roleMailboxes = { inboxMailboxId, junkMailboxId };
-	const show = isAutoMoveInEffect(autoMoved, mailboxId, roleMailboxes);
 	const undoTargetMailboxId = resolveUndoTargetMailboxId(
 		autoMoved,
 		roleMailboxes,
 	);
 
-	const handleUndo = useCallback(() => {
+	const handleUndoMove = useCallback(() => {
 		if (!undoTargetMailboxId) return;
 		moveMessages([messageId], undoTargetMailboxId);
 	}, [moveMessages, messageId, undoTargetMailboxId]);
 
+	const handleUndoReport = useCallback(() => {
+		notSpam([messageId]);
+	}, [notSpam, messageId]);
+
+	if (spamReport) {
+		return {
+			show: true,
+			label: spamReportLabel,
+			onUndo: handleUndoReport,
+			isUndoing: isSpamUndoing,
+		};
+	}
+
+	const show = isAutoMoveInEffect(autoMoved, mailboxId, roleMailboxes);
 	if (!show || !autoMoved) {
 		return { show: false, label: "", isUndoing: false };
 	}
@@ -101,8 +138,8 @@ export const useAutoMovedBadge = ({
 	return {
 		show: true,
 		label: autoMovedLabel(autoMoved, sourceFolderName),
-		onUndo: undoTargetMailboxId ? handleUndo : undefined,
-		isUndoing: isPending,
+		onUndo: undoTargetMailboxId ? handleUndoMove : undefined,
+		isUndoing: isMoveUndoing,
 		...(autoMoved.filterId ? { filtersHref: "/settings/filters" } : {}),
 	};
 };

package/src/hooks/useReportSpam.integration.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Integration: prove a per-message report-spam/not-spam failure resolves to a
+ * banner, never the full-screen fatal overlay, through the REAL global
+ * `MutationCache` wiring (`lib/query-error-handler.ts`, wired on the
+ * `QueryClient` in `shell/index.tsx`) — not just `ErrorBannerProvider`'s own
+ * `isAlwaysFatal` check.
+ *
+ * That distinction is the whole point of this file. `ErrorBannerProvider.
+ * pushError` refuses to banner an always-fatal error, but every mutation
+ * ALSO reports to the MutationCache's global `onError`, independent of
+ * whatever the per-mutation `onError` did — and `shouldEscalate` (what the
+ * global handler calls) escalates by DEFAULT for any non-5xx that didn't opt
+ * out via `meta.softError`. A test that only checked `isAlwaysFatal` passed
+ * while the real app crashed to the fatal overlay on the same error: this is
+ * exactly `query-escalation.integration.test.ts`'s pattern, applied to
+ * `useReportSpam`'s own mutation shape (mutationFn + meta), because that is
+ * the seam the earlier fix went through unexercised.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
+import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "../lib/query-error-handler";
+import { throwOnBulkFailure } from "./useReportSpam.js";
+
+afterEach(() => {
+	__resetFatalError();
+});
+
+const makeClient = () =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: { mutations: { retry: false } },
+	});
+
+/** The exact shape a failed report-spam/not-spam call resolves to on the wire (200, not a rejection) — see `throwOnBulkFailure`. */
+const failedBulkResult = () => ({
+	successCount: 0,
+	failureCount: 1,
+	failures: [
+		{
+			messageId: "9m2k7x4vqz1jd0tn3wf8b6y5c",
+			reason:
+				"Message 9m2k7x4vqz1jd0tn3wf8b6y5c's move to Junk has not settled yet; try again in a moment.",
+		},
+	],
+});
+
+describe("useReportSpam's mutations under the real MutationCache (#648 review)", () => {
+	it("with meta.softError, a per-message failure does NOT escalate to the fatal overlay (regression)", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+
+		const mutation = client.getMutationCache().build(client, {
+			mutationFn: async () => {
+				throwOnBulkFailure(failedBulkResult());
+			},
+			meta: { softError: true },
+		});
+		await mutation.execute(undefined).catch(() => {});
+
+		assert.deepEqual(
+			seen,
+			[],
+			"a designed, retryable per-message failure must not reach the fatal overlay",
+		);
+	});
+
+	it("without meta.softError, the same failure DOES escalate — proving the opt-out is load-bearing, not a no-op", async () => {
+		const seen: string[] = [];
+		subscribeFatalError((fatal) => seen.push(fatal.message));
+		const client = makeClient();
+
+		const mutation = client.getMutationCache().build(client, {
+			mutationFn: async () => {
+				throwOnBulkFailure(failedBulkResult());
+			},
+		});
+		await mutation.execute(undefined).catch(() => {});
+
+		assert.equal(
+			seen.length,
+			1,
+			"this asserts the failure mode the fix removes — a non-5xx with no softError opt-out escalates by default",
+		);
+	});
+});

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

@@ -0,0 +1,113 @@
+/**
+ * Mounts the real hook against the real fetch seam to prove the pending state
+ * a press needs actually toggles (issue #648 review): with no optimistic
+ * cache patch, a press that never flips `isReporting`/`isRestoring` would be
+ * a genuinely dead control — nothing visible changes until the request lands.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement } from "react";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, mockFetch } from "../test-support/http";
+import { useReportSpam } from "./useReportSpam";
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+const mountHook = <T>(useHook: () => T): (() => T) => {
+	let value: T | undefined;
+	const Probe = () => {
+		value = useHook();
+		return null;
+	};
+	harness = createDomHarness();
+	harness.renderApp(createElement(Probe));
+	return () => {
+		if (value === undefined) throw new Error("hook did not render");
+		return value;
+	};
+};
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+});
+
+/**
+ * Polls `predicate` until it's true, yielding real event-loop turns between
+ * attempts rather than spinning a fixed count of microtask flushes — the
+ * chain from a resolved fetch to a re-render crosses enough async boundaries
+ * (response parsing, `throwOnBulkFailure`, `onSuccess`'s invalidation, React's
+ * commit) that a fixed count reads as flaky under load instead of wrong.
+ */
+const waitFor = async (
+	predicate: () => boolean,
+	timeoutMs = 2000,
+): Promise<void> => {
+	if (!harness) throw new Error("nothing mounted");
+	const deadline = Date.now() + timeoutMs;
+	while (!predicate()) {
+		if (Date.now() > deadline) {
+			throw new Error(
+				`waitFor: condition never became true within ${timeoutMs}ms`,
+			);
+		}
+		await harness.flush();
+		await harness.wait(5);
+	}
+};
+
+describe("useReportSpam pending state (#648 review)", () => {
+	it("isReporting goes true for the duration of an in-flight report, then false", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
+
+		assert.equal(hook().isReporting, false);
+
+		hook().reportSpam(["msg-1"]);
+		await waitFor(() => hook().isReporting === true);
+
+		assert.ok(resolveRequest, "the request never reached the mock");
+		resolveRequest?.();
+		await waitFor(() => hook().isReporting === false);
+	});
+
+	it("isRestoring goes true for the duration of an in-flight undo, then false", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-junk" }));
+
+		assert.equal(hook().isRestoring, false);
+
+		hook().notSpam(["msg-1"]);
+		await waitFor(() => hook().isRestoring === true);
+
+		resolveRequest?.();
+		await waitFor(() => hook().isRestoring === false);
+	});
+
+	it("sends the request to the report-spam endpoint with the pressed message id", async () => {
+		http = mockFetch(() => ({ successCount: 1, failureCount: 0 }));
+		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
+
+		hook().reportSpam(["msg-1"]);
+		await waitFor(() => http.to("/messages/report-spam").length > 0);
+
+		const calls = http.to("/messages/report-spam");
+		assert.equal(calls.length, 1);
+		assert.deepEqual(calls[0].body, { messageIds: ["msg-1"] });
+	});
+});

package/src/hooks/useReportSpam.test.ts

@@ -0,0 +1,115 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import {
+	GENERIC_SPAM_ACTION_FAILURE,
+	humanizeSpamFailureReason,
+	throwOnBulkFailure,
+} from "./useReportSpam.js";
+
+describe("throwOnBulkFailure (#648)", () => {
+	test("does not throw when the whole batch succeeded", () => {
+		assert.doesNotThrow(() =>
+			throwOnBulkFailure({ successCount: 1, failureCount: 0 }),
+		);
+	});
+
+	test("throws the server's own reason for a designed failure", () => {
+		// Both bulk endpoints answer 200 even when every message failed —
+		// settleSpamReportBulk never rejects the HTTP call — so a caller that
+		// only checks for a thrown/rejected request would read this as success.
+		assert.throws(
+			() =>
+				throwOnBulkFailure({
+					successCount: 0,
+					failureCount: 1,
+					failures: [
+						{
+							messageId: "m1",
+							reason:
+								"Message m1's move to Junk has not settled yet; try again in a moment.",
+						},
+					],
+				}),
+			/has not settled yet/,
+		);
+	});
+
+	test("falls back to a generic message when a failure carries no reason", () => {
+		assert.throws(
+			() =>
+				throwOnBulkFailure({
+					successCount: 0,
+					failureCount: 1,
+					failures: [],
+				}),
+			new RegExp(GENERIC_SPAM_ACTION_FAILURE.replace(/[.]/g, "\\.")),
+		);
+	});
+
+	test("throws on a partial batch, not just a total failure", () => {
+		// This hook is always called with exactly one message today, but the
+		// check itself must not treat "some succeeded" as "nothing to report".
+		assert.throws(
+			() =>
+				throwOnBulkFailure({
+					successCount: 2,
+					failureCount: 1,
+					failures: [{ messageId: "m3", reason: "boom" }],
+				}),
+			/boom/,
+		);
+	});
+
+	test("strips the real messageId shape out of the designed reason", () => {
+		// Message ids are 25-char base36 (`translator.generate()` in
+		// packages/data-ports/src/id.ts), never a dashed UUID — a fixture
+		// shaped like one proves nothing about what the user actually sees.
+		const realId = "9m2k7x4vqz1jd0tn3wf8b6y5c";
+		assert.throws(
+			() =>
+				throwOnBulkFailure({
+					successCount: 0,
+					failureCount: 1,
+					failures: [
+						{
+							messageId: realId,
+							reason: `Message ${realId}'s move to Junk has not settled yet; try again in a moment.`,
+						},
+					],
+				}),
+			(error: unknown) => {
+				assert.ok(error instanceof Error);
+				assert.equal(
+					error.message,
+					"This message's move to Junk has not settled yet; try again in a moment.",
+				);
+				assert.ok(!error.message.includes(realId), "the raw id must not leak");
+				return true;
+			},
+		);
+	});
+});
+
+describe("humanizeSpamFailureReason (#648)", () => {
+	test("replaces the real-shaped messageId possessive with plain language", () => {
+		// Base36, not a dashed UUID — see the note above.
+		const realId = "9m2k7x4vqz1jd0tn3wf8b6y5c";
+		assert.equal(
+			humanizeSpamFailureReason(
+				`Message ${realId}'s move to Junk has not settled yet; try again in a moment.`,
+				realId,
+			),
+			"This message's move to Junk has not settled yet; try again in a moment.",
+		);
+	});
+
+	test("leaves a reason with no embedded messageId unchanged", () => {
+		assert.equal(
+			humanizeSpamFailureReason(
+				GENERIC_SPAM_ACTION_FAILURE,
+				"9m2k7x4vqz1jd0tn3wf8b6y5c",
+			),
+			GENERIC_SPAM_ACTION_FAILURE,
+		);
+	});
+});