@remit/web-client 0.0.75 → 0.0.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.75",
+  "version": "0.0.76",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/mail/MoveToTrigger.tsx

@@ -130,8 +130,8 @@ export const MoveToTrigger = ({
 	);
 
 	const handleCreateFolder = useCallback(
-		async (name: string): Promise<MoveMailboxOption> => {
-			const folder = await createFolder(name);
+		async (name: string, signal?: AbortSignal): Promise<MoveMailboxOption> => {
+			const folder = await createFolder(name, signal);
 			return { id: folder.id, label: folder.label };
 		},
 		[createFolder],

package/src/components/settings/DeleteFolderDialog.tsx

@@ -103,8 +103,9 @@ export function DeleteFolderDialog({
 
 	const handleCreateFolder = async (
 		name: string,
+		signal?: AbortSignal,
 	): Promise<MoveMailboxOption> => {
-		const created = await createFolder(name);
+		const created = await createFolder(name, signal);
 		return { id: created.id, label: created.label };
 	};
 

package/src/hooks/useCreateMailbox.render.test.ts

@@ -1,9 +1,11 @@
 /**
- * useCreateMailbox.createFolder — the shared create seam the kit surfaces call.
- * It validates the typed name against the account's current folders with the
- * same IMAP-aware rules the settings form uses, and rejects with the
- * human-readable reason before any request. The mailbox list is seeded into the
- * query cache the hook reads, so validation runs against real paths.
+ * useCreateMailbox.createFolder — the shared create seam the kit surfaces call
+ * for a dependent write. It validates the typed name against the account's
+ * current folders with the same IMAP-aware rules the settings form uses, rejects
+ * with the human-readable reason before any request, then waits for the mail
+ * server to confirm the folder before resolving — so a filter or a move never
+ * binds to a still-pending row. The mailbox list is seeded into the query cache
+ * the hook reads, so validation runs against real paths.
  */
 
 import assert from "node:assert/strict";
@@ -13,8 +15,10 @@ import type {
 	MailboxOperationsListMailboxesResponse,
 	RemitImapMailboxResponse,
 } from "@remit/api-http-client/types.gen.ts";
+import { MailboxSyncStatus } from "@remit/domain-enums";
 import type { FolderOption } from "@remit/ui";
 import { act, createElement } from "react";
+import { MAILBOX_SYNC_FAILED_MESSAGE } from "../lib/mailbox-sync-wait";
 import { createDomHarness, type DomHarness } from "../test-support/dom";
 import { type HttpMock, mockFetch } from "../test-support/http";
 import { useCreateMailbox } from "./useCreateMailbox";
@@ -23,7 +27,9 @@ const ACCOUNT = "acc-1";
 
 let harness: DomHarness | undefined;
 let http: HttpMock | undefined;
-let createFolder: ((name: string) => Promise<FolderOption>) | undefined;
+let createFolder:
+	| ((name: string, signal?: AbortSignal) => Promise<FolderOption>)
+	| undefined;
 
 afterEach(() => {
 	harness?.close();
@@ -49,13 +55,23 @@ function Probe() {
 	return null;
 }
 
-const mount = (items: RemitImapMailboxResponse[]) => {
+const mount = (
+	items: RemitImapMailboxResponse[],
+	createdSyncStatus: RemitImapMailboxResponse["syncStatus"] = MailboxSyncStatus.synced,
+) => {
+	const created: RemitImapMailboxResponse[] = [];
 	http = mockFetch((call) => {
 		if (call.method === "POST") {
 			const body = call.body as { fullPath: string };
+			created.push({
+				mailboxId: `mbx-${body.fullPath}`,
+				accountId: ACCOUNT,
+				fullPath: body.fullPath,
+				syncStatus: createdSyncStatus,
+			} as RemitImapMailboxResponse);
 			return { mailboxId: `mbx-${body.fullPath}`, fullPath: body.fullPath };
 		}
-		return { items };
+		return { items: [...items, ...created] };
 	});
 	harness = createDomHarness();
 	harness.queryClient.setQueryData<MailboxOperationsListMailboxesResponse>(
@@ -114,7 +130,7 @@ describe("useCreateMailbox.createFolder validation", () => {
 		assert.equal(postCount(), 0);
 	});
 
-	it("passes a valid name through to the create request and maps the result", async () => {
+	it("passes a valid name through and resolves once the folder is confirmed synced", async () => {
 		mount([mailbox("INBOX", "/")]);
 		let result: FolderOption | undefined;
 		await act(async () => {
@@ -126,6 +142,90 @@ describe("useCreateMailbox.createFolder validation", () => {
 			fullPath: "Taxes",
 			namespaceType: "personal",
 		});
+		// It polled the list after the create to confirm the folder before resolving.
+		const gets = (http?.calls ?? []).filter((call) => call.method === "GET");
+		assert.ok(gets.length >= 1, "polls the mailbox list for confirmation");
 		assert.equal(result?.label, "Taxes");
 	});
+
+	it("rejects — no folder to bind a dependent write to — when the create is reported failed", async () => {
+		mount([mailbox("INBOX", "/")], MailboxSyncStatus.failed);
+		let caught: unknown;
+		await act(async () => {
+			caught = await createFolder?.("Taxes").then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.ok(caught instanceof Error);
+		assert.equal(caught.message, MAILBOX_SYNC_FAILED_MESSAGE);
+	});
+
+	it("retry resumes the wait on the folder it already made — no second create, no 'already exists'", async () => {
+		// The created folder is reported failed on the first attempt, then synced.
+		let status: RemitImapMailboxResponse["syncStatus"] =
+			MailboxSyncStatus.failed;
+		const created: RemitImapMailboxResponse[] = [];
+		http = mockFetch((call) => {
+			if (call.method === "POST") {
+				const body = call.body as { fullPath: string };
+				created.push({
+					mailboxId: `mbx-${body.fullPath}`,
+					accountId: ACCOUNT,
+					fullPath: body.fullPath,
+				} as RemitImapMailboxResponse);
+				return { mailboxId: `mbx-${body.fullPath}`, fullPath: body.fullPath };
+			}
+			return {
+				items: [
+					mailbox("INBOX", "/"),
+					...created.map((entry) => ({ ...entry, syncStatus: status })),
+				],
+			};
+		});
+		harness = createDomHarness();
+		harness.queryClient.setQueryData<MailboxOperationsListMailboxesResponse>(
+			mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT } }),
+			{ items: [mailbox("INBOX", "/")] },
+		);
+		harness.renderApp(createElement(Probe));
+
+		let first: unknown;
+		await act(async () => {
+			first = await createFolder?.("Taxes").then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.ok(first instanceof Error);
+		assert.equal(first.message, MAILBOX_SYNC_FAILED_MESSAGE);
+
+		// The server confirms; the user presses "Create folder" again, same name.
+		status = MailboxSyncStatus.synced;
+		let result: FolderOption | undefined;
+		await act(async () => {
+			result = await createFolder?.("Taxes");
+		});
+		assert.equal(result?.label, "Taxes");
+
+		// Exactly one create across both attempts — the retry resumed, it did not
+		// re-validate (which would throw "already exists") or re-POST.
+		const posts = (http?.calls ?? []).filter((call) => call.method === "POST");
+		assert.equal(posts.length, 1);
+	});
+
+	it("abort stops the wait so a folder that confirms later never resolves", async () => {
+		mount([mailbox("INBOX", "/")], MailboxSyncStatus.pending);
+		const controller = new AbortController();
+		let caught: unknown;
+		await act(async () => {
+			const promise = createFolder?.("Taxes", controller.signal);
+			controller.abort();
+			caught = await promise?.then(
+				() => undefined,
+				(error: unknown) => error,
+			);
+		});
+		assert.equal((caught as { name?: string })?.name, "AbortError");
+	});
 });

package/src/hooks/useCreateMailbox.ts

@@ -5,21 +5,40 @@ import {
 } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
 import type { FolderOption } from "@remit/ui";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { getMailboxDisplayName } from "@/lib/folder-roles";
+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, so the folder is usable as a move destination immediately.
+ * create.
  *
- * `createFolder` 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. The kit surfaces that pick the
- * result render that rejection inline. `mutation` is exposed for callers that
- * drive their own form state and error surface.
+ * `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.
+ *
+ * `mutation` is exposed for callers that drive their own form state and want the
+ * optimistic, non-waiting create (the standalone settings create).
  */
 export function useCreateMailbox(accountId: string) {
 	const queryClient = useQueryClient();
@@ -39,26 +58,48 @@ export function useCreateMailbox(accountId: string) {
 		},
 	});
 
+	// 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<string, string>());
+
 	const createFolder = useCallback(
-		async (name: string): Promise<FolderOption> => {
-			const items = data?.items ?? [];
-			const delimiter = items[0]?.hierarchyDelimiter ?? "/";
-			const problem = validateNewFolderName({
-				name,
-				delimiter,
-				existingPaths: items.map((item) => item.fullPath),
-			});
-			if (problem) throw new Error(problem);
-			const mailbox = await mutation.mutateAsync({
-				path: { accountId },
-				body: { fullPath: composeFolderPath(name), namespaceType: "personal" },
+		async (name: string, signal?: AbortSignal): Promise<FolderOption> => {
+			const fullPath = composeFolderPath(name);
+			let mailboxId = pendingByPath.current.get(fullPath);
+			if (!mailboxId) {
+				const items = data?.items ?? [];
+				const delimiter = items[0]?.hierarchyDelimiter ?? "/";
+				const problem = validateNewFolderName({
+					name,
+					delimiter,
+					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: mailbox.mailboxId,
-				label: getMailboxDisplayName(mailbox.fullPath),
+				id: confirmed.mailboxId,
+				label: getMailboxDisplayName(confirmed.fullPath),
 			};
 		},
-		[mutation, accountId, data],
+		[mutation, accountId, data, queryClient],
 	);
 
 	return { createFolder, mutation };

package/src/lib/mailbox-sync-wait.test.ts

@@ -0,0 +1,186 @@
+/**
+ * waitForMailboxSynced — the gate a dependent write (a filter, a move) holds
+ * behind while a freshly-created folder is confirmed on the mail server. It
+ * resolves only on `synced`, rejects distinctly on `failed` and on timeout, and
+ * keeps polling while the row is still `pending` or not yet listed.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import {
+	MAILBOX_SYNC_FAILED_MESSAGE,
+	MAILBOX_SYNC_TIMEOUT_MESSAGE,
+	type MailboxSyncSignal,
+	waitForMailboxSynced,
+} from "./mailbox-sync-wait.js";
+
+const row = (
+	mailboxId: string,
+	syncStatus?: MailboxSyncSignal["syncStatus"],
+	extra: Record<string, unknown> = {},
+): MailboxSyncSignal & Record<string, unknown> => ({
+	mailboxId,
+	syncStatus,
+	...extra,
+});
+
+const noDelay = () => Promise.resolve();
+
+describe("waitForMailboxSynced", () => {
+	it("resolves with the confirmed row once it reaches synced", async () => {
+		const responses = [
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.synced, { fullPath: "Server/Receipts" })],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			fetchMailboxes: async () => responses[call++],
+			delay: noDelay,
+		});
+		assert.equal(result.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(
+			(result as Record<string, unknown>).fullPath,
+			"Server/Receipts",
+		);
+		assert.equal(call, 3);
+	});
+
+	it("keeps polling while the row is not yet listed", async () => {
+		const responses = [
+			[] as MailboxSyncSignal[],
+			[row("other", MailboxSyncStatus.synced)],
+			[row("mbx-1", MailboxSyncStatus.synced)],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			fetchMailboxes: async () => responses[call++],
+			delay: noDelay,
+		});
+		assert.equal(result.mailboxId, "mbx-1");
+		assert.equal(call, 3);
+	});
+
+	it("rejects with the failure message when the create is reported failed", async () => {
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.failed)],
+				delay: noDelay,
+			}),
+			(error: unknown) =>
+				error instanceof Error && error.message === MAILBOX_SYNC_FAILED_MESSAGE,
+		);
+	});
+
+	it("rejects with the timeout message when the row never confirms", async () => {
+		let clock = 0;
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => {
+					fetches += 1;
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				timeoutMs: 30_000,
+				pollIntervalMs: 1_000,
+				now: () => clock,
+				delay: async (ms) => {
+					clock += ms;
+				},
+			}),
+			(error: unknown) =>
+				error instanceof Error &&
+				error.message === MAILBOX_SYNC_TIMEOUT_MESSAGE,
+		);
+		assert.ok(fetches > 1, "polls more than once before timing out");
+	});
+
+	it("does not treat failed as timeout even past the deadline", async () => {
+		let clock = 100_000;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.failed)],
+				timeoutMs: 1,
+				now: () => clock++,
+				delay: noDelay,
+			}),
+			(error: unknown) =>
+				error instanceof Error && error.message === MAILBOX_SYNC_FAILED_MESSAGE,
+		);
+	});
+
+	const isAbort = (error: unknown): boolean =>
+		typeof error === "object" &&
+		error !== null &&
+		(error as { name?: unknown }).name === "AbortError";
+
+	it("rejects without polling when the signal is already aborted", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				signal: controller.signal,
+				fetchMailboxes: async () => {
+					fetches += 1;
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				delay: noDelay,
+			}),
+			isAbort,
+		);
+		assert.equal(fetches, 0);
+	});
+
+	it("stops polling and rejects when the signal aborts mid-wait", async () => {
+		const controller = new AbortController();
+		let fetches = 0;
+		await assert.rejects(
+			waitForMailboxSynced({
+				mailboxId: "mbx-1",
+				signal: controller.signal,
+				fetchMailboxes: async () => {
+					fetches += 1;
+					if (fetches === 2) controller.abort();
+					return [row("mbx-1", MailboxSyncStatus.pending)];
+				},
+				delay: noDelay,
+			}),
+			isAbort,
+		);
+		assert.equal(fetches, 2);
+	});
+
+	it("resolves across the real timer delay between polls", async () => {
+		const responses = [
+			[row("mbx-1", MailboxSyncStatus.pending)],
+			[row("mbx-1", MailboxSyncStatus.synced)],
+		];
+		let call = 0;
+		const result = await waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			pollIntervalMs: 1,
+			fetchMailboxes: async () => responses[call++],
+		});
+		assert.equal(result.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("aborts an in-progress real timer delay", async () => {
+		const controller = new AbortController();
+		const pending = waitForMailboxSynced({
+			mailboxId: "mbx-1",
+			signal: controller.signal,
+			pollIntervalMs: 10_000,
+			fetchMailboxes: async () => [row("mbx-1", MailboxSyncStatus.pending)],
+		});
+		setTimeout(() => controller.abort(), 5);
+		await assert.rejects(pending, isAbort);
+	});
+});

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

@@ -0,0 +1,98 @@
+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 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.";
+
+const defaultDelay = (ms: number, signal?: AbortSignal): Promise<void> =>
+	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<T extends MailboxSyncSignal>({
+	fetchMailboxes,
+	mailboxId,
+	signal,
+	timeoutMs = MAILBOX_SYNC_TIMEOUT_MS,
+	pollIntervalMs = MAILBOX_SYNC_POLL_INTERVAL_MS,
+	delay = defaultDelay,
+	now = Date.now,
+}: WaitForMailboxSyncedOptions<T>): Promise<T> {
+	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);
+	}
+}