@remit/web-client 0.0.62 → 0.0.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.62",
+  "version": "0.0.63",
   "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/self-update/SelfUpdateOverlay.tsx

@@ -0,0 +1,45 @@
+/**
+ * The full-window blocking screen an update takes over.
+ *
+ * Once consent is given the server is genuinely going away, so a quiet spinner
+ * over a mailbox that cannot load would let a broken system look healthy. This
+ * mounts at the app root and owns the window for the whole apply, and for the
+ * "server never came back" verdict — from any route, so a reload mid-apply or a
+ * second tab resumes straight into it.
+ */
+import {
+	SelfUpdateProgressOverlay,
+	SelfUpdateUnreachableScreen,
+} from "@remit/ui";
+import { useSelfUpdate } from "@/hooks/use-system-update";
+
+export function SelfUpdateOverlay() {
+	const { surface, onRetryConnection } = useSelfUpdate();
+
+	if (surface.status !== "ready") return null;
+	const { overlay } = surface;
+
+	if (overlay.kind === "applying") {
+		return (
+			<SelfUpdateProgressOverlay
+				target={overlay.target}
+				phase={overlay.phase}
+				elapsedSeconds={overlay.elapsedSeconds}
+			/>
+		);
+	}
+
+	if (overlay.kind === "neverCameBack") {
+		return (
+			<SelfUpdateUnreachableScreen
+				attemptedVersion={overlay.attemptedVersion}
+				previousVersion={overlay.previousVersion}
+				elapsedSeconds={overlay.elapsedSeconds}
+				logsCommand={overlay.logsCommand}
+				onRetryConnection={onRetryConnection}
+			/>
+		);
+	}
+
+	return null;
+}

package/src/components/settings/AdvancedNavIcon.tsx

@@ -0,0 +1,23 @@
+/**
+ * The Advanced nav icon, with the update dot.
+ *
+ * A dot on the way to settings is the entire notification budget an available
+ * update gets outside the pane — no count, no copy, no action. Everywhere else
+ * stays silent.
+ */
+import { UpdateAvailableDot } from "@remit/ui";
+import { Wrench } from "lucide-react";
+import { useOptionalSelfUpdate } from "@/hooks/use-system-update";
+
+export function AdvancedNavIcon() {
+	const selfUpdate = useOptionalSelfUpdate();
+	const updateAvailable =
+		selfUpdate?.surface.status === "ready" &&
+		selfUpdate.surface.section.status === "available";
+
+	return (
+		<UpdateAvailableDot show={updateAvailable}>
+			<Wrench className="size-4" />
+		</UpdateAvailableDot>
+	);
+}

package/src/components/settings/SelfUpdatePanel.tsx

@@ -0,0 +1,47 @@
+/**
+ * The self-update surface in Settings › Advanced — the only place that talks
+ * about updates. Renders nothing when the surface is absent (no manifest URL,
+ * not the owner, not signed in), so there is no entry point at all in that case.
+ */
+import { SelfUpdateConfirmDialog, SelfUpdateSection } from "@remit/ui";
+import { useState } from "react";
+import { useSelfUpdate } from "@/hooks/use-system-update";
+
+export function SelfUpdatePanel() {
+	const {
+		surface,
+		release,
+		currentVersion,
+		appliesSchemaMigration,
+		onCheck,
+		install,
+		onDismissResult,
+	} = useSelfUpdate();
+	const [confirming, setConfirming] = useState(false);
+
+	if (surface.status !== "ready") return null;
+
+	return (
+		<>
+			<SelfUpdateSection
+				state={surface.section}
+				onCheck={onCheck}
+				onInstall={() => setConfirming(true)}
+				onDismissResult={onDismissResult}
+			/>
+			{release && currentVersion && (
+				<SelfUpdateConfirmDialog
+					open={confirming}
+					currentVersion={currentVersion}
+					release={release}
+					appliesSchemaMigration={appliesSchemaMigration}
+					onClose={() => setConfirming(false)}
+					onConfirm={() => {
+						setConfirming(false);
+						install(release.version);
+					}}
+				/>
+			)}
+		</>
+	);
+}

package/src/hooks/use-system-update.test.ts

