@remit/web-client 0.0.325 → 0.0.326

package/src/hooks/useEscalatedActions.ts

@@ -1,334 +0,0 @@
-import {
-	messageBulkOperationsDeleteMessages,
-	messageBulkOperationsMoveMessages,
-	messageBulkOperationsUpdateFlags,
-	threadOperationsSearchThreads,
-} from "@remit/api-http-client/sdk.gen.ts";
-import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
-import { useCallback, useEffect, useRef, useState } from "react";
-import {
-	type BulkRunRequest,
-	type BulkRunSource,
-	useBulkRun,
-} from "@/components/mail/BulkRunProvider";
-import { useErrorBanners } from "@/components/ui/ErrorBannerProvider";
-import { buildMutationErrorBanner } from "@/components/ui/error-banners";
-import type {
-	ApplyBatch,
-	BulkActionProgress,
-	BulkActionTarget,
-	BulkRunStart,
-	EscalatedAction,
-	FetchIdsPage,
-} from "@/lib/bulk-actions";
-
-/** The predicate a search-scoped run re-issues on every page — the same
- *  filters the visible list is searching with, minus pagination/count knobs. */
-export type EscalationSearchQuery = Pick<
-	NonNullable<ThreadOperationsSearchThreadsData["query"]>,
-	| "order"
-	| "query"
-	| "subject"
-	| "from"
-	| "unread"
-	| "starred"
-	| "attachments"
-	| "category"
->;
-
-/** Page size for the execution loop. Set to the write side's own 100-id cap so
- *  an execution page IS a write chunk — no in-memory accumulation step between
- *  reading ids and sending them. */
-const PAGE_SIZE = 100;
-
-export type EscalationPhase =
-	| { kind: "idle" }
-	| { kind: "counting" }
-	| { kind: "escalated"; total: number };
-
-interface UseEscalatedActionsOptions {
-	mailboxId: string;
-	/** The mailbox in the user's words, for a commit refused while this runs. */
-	mailboxLabel?: string;
-	/** Owning account, forwarded to the unseen-count invalidation on completion. */
-	accountId?: string;
-	/** Disables escalation entirely (e.g. not searching). Resets any in-flight
-	 *  phase back to idle. */
-	enabled: boolean;
-	/** Identifies the active predicate; escalation resets to idle whenever this
-	 *  changes (a different search is a different question). */
-	predicateKey: string;
-	searchQuery: EscalationSearchQuery;
-	/**
-	 * States how a run ended, for a user who is no longer looking at any screen
-	 * that could show it. Handed to the run's owner rather than called here, so
-	 * an ending that lands after this hook unmounted is still said (#112).
-	 */
-	reportEnding?: BulkRunRequest["reportEnding"];
-}
-
-export interface UseEscalatedActionsResult {
-	phase: EscalationPhase;
-	/** Ask the server how many messages the predicate matches, and switch the
-	 *  selection to that predicate once it answers. */
-	escalate: () => void;
-	/**
-	 * Stop whatever this mailbox has running — its count, and the run when the
-	 * run is its own. The request in flight is aborted and nothing further leaves
-	 * (#113); a delete the server has already accepted still applies, so the
-	 * batch on the wire is what a stop is worth. A no-op when nothing is running.
-	 * Cancelling a count here never reaches a run in another mailbox: that run is
-	 * not what this screen is offering to stop, and ending it would be silent.
-	 * The only thing that ends a run in flight: leaving the selection, the
-	 * wizard, the search or the mailbox does not.
-	 */
-	stop: () => void;
-	/**
-	 * Drop an escalated selection back to bounded without confirming anything.
-	 * A run in flight owns the phase and holds it until it ends, so this is a
-	 * no-op then — the selection the user is leaving and the run they started
-	 * from it are two different things.
-	 */
-	clear: () => void;
-	/** True while a chunked run (bounded->100 ids, or the escalated predicate)
-	 *  over this mailbox is in flight, whichever screen started it. */
-	isRunning: boolean;
-	/** The action currently in flight, for status and progress wording. */
-	runningAction: EscalatedAction | undefined;
-	progress: BulkActionProgress | undefined;
-	/**
-	 * Runs `action` in chunks. Pass `targets` for a materialized (bounded)
-	 * selection; omit them to run against the escalated predicate (`phase` must
-	 * be "escalated"). Each target names the account that owns it, so a
-	 * selection spanning accounts is sent as one batch per account rather than
-	 * as one batch the endpoint refuses whole (#872). Resolves once the run ends
-	 * for any reason — cancelled, errored, or complete — with a
-	 * `done`/`failedIds` outcome the caller reads to decide what is still
-	 * outstanding, or with the refusal of a run that never started because
-	 * another one is still going.
-	 *
-	 * The run itself belongs to `BulkRunProvider`, which outlives every screen
-	 * that can show it: the caches, the refusal replay, the failure banner and
-	 * the ending are its, so none of them are lost when the surface that started
-	 * the run goes (#112).
-	 */
-	runAction: (
-		action: EscalatedAction,
-		targets?: readonly BulkActionTarget[],
-		claimEnding?: BulkRunRequest["claimEnding"],
-	) => Promise<BulkRunStart>;
-}
-
-export const useEscalatedActions = ({
-	mailboxId,
-	mailboxLabel,
-	accountId,
-	enabled,
-	predicateKey,
-	searchQuery,
-	reportEnding,
-}: UseEscalatedActionsOptions): UseEscalatedActionsResult => {
-	const [phase, setPhase] = useState<EscalationPhase>({ kind: "idle" });
-	// The count's own signal, which is not the run's: leaving the search ends a
-	// count, and never a run (#112).
-	const countAbortRef = useRef<AbortController | undefined>(undefined);
-	const { run, start, stop: stopRun } = useBulkRun();
-	const { pushError } = useErrorBanners();
-
-	// The live run, when it is this mailbox's. A run is mail leaving one mailbox,
-	// so it reports on that mailbox's list — not on whichever list is on screen.
-	const activeRun = run?.mailboxId === mailboxId ? run : undefined;
-	const isRunning = activeRun !== undefined;
-	// Read by callbacks that must not close over a stale render's answer.
-	const isRunningRef = useRef(false);
-	isRunningRef.current = isRunning;
-
-	// A different search (or leaving search/desktop) makes any in-flight
-	// escalation meaningless — it would otherwise keep counting or offering to
-	// act on a predicate the visible list no longer reflects. The selection goes;
-	// a run already going does not. It pages the predicate it was started
-	// against and reports what it reached, wherever the list moved on to.
-	// biome-ignore lint/correctness/useExhaustiveDependencies: enabled/predicateKey are trigger-only — the reset itself reads neither.
-	useEffect(() => {
-		countAbortRef.current?.abort();
-		setPhase({ kind: "idle" });
-	}, [enabled, predicateKey]);
-
-	const searchQueryRef = useRef(searchQuery);
-	searchQueryRef.current = searchQuery;
-
-	const fetchPagesOf = useCallback(
-		(query: EscalationSearchQuery): FetchIdsPage =>
-			async (continuationToken, signal) => {
-				const { data } = await threadOperationsSearchThreads({
-					path: { mailboxId },
-					query: { ...query, continuationToken, limit: PAGE_SIZE },
-					signal,
-					throwOnError: true,
-				});
-				return {
-					ids: (data.items ?? []).map((item) => item.messageId),
-					continuationToken: data.continuationToken,
-				};
-			},
-		[mailboxId],
-	);
-
-	/**
-	 * How many messages the predicate matches, straight from the server that
-	 * resolves it (#509). One count-only request: `limit` is a page size and has
-	 * no bearing on the answer, so nothing is paged to arrive at it.
-	 */
-	const fetchMatchCount = useCallback(
-		async (signal: AbortSignal): Promise<number> => {
-			const { data } = await threadOperationsSearchThreads({
-				path: { mailboxId },
-				query: { ...searchQueryRef.current, count: true, results: false },
-				signal,
-				throwOnError: true,
-			});
-			if (data.count === undefined) {
-				throw new Error("the search returned no count for the selection");
-			}
-			return data.count;
-		},
-		[mailboxId],
-	);
-
-	const applyBatchFor = useCallback(
-		(action: EscalatedAction): ApplyBatch =>
-			async (ids: string[], signal: AbortSignal) => {
-				if (action.kind === "move") {
-					const { data } = await messageBulkOperationsMoveMessages({
-						body: {
-							messageIds: ids,
-							destinationMailboxId: action.destinationMailboxId,
-						},
-						signal,
-						throwOnError: true,
-					});
-					return data;
-				}
-				if (action.kind === "markRead") {
-					const { data } = await messageBulkOperationsUpdateFlags({
-						body: { messageIds: ids, isRead: true },
-						signal,
-						throwOnError: true,
-					});
-					return data;
-				}
-				const { data } = await messageBulkOperationsDeleteMessages({
-					body: { messageIds: ids },
-					signal,
-					throwOnError: true,
-				});
-				return data;
-			},
-		[],
-	);
-
-	const escalate = useCallback(() => {
-		const controller = new AbortController();
-		countAbortRef.current = controller;
-		setPhase({ kind: "counting" });
-		fetchMatchCount(controller.signal).then(
-			(total) => {
-				if (controller.signal.aborted) {
-					setPhase({ kind: "idle" });
-					return;
-				}
-				setPhase({ kind: "escalated", total });
-			},
-			(error: unknown) => {
-				// A stopped count rejects with its own abort. That is the press the
-				// user made, not a failure to report back to them.
-				if (controller.signal.aborted) {
-					setPhase({ kind: "idle" });
-					return;
-				}
-				pushError(
-					buildMutationErrorBanner(
-						"Couldn't count matching messages",
-						"The count didn't finish.",
-						error,
-					),
-				);
-				setPhase({ kind: "idle" });
-			},
-		);
-	}, [fetchMatchCount, pushError]);
-
-	const stop = useCallback(() => {
-		countAbortRef.current?.abort();
-		if (isRunningRef.current) stopRun(mailboxId);
-	}, [stopRun, mailboxId]);
-
-	const clear = useCallback(() => {
-		if (isRunningRef.current) return;
-		countAbortRef.current?.abort();
-		setPhase({ kind: "idle" });
-	}, []);
-
-	const runAction = useCallback(
-		async (
-			action: EscalatedAction,
-			targets?: readonly BulkActionTarget[],
-			claimEnding?: BulkRunRequest["claimEnding"],
-		): Promise<BulkRunStart> => {
-			// Read before the run clears the phase below, so a refusal can say how
-			// many messages the appointment's replay is about.
-			const matched =
-				targets?.length ?? (phase.kind === "escalated" ? phase.total : 0);
-			// The predicate as it read when the run was confirmed. The run outlives
-			// the screen that started it, so reading the live query on every page
-			// would let a search typed afterwards redirect what is being deleted.
-			const source: BulkRunSource =
-				targets !== undefined
-					? { kind: "targets", targets }
-					: {
-							kind: "predicate",
-							fetchPage: fetchPagesOf(searchQueryRef.current),
-						};
-
-			const started = await start({
-				action,
-				mailboxId,
-				mailboxLabel,
-				accountId,
-				matched,
-				source,
-				applyBatch: applyBatchFor(action),
-				reportEnding,
-				claimEnding,
-			});
-
-			// The escalated selection was what the run was confirmed from, and the
-			// run has now happened to it. A refused commit leaves it standing: the
-			// selection is still the question, and stopping the other run is what
-			// makes it answerable.
-			if (started.kind === "ran") setPhase({ kind: "idle" });
-			return started;
-		},
-		[
-			applyBatchFor,
-			fetchPagesOf,
-			phase,
-			mailboxId,
-			mailboxLabel,
-			accountId,
-			reportEnding,
-			start,
-		],
-	);
-
-	return {
-		phase,
-		escalate,
-		stop,
-		clear,
-		isRunning,
-		runningAction: activeRun?.action,
-		progress: activeRun?.progress,
-		runAction,
-	};
-};

