@remit/web-client 0.0.324 → 0.0.326

package/dist/src/lib/mail-freshness.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { syncOperationsGetSyncStatusOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries, useQueryClient } from "@tanstack/react-query";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { useMailContext } from "./mail-context";
+import { invalidateThreadListQueries, threadListCacheKeys, } from "./thread-list-cache";
+/**
+ * How often the background poll re-reads each open account's sync status.
+ * `getSyncStatus` is a DDB read with no IMAP call and no queue write (see
+ * typespec Sync Operations), so this is the cheap side of the refresh
+ * feature — the once-a-minute check that decides whether anything is worth
+ * surfacing, never a refetch of the mailbox or brief content itself.
+ */
+export const FRESHNESS_POLL_MS = 60_000;
+/**
+ * Roles whose own new messages are the user's doing, not an arrival: sending
+ * appends to Sent, deleting or archiving appends to Trash/Archive, and a Draft
+ * is an autosave. Counting any of these as "new mail" would light the dot on a
+ * message the user just moved themselves. Junk is kept in — spam is still an
+ * arrival, just an unwanted one — and a mailbox with no resolved role (a
+ * custom folder, or one a filter files mail into directly) is never excluded.
+ */
+const EXCLUDED_GROWTH_ROLES = new Set([
+    "sent",
+    "drafts",
+    "trash",
+    "archive",
+]);
+export const highWaterMarksFrom = (mailboxes, resultFolderIndex) => {
+    const marks = new Map();
+    for (const mailbox of mailboxes) {
+        const role = resultFolderIndex.get(mailbox.mailboxId)?.role;
+        if (role && EXCLUDED_GROWTH_ROLES.has(role))
+            continue;
+        marks.set(mailbox.mailboxId, mailbox.highWaterMarkUid);
+    }
+    return marks;
+};
+/**
+ * Which mailboxes took a UID above the highest one in the baseline. Pure so the
+ * "did mail arrive" call is unit-testable without a DOM or a QueryClient. A
+ * mailbox missing from the baseline (new folder, first-ever reading) counts
+ * from zero rather than being skipped, so mail landing in a folder created
+ * since the last look still counts as an arrival.
+ */
+export const grownMailboxIds = (baseline, current) => {
+    const grown = [];
+    for (const [mailboxId, uid] of current) {
+        if (uid > (baseline.get(mailboxId) ?? 0))
+            grown.push(mailboxId);
+    }
+    return grown;
+};
+/** Whether any mailbox took a new message at all — the dot's own question. */
+export const hasGrown = (baseline, current) => grownMailboxIds(baseline, current).length > 0;
+const MailFreshnessContext = createContext(null);
+export const useMailFreshness = () => {
+    const ctx = useContext(MailFreshnessContext);
+    if (!ctx) {
+        throw new Error("useMailFreshness must be used inside <MailFreshnessProvider>");
+    }
+    return ctx;
+};
+/**
+ * Watches every open account's sync status once a minute and flags which
+ * accounts have grown since they were last shown to the user (#582 clause
+ * 4). The flag is sticky until acknowledged: it lights the dot on whichever
+ * `RefreshButton` reads this context and stays lit until a refresh clears it.
+ *
+ * A tick that sees a folder take a new highest UID also invalidates that
+ * folder's thread listing. It reorders nothing and asks the mail server for
+ * nothing — the message is already on our side, so an open list showing it is a
+ * cache read, not IMAP work. The dot is still the account-level signal.
+ */
+export function MailFreshnessProvider({ accountIds, children, }) {
+    const queryClient = useQueryClient();
+    const { resultFolderIndex } = useMailContext();
+    const baselineRef = useRef(new Map());
+    const seededRef = useRef(new Set());
+    // The previous tick's reading, distinct from the dot's baseline: the dot's
+    // baseline is sticky until acknowledged, so comparing against it would
+    // re-invalidate on every tick for as long as the dot stays lit.
+    const previousMarksRef = useRef(new Map());
+    const [newMail, setNewMail] = useState(new Set());
+    const queries = useQueries({
+        queries: accountIds.map((accountId) => ({
+            ...syncOperationsGetSyncStatusOptions({ path: { accountId } }),
+            refetchInterval: FRESHNESS_POLL_MS,
+            staleTime: FRESHNESS_POLL_MS,
+            meta: { softError: true },
+        })),
+    });
+    const updatedKey = queries.map((query) => query.dataUpdatedAt).join(",");
+    const accountIdsKey = accountIds.join(",");
+    // biome-ignore lint/correctness/useExhaustiveDependencies: updatedKey is the real trigger (each query's own dataUpdatedAt); queries and resultFolderIndex are read fresh each run, not values this effect reacts to on their own.
+    useEffect(() => {
+        let changed = false;
+        const next = new Set(newMail);
+        accountIds.forEach((accountId, index) => {
+            const data = queries[index]?.data;
+            if (!data)
+                return;
+            const current = highWaterMarksFrom(data.mailboxes ?? [], resultFolderIndex);
+            // Mail that has already landed on the server costs nothing more to
+            // show, so a folder that took a UID above the last tick's reloads
+            // its listing here. That caps how stale an open tab's list can get
+            // at this poll's own interval, without a single extra IMAP round.
+            const previous = previousMarksRef.current.get(accountId);
+            previousMarksRef.current.set(accountId, current);
+            if (previous) {
+                const grown = grownMailboxIds(previous, current);
+                if (grown.length > 0) {
+                    invalidateThreadListQueries(queryClient, threadListCacheKeys(grown));
+                }
+            }
+            if (!seededRef.current.has(accountId)) {
+                seededRef.current.add(accountId);
+                baselineRef.current.set(accountId, current);
+                return;
+            }
+            if (next.has(accountId))
+                return;
+            const baseline = baselineRef.current.get(accountId) ?? new Map();
+            if (hasGrown(baseline, current)) {
+                next.add(accountId);
+                changed = true;
+            }
+        });
+        if (changed)
+            setNewMail(next);
+    }, [accountIdsKey, updatedKey]);
+    const hasNewMail = useCallback((ids) => ids.some((id) => newMail.has(id)), [newMail]);
+    const acknowledge = useCallback((ids) => {
+        setNewMail((prev) => {
+            if (ids.every((id) => !prev.has(id)))
+                return prev;
+            const next = new Set(prev);
+            for (const id of ids)
+                next.delete(id);
+            return next;
+        });
+        for (const accountId of ids) {
+            // `useRefreshControl` reads and writes this exact query key through
+            // `queryClient.fetchQuery` as its own wait settles, so this is the
+            // data that refresh just showed the user — never a round-old
+            // cached reading from this provider's own 60s interval.
+            const data = queryClient.getQueryData(syncOperationsGetSyncStatusOptions({ path: { accountId } }).queryKey);
+            baselineRef.current.set(accountId, highWaterMarksFrom(data?.mailboxes ?? [], resultFolderIndex));
+            seededRef.current.add(accountId);
+        }
+    }, [queryClient, resultFolderIndex]);
+    // The sync-status queries update on their own cadence (this poll's 60s, or
+    // every 3s while `useInitialSyncProgress` shares the same key during an
+    // initial sync) — memoized so a tick that changes nothing about the
+    // flag set does not re-render every consumer down the tree.
+    const value = useMemo(() => ({ hasNewMail, acknowledge }), [hasNewMail, acknowledge]);
+    return (_jsx(MailFreshnessContext.Provider, { value: value, children: children }));
+}