@@ -0,0 +1,342 @@
+/**
+ * The self-update hook, wired end to end against the generated client through a
+ * mocked fetch. The pure state machine is covered in `lib/self-update-state.test.ts`;
+ * these exercise the parts only the live hook has: resuming a persisted run
+ * across a request that fails, the poll that survives a dead server, and the
+ * POST that persists a run id the reload will pick up.
+ */
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, test } from "node:test";
+import { systemOperationsGetSystemUpdateQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapSystemUpdateResponse,
+	RemitImapSystemUpdateRun,
+} from "@remit/api-http-client/types.gen.ts";
+import { act, createElement, type ReactNode } from "react";
+import { SelfUpdateOverlay } from "../components/self-update/SelfUpdateOverlay";
+import { AdvancedNavIcon } from "../components/settings/AdvancedNavIcon";
+import { SelfUpdatePanel } from "../components/settings/SelfUpdatePanel";
+import {
+	loadHeldRun,
+	SELF_UPDATE_RUN_KEY,
+	saveHeldRun,
+} from "../lib/self-update-state";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import { type HttpMock, httpError, mockFetch } from "../test-support/http";
+import {
+	type SelfUpdateApi,
+	SelfUpdateProvider,
+	useSelfUpdate,
+} from "./use-system-update";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+function installMemoryStorage(): void {
+	const store = new Map<string, string>();
+	globalThis.localStorage = {
+		getItem: (k: string) => store.get(k) ?? null,
+		setItem: (k: string, v: string) => void store.set(k, v),
+		removeItem: (k: string) => void store.delete(k),
+		clear: () => store.clear(),
+		key: () => null,
+		length: 0,
+	} as Storage;
+}
+
+beforeEach(installMemoryStorage);
+
+afterEach(() => {
+	http?.restore();
+	http = undefined;
+	harness?.close();
+	harness = undefined;
+});
+
+function run(
+	overrides: Partial<RemitImapSystemUpdateRun> = {},
+): RemitImapSystemUpdateRun {
+	return {
+		runId: "upd_1",
+		fromVersion: "0.9.3",
+		targetVersion: "0.9.4",
+		phase: "starting",
+		outcome: null,
+		startedAt: "2026-07-20T11:59:30.000Z",
+		updatedAt: "2026-07-20T11:59:45.000Z",
+		message: "Restarting Remit on 0.9.4.",
+		logCommand: "remit logs --since 10m",
+		...overrides,
+	};
+}
+
+const available: RemitImapSystemUpdateResponse = {
+	currentVersion: "0.9.3",
+	check: {
+		status: "ok",
+		updateAvailable: true,
+		latestVersion: "0.9.4",
+		publishedAt: "2026-07-14T09:00:00.000Z",
+		summary: "Faster first sync.",
+		releaseNotesUrl: "https://example.test/notes",
+	},
+	run: null,
+};
+
+const updateKey = systemOperationsGetSystemUpdateQueryKey();
+
+async function settle(dom: DomHarness): Promise<void> {
+	for (let attempt = 0; attempt < 40; attempt += 1) {
+		await dom.flush();
+		const state = dom.queryClient.getQueryState(updateKey);
+		const done =
+			state &&
+			state.fetchStatus === "idle" &&
+			(state.data !== undefined || state.error != null);
+		if (done) {
+			// The cache has settled; give React the turns to commit the render it
+			// scheduled off that settle before the assert reads the DOM.
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
+			return;
+		}
+		await dom.wait(1);
+	}
+}
+
+async function renderSurface(
+	getResponse: () => unknown,
+	children: ReactNode,
+): Promise<DomHarness> {
+	http = mockFetch((call) => {
+		if (call.path.endsWith("/system/update") && call.method === "GET") {
+			return getResponse();
+		}
+		return {};
+	});
+	harness = createDomHarness();
+	harness.renderApp(createElement(SelfUpdateProvider, null, children));
+	await settle(harness);
+	return harness;
+}
+
+describe("SelfUpdatePanel — the surface in Advanced", () => {
+	test("a 404 renders no entry point at all", async () => {
+		const dom = await renderSurface(
+			() => httpError(404),
+			createElement(SelfUpdatePanel),
+		);
+		assert.equal(dom.html(), "");
+	});
+
+	test("an available update shows the install action", async () => {
+		const dom = await renderSurface(
+			() => available,
+			createElement(SelfUpdatePanel),
+		);
+		assert.match(dom.html(), /Install 0\.9\.4/);
+	});
+
+	test("a rolled-back run shows the reason and command verbatim", async () => {
+		const dom = await renderSurface(
+			() => ({
+				currentVersion: "0.9.3",
+				check: { status: "ok", updateAvailable: false },
+				run: run({
+					outcome: "rolledBack",
+					message: "migration 0042 failed and was reverted",
+					logCommand: "remit logs --since 30m",
+				}),
+			}),
+			createElement(SelfUpdatePanel),
+		);
+		assert.match(dom.html(), /migration 0042 failed and was reverted/);
+		assert.match(dom.html(), /remit logs --since 30m/);
+	});
+
+	test("a rollback that failed is shown verbatim and needs a shell", async () => {
+		const dom = await renderSurface(
+			() => ({
+				currentVersion: "0.9.3",
+				check: { status: "ok", updateAvailable: false },
+				run: run({
+					outcome: "rollbackFailed",
+					message: "snapshot restore errored: database is locked",
+					logCommand: "remit logs --since 1h",
+				}),
+			}),
+			createElement(SelfUpdatePanel),
+		);
+		assert.match(dom.html(), /snapshot restore errored: database is locked/);
+		assert.match(dom.html(), /remit logs --since 1h/);
+		assert.match(dom.html(), /needs you at a shell/);
+	});
+});
+
+describe("AdvancedNavIcon — the dot", () => {
+	test("shows the update dot when one is available", async () => {
+		const dom = await renderSurface(
+			() => available,
+			createElement(AdvancedNavIcon),
+		);
+		assert.match(dom.html(), /Update available/);
+	});
+
+	test("shows no dot when up to date", async () => {
+		const dom = await renderSurface(
+			() => ({
+				currentVersion: "0.9.3",
+				check: { status: "ok", updateAvailable: false },
+				run: null,
+			}),
+			createElement(AdvancedNavIcon),
+		);
+		assert.doesNotMatch(dom.html(), /Update available/);
+	});
+});
+
+describe("SelfUpdateOverlay — the blocking screen", () => {
+	test("a run this client never started still renders", async () => {
+		const dom = await renderSurface(
+			() => ({
+				currentVersion: "0.9.3",
+				check: { status: "ok", updateAvailable: false },
+				run: run({ outcome: null }),
+			}),
+			createElement(SelfUpdateOverlay),
+		);
+		assert.match(dom.html(), /Installing Remit 0\.9\.4/);
+	});
+
+	test("a held run resumes into applying when the request fails", async () => {
+		saveHeldRun({
+			runId: "upd_1",
+			attemptedVersion: "0.9.4",
+			previousVersion: "0.9.3",
+			startedAt: Date.now() - 20_000,
+		});
+		const dom = await renderSurface(() => {
+			throw new Error("connection refused");
+		}, createElement(SelfUpdateOverlay));
+		assert.match(dom.html(), /Installing Remit 0\.9\.4/);
+		assert.doesNotMatch(dom.html(), /has not answered since the restart/);
+	});
+
+	test("the budget elapsing flips a held run to never-came-back", async () => {
+		saveHeldRun({
+			runId: "upd_1",
+			attemptedVersion: "0.9.4",
+			previousVersion: "0.9.3",
+			startedAt: Date.now() - 60 * 60_000,
+		});
+		const dom = await renderSurface(() => {
+			throw new Error("connection refused");
+		}, createElement(SelfUpdateOverlay));
+		assert.match(dom.html(), /has not answered since the restart/);
+		assert.match(dom.html(), /remit logs/);
+	});
+});
+
+describe("useSystemUpdate — actions", () => {
+	function mountApi(getResponse: () => unknown): {
+		dom: DomHarness;
+		api: () => SelfUpdateApi;
+	} {
+		http = mockFetch((call) => {
+			if (call.path.endsWith("/system/update") && call.method === "GET") {
+				return getResponse();
+			}
+			return {
+				currentVersion: "0.9.3",
+				check: { status: "ok", updateAvailable: true, latestVersion: "0.9.4" },
+				run: run({ outcome: null }),
+			};
+		});
+		let captured: SelfUpdateApi | undefined;
+		const Probe = () => {
+			captured = useSelfUpdate();
+			return null;
+		};
+		harness = createDomHarness();
+		harness.renderApp(
+			createElement(SelfUpdateProvider, null, createElement(Probe)),
+		);
+		return {
+			dom: harness,
+			api: () => {
+				if (!captured) throw new Error("hook not mounted");
+				return captured;
+			},
+		};
+	}
+
+	test("install persists the run id the surface returns", async () => {
+		const { dom, api } = mountApi(() => available);
+		await settle(dom);
+
+		await act(async () => {
+			api().install("0.9.4");
+			await dom.flush();
+			await dom.wait(1);
+			await dom.flush();
+		});
+
+		const held = loadHeldRun();
+		assert.equal(held?.runId, "upd_1");
+		assert.equal(localStorage.getItem(SELF_UPDATE_RUN_KEY) !== null, true);
+		const surface = api().surface;
+		assert.equal(
+			surface.status === "ready" && surface.overlay.kind,
+			"applying",
+		);
+	});
+
+	test("dismissing a finished result clears the pane", async () => {
+		const { dom, api } = mountApi(() => ({
+			currentVersion: "0.9.4",
+			check: { status: "ok", updateAvailable: false },
+			run: run({
+				runId: "upd_9",
+				outcome: "succeeded",
+				targetVersion: "0.9.4",
+			}),
+		}));
+		await settle(dom);
+
+		const before = api().surface;
+		assert.equal(
+			before.status === "ready" && before.section.status,
+			"succeeded",
+		);
+
+		await act(async () => {
+			api().onDismissResult();
+			await dom.flush();
+		});
+
+		const after = api().surface;
+		assert.equal(after.status === "ready" && after.section.status, "upToDate");
+	});
+
+	test("checking and retrying re-poll the surface", async () => {
+		let calls = 0;
+		const { dom, api } = mountApi(() => {
+			calls += 1;
+			return available;
+		});
+		await settle(dom);
+		const afterMount = calls;
+
+		await act(async () => {
+			api().onCheck();
+			await dom.flush();
+		});
+		await act(async () => {
+			api().onRetryConnection();
+			await dom.flush();
+		});
+
+		assert.equal(calls > afterMount, true);
+	});
+});

