@remit/web-client 0.0.325 → 0.0.326

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

@@ -0,0 +1,20 @@
+import { type DraftForAttachment } from "../lib/compose-attachment-controller";
+export type { DraftForAttachment };
+interface UseComposeAttachmentsOptions {
+    ensureDraft: () => Promise<DraftForAttachment>;
+}
+/** The composer's side of `ComposeAttachmentController`, over the app's API. */
+export declare const useComposeAttachments: ({ ensureDraft, }: UseComposeAttachmentsOptions) => {
+    items: import("@remit/ui").ComposeAttachmentItem[];
+    attach: (files: File[], placement?: import("../lib/compose-attachment-controller").AttachmentPlacement) => Promise<void>;
+    retry: (key: string) => Promise<void>;
+    remove: (key: string) => Promise<void>;
+    load: (outboxMessageId: string, attachments: readonly import("@remit/api-http-client").RemitImapOutboxAttachmentResponse[]) => void;
+    reset: (outboxMessageId: string | undefined) => void;
+    owns: (contentId: string) => boolean;
+    isLoaded: () => boolean;
+    refreshLinks: (attachments: readonly import("@remit/api-http-client").RemitImapOutboxAttachmentResponse[]) => void;
+    storedContent: (contentId: string) => import("../lib/compose-attachment-controller").StoredContent | null;
+    onRemoved: (listener: (contentId: string) => void) => (() => void);
+    blockingReason: string | undefined;
+};

package/dist/src/hooks/useComposeAttachments.js

@@ -0,0 +1,72 @@
+import { outboxAttachmentOperationsCompleteOutboxAttachmentMutation, outboxDetailOperationsMintOutboxAttachmentMutation, outboxDetailOperationsUpdateOutboxMessageMutation, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation } from "@tanstack/react-query";
+import { useRef, useState, useSyncExternalStore } from "react";
+import { ComposeAttachmentController, } from "../lib/compose-attachment-controller";
+import { softErrorMeta } from "../lib/error-classifier";
+const putFile = (uploadUrl, file, signal) => fetch(uploadUrl, { method: "PUT", body: file, signal }).then((response) => {
+    if (!response.ok) {
+        throw new Error(`the server answered ${response.status}`);
+    }
+});
+/** The composer's side of `ComposeAttachmentController`, over the app's API. */
+export const useComposeAttachments = ({ ensureDraft, }) => {
+    const mintMutation = useMutation({
+        ...outboxDetailOperationsMintOutboxAttachmentMutation(),
+        meta: softErrorMeta,
+    });
+    const completeMutation = useMutation({
+        ...outboxAttachmentOperationsCompleteOutboxAttachmentMutation(),
+        meta: softErrorMeta,
+    });
+    const updateMutation = useMutation({
+        ...outboxDetailOperationsUpdateOutboxMessageMutation(),
+        meta: softErrorMeta,
+    });
+    const transportRef = useRef(null);
+    transportRef.current = {
+        mint: (outboxMessageId, file) => mintMutation.mutateAsync({
+            path: { outboxMessageId },
+            body: {
+                filename: file.name,
+                contentType: file.type || "application/octet-stream",
+                sizeBytes: file.size,
+            },
+        }),
+        put: putFile,
+        complete: (outboxMessageId, outboxAttachmentId) => completeMutation
+            .mutateAsync({ path: { outboxMessageId, outboxAttachmentId } })
+            .then((attachment) => ({ contentUrl: attachment.contentUrl })),
+        keep: (outboxMessageId, attachmentIds) => updateMutation
+            .mutateAsync({
+            path: { outboxMessageId },
+            body: { attachmentIds },
+        })
+            .then(() => undefined),
+    };
+    const ensureDraftRef = useRef(ensureDraft);
+    ensureDraftRef.current = ensureDraft;
+    const [controller] = useState(() => new ComposeAttachmentController({
+        transport: () => {
+            const transport = transportRef.current;
+            if (!transport)
+                throw new Error("attachment transport not ready");
+            return transport;
+        },
+        ensureDraft: () => ensureDraftRef.current(),
+    }));
+    const items = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    return {
+        items,
+        attach: controller.attach,
+        retry: controller.retry,
+        remove: controller.remove,
+        load: controller.load,
+        reset: controller.reset,
+        owns: controller.owns,
+        isLoaded: controller.isLoaded,
+        refreshLinks: controller.refreshLinks,
+        storedContent: controller.storedContent,
+        onRemoved: controller.onRemoved,
+        blockingReason: controller.blockingReason(),
+    };
+};

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