package/src/hooks/useFilters.test.ts

@@ -1,106 +0,0 @@
-/**
- * useFilters — the settings-page filter list read and the create/delete
- * invalidation contract.
- *
- * `useFilterList` is exercised the same way `useRescueCandidates` is: a
- * QueryClient is pre-seeded under the key the hook generates and the hook is
- * rendered synchronously via renderToString, so the queryFn never fires and
- * mapping drift breaks the assertions.
- *
- * Create and delete both invalidate `buildFilterListKey` on success; a drift
- * between that key and the one the list subscribes to would leave the settings
- * list stale after a filter is created or deleted, so the contract is pinned
- * directly against the generated SDK key (the pattern `buildMailboxListKey`
- * uses for trigger-sync).
- */
-import assert from "node:assert/strict";
-import { describe, test } from "node:test";
-import { filterOperationsListFiltersQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { createElement } from "react";
-import { renderToString } from "react-dom/server";
-import { buildFilterListKey, useFilterList } from "./useFilters.js";
-
-const ACCOUNT_ID = "acc-1";
-
-const filter = (
-	overrides: Partial<RemitImapFilterResponse> & { filterId: string },
-): RemitImapFilterResponse =>
-	({
-		accountConfigId: "cfg-1",
-		name: "Travel",
-		scope: "Standing",
-		state: "Active",
-		ruleChangedAt: 0,
-		actionChangedAt: 0,
-		matchOperator: "And",
-		literalClauses: [],
-		actionLabelId: "None",
-		actionMailboxId: "None",
-		createdAt: 0,
-		updatedAt: 0,
-		...overrides,
-	}) as RemitImapFilterResponse;
-
-function renderFilterList(
-	accountId: string | undefined,
-	seed?: RemitImapFilterResponse[],
-): ReturnType<typeof useFilterList> {
-	const client = new QueryClient({
-		defaultOptions: { queries: { retry: false } },
-	});
-	if (accountId && seed) {
-		client.setQueryData(buildFilterListKey(accountId), { items: seed });
-	}
-
-	let captured = {} as ReturnType<typeof useFilterList>;
-	function Capture() {
-		captured = useFilterList(accountId);
-		return null;
-	}
-
-	renderToString(
-		createElement(
-			QueryClientProvider,
-			{ client },
-			createElement(Capture),
-		) as never,
-	);
-
-	return captured;
-}
-
-describe("buildFilterListKey", () => {
-	test("matches the generated SDK key create/delete invalidate", () => {
-		assert.deepEqual(
-			buildFilterListKey(ACCOUNT_ID),
-			filterOperationsListFiltersQueryKey({ path: { accountId: ACCOUNT_ID } }),
-		);
-	});
-});
-
-describe("useFilterList", () => {
-	test("returns the account's filters from the cache", () => {
-		const { filters } = renderFilterList(ACCOUNT_ID, [
-			filter({ filterId: "f1", name: "Travel" }),
-			filter({ filterId: "f2", name: "Receipts", scope: "Temporary" }),
-		]);
-		assert.deepEqual(
-			filters.map((f) => f.name),
-			["Travel", "Receipts"],
-		);
-	});
-
-	test("returns an empty list, not undefined, before any data lands", () => {
-		const { filters } = renderFilterList(ACCOUNT_ID);
-		assert.deepEqual(filters, []);
-	});
-
-	test("stays empty and disabled when no account is selected", () => {
-		const { filters, isPending } = renderFilterList(undefined);
-		assert.deepEqual(filters, []);
-		// `enabled: false` keeps the query from fetching for an absent account.
-		assert.equal(isPending, true);
-	});
-});

package/src/hooks/useFilters.ts

@@ -1,188 +0,0 @@
-import {
-	filterDetailOperationsDeleteFilterMutation,
-	filterDetailOperationsUpdateFilterMutation,
-	filterOperationsCreateFilterMutation,
-	filterOperationsListFiltersOptions,
-	filterOperationsListFiltersQueryKey,
-} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import type { RemitImapCreateFilterResponse } from "@remit/api-http-client/types.gen.ts";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
-import {
-	buildCreateFilterInput,
-	type OrganizeDraft,
-	type OrganizeScope,
-} from "@/lib/organize/organize-model";
-
-/**
- * The query key the filter list reads and both mutations invalidate on success.
- * Extracted so create/delete invalidate exactly the key `useFilterList`
- * subscribes to — a drift here would leave the settings list stale after a
- * filter is created or deleted (the same contract `buildMailboxListKey` pins
- * for trigger-sync).
- */
-export const buildFilterListKey = (accountId: string) =>
-	filterOperationsListFiltersQueryKey({ path: { accountId } });
-
-/**
- * List the account's standing filters (Standing + Temporary). Expired
- * Temporary filters stay in the list — they are shown distinctly, never hidden
- * (RFC 034 Decision 1.2).
- */
-export const useFilterList = (accountId: string | undefined) => {
-	const query = useQuery({
-		...filterOperationsListFiltersOptions({
-			path: { accountId: accountId ?? "" },
-		}),
-		enabled: !!accountId,
-	});
-
-	return {
-		filters: query.data?.items ?? [],
-		isPending: query.isPending,
-		isError: query.isError,
-		error: query.error,
-		refetch: query.refetch,
-	};
-};
-
-/**
- * Create the standing (`"these and new mail like this"`) or temporary
- * (`"until <date>"`) filter for an organize draft. The two one-time scopes
- * never create a filter (RFC 034 recap) and are not handled here.
- */
-export const useCreateFilter = (accountId: string | undefined) => {
-	const queryClient = useQueryClient();
-	const mutation = useMutation({
-		...filterOperationsCreateFilterMutation(),
-		onSuccess: () => {
-			if (!accountId) return;
-			queryClient.invalidateQueries({
-				queryKey: buildFilterListKey(accountId),
-			});
-		},
-	});
-	const { mutate, mutateAsync } = mutation;
-
-	const createFilter = useCallback(
-		(
-			draft: OrganizeDraft,
-			scope: Extract<OrganizeScope, "standing" | "temporary">,
-			name: string,
-		) => {
-			if (!accountId) return;
-			mutate({
-				path: { accountId },
-				body: buildCreateFilterInput(draft, scope, name),
-			});
-		},
-		[accountId, mutate],
-	);
-
-	/**
-	 * The same create, resolved once the server has the filter, for work that has
-	 * to follow it — the pass over the mail already in the mailbox. Chaining that
-	 * to the request rather than to the surface is what keeps it running when the
-	 * surface is closed while the create is still in flight.
-	 *
-	 * `undefined` means the create did not land. The failure itself is on
-	 * `isError`, which is what the surface reports and retries from, so it is not
-	 * raised a second time here.
-	 */
-	const createFilterAsync = useCallback(
-		async (
-			draft: OrganizeDraft,
-			scope: Extract<OrganizeScope, "standing" | "temporary">,
-			name: string,
-		): Promise<RemitImapCreateFilterResponse | undefined> => {
-			if (!accountId) return undefined;
-			return mutateAsync({
-				path: { accountId },
-				body: buildCreateFilterInput(draft, scope, name),
-			}).then(
-				(created) => created,
-				() => undefined,
-			);
-		},
-		[accountId, mutateAsync],
-	);
-
-	return {
-		createFilter,
-		createFilterAsync,
-		data: mutation.data,
-		isPending: mutation.isPending,
-		isSuccess: mutation.isSuccess,
-		isError: mutation.isError,
-		error: mutation.error,
-		reset: mutation.reset,
-	};
-};
-
-export const useDeleteFilter = (accountId: string | undefined) => {
-	const queryClient = useQueryClient();
-	const mutation = useMutation({
-		...filterDetailOperationsDeleteFilterMutation(),
-		onSuccess: () => {
-			if (!accountId) return;
-			queryClient.invalidateQueries({
-				queryKey: buildFilterListKey(accountId),
-			});
-		},
-	});
-	const { mutate } = mutation;
-
-	const deleteFilter = useCallback(
-		(filterId: string) => {
-			if (!accountId) return;
-			mutate({ path: { accountId, filterId } });
-		},
-		[accountId, mutate],
-	);
-
-	return {
-		deleteFilter,
-		isPending: mutation.isPending,
-		deletingFilterId: mutation.isPending
-			? mutation.variables?.path.filterId
-			: undefined,
-	};
-};
-
-export const useToggleFilter = (accountId: string | undefined) => {
-	const queryClient = useQueryClient();
-	const mutation = useMutation({
-		...filterDetailOperationsUpdateFilterMutation(),
-		onSuccess: () => {
-			if (!accountId) return;
-			queryClient.invalidateQueries({
-				queryKey: buildFilterListKey(accountId),
-			});
-		},
-	});
-	const { mutate, variables } = mutation;
-
-	const toggleFilter = useCallback(
-		(filterId: string, enabled: boolean) => {
-			if (!accountId) return;
-			mutate({
-				path: { accountId, filterId },
-				body: { state: enabled ? "Active" : "Disabled" },
-			});
-		},
-		[accountId, mutate],
-	);
-
-	const retry = useCallback(() => {
-		if (variables) mutate(variables);
-	}, [mutate, variables]);
-
-	return {
-		toggleFilter,
-		retry,
-		togglingFilterId: mutation.isPending ? variables?.path.filterId : undefined,
-		isError: mutation.isError,
-		error: mutation.error,
-		enabling: variables?.body?.state === "Active",
-	};
-};

package/src/hooks/useFolderLabelTranslator.ts

@@ -1,19 +0,0 @@
-import { useCallback } from "react";
-import { useTranslation } from "react-i18next";
-
-/**
- * `labelForMailbox` expects a positional `(key, fallback)` translator; i18next's
- * `t` reads its second argument as an options object, which drops the fallback.
- * Memoized so callers can hold it as a `useMemo` dependency.
- */
-export const useFolderLabelTranslator = (): ((
-	key: string,
-	fallback: string,
-) => string) => {
-	const { t } = useTranslation("mail", { useSuspense: false });
-	return useCallback(
-		(key: string, fallback: string): string =>
-			t(key, { defaultValue: fallback }),
-		[t],
-	);
-};