@remit/web-client 0.0.237 → 0.0.239

package/src/components/settings/calendar-feed-flow.render.test.ts

@@ -0,0 +1,449 @@
+/**
+ * Sharing a calendar by its secret address, and taking it back (#1067).
+ *
+ * What is asserted is the request that left and what the panel then shows,
+ * because the address is only legible for one render: a control that posted
+ * nothing and a control that posted and dropped the answer look identical.
+ *
+ * Held with the real caches from `lib/query-error-handler.ts` and the overlay
+ * they escalate to. Which failures this card owns and which take the whole
+ * screen is the decision under test: on the harness's quiet default client
+ * every status stays inline, so a card that had quietly lost its 403 would
+ * still pass.
+ */
+
+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 { CalendarFeedPanel } from "@/components/settings/CalendarFeedPanel";
+import { FatalErrorOverlay } from "@/components/ui/FatalErrorOverlay";
+import { __resetFatalError } from "@/lib/fatal-error";
+import {
+	handleMutationCacheError,
+	handleQueryCacheError,
+} from "@/lib/query-error-handler";
+import { createDomHarness, type DomHarness } from "../../test-support/dom";
+import {
+	type HttpCall,
+	type HttpMock,
+	httpError,
+	mockFetch,
+} from "../../test-support/http";
+
+const WORK = "11111111-1111-4111-8111-111111111111";
+const FEED_PATH = `/calendars/${WORK}/feed`;
+const TOKEN = "9Xq2mB7tK1vHs4dLpZ0rY6wJfN3aC8eQuIoT5gRbVkE";
+const NEXT_TOKEN = "Ab1Cd2Ef3Gh4Ij5Kl6Mn7Op8Qr9St0UvWxYz-_1234A";
+const CREATED = Date.parse("2026-05-04T09:12:00Z");
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+	__resetFatalError();
+});
+
+type Responder = (call: HttpCall) => unknown;
+
+const escalatingClient = (): QueryClient =>
+	new QueryClient({
+		queryCache: new QueryCache({ onError: handleQueryCacheError }),
+		mutationCache: new MutationCache({ onError: handleMutationCacheError }),
+		defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+	});
+
+const mount = async (responder: Responder) => {
+	http = mockFetch(responder);
+	harness = createDomHarness({ queryClient: escalatingClient() });
+	harness.renderApp(
+		createElement(
+			Fragment,
+			null,
+			createElement(FatalErrorOverlay),
+			createElement(CalendarFeedPanel, {
+				calendarId: WORK,
+				calendarName: "Work",
+			}),
+		),
+	);
+	await harness.flush();
+	await harness.wait(20);
+	await harness.flush();
+};
+
+/** The full-screen page took over, instead of this card answering for itself. */
+const escalated = (): boolean =>
+	harness?.query('[data-testid="fatal-error-overlay"]') != null;
+
+const settle = async () => {
+	await harness?.flush();
+	await harness?.wait(20);
+	await harness?.flush();
+};
+
+/**
+ * The card's own controls, never the confirmation's. Both spell the action the
+ * same way on purpose — the dialog repeats the verb of the button that opened
+ * it — so a lookup across the whole panel would answer the confirmation and
+ * make "asked before writing" untestable.
+ */
+const cardButtons = (): HTMLButtonElement[] =>
+	(harness?.queryAll<HTMLButtonElement>("button") ?? []).filter(
+		(node) => node.closest('[role="dialog"]') === null,
+	);
+
+const named = (
+	nodes: HTMLButtonElement[],
+	label: string,
+): HTMLButtonElement | undefined =>
+	nodes.find((node) => (node.textContent ?? "").trim() === label);
+
+const button = (label: string): HTMLButtonElement => {
+	const found = named(cardButtons(), label);
+	if (!found) throw new Error(`no button labelled "${label}"`);
+	return found;
+};
+
+const hasButton = (label: string): boolean =>
+	named(cardButtons(), label) !== undefined;
+
+const confirmButton = (label: string): HTMLButtonElement => {
+	const dialog = harness?.query('[role="dialog"]');
+	if (!dialog) throw new Error("no confirmation is open");
+	const found = named(
+		[...dialog.querySelectorAll("button")] as HTMLButtonElement[],
+		label,
+	);
+	if (!found) throw new Error(`the confirmation has no "${label}"`);
+	return found;
+};
+
+/** A calendar nobody has ever shared: the read is a 404 and owns it. */
+const unshared: Responder = (call) => {
+	if (call.method === "GET") return httpError(404, "no feed");
+	return {};
+};
+
+describe("a calendar that is not shared", () => {
+	it("offers to create an address instead of reporting a failure", async () => {
+		await mount(unshared);
+		assert.match(harness?.text() ?? "", /Create subscription address/);
+		assert.doesNotMatch(harness?.text() ?? "", /Couldn't read/);
+	});
+
+	it("mints the address with one PUT to the calendar's feed", async () => {
+		let feed: unknown;
+		await mount((call) => {
+			if (call.method === "PUT") {
+				feed = {
+					calendarId: WORK,
+					feedToken: TOKEN,
+					createdAt: CREATED,
+					rotatedAt: 0,
+				};
+				return feed;
+			}
+			if (feed) return feed;
+			return httpError(404, "no feed");
+		});
+
+		harness?.click(button("Create subscription address"));
+		await settle();
+
+		const writes = (http?.to(FEED_PATH) ?? []).filter(
+			(call) => call.method === "PUT",
+		);
+		assert.equal(writes.length, 1, "one write minted the address");
+	});
+
+	/**
+	 * The one render the plaintext exists in. Nothing stores it, so a panel that
+	 * dropped it here has handed the reader a calendar they cannot subscribe to
+	 * without rotating it again.
+	 */
+	it("shows the address once, then never again", async () => {
+		let feed: unknown;
+		await mount((call) => {
+			if (call.method === "PUT") {
+				feed = {
+					calendarId: WORK,
+					feedToken: TOKEN,
+					createdAt: CREATED,
+					rotatedAt: 0,
+				};
+				return feed;
+			}
+			if (feed) return feed;
+			return httpError(404, "no feed");
+		});
+
+		harness?.click(button("Create subscription address"));
+		await settle();
+
+		const shown = harness?.text() ?? "";
+		assert.match(shown, /shown once and cannot be read back/);
+		assert.ok(
+			harness
+				?.queryAll<HTMLInputElement>("input")
+				.some(
+					(input) =>
+						input.value === `webcal://localhost/feeds/calendar/${TOKEN}.ics`,
+				),
+			`the webcal address was not on screen: ${harness?.html()}`,
+		);
+
+		harness?.click(button("I've saved it"));
+		await settle();
+
+		assert.doesNotMatch(harness?.text() ?? "", /shown once/);
+		assert.ok(
+			!(harness?.html() ?? "").includes(TOKEN),
+			"the dismissed address is gone from the document",
+		);
+		assert.match(harness?.text() ?? "", /Address created/);
+	});
+
+	/**
+	 * Off the screen is not gone. React Query keeps a mutation's answer for its
+	 * whole gcTime, and that answer is the plaintext token — the one thing this
+	 * feature promises exists nowhere it can be read back from.
+	 */
+	it("drops the minted token from the mutation cache when it is dismissed", async () => {
+		let feed: unknown;
+		await mount((call) => {
+			if (call.method === "PUT") {
+				feed = {
+					calendarId: WORK,
+					feedToken: TOKEN,
+					createdAt: CREATED,
+					rotatedAt: 0,
+				};
+				return feed;
+			}
+			if (feed) return feed;
+			return httpError(404, "no feed");
+		});
+
+		harness?.click(button("Create subscription address"));
+		await settle();
+
+		const cached = () =>
+			(harness?.queryClient.getMutationCache().getAll() ?? []).filter(
+				(mutation) => mutation.state.data !== undefined,
+			);
+		assert.equal(cached().length, 1, "the answer is held while it is shown");
+
+		harness?.click(button("I've saved it"));
+		await settle();
+
+		assert.deepEqual(cached(), [], "no cached answer still holds the token");
+		assert.ok(
+			!JSON.stringify(
+				(harness?.queryClient.getMutationCache().getAll() ?? []).map(
+					(mutation) => mutation.state,
+				),
+			).includes(TOKEN),
+			"the token survived in the mutation cache",
+		);
+	});
+
+	it("states a refused write where the button is", async () => {
+		await mount((call) => {
+			if (call.method === "PUT") return httpError(404, "Calendar not found");
+			return httpError(404, "no feed");
+		});
+
+		harness?.click(button("Create subscription address"));
+		await settle();
+
+		assert.match(harness?.text() ?? "", /was not changed/);
+		assert.match(harness?.text() ?? "", /Calendar not found/);
+		assert.ok(!escalated(), "the card owns a refused write, inline");
+	});
+});
+
+describe("a calendar that is shared", () => {
+	const shared =
+		(rotatedAt: number): Responder =>
+		(call) => {
+			if (call.method === "GET")
+				return { calendarId: WORK, createdAt: CREATED, rotatedAt };
+			return {};
+		};
+
+	it("shows no address for the feed it merely knows exists", async () => {
+		await mount(shared(0));
+		assert.match(harness?.text() ?? "", /Address created/);
+		assert.ok(!(harness?.html() ?? "").includes("webcal://"));
+	});
+
+	it("asks before replacing the address, and says the old one stops", async () => {
+		await mount(shared(0));
+
+		harness?.click(button("Replace address"));
+		await settle();
+
+		const asked = harness?.text() ?? "";
+		assert.match(asked, /Replace the address for Work\?/);
+		assert.match(asked, /stops updating/);
+		assert.equal(
+			(http?.to(FEED_PATH) ?? []).filter((call) => call.method === "PUT")
+				.length,
+			0,
+			"nothing was written before the confirmation was answered",
+		);
+	});
+
+	it("replaces the address and hands back the new one, once", async () => {
+		let rotated = false;
+		await mount((call) => {
+			if (call.method === "PUT") {
+				rotated = true;
+				return {
+					calendarId: WORK,
+					feedToken: NEXT_TOKEN,
+					createdAt: CREATED,
+					rotatedAt: CREATED + 1000,
+				};
+			}
+			return {
+				calendarId: WORK,
+				createdAt: CREATED,
+				rotatedAt: rotated ? CREATED + 1000 : 0,
+			};
+		});
+
+		harness?.click(button("Replace address"));
+		await settle();
+		harness?.click(confirmButton("Replace address"));
+		await settle();
+
+		assert.equal(
+			(http?.to(FEED_PATH) ?? []).filter((call) => call.method === "PUT")
+				.length,
+			1,
+		);
+		assert.ok(
+			harness
+				?.queryAll<HTMLInputElement>("input")
+				.some((input) => input.value.includes(NEXT_TOKEN)),
+			"the replacement address was shown",
+		);
+		assert.match(harness?.text() ?? "", /last replaced/);
+	});
+
+	it("asks before revoking, then leaves the calendar unshared", async () => {
+		let revoked = false;
+		await mount((call) => {
+			if (call.method === "DELETE") {
+				revoked = true;
+				return {};
+			}
+			if (revoked) return httpError(404, "no feed");
+			return { calendarId: WORK, createdAt: CREATED, rotatedAt: 0 };
+		});
+
+		harness?.click(button("Stop sharing"));
+		await settle();
+		assert.match(harness?.text() ?? "", /Stop sharing Work\?/);
+
+		harness?.click(confirmButton("Stop sharing"));
+		await settle();
+
+		assert.equal(
+			(http?.to(FEED_PATH) ?? []).filter((call) => call.method === "DELETE")
+				.length,
+			1,
+		);
+		assert.ok(hasButton("Create subscription address"));
+		assert.doesNotMatch(harness?.text() ?? "", /Address created/);
+	});
+
+	/**
+	 * A refusal is about the write that was refused, not about the card. Left
+	 * standing, it reads as if the replacement that just landed had failed too —
+	 * over an address that is on screen and working.
+	 */
+	it("clears a refused revoke once the next write succeeds", async () => {
+		let rotated = false;
+		await mount((call) => {
+			if (call.method === "DELETE") return httpError(409, "Feed is locked");
+			if (call.method === "PUT") {
+				rotated = true;
+				return {
+					calendarId: WORK,
+					feedToken: NEXT_TOKEN,
+					createdAt: CREATED,
+					rotatedAt: CREATED + 1000,
+				};
+			}
+			return {
+				calendarId: WORK,
+				createdAt: CREATED,
+				rotatedAt: rotated ? CREATED + 1000 : 0,
+			};
+		});
+
+		harness?.click(button("Stop sharing"));
+		await settle();
+		harness?.click(confirmButton("Stop sharing"));
+		await settle();
+		assert.match(harness?.text() ?? "", /Feed is locked/);
+
+		harness?.click(button("Replace address"));
+		await settle();
+		harness?.click(confirmButton("Replace address"));
+		await settle();
+
+		assert.doesNotMatch(
+			harness?.text() ?? "",
+			/was not changed/,
+			"the refused revoke outlived the replacement that succeeded",
+		);
+		assert.doesNotMatch(harness?.text() ?? "", /Feed is locked/);
+		assert.ok(
+			harness
+				?.queryAll<HTMLInputElement>("input")
+				.some((input) => input.value.includes(NEXT_TOKEN)),
+			"the replacement address was shown",
+		);
+	});
+});
+
+describe("a read the server refuses", () => {
+	/**
+	 * A 403 is not "not shared". Drawing the create button for it would tell the
+	 * reader their calendar is private while it may be subscribed to right now.
+	 */
+	it("says the state is unknown rather than offering to create one", async () => {
+		await mount((call) => {
+			if (call.method === "GET") return httpError(403, "not yours");
+			return {};
+		});
+
+		assert.ok(
+			!escalated(),
+			"a 403 the card draws inline must not take the whole screen",
+		);
+		assert.match(harness?.text() ?? "", /Couldn't read whether Work is shared/);
+		assert.ok(!hasButton("Create subscription address"));
+	});
+
+	/**
+	 * The one status this card may not keep to itself. No banner here signs
+	 * anyone back in, so a 401 belongs on the page that does.
+	 */
+	it("escalates a lapsed session instead of drawing it in the card", async () => {
+		await mount((call) => {
+			if (call.method === "GET") return httpError(401, "signed out");
+			return {};
+		});
+
+		assert.ok(escalated(), "a 401 on the read stayed inside the card");
+	});
+});

package/src/hooks/calendar/useCalendarFeed.ts

@@ -0,0 +1,163 @@
+/**
+ * A calendar's secret subscription address, as the settings surface holds it
+ * (issue #1067).
+ *
+ * The plaintext token exists in exactly one place: the answer to the write that
+ * minted it. It is kept here until the reader dismisses it and is never read
+ * back — the server stores a hash, so a lost address is rotated rather than
+ * recovered.
+ *
+ * The read owns its 404 and its 403 and nothing else. "This calendar has no
+ * feed" and "this calendar is not yours" are both answers the card states where
+ * it stands — the 404 as the offer to create one, the 403 as "couldn't read
+ * whether it is shared", never as "not shared yet". A 401 is the session gone,
+ * and no banner on this card signs anyone back in, so it escalates.
+ */
+import {
+	calendarDetailOperationsGetCalendarFeedOptions,
+	calendarDetailOperationsGetCalendarFeedQueryKey,
+	calendarDetailOperationsPutCalendarFeedMutation,
+	calendarDetailOperationsRevokeCalendarFeedMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { calendarFeedUrl } from "@/lib/calendar-feed-url";
+import {
+	isNotFound,
+	softErrorMeta,
+	softErrorStatuses,
+} from "@/lib/error-classifier";
+
+export type CalendarFeedState =
+	| { status: "loading" }
+	/** The server answered, and this calendar is not shared. */
+	| { status: "absent" }
+	| { status: "active"; createdAt: number; rotatedAt: number }
+	/** The server refused to say, which is not the same as "not shared". */
+	| { status: "unreadable"; error: unknown };
+
+export interface CalendarFeedControls {
+	state: CalendarFeedState;
+	/** The address just minted, shown once. Empty at every other moment. */
+	mintedUrl: string;
+	isBusy: boolean;
+	/** A create, rotate or revoke the server turned down. */
+	actionError: unknown;
+	mint: () => void;
+	revoke: () => void;
+	dismissMinted: () => void;
+	retry: () => void;
+}
+
+export function useCalendarFeed(calendarId: string): CalendarFeedControls {
+	const queryClient = useQueryClient();
+	const [mintedUrl, setMintedUrl] = useState("");
+
+	const queryKey = calendarDetailOperationsGetCalendarFeedQueryKey({
+		path: { calendarId },
+	});
+
+	const query = useQuery({
+		...calendarDetailOperationsGetCalendarFeedOptions({
+			path: { calendarId },
+		}),
+		meta: softErrorStatuses(404, 403),
+		retry: false,
+	});
+
+	const invalidate = () => {
+		queryClient.invalidateQueries({ queryKey });
+	};
+
+	// Each write clears the other's refusal as it starts, so the card never
+	// states a failure the reader has already written past. Only one of the two
+	// can name the other directly; the revoke is declared first and reaches
+	// forward through this ref.
+	const resetMint = useRef<() => void>(() => {});
+
+	const revokeMutation = useMutation({
+		...calendarDetailOperationsRevokeCalendarFeedMutation(),
+		meta: softErrorMeta,
+		onMutate: () => {
+			resetMint.current();
+		},
+		onSuccess: () => {
+			setMintedUrl("");
+			invalidate();
+		},
+	});
+
+	const mintMutation = useMutation({
+		...calendarDetailOperationsPutCalendarFeedMutation(),
+		meta: softErrorMeta,
+		// The answer to this write is the plaintext token. Nothing may hold it
+		// once the surface showing it lets go, so it is collected the moment the
+		// observer detaches — on dismissal, and on leaving the page — instead of
+		// sitting in the mutation cache for the default five minutes.
+		gcTime: 0,
+		onMutate: () => {
+			revokeMutation.reset();
+		},
+		onSuccess: (data) => {
+			setMintedUrl(calendarFeedUrl(window.location.host, data.feedToken));
+			invalidate();
+		},
+	});
+
+	resetMint.current = mintMutation.reset;
+
+	const { mutate: mintFeed, reset: resetMintMutation } = mintMutation;
+	const { mutate: revokeFeed } = revokeMutation;
+
+	const mint = useCallback(() => {
+		mintFeed({ path: { calendarId } });
+	}, [calendarId, mintFeed]);
+
+	const revoke = useCallback(() => {
+		revokeFeed({ path: { calendarId } });
+	}, [calendarId, revokeFeed]);
+
+	// Resetting the mutation drops the answer that carried the plaintext token,
+	// which otherwise sits in the mutation cache for its whole gcTime after the
+	// reader has said they saved it.
+	const dismissMinted = useCallback(() => {
+		setMintedUrl("");
+		resetMintMutation();
+	}, [resetMintMutation]);
+
+	const { refetch } = query;
+	const retry = useCallback(() => {
+		refetch();
+	}, [refetch]);
+
+	return {
+		state: readState(query),
+		mintedUrl,
+		isBusy: mintMutation.isPending || revokeMutation.isPending,
+		actionError: mintMutation.error ?? revokeMutation.error,
+		mint,
+		revoke,
+		dismissMinted,
+		retry,
+	};
+}
+
+interface FeedQuery {
+	data?: { createdAt: number; rotatedAt: number };
+	error: unknown;
+	isPending: boolean;
+}
+
+function readState(query: FeedQuery): CalendarFeedState {
+	if (query.error) {
+		if (isNotFound(query.error)) return { status: "absent" };
+		return { status: "unreadable", error: query.error };
+	}
+	if (query.isPending) return { status: "loading" };
+	if (!query.data) return { status: "absent" };
+	return {
+		status: "active",
+		createdAt: query.data.createdAt,
+		rotatedAt: query.data.rotatedAt,
+	};
+}

package/src/hooks/useIntelligenceData.ts

@@ -18,6 +18,7 @@ import type {
 import { isThreadCategory } from "@remit/ui";
 import { useQuery } from "@tanstack/react-query";
 import { useMemo } from "react";
+import { useSemanticSearchEnabled } from "@/hooks/useSemanticSearchEnabled";
 import { isServerError } from "@/lib/error-classifier";
 import { formatDate, formatEmailDate } from "@/lib/format";
 import {
@@ -291,6 +292,12 @@ export interface UseIntelligenceDataResult {
 	 * error or an empty result keeps the panel quiet.
 	 */
 	similarErrorIsFatal: boolean;
+	/**
+	 * False on an instance with semantic search off (#1068): nothing is embedded,
+	 * so the query is never sent and the section states the setting instead of
+	 * rendering an empty list. `undefined` until the config read answers.
+	 */
+	semanticEnabled: boolean | undefined;
 	/**
 	 * True when the address lookup failed with a fatal first-party 5xx. The panel
 	 * must not silently render the sender's flags (VIP/muted/blocked) as absent —
@@ -342,6 +349,7 @@ export function useIntelligenceData(
 	);
 
 	// --- Semantic search: similar messages ---
+	const semanticEnabled = useSemanticSearchEnabled();
 	const semanticQuery = [subject, senderEmail].filter(Boolean).join(" ");
 	const {
 		data: semanticResult,
@@ -351,7 +359,13 @@ export function useIntelligenceData(
 		...semanticSearchOperationsSemanticSearchOptions({
 			query: { query: semanticQuery, limit: 5 },
 		}),
-		enabled: Boolean(thread && semanticQuery.length > 3),
+		// Waits for the config read rather than racing it. An off instance answers
+		// this query with an empty list, which the panel cannot tell from a sender
+		// nothing resembles, so the request is not worth sending on the chance the
+		// instance turns out to be on. `undefined` is that read still in flight;
+		// it is cached process-wide and every other surface already made it.
+		enabled:
+			Boolean(thread && semanticQuery.length > 3) && semanticEnabled === true,
 		staleTime: 60_000,
 		// A non-fatal failure (e.g. 404, no index yet) is acceptable — the sidebar
 		// degrades gracefully. A 5xx is NOT acceptable: it escalates globally and
@@ -397,6 +411,7 @@ export function useIntelligenceData(
 		isSimilarLoading,
 		similarError,
 		similarErrorIsFatal: isServerError(similarError),
+		semanticEnabled,
 		addressErrorIsFatal: isServerError(addressError),
 		addressId: address?.addressId,
 		address,

package/src/hooks/useSemanticSearchEnabled.ts

@@ -0,0 +1,23 @@
+import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+
+/**
+ * Whether this instance stores message vectors (#1068).
+ *
+ * A property of the deployment, so it rides the config read every surface
+ * already makes rather than a probe of its own: the semantic surfaces need the
+ * answer before they have a query to send, and an empty semantic result is
+ * indistinguishable from a mailbox with nothing similar in it.
+ *
+ * `undefined` while the config is in flight, and for a server that predates the
+ * field. Callers must therefore branch on `=== false`, so an instance whose
+ * answer has not arrived shows what it showed before rather than an off state
+ * it may not be in.
+ */
+export const useSemanticSearchEnabled = (): boolean | undefined => {
+	const { data } = useQuery({
+		...configOperationsGetConfigOptions(),
+		staleTime: Infinity,
+	});
+	return data?.semanticSearchEnabled;
+};