@remit/web-client 0.0.325 → 0.0.327

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

@@ -1,135 +0,0 @@
-/**
- * Closes the seam the existing #648-review tests each cover half of.
- * `useReportSpam.integration.test.ts` builds a synthetic mutation via
- * `mutationCache.build()` and never mounts the hook; `useReportSpam.render.
- * test.ts` mounts the hook but under `createDomHarness`'s default
- * `QueryClient`, which carries no global cache handlers. Neither exercises the
- * JOIN: the real `useMutation` calls in `useReportSpam.ts`, under a
- * `QueryClient` wired with the real `QueryCache`/`MutationCache` handlers from
- * `lib/query-error-handler.ts` the way `shell/index.tsx` builds it, wrapped in
- * the real `ErrorBannerProvider`. Deleting `meta: { softError: true }` from
- * the real hook passes both existing tests — that is the bug that shipped
- * twice and passed CI both times.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
-import { createElement, Fragment } from "react";
-import { FatalErrorOverlay } from "../components/ui/FatalErrorOverlay";
-import { __resetFatalError, subscribeFatalError } from "../lib/fatal-error";
-import {
-	handleMutationCacheError,
-	handleQueryCacheError,
-} from "../lib/query-error-handler";
-import { createDomHarness, type DomHarness } from "../test-support/dom";
-import { type HttpMock, httpError, 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;
-	};
-	const queryClient = new QueryClient({
-		queryCache: new QueryCache({ onError: handleQueryCacheError }),
-		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
-		defaultOptions: { mutations: { retry: false } },
-	});
-	harness = createDomHarness({ queryClient });
-	harness.renderApp(
-		createElement(
-			Fragment,
-			null,
-			createElement(FatalErrorOverlay),
-			createElement(Probe),
-		),
-	);
-	return () => {
-		if (value === undefined) throw new Error("hook did not render");
-		return value;
-	};
-};
-
-/** See `useReportSpam.render.test.ts` — the chain from a resolved fetch to a re-render crosses enough async boundaries that a fixed microtask count reads as flaky under load. */
-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);
-	}
-};
-
-const bannerAlerts = () =>
-	harness?.queryAll('[aria-label="Notifications"] [role="alert"]') ?? [];
-
-const fatalOverlay = () =>
-	harness?.query('[data-testid="fatal-error-overlay"]') ?? null;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-	http.restore();
-	__resetFatalError();
-});
-
-describe("useReportSpam under the real global cache handlers (#648 review, the join both existing tests missed)", () => {
-	it("a per-message report failure banners once and never mounts the fatal overlay — report direction", async () => {
-		const fatalsSeen: string[] = [];
-		subscribeFatalError((fatal) => fatalsSeen.push(fatal.message));
-		http = mockFetch(() => ({ failureCount: 1 }));
-		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
-
-		hook().reportSpam(["msg-1"]);
-		await waitFor(() => bannerAlerts().length > 0);
-
-		assert.equal(
-			fatalOverlay() !== null,
-			false,
-			"the fatal overlay must not mount",
-		);
-		assert.deepEqual(fatalsSeen, [], "no fatal error must be raised");
-		assert.equal(bannerAlerts().length, 1, "exactly one banner");
-	});
-
-	it("a per-message undo failure banners once and never mounts the fatal overlay — undo direction", async () => {
-		const fatalsSeen: string[] = [];
-		subscribeFatalError((fatal) => fatalsSeen.push(fatal.message));
-		http = mockFetch(() => ({ failureCount: 1 }));
-		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-junk" }));
-
-		hook().notSpam(["msg-1"]);
-		await waitFor(() => bannerAlerts().length > 0);
-
-		assert.equal(
-			fatalOverlay() !== null,
-			false,
-			"the fatal overlay must not mount",
-		);
-		assert.deepEqual(fatalsSeen, [], "no fatal error must be raised");
-		assert.equal(bannerAlerts().length, 1, "exactly one banner");
-	});
-
-	it("a genuine 500 from the same endpoint still escalates — meta.softError must not swallow the 5xx class", async () => {
-		http = mockFetch(() => httpError(500, "spam service is down"));
-		const hook = mountHook(() => useReportSpam({ mailboxId: "mbx-inbox" }));
-
-		hook().reportSpam(["msg-1"]);
-		await waitFor(() => fatalOverlay() !== null);
-
-		assert.ok(fatalOverlay(), "a 5xx must still reach the fatal overlay");
-	});
-});

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

