@remit/web-client 0.0.325 → 0.0.326

package/dist/src/hooks/useRefreshControl.js

@@ -0,0 +1,234 @@
+import { mailboxOperationsListMailboxesQueryKey, syncOperationsGetSyncStatusOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { syncOperationsTriggerSync } from "@remit/api-http-client/sdk.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { shouldEscalate } from "../lib/error-classifier";
+import { reportFatalError } from "../lib/fatal-error";
+import { startHotSyncWindow } from "../lib/hot-sync-window";
+import { useMailFreshness } from "../lib/mail-freshness";
+import { useTelemetry } from "../lib/telemetry-context";
+import { isSyncingPhase } from "./useInitialSyncProgress";
+/** How often the wait polls an account's own sync status once a round is
+ * enqueued — fast enough to feel responsive, far below the once-a-minute
+ * background cadence, and bounded by {@link REFRESH_TIMEOUT_MS} either way. */
+export const REFRESH_POLL_MS = 2000;
+/** A refresh that gets no answer must terminate in a stated failure rather
+ * than spin forever — this is that bound. */
+export const REFRESH_TIMEOUT_MS = 45_000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const messageFor = (error) => error instanceof Error && error.message
+    ? error.message
+    : "Something went wrong";
+// The user pulled to refresh and is watching the spinner, so this is theirs to
+// be answered: a 401 here escalates over the soft meta rather than resolving
+// into a spinner that stops for no stated reason.
+const escalateIfFatal = (error) => {
+    if (shouldEscalate(error, { softError: true }, "user")) {
+        reportFatalError(error);
+    }
+};
+/**
+ * `getSyncStatus` for one account, always as a real network read: `staleTime:
+ * 0` means even a reading `MailFreshnessProvider` fetched a moment ago is
+ * treated as stale. Sharing the query key means every fetch here also lands
+ * in the same cache `MailFreshnessProvider` reads, so acknowledging a refresh
+ * (see `useMailFreshness().acknowledge`) re-baselines from data this wait
+ * itself just fetched — never a round-old cached reading.
+ *
+ * Routed through `queryClient.fetchQuery` rather than the raw SDK call, so a
+ * failure here already reaches the global `QueryCache` error sink
+ * (`main.tsx` wires `handleQueryCacheError`) on the same terms as every other
+ * query — a manual `escalateIfFatal` on top would double-report the same
+ * error. `syncOperationsTriggerSync` below is the one call in this file that
+ * genuinely needs it: it's a raw SDK call outside React Query, so nothing
+ * else escalates it.
+ */
+const fetchStatus = (queryClient, accountId) => queryClient.fetchQuery({
+    ...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
+    staleTime: 0,
+});
+/**
+ * The account's INBOX stamp, or 0 when the account has no INBOX or has never
+ * synced one. `getSyncStatus` reports `lastSyncedAt` per mailbox, which is what
+ * lets the wait answer "the inbox is current" ahead of "the round is done".
+ */
+export const inboxSyncedAt = (reading) => reading.mailboxes?.find((mailbox) => mailbox.fullPath?.toUpperCase() === "INBOX")?.lastSyncedAt ?? 0;
+/**
+ * Poll one account's sync status until a round that started at or after this
+ * refresh triggered has settled, or `deadline` passes.
+ *
+ * `account.lastSyncAt` is the worker's own once-per-round stamp, and it is the
+ * only thing here that tells one round from another. A phase seen mid-flight
+ * does not: the tab's background poll, another tab, and every `GET /config`
+ * trigger rounds nobody clicked for, so a click landing while one of those is
+ * in flight used to confirm on it — a checkmark and an invalidated list with
+ * the clicked round still unrun, and the new mail it would have fetched unseen
+ * until the next poll (#953). Requiring the stamp to pass the reading taken
+ * before the trigger admits only a round that started after it.
+ *
+ * `POST /sync` enqueues and returns, so the first reading after triggering
+ * still shows the previous round — including a previous round's `error` phase,
+ * which is why that phase only speaks once the stamp has moved.
+ *
+ * A round is the whole account — every folder, in queue order — but the mail
+ * a person pressed refresh for is in their inbox. `onInboxSynced` fires the
+ * moment that one mailbox's own stamp passes the baseline, so the list on
+ * screen reloads then rather than after Junk and Trash have also gone by. The
+ * round-level stamp still decides the button's confirmed state.
+ *
+ * Read-only (`getSyncStatus`, no IMAP call, no queue write), so waiting costs
+ * a handful of cheap GETs — never a refetch of the account's own message
+ * list.
+ */
+export const waitForSettled = async ({ accountId, readStatus, baselineLastSyncAt, baselineInboxSyncedAt = 0, onInboxSynced, deadline, pollMs = REFRESH_POLL_MS, }) => {
+    let inboxAnnounced = false;
+    for (;;) {
+        const outcome = await readStatus()
+            .then((data) => ({ ok: true, data }))
+            .catch((error) => ({ ok: false, error }));
+        if (!outcome.ok) {
+            return { accountId, message: messageFor(outcome.error) };
+        }
+        const { syncPhase, lastSyncAt } = outcome.data;
+        const startedAfterTrigger = (lastSyncAt ?? 0) > baselineLastSyncAt;
+        if (startedAfterTrigger && !isSyncingPhase(syncPhase)) {
+            if (syncPhase === "error") {
+                return { accountId, message: "Sync failed for this account" };
+            }
+            return undefined;
+        }
+        if (!inboxAnnounced &&
+            inboxSyncedAt(outcome.data) > baselineInboxSyncedAt) {
+            inboxAnnounced = true;
+            onInboxSynced?.();
+        }
+        if (Date.now() >= deadline) {
+            return { accountId, message: "Refresh is taking longer than usual" };
+        }
+        await sleep(pollMs);
+    }
+};
+const refreshOneAccount = async (queryClient, telemetry, accountId, deadline, onInboxSynced) => {
+    const baseline = await fetchStatus(queryClient, accountId)
+        .then((data) => ({
+        ok: true,
+        lastSyncAt: data.lastSyncAt ?? 0,
+        inboxSyncedAt: inboxSyncedAt(data),
+    }))
+        .catch((error) => ({ ok: false, error }));
+    if (!baseline.ok) {
+        return {
+            accountId,
+            enqueued: false,
+            ok: false,
+            message: messageFor(baseline.error),
+        };
+    }
+    const triggered = await syncOperationsTriggerSync({
+        path: { accountId },
+        throwOnError: true,
+    })
+        .then(() => ({ ok: true }))
+        .catch((error) => ({ ok: false, error }));
+    if (!triggered.ok) {
+        escalateIfFatal(triggered.error);
+        return {
+            accountId,
+            enqueued: false,
+            ok: false,
+            message: messageFor(triggered.error),
+        };
+    }
+    telemetry.recordEvent("sync.triggered");
+    const settled = await waitForSettled({
+        accountId,
+        readStatus: () => fetchStatus(queryClient, accountId),
+        baselineLastSyncAt: baseline.lastSyncAt,
+        baselineInboxSyncedAt: baseline.inboxSyncedAt,
+        onInboxSynced: () => onInboxSynced(accountId),
+        deadline,
+    });
+    if (settled)
+        return { accountId, enqueued: true, ok: false, message: settled.message };
+    return { accountId, enqueued: true, ok: true };
+};
+/**
+ * Drives the shared `RefreshButton` for one or more accounts: triggers a sync
+ * for each, waits for the server's own sync-status to settle — not just the
+ * enqueue ack — then invalidates the queries the caller names. A manual
+ * refresh is an explicit user action, so unlike the background poll it always
+ * shows the result; what it must never do is leave the button spinning with
+ * no answer.
+ */
+export const useRefreshControl = (accountIds, options = {}) => {
+    const queryClient = useQueryClient();
+    const telemetry = useTelemetry();
+    const { acknowledge } = useMailFreshness();
+    const [state, setState] = useState("idle");
+    const [errorMessage, setErrorMessage] = useState();
+    const runIdRef = useRef(0);
+    const accountIdsRef = useRef(accountIds);
+    accountIdsRef.current = accountIds;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    // A success confirmation is a beat, not a permanent state — it hands the
+    // button back to idle on its own so a stale checkmark never lingers.
+    useEffect(() => {
+        if (state !== "success")
+            return;
+        const timer = setTimeout(() => setState("idle"), 2000);
+        return () => clearTimeout(timer);
+    }, [state]);
+    const refresh = useCallback(() => {
+        const ids = accountIdsRef.current;
+        if (ids.length === 0) {
+            // Reachable before the owning account resolves (a fresh mailbox
+            // route) or when every account is muted (the brief) — a click here
+            // must say why it did nothing, never sit as a dead button.
+            setState("error");
+            setErrorMessage("Nothing to refresh yet");
+            return;
+        }
+        const runId = ++runIdRef.current;
+        setState("refreshing");
+        setErrorMessage(undefined);
+        startHotSyncWindow();
+        // The account's own lists, reloaded. Called once as soon as that
+        // account's INBOX is current and again when its round confirms: the
+        // first is what puts the new mail on screen without waiting for Junk
+        // and Trash, the second is the settled state.
+        const showAccount = (accountId) => {
+            if (runIdRef.current !== runId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: mailboxOperationsListMailboxesQueryKey({
+                    path: { accountId },
+                }),
+            });
+            optionsRef.current.onSettled?.();
+        };
+        void (async () => {
+            const deadline = Date.now() + REFRESH_TIMEOUT_MS;
+            const results = await Promise.all(ids.map((accountId) => refreshOneAccount(queryClient, telemetry, accountId, deadline, showAccount)));
+            if (runIdRef.current !== runId)
+                return;
+            const enqueued = results
+                .filter((result) => result.enqueued)
+                .map((result) => result.accountId);
+            for (const accountId of enqueued)
+                showAccount(accountId);
+            if (enqueued.length > 0) {
+                acknowledge(enqueued);
+            }
+            const failures = results.filter((result) => !result.ok);
+            if (failures.length === 0) {
+                setState("success");
+            }
+            else {
+                setState("error");
+                setErrorMessage(failures[0]?.message);
+            }
+        })();
+    }, [acknowledge, queryClient, telemetry]);
+    return { state, errorMessage, refresh };
+};