@@ -0,0 +1,11 @@
+/**
+ * The account's writing languages: the menu the composer's language chip
+ * offers, and the set detection is allowed to choose inside. Absent on the
+ * server means the user has never been here, and the browser's own ordered
+ * answer stands in.
+ */
+export declare const useComposeLanguages: (accountId?: string) => {
+    languages: string[];
+    setLanguages: (next: string[]) => void;
+    isSaving: boolean;
+};

package/dist/src/hooks/useComposeLanguages.js

@@ -0,0 +1,44 @@
+import { accountDetailOperationsUpdateAccountMutation, configOperationsGetConfigOptions, configOperationsGetConfigQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { defaultComposeLanguages } from "@remit/ui";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "../components/ui/error-banners";
+/**
+ * The account's writing languages: the menu the composer's language chip
+ * offers, and the set detection is allowed to choose inside. Absent on the
+ * server means the user has never been here, and the browser's own ordered
+ * answer stands in.
+ */
+export const useComposeLanguages = (accountId) => {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const { data: config } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+    });
+    const configured = config?.accounts.find((account) => account.accountId === accountId)?.composeLanguages;
+    const languages = useMemo(() => configured && configured.length > 0
+        ? [...configured]
+        : defaultComposeLanguages(navigator.languages), [configured]);
+    const mutation = useMutation({
+        ...accountDetailOperationsUpdateAccountMutation(),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: configOperationsGetConfigQueryKey(),
+            });
+        },
+        onError: (error) => {
+            pushError(buildMutationErrorBanner("Couldn't save languages", "The writing languages weren't saved.", error));
+        },
+    });
+    const setLanguages = useCallback((next) => {
+        if (!accountId)
+            return;
+        mutation.mutate({
+            path: { accountId },
+            body: { composeLanguages: next },
+        });
+    }, [accountId, mutation]);
+    return { languages, setLanguages, isSaving: mutation.isPending };
+};

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

@@ -0,0 +1,40 @@
+import type { FolderTreeNode } from "@remit/ui";
+/**
+ * Creates a mailbox for an account and refreshes the folder list on success.
+ * The backend creates the row with a pending sync status and queues the IMAP
+ * create.
+ *
+ * `createFolder` is the seam for dependent writes: a folder created so a filter
+ * can move mail into it, or so a move can land mail there. It takes a leaf name,
+ * validates it against the account's current folders with the same IMAP-aware
+ * rules the settings form uses (non-empty, no hierarchy delimiter, no collision —
+ * INBOX case-insensitive), and rejects with the human-readable reason before any
+ * request. It then WAITS for the mail server to confirm the folder before
+ * resolving — a folder is not a valid target until it exists on the server, and
+ * binding a filter or a move to a still-pending row races the folder into
+ * existence and cannot report a create that fails. It resolves with the confirmed
+ * folder (carrying the path the server normalized to), rejects with a distinct
+ * message when the create fails or never confirms, and the kit surfaces that
+ * render either the "Creating folder…" wait or the failure inline.
+ *
+ * Retry is a resume, not a re-create: a create that timed out or failed leaves
+ * the row already made, so pressing "Create folder" again calls `createFolder`
+ * with the same name — which resumes the wait on the mailboxId it already made
+ * rather than re-validating (the pending row would collide as "already exists")
+ * and re-POSTing. The mailboxId is carried per-name until the folder confirms.
+ *
+ * `createFolder` takes an `AbortSignal` the surface aborts on unmount/cancel/
+ * close, so a folder that confirms after the surface is gone resolves nothing.
+ *
+ * `createFolderIn` is the same seam for a folder made inside another one: the
+ * parent is named by its provider path, and the name is joined to it with that
+ * parent's own hierarchy delimiter. `createFolder` is it with no parent.
+ *
+ * `mutation` is exposed for callers that drive their own form state and want the
+ * optimistic, non-waiting create.
+ */
+export declare function useCreateMailbox(accountId: string | undefined): {
+    createFolder: (name: string, signal?: AbortSignal) => Promise<FolderTreeNode>;
+    createFolderIn: (name: string, parentPath: string, signal?: AbortSignal) => Promise<FolderTreeNode>;
+    mutation: import("@tanstack/react-query").UseMutationResult<import("@remit/api-http-client").RemitImapMailboxResponse, import("@remit/api-http-client").ApiError | import("@remit/api-http-client").ValidationError, import("@remit/api-http-client").Options<import("@remit/api-http-client").MailboxOperationsCreateMailboxData>, unknown>;
+};