@@ -1,113 +0,0 @@
-/**
- * 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

@@ -1,115 +0,0 @@
-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,
-		);
-	});
-});

package/src/hooks/useReportSpam.ts

@@ -1,244 +0,0 @@
-import {
-	mailboxOperationsListMailboxesQueryKey,
-	threadDetailOperationsListThreadMessagesQueryKey,
-} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import {
-	messageBulkOperationsNotSpam,
-	messageBulkOperationsReportSpam,
-} from "@remit/api-http-client/sdk.gen.ts";
-import type { RemitImapSpamReportBulkResult } from "@remit/api-http-client/types.gen.ts";
-import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
-import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
-import { formatErrorDetail } from "@/components/ui/error-banners";
-import { ApiError } from "@/lib/api";
-import { runChunkedMutation } from "@/lib/bulk-actions";
-import {
-	invalidateThreadListQueries,
-	threadListCacheKeys,
-} from "@/lib/thread-list-cache";
-
-interface UseReportSpamOptions {
-	/** The mailbox the message currently sits in — scopes which list caches settle-time invalidation reaches. */
-	mailboxId: string;
-	threadId?: string;
-	accountId?: string;
-	/**
-	 * Called once a report or undo succeeds, with the message ids it acted on
-	 * — the same shape as `useMoveMessages`/`useDeleteMessages`'s option of the
-	 * same name, so a host wires the identical `handleDeselectIfRemoved` it
-	 * already has. Fires on SUCCESS here, not optimistically like those two:
-	 * neither endpoint tells the client whether the message actually left
-	 * `mailboxId` (reporting or undoing a message already in Junk is a real
-	 * no-op-move, and the client has no way to predict it — see
-	 * `throwOnBulkFailure`'s neighbour below), so this fires for every success,
-	 * no-op included — a no-op report/undo still deselects even though the row
-	 * never actually left the list the host is watching. That trades an
-	 * occasional unnecessary pane-close for never leaving a reported message
-	 * rendering a pre-report snapshot forever, which is the bug this exists to
-	 * fix (issue #648 review).
-	 */
-	onAfterOptimisticRemove?: (messageIds: string[]) => void;
-}
-
-/**
- * The one designed, allowlisted reason returned by the server as-is (e.g.
- * `notSpam`'s move-not-settled-yet message) is safe to show verbatim; an
- * unexpected failure is already flattened server-side to this same generic
- * text (`GENERIC_FAILURE_REASON` in `packages/backend/src/handlers/message.ts`)
- * before it reaches the client. Used only as a fallback for the case neither
- * hits: a `failures` entry missing its `reason`, or no `failures` array at all
- * despite a non-zero `failureCount`.
- */
-export const GENERIC_SPAM_ACTION_FAILURE =
-	"This message could not be processed. Please try again. If it keeps failing, report it.";
-
-/**
- * The server's designed failure text names the message by putting its raw
- * id as a possessive subject — e.g. "Message 4kv0xxyfhg4dhzqvxd105v840's move
- * to Junk has not settled yet; try again in a moment." (message ids here are
- * 25-char base36, `translator.generate()` in `packages/data-ports/src/id.ts`
- * — not a dashed UUID). Accurate, but not something to put in front of a
- * person. `messageId` is the exact id the failure names — `SpamReportFailure`
- * pairs it with `reason` for precisely this — so this strips that literal
- * substring rather than pattern-matching an id shape that could change under
- * it. Not a parse of the reason's meaning (the field is documented "not
- * intended to be parsed programmatically"): removing a known, opaque
- * identifier from where it renders reads nothing into what the sentence says.
- */
-export const humanizeSpamFailureReason = (
-	reason: string,
-	messageId: string,
-): string => reason.replace(`Message ${messageId}'s`, "This message's");
-
-/**
- * `settleSpamReportBulk` (backend) runs the batch with `Promise.allSettled`
- * and always answers 200, folding per-message outcomes into
- * `successCount`/`failureCount`/`failures` rather than rejecting the HTTP
- * call — a partial (or total) failure is not a thrown error on the wire. The
- * generated mutation helpers only ever reject on a non-2xx response, so
- * without this the hook would report success for a message whose report or
- * undo never actually happened. Every caller here sends exactly one message
- * per call, so surfacing the first failure's reason is surfacing the whole
- * story, not truncating a real batch.
- *
- * Throws `ApiError` — not a bare `Error` — carrying a 4xx status. The
- * client's fail-fast contract (`lib/error-classifier.ts`'s `shouldEscalate`,
- * wired globally on the `MutationCache` in `lib/query-error-handler.ts`)
- * escalates anything that isn't a 5xx by default UNLESS the call site opts
- * out via `meta.softError` — a statusless `Error` escalates too, as a client
- * bug. Either way, without both the status AND `meta.softError` (set on the
- * `useMutation` calls below) this would crash to the full-screen fatal
- * overlay for a designed, expected, retryable outcome the backend wrote
- * user-facing copy for. Every other call site in this app forwards a
- * status-carrying error the generated client already threw and never needs
- * the opt-out because none of them are a routine, expected-failure signal
- * like this one; this is the one place synthesizing a failure from a 200
- * body, so it has to synthesize both.
- */
-export const throwOnBulkFailure = (
-	data: RemitImapSpamReportBulkResult,
-): void => {
-	if (data.failureCount === 0) return;
-	const failure = data.failures?.[0];
-	const reason = failure?.reason ?? GENERIC_SPAM_ACTION_FAILURE;
-	const message = failure
-		? humanizeSpamFailureReason(reason, failure.messageId)
-		: reason;
-	throw new ApiError(message, 422);
-};
-
-/**
- * Composes `POST /messages/report-spam` and `POST /messages/not-spam`
- * (issue #648). Both fold the sender-flag write, the Junk move and the
- * `$Junk` keyword marker into one server-side operation
- * (`SpamReportService`) — the client only sends `messageIds` and reflects the
- * result, it does not sequence the three writes itself, and it never derives
- * "reported" from placement (a report on a message already in Junk — the
- * provider's own filter put it there — is a real, no-op-move case).
- *
- * No optimistic cache patch, unlike `useMoveMessages`/`useDeleteMessages`:
- * neither endpoint's response says whether the message actually changed
- * mailboxes (a report or undo against a message already in Junk is a real,
- * silent no-op), so predicting the row should vanish would flicker it back
- * on invalidation for a no-op — worst on `notSpam`, whose R2 wait can run
- * several seconds before the row "pops back". The list settles from
- * `onSuccess`'s invalidation instead, which is always correct. `isReporting`/
- * `isRestoring` below exist to pay for the UX this trades away: without them
- * a press produces no visible change at all until the request lands — the
- * caller wires them into the quick action's pending state.
- */
-export function useReportSpam({
-	mailboxId,
-	threadId,
-	accountId,
-	onAfterOptimisticRemove,
-}: UseReportSpamOptions) {
-	const queryClient = useQueryClient();
-	const { pushError } = useErrorBanners();
-
-	const listPrefixes = threadListCacheKeys([mailboxId]);
-	const threadMessagesPrefix = threadId
-		? threadDetailOperationsListThreadMessagesQueryKey({ path: { threadId } })
-		: [];
-
-	const invalidateAffectedQueries = () => {
-		if (threadId) {
-			queryClient.invalidateQueries({ queryKey: threadMessagesPrefix });
-		}
-		invalidateThreadListQueries(queryClient, listPrefixes);
-		if (accountId) {
-			queryClient.invalidateQueries({
-				queryKey: mailboxOperationsListMailboxesQueryKey({
-					path: { accountId },
-				}),
-			});
-		}
-	};
-
-	const buildOnSuccess =
-		() => (_data: unknown, variables: { body: { messageIds: string[] } }) => {
-			invalidateAffectedQueries();
-			onAfterOptimisticRemove?.(variables.body.messageIds);
-		};
-
-	const buildOnError =
-		(failureTitle: (count: number) => string) =>
-		(err: unknown, vars: { body: { messageIds: string[] } }) => {
-			pushError({
-				title: failureTitle(vars.body.messageIds.length),
-				detail: formatErrorDetail(err),
-				error: err,
-			});
-		};
-
-	const report = useMutation({
-		mutationFn: async (variables: { body: { messageIds: string[] } }) => {
-			const { data } = await messageBulkOperationsReportSpam({
-				...variables,
-				throwOnError: true,
-			});
-			throwOnBulkFailure(data);
-			return data;
-		},
-		// A per-message report failure is a routine, expected, retryable outcome
-		// with backend-written user-facing copy — never the fatal overlay. See
-		// `throwOnBulkFailure`'s doc for why the thrown ApiError's status alone
-		// isn't enough: `shouldEscalate` defaults to escalate for a non-5xx that
-		// doesn't opt out here.
-		meta: { softError: true },
-		onSuccess: buildOnSuccess(),
-		onError: buildOnError((count) =>
-			count > 1
-				? `Couldn't report ${count} messages as spam`
-				: "Couldn't report this message as spam",
-		),
-	});
-
-	const restore = useMutation({
-		mutationFn: async (variables: { body: { messageIds: string[] } }) => {
-			const { data } = await messageBulkOperationsNotSpam({
-				...variables,
-				throwOnError: true,
-			});
-			throwOnBulkFailure(data);
-			return data;
-		},
-		meta: { softError: true },
-		onSuccess: buildOnSuccess(),
-		onError: buildOnError((count) =>
-			count > 1
-				? `Couldn't undo the spam report for ${count} messages`
-				: "Couldn't undo the spam report",
-		),
-	});
-
-	const reportSpam = useCallback(
-		(messageIds: string[]) => {
-			if (messageIds.length === 0) return;
-			void runChunkedMutation(messageIds, (chunk) =>
-				report.mutateAsync({ body: { messageIds: chunk } }),
-			);
-		},
-		[report.mutateAsync],
-	);
-
-	const notSpam = useCallback(
-		(messageIds: string[]) => {
-			if (messageIds.length === 0) return;
-			void runChunkedMutation(messageIds, (chunk) =>
-				restore.mutateAsync({ body: { messageIds: chunk } }),
-			);
-		},
-		[restore.mutateAsync],
-	);
-
-	return {
-		reportSpam,
-		notSpam,
-		/** True while a report is in flight — wire into the "Report spam" quick action's pending state; a press with no visible response is the dead-button failure mode. */
-		isReporting: report.isPending,
-		/** True while an undo is in flight — wire into the "Not spam" quick action's pending state. */
-		isRestoring: restore.isPending,
-	};
-}