package/dist/src/hooks/useReportSpam.d.ts

@@ -0,0 +1,102 @@
+import type { RemitImapSpamReportBulkResult } from "@remit/api-http-client/types.gen.ts";
+interface UseReportSpamOptions {
+    /** The mailbox the message currently sits in — scopes which list caches settle-time invalidation reaches. */
+    mailboxId: string;
+    threadId?: string;
+    accountId?: string;
+    /**
+     * Called once a report or undo succeeds, with the message ids it acted on
+     * — the same shape as `useMoveMessages`/`useDeleteMessages`'s option of the
+     * same name, so a host wires the identical `handleDeselectIfRemoved` it
+     * already has. Fires on SUCCESS here, not optimistically like those two:
+     * neither endpoint tells the client whether the message actually left
+     * `mailboxId` (reporting or undoing a message already in Junk is a real
+     * no-op-move, and the client has no way to predict it — see
+     * `throwOnBulkFailure`'s neighbour below), so this fires for every success,
+     * no-op included — a no-op report/undo still deselects even though the row
+     * never actually left the list the host is watching. That trades an
+     * occasional unnecessary pane-close for never leaving a reported message
+     * rendering a pre-report snapshot forever, which is the bug this exists to
+     * fix (issue #648 review).
+     */
+    onAfterOptimisticRemove?: (messageIds: string[]) => void;
+}
+/**
+ * The one designed, allowlisted reason returned by the server as-is (e.g.
+ * `notSpam`'s move-not-settled-yet message) is safe to show verbatim; an
+ * unexpected failure is already flattened server-side to this same generic
+ * text (`GENERIC_FAILURE_REASON` in `packages/backend/src/handlers/message.ts`)
+ * before it reaches the client. Used only as a fallback for the case neither
+ * hits: a `failures` entry missing its `reason`, or no `failures` array at all
+ * despite a non-zero `failureCount`.
+ */
+export declare const GENERIC_SPAM_ACTION_FAILURE = "This message could not be processed. Please try again. If it keeps failing, report it.";
+/**
+ * The server's designed failure text names the message by putting its raw
+ * id as a possessive subject — e.g. "Message 4kv0xxyfhg4dhzqvxd105v840's move
+ * to Junk has not settled yet; try again in a moment." (message ids here are
+ * 25-char base36, `translator.generate()` in `packages/data-ports/src/id.ts`
+ * — not a dashed UUID). Accurate, but not something to put in front of a
+ * person. `messageId` is the exact id the failure names — `SpamReportFailure`
+ * pairs it with `reason` for precisely this — so this strips that literal
+ * substring rather than pattern-matching an id shape that could change under
+ * it. Not a parse of the reason's meaning (the field is documented "not
+ * intended to be parsed programmatically"): removing a known, opaque
+ * identifier from where it renders reads nothing into what the sentence says.
+ */
+export declare const humanizeSpamFailureReason: (reason: string, messageId: string) => string;
+/**
+ * `settleSpamReportBulk` (backend) runs the batch with `Promise.allSettled`
+ * and always answers 200, folding per-message outcomes into
+ * `successCount`/`failureCount`/`failures` rather than rejecting the HTTP
+ * call — a partial (or total) failure is not a thrown error on the wire. The
+ * generated mutation helpers only ever reject on a non-2xx response, so
+ * without this the hook would report success for a message whose report or
+ * undo never actually happened. Every caller here sends exactly one message
+ * per call, so surfacing the first failure's reason is surfacing the whole
+ * story, not truncating a real batch.
+ *
+ * Throws `ApiError` — not a bare `Error` — carrying a 4xx status. The
+ * client's fail-fast contract (`lib/error-classifier.ts`'s `shouldEscalate`,
+ * wired globally on the `MutationCache` in `lib/query-error-handler.ts`)
+ * escalates anything that isn't a 5xx by default UNLESS the call site opts
+ * out via `meta.softError` — a statusless `Error` escalates too, as a client
+ * bug. Either way, without both the status AND `meta.softError` (set on the
+ * `useMutation` calls below) this would crash to the full-screen fatal
+ * overlay for a designed, expected, retryable outcome the backend wrote
+ * user-facing copy for. Every other call site in this app forwards a
+ * status-carrying error the generated client already threw and never needs
+ * the opt-out because none of them are a routine, expected-failure signal
+ * like this one; this is the one place synthesizing a failure from a 200
+ * body, so it has to synthesize both.
+ */
+export declare const throwOnBulkFailure: (data: RemitImapSpamReportBulkResult) => void;
+/**
+ * Composes `POST /messages/report-spam` and `POST /messages/not-spam`
+ * (issue #648). Both fold the sender-flag write, the Junk move and the
+ * `$Junk` keyword marker into one server-side operation
+ * (`SpamReportService`) — the client only sends `messageIds` and reflects the
+ * result, it does not sequence the three writes itself, and it never derives
+ * "reported" from placement (a report on a message already in Junk — the
+ * provider's own filter put it there — is a real, no-op-move case).
+ *
+ * No optimistic cache patch, unlike `useMoveMessages`/`useDeleteMessages`:
+ * neither endpoint's response says whether the message actually changed
+ * mailboxes (a report or undo against a message already in Junk is a real,
+ * silent no-op), so predicting the row should vanish would flicker it back
+ * on invalidation for a no-op — worst on `notSpam`, whose R2 wait can run
+ * several seconds before the row "pops back". The list settles from
+ * `onSuccess`'s invalidation instead, which is always correct. `isReporting`/
+ * `isRestoring` below exist to pay for the UX this trades away: without them
+ * a press produces no visible change at all until the request lands — the
+ * caller wires them into the quick action's pending state.
+ */
+export declare function useReportSpam({ mailboxId, threadId, accountId, onAfterOptimisticRemove, }: UseReportSpamOptions): {
+    reportSpam: (messageIds: string[]) => void;
+    notSpam: (messageIds: string[]) => void;
+    /** True while a report is in flight — wire into the "Report spam" quick action's pending state; a press with no visible response is the dead-button failure mode. */
+    isReporting: boolean;
+    /** True while an undo is in flight — wire into the "Not spam" quick action's pending state. */
+    isRestoring: boolean;
+};
+export {};

