@remit/web-client 0.0.325 → 0.0.327

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

@@ -1,341 +0,0 @@
-/**
- * The self-update surface, wired to the generated client.
- *
- * A single instance owns the query, the mutation, and the run this page asked
- * for, 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`.
- *
- * The held run lives here and nowhere else. A restart does not reload the page,
- * so this state spans the whole window; a page that loads afterwards holds
- * nothing and takes the server's answer as it finds it.
- *
- * Polling follows the run: every 30 seconds while idle, every 5 seconds while a
- * run is in flight, this page is waiting on one it started, or it is waiting on
- * a check it pressed for.
- */
-import {
-	systemOperationsApplySystemUpdateMutation,
-	systemOperationsGetSystemUpdateOptions,
-	systemOperationsGetSystemUpdateQueryKey,
-} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { systemOperationsGetSystemUpdate } from "@remit/api-http-client/sdk.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 {
-	restartExpectedMeta,
-	shouldEscalate,
-	softErrorMeta,
-} from "@/lib/error-classifier";
-import { reportFatalError } from "@/lib/fatal-error";
-import {
-	appliesSchemaMigration,
-	type CheckPress,
-	checkAnswered,
-	checkRequestFailureReason,
-	deriveUpdateSurface,
-	type HeldRun,
-	isSurfaceAbsent,
-	mapUpdatePhase,
-	type RunSighting,
-	releaseFromCheck,
-	runInFlight,
-	type UpdateSurface,
-} from "@/lib/self-update-state";
-
-const IDLE_POLL_MS = 30_000;
-const RUN_POLL_MS = 5_000;
-
-/**
- * The poll's own error UX, and — while a run is known to be in flight — the
- * restart that run performs. Stopping and starting the backend is what the run
- * is, so the gateway statuses answered while it is down belong to the surface
- * below, which shows the phase and gives up loudly if the server never comes
- * back (#468). Outside that window the poll carries no such claim.
- *
- * "Known" is either source: the run this page started and holds, or the run the
- * server last reported as going. The overlay speaks for a run in any tab, so the
- * window it rides has to open in any tab too — a second tab, or this one after a
- * reload, holds nothing and would otherwise meet the restart with no claim on it.
- */
-const POLL_META = softErrorMeta;
-const POLL_ACROSS_RESTART_META = { ...softErrorMeta, ...restartExpectedMeta };
-
-/**
- * How long a pressed check waits for the updater before the pane calls it a
- * failure. The backend only records the request; the updater picks it up on a
- * five-second watch tick, so half a minute is several ticks — patient enough for
- * a busy box, short enough that a press against a dead updater is answered
- * rather than left spinning for good.
- */
-export const CHECK_ANSWER_BUDGET_MS = 30_000;
-
-/** The press was recorded and nothing came back. Names the process and the log. */
-export const UPDATER_SILENT_REASON =
-	"The updater did not answer. Run `remit logs updater` to see why.";
-
-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;
-	/** Ask the updater for a fresh check, showing a `checking` pane until it answers. */
-	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,
-	hasPress: boolean,
-): number | false {
-	if (isSurfaceAbsent(error) && !hasHeldRun) return false;
-	const inFlight = run !== null && run.outcome === null;
-	// A press is waiting on the updater's next watch tick (#599), so it polls at
-	// the run cadence — and only until the wait ends, which drops the press.
-	if (hasHeldRun || inFlight || hasPress) return RUN_POLL_MS;
-	return IDLE_POLL_MS;
-}
-
-export function useSystemUpdate(): SelfUpdateApi {
-	const queryClient = useQueryClient();
-	const [held, setHeld] = useState<HeldRun | null>(null);
-	const [dismissedRunId, setDismissedRunId] = useState<string | null>(null);
-	const [checkPress, setCheckPress] = useState<CheckPress | null>(null);
-	const [checkFailure, setCheckFailure] = useState<string | null>(null);
-	const [sighting, setSighting] = useState<RunSighting | null>(null);
-
-	const heldRef = useRef(held);
-	heldRef.current = held;
-	const pressRef = useRef(checkPress);
-	pressRef.current = checkPress;
-
-	// The last answer, which outlives the failed requests after it: a tab that
-	// never pressed install learns from here that it is inside a restart.
-	const lastKnown = queryClient.getQueryData<RemitImapSystemUpdateResponse>(
-		systemOperationsGetSystemUpdateQueryKey(),
-	);
-	const insideRestart =
-		held !== null || runInFlight(lastKnown, dismissedRunId) !== null;
-
-	const query = useQuery({
-		...systemOperationsGetSystemUpdateOptions(),
-		retry: false,
-		meta: insideRestart ? POLL_ACROSS_RESTART_META : POLL_META,
-		refetchInterval: (query) =>
-			pollInterval(
-				query.state.error,
-				query.state.data?.run ?? null,
-				heldRef.current !== null,
-				pressRef.current !== null,
-			),
-	});
-
-	const dataRef = useRef(query.data);
-	dataRef.current = query.data;
-
-	const derived = deriveUpdateSurface({
-		data: query.data,
-		isError: query.isError,
-		error: query.error,
-		held,
-		dismissedRunId,
-		checkPress,
-		checkFailure,
-		sighting,
-		now: Date.now(),
-	});
-
-	// Stamp the run the server reports, once, off this tab's clock. The stamp is
-	// what the give-up is measured against, so it must not move while the server
-	// is unreachable — and it must not carry over to the next run.
-	const reported = runInFlight(query.data, dismissedRunId);
-	useEffect(() => {
-		if (reported === null) {
-			setSighting((current) => (current === null ? current : null));
-			return;
-		}
-		setSighting((current) =>
-			current !== null && current.runId === reported.runId
-				? current
-				: { runId: reported.runId, observedAt: Date.now() },
-		);
-	}, [reported]);
-
-	const shownRunIdRef = useRef<string | null>(null);
-	shownRunIdRef.current =
-		derived.surface.status === "ready" && "runId" in derived.surface.section
-			? derived.surface.section.runId
-			: null;
-
-	const { releaseHeld } = derived;
-
-	useEffect(() => {
-		if (releaseHeld) setHeld((current) => (current === null ? current : null));
-	}, [releaseHeld]);
-
-	// The updater answered the press: let go of it, so the next poll renders the
-	// verdict rather than the spinner.
-	useEffect(() => {
-		if (checkPress !== null && checkAnswered(checkPress, query.data))
-			setCheckPress(null);
-	}, [checkPress, query.data]);
-
-	// The wait has to end itself. A poll that answers with the same bytes changes
-	// nothing this hook reads, so nothing would re-render to notice the budget had
-	// run out, and the spinner would sit there for good (#599).
-	useEffect(() => {
-		if (checkPress === null) return;
-		const remaining =
-			checkPress.pressedAt + CHECK_ANSWER_BUDGET_MS - Date.now();
-		const timer = setTimeout(
-			() => {
-				setCheckPress(null);
-				setCheckFailure(UPDATER_SILENT_REASON);
-			},
-			Math.max(0, remaining),
-		);
-		return () => clearTimeout(timer);
-	}, [checkPress]);
-
-	const { refetch } = query;
-
-	const onCheck = useCallback(() => {
-		// A plain refetch only re-reads state.json, so the answer would be exactly
-		// as old as it was before the press. refresh=true has the backend record a
-		// check request for the updater; the wait is this page's to keep, against
-		// the `lastCheckedAt` the server had when the control was pressed (#599).
-		setCheckFailure(null);
-		setCheckPress({
-			pressedAt: Date.now(),
-			since: dataRef.current?.check.lastCheckedAt,
-		});
-
-		void systemOperationsGetSystemUpdate({
-			query: { refresh: true },
-			throwOnError: true,
-		})
-			.then(() => {
-				void refetch();
-			})
-			.catch((error: unknown) => {
-				// The request never reached the seam, so nothing is coming. Say so
-				// where the press was made instead of reverting to the old verdict.
-				// This is a raw SDK call, outside the query cache that feeds the
-				// global sink, so the 5xx the seam answers when the control volume
-				// is unwritable escalates from here or from nowhere.
-				if (shouldEscalate(error, softErrorMeta, "user")) {
-					reportFatalError(error);
-				}
-				setCheckPress(null);
-				setCheckFailure(checkRequestFailureReason(error));
-			});
-	}, [refetch]);
-
-	const onRetryConnection = useCallback(() => {
-		void refetch();
-	}, [refetch]);
-
-	const mutation = useMutation({
-		...systemOperationsApplySystemUpdateMutation(),
-		meta: { softError: true },
-		onSuccess: (response: RemitImapSystemUpdateResponse) => {
-			const run = response.run;
-			if (run !== null) {
-				setHeld({
-					runId: run.runId,
-					attemptedVersion: run.targetVersion,
-					previousVersion: run.fromVersion,
-					phase: mapUpdatePhase(run.phase),
-					startedAt: Date.now(),
-				});
-				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);
-		setHeld(null);
-		// Retiring the outcome uncovers the check verdict beneath it. A failure
-		// recorded while the outcome held the pane describes a press the user can
-		// no longer see, and an update run of its own supersedes anything an
-		// earlier check concluded — either way it must not resurface here.
-		setCheckPress(null);
-		setCheckFailure(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);
-}

package/src/hooks/useApplyLabel.ts

@@ -1,71 +0,0 @@
-import { messageBulkOperationsUpdateMessageLabelsMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type {
-	RemitImapLabelAction,
-	RemitImapThreadMessageResponse,
-} 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 { resolveMailboxesForMessages } from "@/hooks/useMarkAsRead";
-import { runChunkedMutation } from "@/lib/bulk-actions";
-import {
-	invalidateThreadListQueries,
-	threadListCacheKeys,
-} from "@/lib/thread-list-cache";
-
-/**
- * Apply or remove a label on a "just these" selection (issue #26, RFC 034
- * recap). No optimistic patch: a label is metadata on the row, not something
- * that removes it from the current view, so settling on the server response
- * and invalidating is enough — unlike a move or delete, which the row leaves
- * immediately.
- */
-export const useApplyLabel = (options: {
-	mailboxId: string;
-	accountId?: string;
-	/** The threads the selection may span, for resolving which mailbox lists to invalidate. */
-	messages?: RemitImapThreadMessageResponse[];
-}) => {
-	const { mailboxId, messages } = options;
-	const queryClient = useQueryClient();
-	const { pushError } = useErrorBanners();
-
-	const { mutateAsync, isPending } = useMutation({
-		...messageBulkOperationsUpdateMessageLabelsMutation(),
-		onError: (error, variables) => {
-			pushError({
-				title:
-					variables.body.action === "Remove"
-						? "Couldn't remove label"
-						: "Couldn't apply label",
-				detail: formatErrorDetail(error),
-				error,
-			});
-		},
-		onSettled: (_data, _error, variables) => {
-			invalidateThreadListQueries(
-				queryClient,
-				threadListCacheKeys(
-					resolveMailboxesForMessages(
-						variables.body.messageIds ?? [],
-						messages ?? [],
-						mailboxId,
-					),
-				),
-			);
-		},
-	});
-
-	const applyLabel = useCallback(
-		(messageIds: string[], labelId: string, action: RemitImapLabelAction) => {
-			if (messageIds.length === 0) return;
-			void runChunkedMutation(messageIds, (chunk) =>
-				mutateAsync({ body: { messageIds: chunk, labelId, action } }),
-			);
-		},
-		[mutateAsync],
-	);
-
-	return { applyLabel, isPending };
-};

package/src/hooks/useArchiveMailbox.ts

@@ -1,162 +0,0 @@
-import { configOperationsGetConfigOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type {
-	RemitImapCanonicalMailboxRole,
-	RemitImapFolderAppointment,
-} from "@remit/api-http-client/types.gen.ts";
-import { useQuery } from "@tanstack/react-query";
-import { useMemo } from "react";
-import type { TrashResolution } from "@/lib/format";
-
-/**
- * RFC 032 exclusive-folder-appointment (#976): every "which mailbox plays
- * role X" question resolves from the account's `folderAppointments` map, not
- * from independently re-detecting SPECIAL-USE flags or hardcoded name lists.
- * The map is server-resolved (persisted user choice, or a proposal for
- * anything unfilled), so a single shared lookup replaces what used to be four
- * near-identical flag-then-name detectors.
- */
-const useFolderRoleMailbox = (
-	accountId: string | undefined,
-	role: RemitImapCanonicalMailboxRole,
-): { mailboxId: string | undefined; isLoading: boolean } => {
-	const { data: config, isLoading } = useQuery({
-		...configOperationsGetConfigOptions(),
-		staleTime: Infinity,
-		enabled: !!accountId,
-	});
-
-	const mailboxId = useMemo(() => {
-		if (!accountId) return undefined;
-		const account = config?.accounts.find((a) => a.accountId === accountId);
-		return account?.folderAppointments.find((fa) => fa.role === role)
-			?.mailboxId;
-	}, [config, accountId, role]);
-
-	return { mailboxId, isLoading };
-};
-
-/**
- * Returns the account's appointed Archive mailbox id. `undefined` while
- * loading or when no folder is appointed to (or proposed for) the role.
- */
-export const useArchiveMailbox = (
-	accountId: string | undefined,
-): { archiveMailboxId: string | undefined; isLoading: boolean } => {
-	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Archive");
-	return { archiveMailboxId: mailboxId, isLoading };
-};
-
-/**
- * Returns the account's appointed Drafts mailbox id. Used by the mailbox
- * route to decide whether to render the segmented Drafts view (Remit drafts +
- * IMAP Drafts) in place of the flat message list (issue #505).
- */
-export const useDraftsMailbox = (
-	accountId: string | undefined,
-): { draftsMailboxId: string | undefined; isLoading: boolean } => {
-	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Drafts");
-	return { draftsMailboxId: mailboxId, isLoading };
-};
-
-/**
- * Returns the account's Inbox mailbox id — the destination for "Not spam"
- * (issue #594), which moves a message out of Junk back to the inbox.
- */
-export const useInboxMailbox = (
-	accountId: string | undefined,
-): { inboxMailboxId: string | undefined; isLoading: boolean } => {
-	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Inbox");
-	return { inboxMailboxId: mailboxId, isLoading };
-};
-
-/**
- * Returns the account's appointed Junk/Spam mailbox id, used by the triage
- * `!` (mark junk) key (#429). The message-flags API has no `$Junk` keyword
- * field, so "mark junk" is realized as a move to the Junk mailbox.
- */
-export const useJunkMailbox = (
-	accountId: string | undefined,
-): { junkMailboxId: string | undefined; isLoading: boolean } => {
-	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Junk");
-	return { junkMailboxId: mailboxId, isLoading };
-};
-
-/**
- * Returns the account's appointed Trash mailbox id, which is how the mailbox
- * pane tells it is looking at Trash and may offer to empty it (#847).
- */
-export const useTrashMailbox = (
-	accountId: string | undefined,
-): { trashMailboxId: string | undefined; isLoading: boolean } => {
-	const { mailboxId, isLoading } = useFolderRoleMailbox(accountId, "Trash");
-	return { trashMailboxId: mailboxId, isLoading };
-};
-
-/**
- * Each account's appointed Trash mailbox, keyed by account. The delete
- * confirmation needs it to tell a move-to-Trash apart from a delete inside
- * Trash, which is an unrecoverable expunge and has to be asked as one (#845),
- * and apart from an account that appoints no Trash at all, where the server
- * refuses the delete outright (#846).
- *
- * A map rather than a set of ids, because the brief and Flagged answer for
- * selections that span accounts (#855): "is this row in Trash" is a question
- * about the row's own account, and "does any Trash exist" has to be answerable
- * as "no" rather than as silence.
- *
- * `hasAppointments` is data presence, never `!isLoading`. React Query v5
- * computes `isLoading` as `isPending && isFetching`, so an offline query is
- * paused and reports neither loading nor error while `data` is still
- * undefined — which read as "no Trash anywhere", and promised a reversible
- * move over an expunge that would replay on reconnect.
- */
-export const useTrashByAccount = (): {
-	trashByAccount: ReadonlyMap<string, TrashResolution>;
-	hasAppointments: boolean;
-	isError: boolean;
-} => {
-	const { data: config, isError } = useQuery({
-		...configOperationsGetConfigOptions(),
-		staleTime: Infinity,
-	});
-
-	const trashByAccount = useMemo(() => {
-		const byAccount = new Map<string, TrashResolution>();
-		for (const account of config?.accounts ?? []) {
-			const trash = account.folderAppointments.find(
-				(appointment) => appointment.role === "Trash",
-			);
-			byAccount.set(account.accountId, {
-				mailboxId: trash?.mailboxId,
-				source: trash?.source ?? "None",
-				staleFolderPath: trash?.staleAppointmentPath,
-			});
-		}
-		return byAccount;
-	}, [config]);
-
-	return { trashByAccount, hasAppointments: config !== undefined, isError };
-};
-
-/**
- * Returns an account's full role→mailbox appointment map, for callers that
- * need more than one role at once (e.g. the Move-to picker excluding both
- * Drafts and Sent, and ordering system folders by role). Empty while loading
- * or when `accountId` is undefined.
- */
-export const useFolderAppointments = (
-	accountId: string | undefined,
-): readonly RemitImapFolderAppointment[] => {
-	const { data: config } = useQuery({
-		...configOperationsGetConfigOptions(),
-		staleTime: Infinity,
-		enabled: !!accountId,
-	});
-
-	return useMemo(
-		() =>
-			config?.accounts.find((a) => a.accountId === accountId)
-				?.folderAppointments ?? [],
-		[config, accountId],
-	);
-};