package/dist/src/lib/mail-route.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Which list the router is showing, and whether a location still sits on one.
+ *
+ * Every mail URL is a list plus, below it, whatever that list has open. The
+ * list is a layout route, so it is named by a matched route id: the parent
+ * `/mail` match carries the pathname "/mail" on every child, and the deepest
+ * match is the thread. A thread opened from the brief and the brief itself
+ * resolve to the same list.
+ */
+/** A matched route, minimal shape needed to identify the list. */
+export interface MailRouteMatch {
+    routeId: string;
+    params?: Record<string, string | undefined>;
+}
+/** The list layout route ids. */
+export declare const MAIL_BRIEF_ROUTE_ID: "/mail/brief";
+export declare const MAIL_MAILBOX_ROUTE_ID: "/mail/$mailboxId";
+export declare const MAIL_OUTBOX_ROUTE_ID: "/mail/outbox";
+export declare const MAIL_FLAGGED_ROUTE_ID: "/mail/flagged";
+/**
+ * The list a location is browsing. A mailbox route carries its id, which is
+ * absent only in the frame before the router has resolved the param.
+ */
+export type MailListRoute = {
+    list: "brief";
+} | {
+    list: "flagged";
+} | {
+    list: "outbox";
+} | {
+    list: "mailbox";
+    mailboxId: string | undefined;
+};
+/**
+ * The list a caller is on, flattened to the two values a navigation to it — or
+ * a decision about it — needs. Both are primitives, so a caller holding them in
+ * a dependency array settles, and `list` is `undefined` outside the mail shell.
+ */
+export interface BrowsedList {
+    list: MailListRoute["list"] | undefined;
+    mailboxId: string | undefined;
+}
+/**
+ * The list layout among the matched routes, or `undefined` outside the mail
+ * shell.
+ *
+ * Reads the shallowest list match, so anything mounted under a list — the open
+ * thread, the message, the compose surface — leaves the answer alone.
+ */
+export declare function mailListRoute(matches: readonly MailRouteMatch[]): MailListRoute | undefined;
+/**
+ * Identity of the list view the shell is showing — one mailbox, the brief, the
+ * flagged list, or the outbox. Opening a thread is not a view change, so the
+ * key of a list and of anything nested under it are equal; `lib/search-view.ts`
+ * re-seeds the search field whenever this changes, and a key that moved when a
+ * message opened would wipe the query the reader had just typed.
+ *
+ * Read off the location's pathname, for the reason `locationIsOnList` is: the
+ * router commits the address before it swaps the matches, and a route the
+ * reader has not visited yet has its component to fetch before it can. The
+ * search field follows the address, so text typed once the address says the
+ * next mailbox belongs to that mailbox — keying this off the matches instead
+ * made those keystrokes read as the previous view's leftovers and dropped them.
+ *
+ * The whole address, never the /mail match's own pathname, which is "/mail" on
+ * every child route.
+ */
+export declare function mailViewKey(pathname: string): string;
+/**
+ * What the address says the query is.
+ *
+ * Read off the location's own search, never off the matched route's, for the
+ * reason `mailViewKey` reads the location's pathname: the router commits the
+ * whole address at once and swaps the matches afterwards. Taking the view from
+ * one and the query from the other splits a single move in two — the field sees
+ * the mailbox it is going to next to the query of the one it is leaving, and
+ * re-seeds itself with a query the reader has already navigated away from (#47).
+ */
+export declare function addressQuery(search: unknown): string;
+/** One mailbox's view key. Two mailboxes are two views. */
+export declare function mailboxViewKey(mailboxId: string): string;
+/**
+ * Whether a location sits on a list, or on something the list has open below it.
+ *
+ * Answers off the pathname rather than the matches on purpose. The router
+ * commits the new location before it swaps the matches, so a component leaving
+ * the screen sees its own matches under the destination's address for as long as
+ * the destination takes to mount. `pathname` is what says where the reader is
+ * going; `matches` is what says where they still are.
+ *
+ * `listPath` is a whole segment: a folder named `briefing` is not the brief.
+ */
+export declare function locationIsOnList(pathname: string, listPath: string): boolean;
+/**
+ * Whether the address names something the list has open below it — a thread, a
+ * message, the compose surface. A list on its own, and its bare reading pane,
+ * do not.
+ *
+ * Answers what an open thread used to be asked of the query. Anything sharing
+ * the single pane with the conversation reads it from here rather than keeping a
+ * second opinion about what is on screen.
+ */
+export declare function locationOpensDetail(pathname: string): boolean;

