@remit/web-client 0.0.132 → 0.0.133

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.132",
+  "version": "0.0.133",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/IntelligencePane.render.test.ts

@@ -0,0 +1,134 @@
+/**
+ * The spam quick action stayed clickable throughout its own request (issue
+ * #648 review): the server dedupes message ids only within a single call, so
+ * two clicks fired two separate HTTP requests. For the undo direction this
+ * produced a wrong message — concurrent `notSpam` #2 reads
+ * `originalMailboxId` before #1 clears it, waits on #1's restore move, and
+ * can throw `MoveNotSettledError` on an undo that already succeeded. Wires
+ * the real `useReportSpam` hook to the real `IntelligencePanel` (the shape
+ * `IntelligencePane.tsx`'s `WiredPanel` uses) and clicks the real button
+ * twice to prove the fix: disabled while pending blocks the second request
+ * at the DOM level, not just in the hook.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import type { IntelligenceData } from "@remit/ui";
+import { IntelligencePanel } from "@remit/ui";
+import { createElement } from "react";
+import { useReportSpam } from "@/hooks/useReportSpam";
+import { createDomHarness, type DomHarness } from "@/test-support/dom";
+import { type HttpMock, mockFetch } from "@/test-support/http";
+
+const baseData: IntelligenceData = {
+	sender: {
+		name: "Alex Rivera",
+		email: "alex@example.com",
+		trust: "wellknown",
+		firstSeenLabel: "Jan 2025",
+	},
+	authenticity: {
+		verdict: "aligned",
+		fromDomain: "example.com",
+		dkimDomain: "example.com",
+		summary: "This message was signed by example.com.",
+	},
+	category: { value: "Personal" },
+	similar: [],
+};
+
+const ReportHarness = () => {
+	const { reportSpam, isReporting } = useReportSpam({ mailboxId: "mbx-inbox" });
+	return createElement(IntelligencePanel, {
+		data: baseData,
+		actions: { onReportSpam: () => reportSpam(["msg-1"]) },
+		reportSpamPending: isReporting,
+	});
+};
+
+const UndoHarness = () => {
+	const { notSpam, isRestoring } = useReportSpam({ mailboxId: "mbx-junk" });
+	return createElement(IntelligencePanel, {
+		data: baseData,
+		actions: { onNotSpam: () => notSpam(["msg-1"]) },
+		notSpamPending: isRestoring,
+	});
+};
+
+let harness: DomHarness | undefined;
+let http: HttpMock;
+
+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);
+	}
+};
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http.restore();
+});
+
+describe("the spam quick action disables itself for the duration of its own request (#648 review)", () => {
+	it("report direction: a second click while the report is in flight sends only one request", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		harness = createDomHarness();
+		harness.renderApp(createElement(ReportHarness));
+
+		const button = harness.byText("button", "Report spam") as HTMLButtonElement;
+		harness.click(button);
+		await waitFor(() => button.textContent === "Reporting…");
+
+		assert.equal(button.disabled, true, "a control mid-request must disable");
+		harness.click(button);
+
+		assert.ok(resolveRequest, "the request never reached the mock");
+		resolveRequest?.();
+		await waitFor(() => button.textContent === "Report spam");
+
+		assert.equal(http.to("/messages/report-spam").length, 1);
+	});
+
+	it("undo direction: a second click while the undo is in flight sends only one request", async () => {
+		let resolveRequest: (() => void) | undefined;
+		http = mockFetch(
+			() =>
+				new Promise((resolve) => {
+					resolveRequest = () => resolve({ successCount: 1, failureCount: 0 });
+				}),
+		);
+		harness = createDomHarness();
+		harness.renderApp(createElement(UndoHarness));
+
+		const button = harness.byText("button", "Not spam") as HTMLButtonElement;
+		harness.click(button);
+		await waitFor(() => button.textContent === "Undoing…");
+
+		assert.equal(button.disabled, true, "a control mid-request must disable");
+		harness.click(button);
+
+		assert.ok(resolveRequest, "the request never reached the mock");
+		resolveRequest?.();
+		await waitFor(() => button.textContent === "Not spam");
+
+		assert.equal(http.to("/messages/not-spam").length, 1);
+	});
+});

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

@@ -0,0 +1,135 @@
+/**
+ * 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/test-support/dom.ts

@@ -46,6 +46,14 @@ export interface DomOptions {
 	/** Screen posture `matchMedia` answers against — jsdom has no device. */
 	orientation?: "portrait" | "landscape";
 	pointer?: "coarse" | "fine";
+	/**
+	 * Use this `QueryClient` instead of the harness's default retry-disabled
+	 * one — e.g. one wired with the real `QueryCache`/`MutationCache` error
+	 * handlers from `lib/query-error-handler.ts`, the way `shell/index.tsx`
+	 * builds it, so a test can exercise the real global escalation path
+	 * instead of just the per-mutation `onError`.
+	 */
+	queryClient?: QueryClient;
 }
 
 export const createDomHarness = (options: DomOptions = {}): DomHarness => {
@@ -64,12 +72,14 @@ export const createDomHarness = (options: DomOptions = {}): DomHarness => {
 	let root: Root | undefined = createRoot(container);
 	// No retries: a test asserting a failure should not have to wait out a
 	// backoff before it can see one.
-	const queryClient = new QueryClient({
-		defaultOptions: {
-			queries: { retry: false },
-			mutations: { retry: false },
-		},
-	});
+	const queryClient =
+		options.queryClient ??
+		new QueryClient({
+			defaultOptions: {
+				queries: { retry: false },
+				mutations: { retry: false },
+			},
+		});
 
 	const requireRoot = (): Root => {
 		if (!root) throw new Error("harness already unmounted");

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

@@ -1,93 +0,0 @@
-/**
- * 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",
-		);
-	});
-});