@remit/web-client 0.0.128 → 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/useIntelligenceData.test.ts

@@ -246,7 +246,11 @@ describe("buildAuthenticityIntel", () => {
 	describe("a passing signature over a claim that does not hold", () => {
 		// The InfoMedics invoice phish: an attacker's own free Atlassian tenant,
 		// so SPF/DKIM/DMARC genuinely pass for a domain nobody recognises, and the
-		// provider's own filter already called it spam.
+		// provider's own filter already called it spam. dkimDomain deliberately
+		// differs from fromDomain here (the delivery host's re-signature,
+		// custmx.one.com, is a different party than the sender's own
+		// serviceupdatebank.atlassian.net) — the display-name check was run
+		// against fromDomain, never dkimDomain, so the copy must name fromDomain.
 		const infoMedics = makeThread({
 			fromEmail: "jira@serviceupdatebank.atlassian.net",
 			fromName: "InfoMedics",
@@ -266,11 +270,17 @@ describe("buildAuthenticityIntel", () => {
 			assert.doesNotMatch(result.summary, /We verified/i);
 		});
 
-		test("names the display name and the link destination", () => {
+		// The copy must name the domain the comparison was actually run
+		// against (fromDomain), never the unrelated dkimDomain — a message
+		// signed by a relay or ESP infrastructure domain must not read as
+		// "the name looks nothing like <that other party>".
+		test("leads with the concern, naming the domain the name was actually compared to, and the link destination", () => {
 			const result = buildAuthenticityIntel(infoMedics, 0);
 			assert.equal(result.verdict, "caution");
-			assert.match(result.summary, /really was sent by/);
+			assert.match(result.summary, /^The name it shows/);
 			assert.match(result.summary, /"InfoMedics"/);
+			assert.match(result.summary, /serviceupdatebank\.atlassian\.net/);
+			assert.doesNotMatch(result.summary, /custmx\.one\.com/);
 			assert.match(result.summary, /betaal-vordering\.example/);
 			assert.doesNotMatch(result.summary, /DKIM|SPF|DMARC/i);
 		});

package/src/hooks/useIntelligenceData.ts

@@ -117,6 +117,16 @@ function joinDomains(domains: readonly string[]): string {
  * out. Empty when everything the backend compared agreed — including when it
  * compared nothing, which is every message the provider's filter did not
  * already call spam.
+ *
+ * Each clause leads with the concern and names `auth.fromDomain` — the
+ * domain `classifyDisplayNameCorrespondence` actually compared the display
+ * name against (`senderMismatch.ts` calls it with the From address's own
+ * domain, never the DKIM signing domain). Naming `auth.dkimDomain` instead
+ * would assert a comparison that was never made: on a message signed by a
+ * relay or ESP infrastructure domain, the display name was checked against
+ * the sender's own address, not that domain. These clauses are the caution
+ * tier's entire summary: there is no separate "verified" sentence in front
+ * of them for the signing fact to hide behind.
  */
 function describeSenderMismatch(
 	auth: NonNullable<RemitImapThreadMessageResponse["authenticity"]>,
@@ -128,11 +138,11 @@ function describeSenderMismatch(
 	if (claimedBrand) {
 		if (correspondence === DisplayNameCorrespondence.Unrelated) {
 			clauses.push(
-				`The name it shows, "${claimedBrand}", has nothing to do with that domain.`,
+				`The name it shows, "${claimedBrand}", has nothing to do with ${auth.fromDomain}.`,
 			);
 		} else if (correspondence === DisplayNameCorrespondence.Lookalike) {
 			clauses.push(
-				`The name it shows, "${claimedBrand}", only looks like that domain.`,
+				`The name it shows, "${claimedBrand}", only looks like ${auth.fromDomain}.`,
 			);
 		}
 	}
@@ -198,10 +208,7 @@ export function buildAuthenticityIntel(
 				fromDomain: auth.fromDomain,
 				dkimDomain: auth.dkimDomain,
 				claimedBrand: claimed,
-				summary: [
-					`This message really was sent by ${auth.fromDomain}.`,
-					...unlike,
-				].join(" "),
+				summary: unlike.join(" "),
 			};
 		}
 		return {
@@ -209,7 +216,7 @@ export function buildAuthenticityIntel(
 			fromDomain: auth.fromDomain,
 			dkimDomain: auth.dkimDomain,
 			summary: auth.dkimDomain
-				? `We verified this message was really sent by ${auth.fromDomain}.`
+				? `This message was signed by ${auth.dkimDomain}.`
 				: `Nothing looks unusual about this sender.`,
 		};
 	}
@@ -217,9 +224,17 @@ export function buildAuthenticityIntel(
 	const fromDomain = auth.fromDomain;
 	const dkimDomain = auth.dkimDomain;
 	const claimedBrand = claimedBrandOf(thread);
+	// dkimDomain is known whenever a mismatch was named against a real
+	// domain; the fallback covers the (defensive, not currently reachable)
+	// case where a mismatch fires with none — say what actually happened
+	// (a signature failed to verify) rather than inventing a sender identity
+	// we do not have.
+	const whatHappened = dkimDomain
+		? `it was actually sent from ${dkimDomain}`
+		: "its signature failed to verify";
 	const summary = claimedBrand
-		? `The display name claims "${claimedBrand}", but this message was actually sent from ${dkimDomain ?? "another sender"} — not ${fromDomain}. Real senders use their own address.`
-		: `This message claims to be from ${fromDomain}, but it was actually sent from ${dkimDomain ?? "a different sender"}.`;
+		? `The display name claims "${claimedBrand}", but ${whatHappened}${dkimDomain ? ` — not ${fromDomain}` : ""}. Real senders use their own address.`
+		: `This message claims to be from ${fromDomain}, but ${whatHappened}.`;
 	return {
 		verdict: "mismatch",
 		fromDomain,

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