@remit/web-client 0.0.13 → 0.0.15

package/src/lib/network-error.ts

@@ -0,0 +1,58 @@
+/**
+ * Transport failures are identified where they happen, not guessed at later.
+ *
+ * `fetch()` rejects for exactly two reasons: the request never completed at the
+ * transport level (DNS, TLS, connection lost, captive portal, timeout), or it
+ * was aborted. It never rejects for an HTTP status. So the one place that knows
+ * for certain that an error is a network error is the call site that wrapped
+ * `fetch` — everywhere downstream is guessing.
+ *
+ * Guessing is what the classifier used to do, first by treating every error
+ * without an HTTP status as a network blip (which swallowed our own exceptions),
+ * then by matching browser failure strings (which is unbounded: WebKit alone
+ * says "Failed to fetch", "Load failed", "The network connection was lost." and
+ * "The request timed out.", and undici says "fetch failed"). Tagging at the
+ * boundary makes the question decidable and the browser's wording irrelevant.
+ */
+
+/** A request that never reached a server. Always soft — never escalated. */
+export class NetworkError extends Error {
+	constructor(cause: unknown) {
+		super(
+			cause instanceof Error && cause.message
+				? cause.message
+				: "The request could not be completed.",
+			{ cause },
+		);
+		this.name = "NetworkError";
+	}
+}
+
+/**
+ * A deliberate cancellation — a route change, a React Query cancellation, a
+ * caller's own `AbortController`. Its own category: not a failure at all, so it
+ * passes through untagged.
+ *
+ * `AbortSignal.timeout()` rejects with a `TimeoutError` rather than an
+ * `AbortError`, and a timeout IS a transport failure, so it is deliberately not
+ * matched here and gets tagged like any other.
+ */
+const isDeliberateAbort = (error: unknown): boolean =>
+	typeof error === "object" &&
+	error !== null &&
+	"name" in error &&
+	(error as { name?: unknown }).name === "AbortError";
+
+/**
+ * `fetch`, with transport failures tagged. Every app-owned request goes through
+ * this — the generated client is configured with it, and the hand-written
+ * wrapper calls it — so a `NetworkError` downstream is a fact, not an inference.
+ */
+export const taggedFetch: typeof fetch = async (input, init) => {
+	try {
+		return await fetch(input, init);
+	} catch (error) {
+		if (isDeliberateAbort(error)) throw error;
+		throw new NetworkError(error);
+	}
+};

package/src/lib/query-error-handler.test.ts