package/dist/src/hooks/useReportSpam.js

@@ -0,0 +1,173 @@
+import { mailboxOperationsListMailboxesQueryKey, threadDetailOperationsListThreadMessagesQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { messageBulkOperationsNotSpam, messageBulkOperationsReportSpam, } from "@remit/api-http-client/sdk.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 { ApiError } from "../lib/api";
+import { runChunkedMutation } from "../lib/bulk-actions";
+import { invalidateThreadListQueries, threadListCacheKeys, } from "../lib/thread-list-cache";
+/**
+ * The one designed, allowlisted reason returned by the server as-is (e.g.
+ * `notSpam`'s move-not-settled-yet message) is safe to show verbatim; an
+ * unexpected failure is already flattened server-side to this same generic
+ * text (`GENERIC_FAILURE_REASON` in `packages/backend/src/handlers/message.ts`)
+ * before it reaches the client. Used only as a fallback for the case neither
+ * hits: a `failures` entry missing its `reason`, or no `failures` array at all
+ * despite a non-zero `failureCount`.
+ */
+export const GENERIC_SPAM_ACTION_FAILURE = "This message could not be processed. Please try again. If it keeps failing, report it.";
+/**
+ * The server's designed failure text names the message by putting its raw
+ * id as a possessive subject — e.g. "Message 4kv0xxyfhg4dhzqvxd105v840's move
+ * to Junk has not settled yet; try again in a moment." (message ids here are
+ * 25-char base36, `translator.generate()` in `packages/data-ports/src/id.ts`
+ * — not a dashed UUID). Accurate, but not something to put in front of a
+ * person. `messageId` is the exact id the failure names — `SpamReportFailure`
+ * pairs it with `reason` for precisely this — so this strips that literal
+ * substring rather than pattern-matching an id shape that could change under
+ * it. Not a parse of the reason's meaning (the field is documented "not
+ * intended to be parsed programmatically"): removing a known, opaque
+ * identifier from where it renders reads nothing into what the sentence says.
+ */
+export const humanizeSpamFailureReason = (reason, messageId) => reason.replace(`Message ${messageId}'s`, "This message's");
+/**
+ * `settleSpamReportBulk` (backend) runs the batch with `Promise.allSettled`
+ * and always answers 200, folding per-message outcomes into
+ * `successCount`/`failureCount`/`failures` rather than rejecting the HTTP
+ * call — a partial (or total) failure is not a thrown error on the wire. The
+ * generated mutation helpers only ever reject on a non-2xx response, so
+ * without this the hook would report success for a message whose report or
+ * undo never actually happened. Every caller here sends exactly one message
+ * per call, so surfacing the first failure's reason is surfacing the whole
+ * story, not truncating a real batch.
+ *
+ * Throws `ApiError` — not a bare `Error` — carrying a 4xx status. The
+ * client's fail-fast contract (`lib/error-classifier.ts`'s `shouldEscalate`,
+ * wired globally on the `MutationCache` in `lib/query-error-handler.ts`)
+ * escalates anything that isn't a 5xx by default UNLESS the call site opts
+ * out via `meta.softError` — a statusless `Error` escalates too, as a client
+ * bug. Either way, without both the status AND `meta.softError` (set on the
+ * `useMutation` calls below) this would crash to the full-screen fatal
+ * overlay for a designed, expected, retryable outcome the backend wrote
+ * user-facing copy for. Every other call site in this app forwards a
+ * status-carrying error the generated client already threw and never needs
+ * the opt-out because none of them are a routine, expected-failure signal
+ * like this one; this is the one place synthesizing a failure from a 200
+ * body, so it has to synthesize both.
+ */
+export const throwOnBulkFailure = (data) => {
+    if (data.failureCount === 0)
+        return;
+    const failure = data.failures?.[0];
+    const reason = failure?.reason ?? GENERIC_SPAM_ACTION_FAILURE;
+    const message = failure
+        ? humanizeSpamFailureReason(reason, failure.messageId)
+        : reason;
+    throw new ApiError(message, 422);
+};
+/**
+ * Composes `POST /messages/report-spam` and `POST /messages/not-spam`
+ * (issue #648). Both fold the sender-flag write, the Junk move and the
+ * `$Junk` keyword marker into one server-side operation
+ * (`SpamReportService`) — the client only sends `messageIds` and reflects the
+ * result, it does not sequence the three writes itself, and it never derives
+ * "reported" from placement (a report on a message already in Junk — the
+ * provider's own filter put it there — is a real, no-op-move case).
+ *
+ * No optimistic cache patch, unlike `useMoveMessages`/`useDeleteMessages`:
+ * neither endpoint's response says whether the message actually changed
+ * mailboxes (a report or undo against a message already in Junk is a real,
+ * silent no-op), so predicting the row should vanish would flicker it back
+ * on invalidation for a no-op — worst on `notSpam`, whose R2 wait can run
+ * several seconds before the row "pops back". The list settles from
+ * `onSuccess`'s invalidation instead, which is always correct. `isReporting`/
+ * `isRestoring` below exist to pay for the UX this trades away: without them
+ * a press produces no visible change at all until the request lands — the
+ * caller wires them into the quick action's pending state.
+ */
+export function useReportSpam({ mailboxId, threadId, accountId, onAfterOptimisticRemove, }) {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const listPrefixes = threadListCacheKeys([mailboxId]);
+    const threadMessagesPrefix = threadId
+        ? threadDetailOperationsListThreadMessagesQueryKey({ path: { threadId } })
+        : [];
+    const invalidateAffectedQueries = () => {
+        if (threadId) {
+            queryClient.invalidateQueries({ queryKey: threadMessagesPrefix });
+        }
+        invalidateThreadListQueries(queryClient, listPrefixes);
+        if (accountId) {
+            queryClient.invalidateQueries({
+                queryKey: mailboxOperationsListMailboxesQueryKey({
+                    path: { accountId },
+                }),
+            });
+        }
+    };
+    const buildOnSuccess = () => (_data, variables) => {
+        invalidateAffectedQueries();
+        onAfterOptimisticRemove?.(variables.body.messageIds);
+    };
+    const buildOnError = (failureTitle) => (err, vars) => {
+        pushError({
+            title: failureTitle(vars.body.messageIds.length),
+            detail: formatErrorDetail(err),
+            error: err,
+        });
+    };
+    const report = useMutation({
+        mutationFn: async (variables) => {
+            const { data } = await messageBulkOperationsReportSpam({
+                ...variables,
+                throwOnError: true,
+            });
+            throwOnBulkFailure(data);
+            return data;
+        },
+        // A per-message report failure is a routine, expected, retryable outcome
+        // with backend-written user-facing copy — never the fatal overlay. See
+        // `throwOnBulkFailure`'s doc for why the thrown ApiError's status alone
+        // isn't enough: `shouldEscalate` defaults to escalate for a non-5xx that
+        // doesn't opt out here.
+        meta: { softError: true },
+        onSuccess: buildOnSuccess(),
+        onError: buildOnError((count) => count > 1
+            ? `Couldn't report ${count} messages as spam`
+            : "Couldn't report this message as spam"),
+    });
+    const restore = useMutation({
+        mutationFn: async (variables) => {
+            const { data } = await messageBulkOperationsNotSpam({
+                ...variables,
+                throwOnError: true,
+            });
+            throwOnBulkFailure(data);
+            return data;
+        },
+        meta: { softError: true },
+        onSuccess: buildOnSuccess(),
+        onError: buildOnError((count) => count > 1
+            ? `Couldn't undo the spam report for ${count} messages`
+            : "Couldn't undo the spam report"),
+    });
+    const reportSpam = useCallback((messageIds) => {
+        if (messageIds.length === 0)
+            return;
+        void runChunkedMutation(messageIds, (chunk) => report.mutateAsync({ body: { messageIds: chunk } }));
+    }, [report.mutateAsync]);
+    const notSpam = useCallback((messageIds) => {
+        if (messageIds.length === 0)
+            return;
+        void runChunkedMutation(messageIds, (chunk) => restore.mutateAsync({ body: { messageIds: chunk } }));
+    }, [restore.mutateAsync]);
+    return {
+        reportSpam,
+        notSpam,
+        /** True while a report is in flight — wire into the "Report spam" quick action's pending state; a press with no visible response is the dead-button failure mode. */
+        isReporting: report.isPending,
+        /** True while an undo is in flight — wire into the "Not spam" quick action's pending state. */
+        isRestoring: restore.isPending,
+    };
+}

package/dist/src/hooks/useRescueCandidates.d.ts

@@ -0,0 +1,15 @@
+import type { RescueCandidate } from "@remit/ui";
+/**
+ * Fetch rescue candidates from the backend for the given Junk mailbox.
+ *
+ * Filters by senderTrust=[vip,wellknown] and dkimMismatch=false. The
+ * dkimMismatch=false filter excludes senders with no authenticity signal
+ * (undefined), not just confirmed mismatches — this is intentional: it closes
+ * the impersonation path where a spoofed trusted-sender From with no DKIM
+ * would otherwise surface as a rescue candidate.
+ *
+ * Only fires when junkMailboxId is provided.
+ */
+export declare function useRescueCandidates(junkMailboxId: string | undefined): {
+    candidates: RescueCandidate[];
+};

package/dist/src/hooks/useRescueCandidates.js

@@ -0,0 +1,41 @@
+import { threadOperationsSearchThreadsOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { rescueCandidateReason } from "../lib/rescue-candidates";
+const TRUST_REASON = "We can verify this sender";
+/**
+ * Fetch rescue candidates from the backend for the given Junk mailbox.
+ *
+ * Filters by senderTrust=[vip,wellknown] and dkimMismatch=false. The
+ * dkimMismatch=false filter excludes senders with no authenticity signal
+ * (undefined), not just confirmed mismatches — this is intentional: it closes
+ * the impersonation path where a spoofed trusted-sender From with no DKIM
+ * would otherwise surface as a rescue candidate.
+ *
+ * Only fires when junkMailboxId is provided.
+ */
+export function useRescueCandidates(junkMailboxId) {
+    const { data } = useQuery({
+        ...threadOperationsSearchThreadsOptions({
+            path: { mailboxId: junkMailboxId ?? "" },
+            query: {
+                senderTrust: ["vip", "wellknown"],
+                dkimMismatch: false,
+                results: true,
+                limit: 500,
+            },
+        }),
+        enabled: !!junkMailboxId,
+        staleTime: 60_000,
+    });
+    const candidates = (data?.items ?? []).map((thread) => ({
+        id: thread.messageId,
+        senderName: thread.fromName || thread.fromEmail || "Unknown sender",
+        senderAddress: thread.fromEmail ?? "",
+        subject: thread.subject || "(no subject)",
+        snippet: thread.snippet ?? "",
+        trustReason: TRUST_REASON,
+        trustSubReason: rescueCandidateReason(thread.senderTrust),
+        senderTrust: thread.senderTrust,
+    }));
+    return { candidates };
+}

package/dist/src/hooks/useResultCount.d.ts

@@ -0,0 +1,26 @@
+import type { ThreadOperationsSearchThreadsData } from "@remit/api-http-client/types.gen.ts";
+import type { ResultCount } from "@remit/ui";
+/**
+ * What the list is asking about, with nothing about paging in it. The count is
+ * a property of the criteria alone, so a page fetch can never trigger one.
+ */
+export type ThreadSearchCriteria = Omit<NonNullable<ThreadOperationsSearchThreadsData["query"]>, "continuationToken" | "limit" | "count" | "results">;
+export interface UseResultCountOptions {
+    mailboxId: string;
+    criteria: ThreadSearchCriteria;
+    /**
+     * Whether this search is worth counting at all — see
+     * `shouldRequestResultCount`. Disabled, the surface renders no number rather
+     * than a stale one from the search before it.
+     */
+    enabled: boolean;
+}
+/**
+ * How many messages the search matches, from the server that resolves it —
+ * one request against the criteria, never a walk of the pages (#307).
+ *
+ * Its own query, keyed on the criteria without the cursor, so the list pages
+ * without re-counting. An answer that carries no count — off-row criteria, per
+ * #305 — stays absent rather than becoming a zero.
+ */
+export declare const useResultCount: ({ mailboxId, criteria, enabled, }: UseResultCountOptions) => ResultCount;

package/dist/src/hooks/useResultCount.js

@@ -0,0 +1,40 @@
+import { threadOperationsSearchThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { threadOperationsSearchThreads } from "@remit/api-http-client/sdk.gen.ts";
+import { useQuery } from "@tanstack/react-query";
+import { toResultCount } from "../lib/result-count";
+/** A minute: long enough that returning to a search just left costs nothing. */
+const COUNT_STALE_TIME_MS = 60_000;
+/**
+ * How many messages the search matches, from the server that resolves it —
+ * one request against the criteria, never a walk of the pages (#307).
+ *
+ * Its own query, keyed on the criteria without the cursor, so the list pages
+ * without re-counting. An answer that carries no count — off-row criteria, per
+ * #305 — stays absent rather than becoming a zero.
+ */
+export const useResultCount = ({ mailboxId, criteria, enabled, }) => {
+    const query = { ...criteria, count: true, results: false };
+    const { data } = useQuery({
+        queryKey: threadOperationsSearchThreadsQueryKey({
+            path: { mailboxId },
+            query,
+        }),
+        queryFn: async () => {
+            const { data: response } = await threadOperationsSearchThreads({
+                path: { mailboxId },
+                query,
+                throwOnError: true,
+            });
+            return response;
+        },
+        enabled,
+        staleTime: COUNT_STALE_TIME_MS,
+    });
+    // `enabled` gates the request, not the cache: a criteria set that asks for no
+    // count still reads whatever the last identical key left behind. Two searches
+    // share a key whenever the terms that separate them reach the request as
+    // nothing — `before:`/`after:`/`account:` are stripped from the free text and
+    // carry no param — so a disabled count that read `data` would render the
+    // previous search's total over this one's rows.
+    return enabled ? toResultCount(data?.count) : { kind: "unknown" };
+};

package/dist/src/hooks/useResultFolderIndex.d.ts

@@ -0,0 +1,8 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { type ResultFolderIndex } from "../lib/result-folder";
+export interface ResultFolderIndexState {
+    index: ResultFolderIndex;
+    isPending: boolean;
+    error: unknown;
+}
+export declare function useResultFolderIndex(accounts: RemitImapAccountResponse[]): ResultFolderIndexState;