package/dist/src/lib/mail-route.js

@@ -0,0 +1,115 @@
+/**
+ * Which list the router is showing, and whether a location still sits on one.
+ *
+ * Every mail URL is a list plus, below it, whatever that list has open. The
+ * list is a layout route, so it is named by a matched route id: the parent
+ * `/mail` match carries the pathname "/mail" on every child, and the deepest
+ * match is the thread. A thread opened from the brief and the brief itself
+ * resolve to the same list.
+ */
+/** The list layout route ids. */
+export const MAIL_BRIEF_ROUTE_ID = "/mail/brief";
+export const MAIL_MAILBOX_ROUTE_ID = "/mail/$mailboxId";
+export const MAIL_OUTBOX_ROUTE_ID = "/mail/outbox";
+export const MAIL_FLAGGED_ROUTE_ID = "/mail/flagged";
+/**
+ * The list layout among the matched routes, or `undefined` outside the mail
+ * shell.
+ *
+ * Reads the shallowest list match, so anything mounted under a list — the open
+ * thread, the message, the compose surface — leaves the answer alone.
+ */
+export function mailListRoute(matches) {
+    for (const match of matches) {
+        if (match.routeId === MAIL_BRIEF_ROUTE_ID)
+            return { list: "brief" };
+        if (match.routeId === MAIL_FLAGGED_ROUTE_ID)
+            return { list: "flagged" };
+        if (match.routeId === MAIL_OUTBOX_ROUTE_ID)
+            return { list: "outbox" };
+        if (match.routeId === MAIL_MAILBOX_ROUTE_ID)
+            return { list: "mailbox", mailboxId: match.params?.mailboxId };
+    }
+    return undefined;
+}
+/**
+ * Identity of the list view the shell is showing — one mailbox, the brief, the
+ * flagged list, or the outbox. Opening a thread is not a view change, so the
+ * key of a list and of anything nested under it are equal; `lib/search-view.ts`
+ * re-seeds the search field whenever this changes, and a key that moved when a
+ * message opened would wipe the query the reader had just typed.
+ *
+ * Read off the location's pathname, for the reason `locationIsOnList` is: the
+ * router commits the address before it swaps the matches, and a route the
+ * reader has not visited yet has its component to fetch before it can. The
+ * search field follows the address, so text typed once the address says the
+ * next mailbox belongs to that mailbox — keying this off the matches instead
+ * made those keystrokes read as the previous view's leftovers and dropped them.
+ *
+ * The whole address, never the /mail match's own pathname, which is "/mail" on
+ * every child route.
+ */
+export function mailViewKey(pathname) {
+    const segments = pathname.split(/[?#]/)[0].split("/").filter(Boolean);
+    if (segments[0] !== "mail")
+        return "";
+    const list = segments[1];
+    if (!list)
+        return "";
+    if (list === "brief")
+        return MAIL_BRIEF_ROUTE_ID;
+    if (list === "flagged")
+        return MAIL_FLAGGED_ROUTE_ID;
+    if (list === "outbox")
+        return MAIL_OUTBOX_ROUTE_ID;
+    return mailboxViewKey(list);
+}
+/**
+ * What the address says the query is.
+ *
+ * Read off the location's own search, never off the matched route's, for the
+ * reason `mailViewKey` reads the location's pathname: the router commits the
+ * whole address at once and swaps the matches afterwards. Taking the view from
+ * one and the query from the other splits a single move in two — the field sees
+ * the mailbox it is going to next to the query of the one it is leaving, and
+ * re-seeds itself with a query the reader has already navigated away from (#47).
+ */
+export function addressQuery(search) {
+    if (typeof search !== "object" || search === null)
+        return "";
+    const { q } = search;
+    return typeof q === "string" ? q : "";
+}
+/** One mailbox's view key. Two mailboxes are two views. */
+export function mailboxViewKey(mailboxId) {
+    return `${MAIL_MAILBOX_ROUTE_ID}:${mailboxId}`;
+}
+/**
+ * Whether a location sits on a list, or on something the list has open below it.
+ *
+ * Answers off the pathname rather than the matches on purpose. The router
+ * commits the new location before it swaps the matches, so a component leaving
+ * the screen sees its own matches under the destination's address for as long as
+ * the destination takes to mount. `pathname` is what says where the reader is
+ * going; `matches` is what says where they still are.
+ *
+ * `listPath` is a whole segment: a folder named `briefing` is not the brief.
+ */
+export function locationIsOnList(pathname, listPath) {
+    if (pathname === listPath)
+        return true;
+    return pathname.startsWith(`${listPath}/`);
+}
+/**
+ * Whether the address names something the list has open below it — a thread, a
+ * message, the compose surface. A list on its own, and its bare reading pane,
+ * do not.
+ *
+ * Answers what an open thread used to be asked of the query. Anything sharing
+ * the single pane with the conversation reads it from here rather than keeping a
+ * second opinion about what is on screen.
+ */
+export function locationOpensDetail(pathname) {
+    const segments = pathname.split(/[?#]/)[0].split("/").filter(Boolean);
+    return segments[0] === "mail" && segments.length > 2;
+}

package/dist/src/lib/mail-search.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The search params each mail list validates.
+ *
+ * `q` lives on the parent `/mail` route, but a child's `validateSearch` is
+ * authoritative for its own URL, so a child that omits `q` strips it: typing a
+ * query on that list does nothing and the query is lost on the next navigation.
+ * Every list extends the same base rather than re-declaring the param, so there
+ * is one place for it to be right.
+ */
+import { z } from "zod";
+/**
+ * The brief's open thread and the message inside it are path segments
+ * (`/mail/brief/<thread>/<message>`), so the query carries nothing but the
+ * search. An old link's selection params are dropped here, which is what
+ * "tolerated and ignored" means.
+ */
+export declare const briefSearchSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
+}, {
+    q?: string | undefined;
+}>;
+/** The same, for `/mail/flagged/<thread>/<message>`. */
+export declare const flaggedSearchSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
+}, {
+    q?: string | undefined;
+}>;
+/**
+ * The outbox's open message is a path segment
+ * (`/mail/outbox/draft/<outboxMessageId>`), so the query carries nothing but
+ * the search. An old link's selection param is dropped here.
+ */
+export declare const outboxSearchSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
+}, {
+    q?: string | undefined;
+}>;
+/**
+ * A folder's open thread and the message inside it are path segments
+ * (`/mail/<mailbox>/<thread>/<message>`), so the query carries nothing but the
+ * search.
+ */
+export declare const mailboxSearchSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
+}, {
+    q?: string | undefined;
+}>;
+/**
+ * `/mail` itself only redirects to the brief, so it accepts what the brief
+ * accepts and hands it straight on.
+ */
+export declare const mailIndexSearchSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    q?: string | undefined;
+}, {
+    q?: string | undefined;
+}>;
+/** Every list's schema, by the path it validates. */
+export declare const mailListSearchSchemas: {
+    readonly "/mail/brief": z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        q?: string | undefined;
+    }, {
+        q?: string | undefined;
+    }>;
+    readonly "/mail/flagged": z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        q?: string | undefined;
+    }, {
+        q?: string | undefined;
+    }>;
+    readonly "/mail/outbox": z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        q?: string | undefined;
+    }, {
+        q?: string | undefined;
+    }>;
+    readonly "/mail/$mailboxId": z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        q?: string | undefined;
+    }, {
+        q?: string | undefined;
+    }>;
+};
+export declare const composeSeedSearch: z.ZodObject<{
+    body: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    body?: string | undefined;
+}, {
+    body?: string | undefined;
+}>;
+export type ComposeSeed = Required<z.infer<typeof composeSeedSearch>>;
+export declare const withoutComposeSeed: (prev: Record<string, unknown>) => Record<string, unknown>;
+export declare const replySearchSchemas: {
+    readonly brief: z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    } & {
+        body: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }>;
+    readonly flagged: z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    } & {
+        body: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }>;
+    readonly mailbox: z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+    } & {
+        body: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }, {
+        body?: string | undefined;
+        q?: string | undefined;
+    }>;
+};