@@ -3,6 +3,7 @@ import { afterEach, describe, it } from "node:test";
 import type { Mutation, Query } from "@tanstack/react-query";
 import { ApiError } from "./api";
 import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import { NetworkError } from "./network-error";
 import {
 	handleMutationCacheError,
 	handleQueryCacheError,
@@ -95,12 +96,15 @@ describe("handleQueryCacheError (fail-fast contract #1059)", () => {
 		assert.equal(escalated, false);
 	});
 
-	it("does NOT escalate a statusless network blip", () => {
+	it("does NOT escalate a network blip tagged at the fetch boundary", () => {
 		let escalated = false;
 		subscribeFatalError(() => {
 			escalated = true;
 		});
-		handleQueryCacheError(new TypeError("Failed to fetch"), fakeQuery());
+		handleQueryCacheError(
+			new NetworkError(new TypeError("Failed to fetch")),
+			fakeQuery(),
+		);
 		assert.equal(escalated, false);
 	});
 });

package/src/lib/query-escalation.integration.test.ts

@@ -11,6 +11,7 @@ import { afterEach, describe, it } from "node:test";
 import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";
 import { ApiError } from "./api";
 import { __resetFatalError, subscribeFatalError } from "./fatal-error";
+import { NetworkError } from "./network-error";
 import {
 	handleMutationCacheError,
 	handleQueryCacheError,
@@ -117,7 +118,7 @@ describe("global query/mutation escalation", () => {
 		assert.deepEqual(seen, ["not found"]);
 	});
 
-	it("a statusless `Failed to fetch` (offline blip) from a query does NOT escalate", async () => {
+	it("an offline blip tagged at the fetch boundary does NOT escalate", async () => {
 		let escalated = false;
 		subscribeFatalError(() => {
 			escalated = true;
@@ -128,7 +129,7 @@ describe("global query/mutation escalation", () => {
 			.fetchQuery({
 				queryKey: ["offline"],
 				queryFn: async () => {
-					throw new TypeError("Failed to fetch");
+					throw new NetworkError(new TypeError("Failed to fetch"));
 				},
 			})
 			.catch(() => {});

package/src/lib/sender-address.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitImapAddressResponse } from "@remit/api-http-client/types.gen.ts";
+import {
+	pickSenderAddress,
+	SENDER_ADDRESS_SEARCH_LIMIT,
+	senderAddressSearchQuery,
+} from "./sender-address";
+
+const address = (
+	addressId: string,
+	normalizedEmail: string,
+): RemitImapAddressResponse =>
+	({ addressId, normalizedEmail }) as RemitImapAddressResponse;
+
+describe("senderAddressSearchQuery", () => {
+	it("lowercases the address and asks for a window, not one row", () => {
+		assert.deepEqual(senderAddressSearchQuery("Support@NPMJS.com"), {
+			q: "support@npmjs.com",
+			limit: SENDER_ADDRESS_SEARCH_LIMIT,
+		});
+		assert.ok(SENDER_ADDRESS_SEARCH_LIMIT > 1);
+	});
+
+	it("is stable for a missing sender, so the cache key stays valid", () => {
+		assert.deepEqual(senderAddressSearchQuery(undefined), {
+			q: "",
+			limit: SENDER_ADDRESS_SEARCH_LIMIT,
+		});
+	});
+});
+
+describe("pickSenderAddress", () => {
+	it("picks the exact address, not the first prefix match", () => {
+		const items = [
+			address("other", "sup@npmjs.com"),
+			address("wanted", "support@npmjs.com"),
+		];
+		assert.equal(
+			pickSenderAddress(items, "support@npmjs.com")?.addressId,
+			"wanted",
+		);
+	});
+
+	it("matches case-insensitively", () => {
+		const items = [address("wanted", "support@npmjs.com")];
+		assert.equal(
+			pickSenderAddress(items, "Support@NPMJS.com")?.addressId,
+			"wanted",
+		);
+	});
+
+	it("resolves to undefined rather than the wrong sender", () => {
+		const items = [address("other", "sup@npmjs.com")];
+		assert.equal(pickSenderAddress(items, "support@npmjs.com"), undefined);
+		assert.equal(pickSenderAddress([], "support@npmjs.com"), undefined);
+		assert.equal(pickSenderAddress(undefined, "support@npmjs.com"), undefined);
+		assert.equal(pickSenderAddress(items, undefined), undefined);
+	});
+});

package/src/lib/sender-address.ts

@@ -0,0 +1,37 @@
+import type { RemitImapAddressResponse } from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * `GET /addresses/search` is a prefix search over both the display-name
+ * compound and the normalized email, so a query for one sender's address can
+ * legitimately return several rows (`sup@x.com` also prefixes `support@x.com`,
+ * and any display name starting with the same characters matches too).
+ *
+ * Asking for a single row and taking `items[0]` is therefore wrong twice over:
+ * the row it returns may belong to a different sender, and the row we actually
+ * want may be past the cut. Fetch a small window instead and pick the exact
+ * address out of it.
+ */
+export const SENDER_ADDRESS_SEARCH_LIMIT = 10;
+
+/** Query params for the sender-address lookup. One shape, used by every caller. */
+export const senderAddressSearchQuery = (
+	senderEmail: string | undefined,
+): { q: string; limit: number } => ({
+	q: senderEmail?.toLowerCase() ?? "",
+	limit: SENDER_ADDRESS_SEARCH_LIMIT,
+});
+
+/**
+ * Select the address row for exactly this sender. A prefix match on another
+ * sender is not this sender, so it resolves to `undefined` rather than the
+ * wrong address — silently flagging the wrong sender is worse than not
+ * resolving.
+ */
+export const pickSenderAddress = (
+	items: RemitImapAddressResponse[] | undefined,
+	senderEmail: string | undefined,
+): RemitImapAddressResponse | undefined => {
+	if (!senderEmail) return undefined;
+	const normalized = senderEmail.toLowerCase();
+	return items?.find((item) => item.normalizedEmail === normalized);
+};

package/src/lib/thread-cache.test.ts

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import {
+	isInfiniteThreadData,
+	patchThreadListCache,
+	type ThreadListCache,
+} from "./thread-cache";
+
+const message = (messageId: string): RemitImapThreadMessageResponse =>
+	({ messageId }) as RemitImapThreadMessageResponse;
+
+const drop = (id: string) => (items: RemitImapThreadMessageResponse[]) =>
+	items.filter((item) => item.messageId !== id);
+
+describe("isInfiniteThreadData", () => {
+	it("recognises only the paged shape", () => {
+		assert.equal(isInfiniteThreadData({ pages: [], pageParams: [] }), true);
+		assert.equal(isInfiniteThreadData({ items: [] }), false);
+		assert.equal(isInfiniteThreadData(undefined), false);
+		assert.equal(isInfiniteThreadData(null), false);
+	});
+});
+
+describe("patchThreadListCache", () => {
+	it("patches every page of an infinite query", () => {
+		const cache: ThreadListCache = {
+			pages: [
+				{ items: [message("a"), message("b")] },
+				{ items: [message("c")] },
+			],
+			pageParams: [undefined, "next"],
+		};
+
+		const patched = patchThreadListCache(cache, drop("b"));
+
+		assert.deepEqual(patched, {
+			pages: [{ items: [message("a")] }, { items: [message("c")] }],
+			pageParams: [undefined, "next"],
+		});
+	});
+
+	it("patches a single-shot page, which shares the query-key prefix", () => {
+		// The rescue-candidate search caches this shape under the same prefix the
+		// mailbox list uses. An updater that assumed `pages` threw here, failing
+		// the whole mutation before it ever reached the server (issues #51, #55).
+		const cache: ThreadListCache = {
+			items: [message("a"), message("b")],
+			continuationToken: "t",
+		};
+
+		const patched = patchThreadListCache(cache, drop("a"));
+
+		assert.deepEqual(patched, {
+			items: [message("b")],
+			continuationToken: "t",
+		});
+	});
+
+	it("leaves an unrecognised entry alone instead of throwing", () => {
+		const cache = { total: 3 } as unknown as ThreadListCache;
+		assert.equal(patchThreadListCache(cache, drop("a")), cache);
+		assert.equal(patchThreadListCache(undefined, drop("a")), undefined);
+	});
+});

package/src/lib/thread-cache.ts

@@ -0,0 +1,76 @@
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+
+/**
+ * Optimistic patching of the thread caches.
+ *
+ * `queryClient.setQueriesData({ queryKey: prefix }, …)` matches by key *prefix*,
+ * so an updater written for the mailbox list also runs against every other
+ * cached query sharing that prefix. Those do not all have the same shape: the
+ * mailbox list is an infinite query (`{ pages: [{ items }] }`) while
+ * single-shot readers of the same endpoint — the rescue-candidate search, for
+ * one — cache a plain page (`{ items }`). An updater that assumed the infinite
+ * shape threw `pages is undefined` inside `onMutate`, which React Query reports
+ * as a failed mutation: the move never fired and the user got an error toast
+ * for an action that was never attempted (issues #51, #55).
+ *
+ * `patchThreadListCache` handles both shapes and leaves anything else it does
+ * not recognise untouched.
+ */
+
+export interface ThreadItemsPage {
+	items: RemitImapThreadMessageResponse[];
+	[key: string]: unknown;
+}
+
+export interface InfiniteThreadData {
+	pages: ThreadItemsPage[];
+	pageParams: Array<string | undefined>;
+}
+
+/** Either cached shape served by the thread list/search endpoints. */
+export type ThreadListCache = InfiniteThreadData | ThreadItemsPage;
+
+export const isInfiniteThreadData = (
+	data: unknown,
+): data is InfiniteThreadData =>
+	typeof data === "object" &&
+	data !== null &&
+	Array.isArray((data as { pages?: unknown }).pages);
+
+const isThreadItemsPage = (data: unknown): data is ThreadItemsPage =>
+	typeof data === "object" &&
+	data !== null &&
+	Array.isArray((data as { items?: unknown }).items);
+
+/**
+ * Apply `patchItems` to every list of thread messages inside a cache entry,
+ * whichever shape it holds.
+ *
+ * `old` is `unknown` because that is the truth: a prefix match hands this
+ * whatever happens to be cached under that prefix, and the two shapes below are
+ * the ones we know about today, not the ones we are guaranteed. Declaring a
+ * narrower parameter type is what produced the original bug — the type asserted
+ * a shape the runtime never promised, and the first entry that disagreed threw.
+ * Anything unrecognised is returned untouched.
+ */
+export const patchThreadListCache = (
+	old: unknown,
+	patchItems: (
+		items: RemitImapThreadMessageResponse[],
+	) => RemitImapThreadMessageResponse[],
+): unknown => {
+	if (old === undefined) return old;
+	if (isInfiniteThreadData(old)) {
+		return {
+			...old,
+			pages: old.pages.map((page) => ({
+				...page,
+				items: patchItems(page.items),
+			})),
+		};
+	}
+	if (isThreadItemsPage(old)) {
+		return { ...old, items: patchItems(old.items) };
+	}
+	return old;
+};