package/dist/src/hooks/useCreateMailbox.js

@@ -0,0 +1,123 @@
+import { mailboxOperationsCreateMailboxMutation, mailboxOperationsListMailboxesOptions, mailboxOperationsListMailboxesQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { mailboxLeafName } from "@remit/data-ports/mailbox-name";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef } from "react";
+import { waitForMailboxSynced } from "../lib/mailbox-sync-wait";
+import { composeFolderPath, validateNewFolderName, } from "../lib/new-folder";
+/**
+ * Creates a mailbox for an account and refreshes the folder list on success.
+ * The backend creates the row with a pending sync status and queues the IMAP
+ * create.
+ *
+ * `createFolder` is the seam for dependent writes: a folder created so a filter
+ * can move mail into it, or so a move can land mail there. It takes a leaf name,
+ * validates it against the account's current folders with the same IMAP-aware
+ * rules the settings form uses (non-empty, no hierarchy delimiter, no collision —
+ * INBOX case-insensitive), and rejects with the human-readable reason before any
+ * request. It then WAITS for the mail server to confirm the folder before
+ * resolving — a folder is not a valid target until it exists on the server, and
+ * binding a filter or a move to a still-pending row races the folder into
+ * existence and cannot report a create that fails. It resolves with the confirmed
+ * folder (carrying the path the server normalized to), rejects with a distinct
+ * message when the create fails or never confirms, and the kit surfaces that
+ * render either the "Creating folder…" wait or the failure inline.
+ *
+ * Retry is a resume, not a re-create: a create that timed out or failed leaves
+ * the row already made, so pressing "Create folder" again calls `createFolder`
+ * with the same name — which resumes the wait on the mailboxId it already made
+ * rather than re-validating (the pending row would collide as "already exists")
+ * and re-POSTing. The mailboxId is carried per-name until the folder confirms.
+ *
+ * `createFolder` takes an `AbortSignal` the surface aborts on unmount/cancel/
+ * close, so a folder that confirms after the surface is gone resolves nothing.
+ *
+ * `createFolderIn` is the same seam for a folder made inside another one: the
+ * parent is named by its provider path, and the name is joined to it with that
+ * parent's own hierarchy delimiter. `createFolder` is it with no parent.
+ *
+ * `mutation` is exposed for callers that drive their own form state and want the
+ * optimistic, non-waiting create.
+ */
+export function useCreateMailbox(accountId) {
+    const queryClient = useQueryClient();
+    // Held by surfaces that are mounted before a selection has named an account —
+    // the selection wizard sits beside every list — so the folder list is only
+    // asked for once there is an account to ask about.
+    const { data } = useQuery({
+        ...mailboxOperationsListMailboxesOptions({
+            path: { accountId: accountId ?? "" },
+        }),
+        enabled: !!accountId,
+    });
+    const mutation = useMutation({
+        ...mailboxOperationsCreateMailboxMutation(),
+        onSuccess: () => {
+            if (!accountId)
+                return;
+            queryClient.invalidateQueries({
+                queryKey: mailboxOperationsListMailboxesQueryKey({
+                    path: { accountId },
+                }),
+            });
+        },
+    });
+    // fullPath -> mailboxId for a folder created but not yet confirmed, so a retry
+    // resumes the wait on it instead of re-creating. Cleared once it confirms.
+    const pendingByPath = useRef(new Map());
+    const createFolderIn = useCallback(async (name, parentPath, signal) => {
+        if (!accountId) {
+            throw new Error("No account to create the folder in. Pick messages from a single account first.");
+        }
+        const items = data?.items ?? [];
+        const parentMailbox = parentPath
+            ? items.find((item) => item.fullPath === parentPath)
+            : undefined;
+        if (parentPath && !parentMailbox) {
+            throw new Error(`Couldn't find the folder "${parentPath}" to create this one inside.`);
+        }
+        const parent = parentMailbox
+            ? {
+                fullPath: parentMailbox.fullPath,
+                hierarchyDelimiter: parentMailbox.hierarchyDelimiter,
+            }
+            : undefined;
+        const fullPath = composeFolderPath(name, parent);
+        let mailboxId = pendingByPath.current.get(fullPath);
+        if (!mailboxId) {
+            const delimiter = parent?.hierarchyDelimiter ?? items[0]?.hierarchyDelimiter ?? "/";
+            const problem = validateNewFolderName({
+                name,
+                delimiter,
+                parent,
+                existingPaths: items.map((item) => item.fullPath),
+            });
+            if (problem)
+                throw new Error(problem);
+            const mailbox = await mutation.mutateAsync({
+                path: { accountId },
+                body: { fullPath, namespaceType: "personal" },
+            });
+            mailboxId = mailbox.mailboxId;
+            pendingByPath.current.set(fullPath, mailboxId);
+        }
+        const confirmed = await waitForMailboxSynced({
+            mailboxId,
+            signal,
+            fetchMailboxes: async () => {
+                const response = await queryClient.fetchQuery({
+                    ...mailboxOperationsListMailboxesOptions({ path: { accountId } }),
+                    staleTime: 0,
+                });
+                return response.items ?? [];
+            },
+        });
+        pendingByPath.current.delete(fullPath);
+        return {
+            id: confirmed.mailboxId,
+            label: mailboxLeafName(confirmed),
+            path: confirmed.fullPath,
+        };
+    }, [mutation, accountId, data, queryClient]);
+    const createFolder = useCallback((name, signal) => createFolderIn(name, "", signal), [createFolderIn]);
+    return { createFolder, createFolderIn, mutation };
+}

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