package/dist/src/lib/mail-search.js

@@ -0,0 +1,55 @@
+/**
+ * The search params each mail list validates.
+ *
+ * `q` lives on the parent `/mail` route, but a child's `validateSearch` is
+ * authoritative for its own URL, so a child that omits `q` strips it: typing a
+ * query on that list does nothing and the query is lost on the next navigation.
+ * Every list extends the same base rather than re-declaring the param, so there
+ * is one place for it to be right.
+ */
+import { z } from "zod";
+/** What every list carries, whatever else it carries. */
+const listSearch = z.object({ q: z.string().optional() });
+/**
+ * The brief's open thread and the message inside it are path segments
+ * (`/mail/brief/<thread>/<message>`), so the query carries nothing but the
+ * search. An old link's selection params are dropped here, which is what
+ * "tolerated and ignored" means.
+ */
+export const briefSearchSchema = listSearch.extend({});
+/** The same, for `/mail/flagged/<thread>/<message>`. */
+export const flaggedSearchSchema = listSearch.extend({});
+/**
+ * The outbox's open message is a path segment
+ * (`/mail/outbox/draft/<outboxMessageId>`), so the query carries nothing but
+ * the search. An old link's selection param is dropped here.
+ */
+export const outboxSearchSchema = listSearch.extend({});
+/**
+ * A folder's open thread and the message inside it are path segments
+ * (`/mail/<mailbox>/<thread>/<message>`), so the query carries nothing but the
+ * search.
+ */
+export const mailboxSearchSchema = listSearch.extend({});
+/**
+ * `/mail` itself only redirects to the brief, so it accepts what the brief
+ * accepts and hands it straight on.
+ */
+export const mailIndexSearchSchema = briefSearchSchema;
+/** Every list's schema, by the path it validates. */
+export const mailListSearchSchemas = {
+    "/mail/brief": briefSearchSchema,
+    "/mail/flagged": flaggedSearchSchema,
+    "/mail/outbox": outboxSearchSchema,
+    "/mail/$mailboxId": mailboxSearchSchema,
+};
+export const composeSeedSearch = z.object({ body: z.string().optional() });
+export const withoutComposeSeed = (prev) => {
+    const { body: _seed, ...rest } = prev;
+    return rest;
+};
+export const replySearchSchemas = {
+    brief: briefSearchSchema.extend(composeSeedSearch.shape),
+    flagged: flaggedSearchSchema.extend(composeSeedSearch.shape),
+    mailbox: mailboxSearchSchema.extend(composeSeedSearch.shape),
+};