package/src/hooks/use-system-update.ts

@@ -0,0 +1,215 @@
+/**
+ * The self-update surface, wired to the generated client.
+ *
+ * A single instance owns the query, the mutation, and the run id the client
+ * persists across a restart, and hands the folded `SelfUpdateState` plus the
+ * blocking-overlay state to every consumer through context — so the Advanced
+ * pane, the root overlay, and the nav dot all read one source of truth. The
+ * state machine itself lives in `lib/self-update-state.ts`.
+ *
+ * Polling follows the run: every 30 seconds while idle, every 5 seconds while a
+ * run is in flight or a persisted run is being resumed.
+ */
+import {
+	systemOperationsApplySystemUpdateMutation,
+	systemOperationsGetSystemUpdateOptions,
+	systemOperationsGetSystemUpdateQueryKey,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type {
+	RemitImapSystemUpdateResponse,
+	RemitImapSystemUpdateRun,
+} from "@remit/api-http-client/types.gen.ts";
+import type { ReleaseInfo } from "@remit/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import {
+	createContext,
+	createElement,
+	type ReactNode,
+	useCallback,
+	useContext,
+	useEffect,
+	useRef,
+	useState,
+} from "react";
+import {
+	appliesSchemaMigration,
+	clearStoredRun,
+	deriveUpdateSurface,
+	type HeldRun,
+	isSurfaceAbsent,
+	loadHeldRun,
+	releaseFromCheck,
+	saveHeldRun,
+	type UpdateSurface,
+} from "@/lib/self-update-state";
+
+const IDLE_POLL_MS = 30_000;
+const RUN_POLL_MS = 5_000;
+
+export interface SelfUpdateApi {
+	surface: UpdateSurface;
+	/** Whether the pending release runs a schema migration during the window. */
+	appliesSchemaMigration: boolean;
+	currentVersion: string | undefined;
+	/** The available release, for the consent dialog. */
+	release: ReleaseInfo | undefined;
+	/** Refetch the surface, showing a `checking` pane until it settles. */
+	onCheck: () => void;
+	/** Request a specific release — consent has been given. */
+	install: (targetVersion: string) => void;
+	/** Clear a finished or given-up result from the pane. */
+	onDismissResult: () => void;
+	/** Re-poll from the "server never came back" screen. */
+	onRetryConnection: () => void;
+}
+
+function pollInterval(
+	error: unknown,
+	run: RemitImapSystemUpdateRun | null,
+	hasHeldRun: boolean,
+): number | false {
+	if (isSurfaceAbsent(error) && !hasHeldRun) return false;
+	const inFlight = run !== null && run.outcome === null;
+	if (hasHeldRun || inFlight) return RUN_POLL_MS;
+	return IDLE_POLL_MS;
+}
+
+export function useSystemUpdate(): SelfUpdateApi {
+	const queryClient = useQueryClient();
+	const [held, setHeld] = useState<HeldRun | null>(() => loadHeldRun());
+	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
+	const [checkRequested, setCheckRequested] = useState(false);
+
+	const heldRef = useRef(held);
+	heldRef.current = held;
+
+	const query = useQuery({
+		...systemOperationsGetSystemUpdateOptions(),
+		retry: false,
+		meta: { softError: true },
+		refetchInterval: (query) =>
+			pollInterval(
+				query.state.error,
+				query.state.data?.run ?? null,
+				heldRef.current !== null,
+			),
+	});
+
+	const derived = deriveUpdateSurface({
+		data: query.data,
+		isError: query.isError,
+		error: query.error,
+		isFetching: query.isFetching,
+		held,
+		dismissedRunId,
+		checkRequested,
+		now: Date.now(),
+	});
+
+	const shownRunIdRef = useRef<string | null>(null);
+	shownRunIdRef.current =
+		derived.surface.status === "ready" && "runId" in derived.surface.section
+			? derived.surface.section.runId
+			: null;
+
+	const { clearStoredRun: shouldClearStored, releaseHeld } = derived;
+
+	useEffect(() => {
+		if (shouldClearStored) clearStoredRun();
+	}, [shouldClearStored]);
+
+	useEffect(() => {
+		if (releaseHeld) setHeld((current) => (current === null ? current : null));
+	}, [releaseHeld]);
+
+	useEffect(() => {
+		if (checkRequested && !query.isFetching) setCheckRequested(false);
+	}, [checkRequested, query.isFetching]);
+
+	const { refetch } = query;
+
+	const onCheck = useCallback(() => {
+		setCheckRequested(true);
+		void refetch();
+	}, [refetch]);
+
+	const onRetryConnection = useCallback(() => {
+		void refetch();
+	}, [refetch]);
+
+	const mutation = useMutation({
+		...systemOperationsApplySystemUpdateMutation(),
+		meta: { softError: true },
+		onSuccess: (response: RemitImapSystemUpdateResponse) => {
+			const run = response.run;
+			if (run !== null) {
+				const record: HeldRun = {
+					runId: run.runId,
+					attemptedVersion: run.targetVersion,
+					previousVersion: run.fromVersion,
+					startedAt: Date.now(),
+				};
+				saveHeldRun(record);
+				setHeld(record);
+				setDismissedRunId(null);
+			}
+			queryClient.setQueryData(
+				systemOperationsGetSystemUpdateQueryKey(),
+				response,
+			);
+		},
+		onError: () => {
+			void refetch();
+		},
+	});
+
+	const { mutate } = mutation;
+	const install = useCallback(
+		(targetVersion: string) => {
+			mutate({ body: { targetVersion } });
+		},
+		[mutate],
+	);
+
+	const onDismissResult = useCallback(() => {
+		if (shownRunIdRef.current !== null)
+			setDismissedRunId(shownRunIdRef.current);
+		clearStoredRun();
+		setHeld(null);
+	}, []);
+
+	return {
+		surface: derived.surface,
+		appliesSchemaMigration: appliesSchemaMigration(query.data),
+		currentVersion: query.data?.currentVersion,
+		release: releaseFromCheck(query.data, Date.now()),
+		onCheck,
+		install,
+		onDismissResult,
+		onRetryConnection,
+	};
+}
+
+const SelfUpdateContext = createContext<SelfUpdateApi | null>(null);
+
+export function SelfUpdateProvider({ children }: { children: ReactNode }) {
+	const value = useSystemUpdate();
+	return createElement(SelfUpdateContext.Provider, { value }, children);
+}
+
+export function useSelfUpdate(): SelfUpdateApi {
+	const value = useContext(SelfUpdateContext);
+	if (value === null) {
+		throw new Error("useSelfUpdate must be used within a SelfUpdateProvider");
+	}
+	return value;
+}
+
+/**
+ * The surface when a provider is present, or null when it is not. For the nav
+ * dot, which renders in settings trees that some tests mount without the
+ * provider — no provider means no update to hint at.
+ */
+export function useOptionalSelfUpdate(): SelfUpdateApi | null {
+	return useContext(SelfUpdateContext);
+}