@@ -0,0 +1,39 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+interface UseCurrentMailboxNameOptions {
+    accounts: RemitImapAccountResponse[];
+}
+/**
+ * Resolves a display label for the mailbox or pseudo-mailbox the user is
+ * currently looking at — used by the mobile top bar so it reads e.g.
+ * "Inbox" or "Outbox" instead of the static "Remit" branding.
+ *
+ * Priority:
+ *   - `/mail/outbox` → "Outbox"
+ *   - `/mail/$mailboxId` → display name from the mailbox query
+ *   - everything else (e.g. `/mail` mid-redirect) → `null`
+ *
+ * Reuses the same `mailboxOperationsListMailboxesOptions` queries the
+ * `MailSidebarAdapter` runs, so on warm cache (the sidebar is always
+ * mounted on `/mail/*`) this is a free lookup.
+ */
+export declare const useCurrentMailboxName: ({ accounts, }: UseCurrentMailboxNameOptions) => string | null;
+/**
+ * Resolves the authoritative unread (unseen) total for the current mailbox
+ * from the mailbox query — the same warm-cache `mailboxOperationsListMailboxes`
+ * data the sidebar and `useCurrentMailboxName` already read.
+ *
+ * Returns `mailbox.unseenCount` (the true server-side total), not a count
+ * derived from the loaded infinite-query pages, which would undercount on any
+ * mailbox larger than one page and creep upward as the user scrolls. Returns
+ * `null` when the mailbox isn't resolvable yet (loading, or no `mailboxId`),
+ * letting callers fall back to a loaded-derived count.
+ */
+export declare const useCurrentMailboxUnseenCount: ({ accounts, }: UseCurrentMailboxNameOptions) => number | null;
+/**
+ * The current mailbox's total message count, from the same warm-cache mailbox
+ * query. `0` while it is unresolvable, so a surface gated on "holds at least
+ * one message" — Empty Trash (#847) — stays down rather than offering a verb
+ * over a folder nothing is known about yet.
+ */
+export declare const useCurrentMailboxMessageCount: ({ accounts, }: UseCurrentMailboxNameOptions) => number;
+export {};

package/dist/src/hooks/useCurrentMailboxName.js