package/dist/src/lib/mailbox-sync-wait.d.ts

@@ -0,0 +1,54 @@
+import { MailboxSyncStatus } from "@remit/domain-enums";
+type MailboxSyncStatusValue = (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus];
+/**
+ * A folder created for a dependent write — a filter that will move mail into it,
+ * or a move that lands mail there — is not usable the instant the create is
+ * queued: the row exists locally with `syncStatus: pending`, and the folder does
+ * not exist on the mail server until the imap-worker confirms the create and
+ * flips it to `synced`. Binding the dependent write to a `pending` row races the
+ * folder into existence across separate FIFO queues and cannot report a create
+ * that fails. This waits for the confirmation before the dependent write runs.
+ *
+ * The standalone create (a folder made in settings with no dependent write) does
+ * not use this — it may stay optimistic. The wait is only for the dependent case.
+ *
+ * The wait honours an `AbortSignal`: the surface that started the create passes
+ * one and aborts it on unmount/cancel/close, so a folder that confirms after the
+ * surface is gone never resolves and never fires the dependent bind or move.
+ */
+/** The read fields the wait needs off a mailbox row. */
+export interface MailboxSyncSignal {
+    mailboxId: string;
+    syncStatus?: MailboxSyncStatusValue;
+}
+export interface WaitForMailboxSyncedOptions<T extends MailboxSyncSignal> {
+    /** Reads the current mailbox rows; called once per poll (forces a fresh read). */
+    fetchMailboxes: () => Promise<readonly T[]>;
+    /** The row to wait on. */
+    mailboxId: string;
+    /** Aborts the wait; a late confirmation after abort resolves nothing. */
+    signal?: AbortSignal;
+    /** How long to wait for confirmation before giving up. */
+    timeoutMs?: number;
+    /** Gap between polls. */
+    pollIntervalMs?: number;
+    /** Injectable clock/sleep for tests. */
+    delay?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now?: () => number;
+}
+export declare const MAILBOX_SYNC_TIMEOUT_MS = 30000;
+export declare const MAILBOX_SYNC_POLL_INTERVAL_MS = 1000;
+export declare const MAILBOX_SYNC_FAILED_MESSAGE = "The folder couldn't be created on the mail server. Please try again.";
+export declare const MAILBOX_SYNC_TIMEOUT_MESSAGE = "The folder was created but the mail server hasn't confirmed it yet, so nothing was attached to it. It's in your folder list \u2014 try again in a moment.";
+/** `setTimeout` that rejects with the signal's reason instead of outliving it. */
+export declare const abortableDelay: (ms: number, signal?: AbortSignal) => Promise<void>;
+/**
+ * Resolve with the mailbox row once its `syncStatus` reaches `synced` — the
+ * server-confirmed row, carrying the path the server normalized the create to.
+ * Reject with a failure message when the create is reported `failed`, with a
+ * distinct timeout message when it never confirms within `timeoutMs`, and with
+ * the signal's reason (an `AbortError`) when `signal` aborts. A row that is still
+ * `pending` (or not yet in the list) keeps the poll running.
+ */
+export declare function waitForMailboxSynced<T extends MailboxSyncSignal>({ fetchMailboxes, mailboxId, signal, timeoutMs, pollIntervalMs, delay, now, }: WaitForMailboxSyncedOptions<T>): Promise<T>;
+export {};