@@ -0,0 +1,109 @@
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { buildMailboxRoleMap, labelForMailbox } from "../lib/folder-roles";
+import { useBrowsedList } from "../routing";
+/**
+ * Resolves a display label for the mailbox or pseudo-mailbox the user is
+ * currently looking at — used by the mobile top bar so it reads e.g.
+ * "Inbox" or "Outbox" instead of the static "Remit" branding.
+ *
+ * Priority:
+ *   - `/mail/outbox` → "Outbox"
+ *   - `/mail/$mailboxId` → display name from the mailbox query
+ *   - everything else (e.g. `/mail` mid-redirect) → `null`
+ *
+ * Reuses the same `mailboxOperationsListMailboxesOptions` queries the
+ * `MailSidebarAdapter` runs, so on warm cache (the sidebar is always
+ * mounted on `/mail/*`) this is a free lookup.
+ */
+export const useCurrentMailboxName = ({ accounts, }) => {
+    const { list, mailboxId } = useBrowsedList();
+    const { t } = useTranslation("mail", { useSuspense: false });
+    const translator = useCallback((key, fallback) => t(key, { defaultValue: fallback }), [t]);
+    const queries = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+    });
+    if (list === "outbox")
+        return "Outbox";
+    if (!mailboxId)
+        return null;
+    for (let i = 0; i < accounts.length; i++) {
+        const items = queries[i]?.data?.items;
+        if (!items)
+            continue;
+        const match = items.find((mailbox) => mailbox.mailboxId === mailboxId);
+        if (!match)
+            continue;
+        const roleMap = buildMailboxRoleMap(accounts[i].folderAppointments);
+        return labelForMailbox(match, roleMap.get(mailboxId), translator);
+    }
+    return null;
+};
+/**
+ * Resolves the authoritative unread (unseen) total for the current mailbox
+ * from the mailbox query — the same warm-cache `mailboxOperationsListMailboxes`
+ * data the sidebar and `useCurrentMailboxName` already read.
+ *
+ * Returns `mailbox.unseenCount` (the true server-side total), not a count
+ * derived from the loaded infinite-query pages, which would undercount on any
+ * mailbox larger than one page and creep upward as the user scrolls. Returns
+ * `null` when the mailbox isn't resolvable yet (loading, or no `mailboxId`),
+ * letting callers fall back to a loaded-derived count.
+ */
+export const useCurrentMailboxUnseenCount = ({ accounts, }) => {
+    const { mailboxId } = useBrowsedList();
+    const queries = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+    });
+    if (!mailboxId)
+        return null;
+    for (const query of queries) {
+        const items = query.data?.items;
+        if (!items)
+            continue;
+        const match = items.find((mailbox) => mailbox.mailboxId === mailboxId);
+        if (match)
+            return match.unseenCount;
+    }
+    return null;
+};
+/**
+ * The current mailbox's total message count, from the same warm-cache mailbox
+ * query. `0` while it is unresolvable, so a surface gated on "holds at least
+ * one message" — Empty Trash (#847) — stays down rather than offering a verb
+ * over a folder nothing is known about yet.
+ */
+export const useCurrentMailboxMessageCount = ({ accounts, }) => {
+    const { mailboxId } = useBrowsedList();
+    const queries = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+    });
+    if (!mailboxId)
+        return 0;
+    for (const query of queries) {
+        const items = query.data?.items;
+        if (!items)
+            continue;
+        const match = items.find((mailbox) => mailbox.mailboxId === mailboxId);
+        if (match)
+            return match.messageCount;
+    }
+    return 0;
+};

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

@@ -0,0 +1 @@
+export declare const useDebouncedValue: <T>(value: T, delay: number) => T;

package/dist/src/hooks/useDebouncedValue.js

@@ -0,0 +1,9 @@
+import { useEffect, useState } from "react";
+export const useDebouncedValue = (value, delay) => {
+    const [debouncedValue, setDebouncedValue] = useState(value);
+    useEffect(() => {
+        const timer = setTimeout(() => setDebouncedValue(value), delay);
+        return () => clearTimeout(timer);
+    }, [value, delay]);
+    return debouncedValue;
+};

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

@@ -0,0 +1,36 @@
+import { type MoveProgress } from "../lib/delete-folder";
+export type DeleteFolderPhase = "idle" | "checking" | "check-stalled" | "moving" | "deleting" | "done" | "error";
+/**
+ * What a delete-as-empty did. `blocked` carries the count that stopped it;
+ * `pending` means the server has not reported yet and the user decides whether
+ * to wait on; `failed` means nothing was established. Neither is ever treated
+ * as empty.
+ */
+export type EmptyDeleteOutcome = {
+    status: "deleted";
+} | {
+    status: "blocked";
+    messageCount: number;
+} | {
+    status: "pending";
+} | {
+    status: "failed";
+};
+interface UseDeleteFolderOptions {
+    accountId: string;
+    mailboxId: string;
+    onDeleted: () => void;
+}
+export declare function useDeleteFolder({ accountId, mailboxId, onDeleted, }: UseDeleteFolderOptions): {
+    phase: DeleteFolderPhase;
+    progress: MoveProgress | null;
+    errorMessage: string | undefined;
+    /** When the running check asked for its round; the surface shows the wait. */
+    checkStartedAt: number | undefined;
+    deleteMailbox: () => Promise<void>;
+    deleteIfEmpty: () => Promise<EmptyDeleteOutcome>;
+    moveThenDelete: (destinationMailboxId: string) => Promise<void>;
+    cancel: () => void;
+    reset: () => void;
+};
+export {};