package/dist/src/lib/mailbox-sync-wait.js

@@ -0,0 +1,44 @@
+import { MailboxSyncStatus } from "@remit/domain-enums";
+export const MAILBOX_SYNC_TIMEOUT_MS = 30_000;
+export const MAILBOX_SYNC_POLL_INTERVAL_MS = 1_000;
+export const MAILBOX_SYNC_FAILED_MESSAGE = "The folder couldn't be created on the mail server. Please try again.";
+export const MAILBOX_SYNC_TIMEOUT_MESSAGE = "The folder was created but the mail server hasn't confirmed it yet, so nothing was attached to it. It's in your folder list — try again in a moment.";
+/** `setTimeout` that rejects with the signal's reason instead of outliving it. */
+export const abortableDelay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(signal?.reason);
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+/**
+ * Resolve with the mailbox row once its `syncStatus` reaches `synced` — the
+ * server-confirmed row, carrying the path the server normalized the create to.
+ * Reject with a failure message when the create is reported `failed`, with a
+ * distinct timeout message when it never confirms within `timeoutMs`, and with
+ * the signal's reason (an `AbortError`) when `signal` aborts. A row that is still
+ * `pending` (or not yet in the list) keeps the poll running.
+ */
+export async function waitForMailboxSynced({ fetchMailboxes, mailboxId, signal, timeoutMs = MAILBOX_SYNC_TIMEOUT_MS, pollIntervalMs = MAILBOX_SYNC_POLL_INTERVAL_MS, delay = abortableDelay, now = Date.now, }) {
+    const deadline = now() + timeoutMs;
+    for (;;) {
+        signal?.throwIfAborted();
+        const mailboxes = await fetchMailboxes();
+        const mailbox = mailboxes.find((entry) => entry.mailboxId === mailboxId);
+        if (mailbox?.syncStatus === MailboxSyncStatus.synced)
+            return mailbox;
+        if (mailbox?.syncStatus === MailboxSyncStatus.failed)
+            throw new Error(MAILBOX_SYNC_FAILED_MESSAGE);
+        if (now() >= deadline)
+            throw new Error(MAILBOX_SYNC_TIMEOUT_MESSAGE);
+        await delay(pollIntervalMs, signal);
+    }
+}