@remit/mailbox-service 0.0.112 → 0.0.114

package/src/mailbox-presence.test.ts

@@ -1,74 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import { MailboxSyncStatus } from "@remit/domain-enums";
-import {
-	isFolderMutationInFlight,
-	isMailboxMutationInFlight,
-} from "./mailbox-presence.js";
-import {
-	openStore,
-	seedAccount,
-	seedMailbox,
-} from "./test-helpers/test-store.js";
-
-describe("isFolderMutationInFlight", () => {
-	for (const [syncStatus, inFlight] of [
-		[MailboxSyncStatus.synced, false],
-		[MailboxSyncStatus.pending, true],
-		[MailboxSyncStatus.deleting, true],
-		[MailboxSyncStatus.failed, false],
-	] as const) {
-		it(`${syncStatus} is ${inFlight ? "" : "not "}a mutation in flight`, () => {
-			assert.equal(isFolderMutationInFlight({ syncStatus }), inFlight);
-		});
-	}
-
-	it("does not read failed as a folder to leave alone", () => {
-		// `failed` means the folder exists at `fullPath` and the last rename or
-		// delete intent did not land — so it holds the user's mail and syncing it
-		// is right. D7 upholds that by leaving no row at all for a create the
-		// server refused. Reading it as in-flight would stop syncing a live folder
-		// permanently and silently.
-		assert.equal(
-			isFolderMutationInFlight({ syncStatus: MailboxSyncStatus.failed }),
-			false,
-		);
-	});
-});
-
-describe("isMailboxMutationInFlight", () => {
-	it("reads the stored row, and treats an absent one as in flight", async () => {
-		const store = await openStore();
-		const account = await seedAccount(store);
-		const deleting = await seedMailbox(store, account, "Receipts", {
-			overrides: { syncStatus: MailboxSyncStatus.deleting },
-		});
-		const settled = await seedMailbox(store, account, "Work");
-
-		assert.equal(
-			await isMailboxMutationInFlight(
-				store.mailbox,
-				account.accountId,
-				deleting.mailboxId,
-			),
-			true,
-		);
-		assert.equal(
-			await isMailboxMutationInFlight(
-				store.mailbox,
-				account.accountId,
-				settled.mailboxId,
-			),
-			false,
-		);
-		assert.equal(
-			await isMailboxMutationInFlight(
-				store.mailbox,
-				account.accountId,
-				"mbx-gone",
-			),
-			true,
-		);
-		await store.close();
-	});
-});

package/src/mailbox-queue.ts

@@ -1,397 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
-import type {
-	CreateMailboxInput,
-	CreateMailboxResult,
-	IMailboxRepository,
-	MailboxItem,
-} from "@remit/data-ports";
-import { NotFoundError } from "@remit/data-ports/errors";
-import { MailboxSyncStatus } from "@remit/domain-enums";
-import { createQueueProducer } from "@remit/sqs-client/producer";
-import {
-	INTENT_RECORDABLE_FROM,
-	recordedByRename,
-	refuseContestedIntent,
-} from "./mailbox-intent.js";
-
-/**
- * MAILBOX_CREATE event structure (matches remit-imap-worker/events.ts)
- */
-interface MailboxCreateEvent {
-	type: "MAILBOX_CREATE";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	mailboxId: string;
-	path: string;
-	subscribe?: boolean;
-}
-
-/**
- * MAILBOX_RENAME event structure (matches remit-imap-worker/events.ts)
- */
-interface MailboxRenameEvent {
-	type: "MAILBOX_RENAME";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	mailboxId: string;
-	oldPath: string;
-	newPath: string;
-}
-
-/**
- * MAILBOX_DELETE event structure (matches remit-imap-worker/events.ts)
- */
-interface MailboxDeleteEvent {
-	type: "MAILBOX_DELETE";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	mailboxId: string;
-	path: string;
-}
-
-type MailboxManagementEvent =
-	| MailboxCreateEvent
-	| MailboxRenameEvent
-	| MailboxDeleteEvent;
-
-/**
- * Logger interface
- */
-export interface MailboxQueueLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: MailboxQueueLogger = {
-	info: () => {},
-	error: () => {},
-};
-
-/**
- * Input for creating a mailbox via the queue service
- */
-export type CreateMailboxQueueInput = Omit<CreateMailboxInput, "syncStatus">;
-
-/**
- * Configuration for MailboxQueueService
- */
-export interface MailboxQueueConfig {
-	mailboxService: IMailboxRepository;
-	sqsQueueUrl: string;
-	sqsEndpoint?: string;
-	logger?: MailboxQueueLogger;
-}
-
-/**
- * Service for mailbox management with automatic IMAP sync queueing.
- *
- * Implements optimistic local-first pattern:
- * 1. Updates local state immediately
- * 2. Enqueues mailbox management event to SQS for worker to sync to IMAP
- *
- * This follows the same pattern as FlagQueueService (RFC 014).
- */
-export class MailboxQueueService {
-	private mailboxService: IMailboxRepository;
-	private sqs: SQSClient;
-	private queueUrl: string;
-	private log: MailboxQueueLogger;
-
-	constructor(config: MailboxQueueConfig) {
-		const { mailboxService, sqsQueueUrl, sqsEndpoint } = config;
-		this.mailboxService = mailboxService;
-		this.queueUrl = sqsQueueUrl;
-		this.log = config.logger ?? noopLogger;
-
-		this.sqs = createQueueProducer({
-			queueUrl: sqsQueueUrl,
-			endpoint: sqsEndpoint,
-		});
-	}
-
-	/**
-	 * Create a new mailbox.
-	 * Updates local state (with syncStatus=pending) and enqueues IMAP CREATE.
-	 *
-	 * @param input - The mailbox creation input (without syncStatus)
-	 * @param accountId - The account ID for the IMAP sync event
-	 * @param subscribe - Whether to subscribe to the mailbox after creation
-	 * @returns The created mailbox, or `PathTaken` when the account already has a folder at that path
-	 */
-	createMailbox = async (
-		input: CreateMailboxQueueInput,
-		accountId: string,
-		subscribe?: boolean,
-	): Promise<CreateMailboxResult> => {
-		const created = await this.mailboxService.create({
-			...input,
-			syncStatus: MailboxSyncStatus.pending,
-		});
-		if (created.outcome === "PathTaken") return created;
-		const { mailbox } = created;
-
-		this.log.info(
-			{ mailboxId: mailbox.mailboxId, path: mailbox.fullPath },
-			"Created mailbox (local)",
-		);
-
-		// Enqueue IMAP sync
-		await this.enqueueEvent({
-			type: "MAILBOX_CREATE",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			accountId,
-			mailboxId: mailbox.mailboxId,
-			path: mailbox.fullPath,
-			subscribe,
-		});
-
-		return created;
-	};
-
-	/**
-	 * Record a rename intent over the folder and every descendant, then enqueue
-	 * IMAP RENAME.
-	 *
-	 * The target is recorded, not the path (D2): every row keeps the `fullPath`
-	 * the server holds and takes its own rewritten target in `pendingPath`, so a
-	 * rename that never lands needs no unwinding — dropping `pendingPath` is the
-	 * whole revert — and nothing that resolves a folder path from a row can
-	 * resolve one the server does not have.
-	 *
-	 * @param mailboxId - The mailbox to rename
-	 * @param newPath - The path the rename is aiming at
-	 * @param accountId - The account ID for the IMAP sync event
-	 * @returns The folder that was named, carrying its recorded target
-	 */
-	renameMailbox = async (
-		mailboxId: string,
-		newPath: string,
-		accountId: string,
-	): Promise<MailboxItem> => {
-		// Get current mailbox to capture old path
-		const mailbox = await this.mailboxService.get(accountId, mailboxId);
-		const oldPath = mailbox.fullPath;
-
-		// One intent over the folder and every descendant, in one batch:
-		// IMAP RENAME moves the subtree in one command, so a partially recorded
-		// rename is the state that produced today's phantom rows (D6). A
-		// descendant already mid-mutation refuses the whole rename.
-		const written = await this.mailboxService.transitionSubtree(
-			accountId,
-			mailboxId,
-			{
-				from: INTENT_RECORDABLE_FROM,
-				to: MailboxSyncStatus.pending,
-				newPath,
-			},
-		);
-		if (!written) {
-			return refuseContestedIntent(
-				this.mailboxService,
-				accountId,
-				mailboxId,
-				"subtree",
-			);
-		}
-		const updated = written.find((row) => row.mailboxId === mailboxId);
-		if (!updated) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
-
-		this.log.info(
-			{
-				accountId,
-				mailboxId,
-				intent: "rename",
-				from: mailbox.syncStatus,
-				to: MailboxSyncStatus.pending,
-				oldPath,
-				newPath,
-				subtreeSize: written.length,
-			},
-			"Recorded rename intent",
-		);
-
-		// Enqueue IMAP sync
-		await this.enqueueEvent({
-			type: "MAILBOX_RENAME",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			accountId,
-			mailboxId,
-			oldPath,
-			newPath,
-		});
-
-		return updated;
-	};
-
-	/**
-	 * The route out of a failed rename or a failed delete that keeps the folder
-	 * as it is (T10, T11): the recorded target is dropped and the row settles
-	 * back to `synced`. Nothing is enqueued — `fullPath` was never written, so
-	 * the server has nothing to undo.
-	 *
-	 * Reached without new API surface, from a PATCH whose `fullPath` equals the
-	 * row's confirmed one. From `synced` it is a no-op; from a state with a
-	 * mutation in flight it is a 409, because dismissing an intent that is still
-	 * running would leave the settle with no row to write.
-	 */
-	dismissMailboxIntent = async (
-		mailboxId: string,
-		accountId: string,
-	): Promise<MailboxItem> => {
-		const current = await this.mailboxService.get(accountId, mailboxId);
-		if (current.syncStatus === MailboxSyncStatus.synced) return current;
-		if (current.syncStatus !== MailboxSyncStatus.failed) {
-			return refuseContestedIntent(
-				this.mailboxService,
-				accountId,
-				mailboxId,
-				"folder",
-			);
-		}
-
-		// A failed rename was recorded over a subtree, so it is dismissed over the
-		// same one. A failed delete carries no target and was recorded on the
-		// folder alone, so there is nothing else to clear.
-		const target = current.pendingPath;
-		const alsoRecorded =
-			target === undefined
-				? []
-				: (
-						await this.mailboxService.findBySyncStatus(
-							accountId,
-							MailboxSyncStatus.failed,
-						)
-					).filter(
-						(row) =>
-							row.mailboxId !== mailboxId &&
-							recordedByRename(
-								row,
-								current.fullPath,
-								target,
-								current.hierarchyDelimiter,
-							),
-					);
-
-		let dismissed: MailboxItem | undefined;
-		// The named folder first, so a caller always gets back the row it asked
-		// about. Each write carries its own predicate, so a row somebody else
-		// moved between the read and the write is skipped, not overwritten (D3).
-		for (const row of [current, ...alsoRecorded]) {
-			const written = await this.mailboxService.transition(
-				accountId,
-				row.mailboxId,
-				{
-					from: [MailboxSyncStatus.failed],
-					wherePendingPath: row.pendingPath ?? null,
-					to: MailboxSyncStatus.synced,
-				},
-			);
-			if (row.mailboxId === mailboxId) dismissed = written ?? undefined;
-			this.log.info(
-				{
-					accountId,
-					mailboxId: row.mailboxId,
-					intent: "dismiss",
-					from: MailboxSyncStatus.failed,
-					to: MailboxSyncStatus.synced,
-					outcome: written ? "settled" : "superseded",
-				},
-				"Dismissed folder intent",
-			);
-		}
-
-		if (dismissed) return dismissed;
-		// The row moved between the read and its write. Re-read rather than
-		// reporting a dismissal that did not happen.
-		return this.mailboxService.get(accountId, mailboxId);
-	};
-
-	/**
-	 * Record a delete intent (T7) and enqueue IMAP DELETE.
-	 *
-	 * The row stays at `deleting` and stays visible until the worker confirms the
-	 * server delete and removes it with the folder's mail (D8, D11). The enqueue
-	 * happens only after the transition wins, and an enqueue failure stays thrown
-	 * — a 500 to the caller, loud — rather than being swallowed or rolled back.
-	 *
-	 * @param mailboxId - The mailbox to delete
-	 * @param accountId - The account ID for the IMAP sync event
-	 */
-	deleteMailbox = async (
-		mailboxId: string,
-		accountId: string,
-	): Promise<void> => {
-		// Get current mailbox to capture path
-		const mailbox = await this.mailboxService.get(accountId, mailboxId);
-
-		const recorded = await this.mailboxService.transition(
-			accountId,
-			mailboxId,
-			{ from: INTENT_RECORDABLE_FROM, to: MailboxSyncStatus.deleting },
-		);
-		if (!recorded) {
-			await refuseContestedIntent(
-				this.mailboxService,
-				accountId,
-				mailboxId,
-				"folder",
-			);
-		}
-
-		this.log.info(
-			{
-				accountId,
-				mailboxId,
-				intent: "delete",
-				from: mailbox.syncStatus,
-				to: MailboxSyncStatus.deleting,
-				path: mailbox.fullPath,
-			},
-			"Recorded delete intent",
-		);
-
-		// Enqueue IMAP sync
-		await this.enqueueEvent({
-			type: "MAILBOX_DELETE",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			accountId,
-			mailboxId,
-			path: mailbox.fullPath,
-		});
-	};
-
-	/**
-	 * Enqueue a mailbox management event to SQS.
-	 *
-	 * FIFO queues require MessageGroupId; standard queues reject it. We detect
-	 * FIFO queues by the `.fifo` suffix on the queue URL and scope ordering to
-	 * the account so events for different accounts can be processed in parallel.
-	 */
-	private enqueueEvent = async (
-		event: MailboxManagementEvent,
-	): Promise<void> => {
-		const useFifo = this.queueUrl.endsWith(".fifo");
-		await this.sqs.send(
-			new SendMessageCommand({
-				QueueUrl: this.queueUrl,
-				MessageBody: JSON.stringify(event),
-				...(useFifo && {
-					MessageGroupId: event.accountId,
-					MessageDeduplicationId: `${event.type}:${event.mailboxId}:${event.eventId}`,
-				}),
-			}),
-		);
-
-		this.log.info(
-			{ eventId: event.eventId, type: event.type, mailboxId: event.mailboxId },
-			`Enqueued ${event.type} event`,
-		);
-	};
-}

package/src/mailbox-rename-intent.test.ts

@@ -1,220 +0,0 @@
-import assert from "node:assert/strict";
-import { afterEach, beforeEach, describe, it } from "node:test";
-import type { AccountItem, MailboxItem } from "@remit/data-ports";
-import { MailboxSyncStatus } from "@remit/domain-enums";
-import { MailboxQueueService } from "./mailbox-queue.js";
-import {
-	beforeNext,
-	captureQueue,
-	openStore,
-	type QueueCapture,
-	type QueuedEvent,
-	type Store,
-	seedAccount,
-	seedMailbox,
-} from "./test-helpers/test-store.js";
-
-let store: Store;
-let capture: QueueCapture;
-let queue: QueuedEvent[];
-let account: AccountItem;
-
-beforeEach(async () => {
-	capture = captureQueue();
-	queue = capture.sent;
-	store = await openStore();
-	account = await seedAccount(store);
-});
-
-afterEach(async () => {
-	capture.restore();
-	await store.close();
-});
-
-const folder = async (
-	fullPath: string,
-	state?: { syncStatus: MailboxItem["syncStatus"]; pendingPath?: string },
-): Promise<MailboxItem> => {
-	const mailbox = await seedMailbox(store, account, fullPath);
-	if (!state) return mailbox;
-	const moved = await store.mailbox.transition(
-		account.accountId,
-		mailbox.mailboxId,
-		{
-			from: [MailboxSyncStatus.synced],
-			to: state.syncStatus,
-			set: state.pendingPath ? { pendingPath: state.pendingPath } : {},
-		},
-	);
-	if (!moved) throw new Error(`could not put ${fullPath} in its state`);
-	return moved;
-};
-
-const queueService = () =>
-	new MailboxQueueService({
-		mailboxService: store.mailbox,
-		sqsQueueUrl: "http://localhost:4566/000000000000/mailbox",
-	});
-
-const rename = (mailbox: MailboxItem, newPath: string) =>
-	queueService().renameMailbox(mailbox.mailboxId, newPath, account.accountId);
-
-const dismiss = (mailbox: MailboxItem) =>
-	queueService().dismissMailboxIntent(mailbox.mailboxId, account.accountId);
-
-const current = (mailbox: MailboxItem) =>
-	store.mailbox.get(account.accountId, mailbox.mailboxId);
-
-const rejectsWith409 = (message: string) => (error: unknown) =>
-	(error as { statusCode?: number }).statusCode === 409 &&
-	(error as Error).message === message;
-
-describe("MailboxQueueService.renameMailbox records the intent", () => {
-	it("records the target over the subtree and leaves every confirmed path alone", async () => {
-		const parent = await folder("Work");
-		const child = await folder("Work/2026");
-		const lookalike = await folder("Workshop");
-
-		const renamed = await rename(parent, "Projects");
-
-		assert.equal(renamed.mailboxId, parent.mailboxId);
-		assert.equal((await current(parent)).fullPath, "Work");
-		assert.equal((await current(parent)).pendingPath, "Projects");
-		const movedChild = await current(child);
-		assert.equal(movedChild.fullPath, "Work/2026");
-		assert.equal(movedChild.pendingPath, "Projects/2026");
-		assert.equal(movedChild.syncStatus, MailboxSyncStatus.pending);
-		assert.equal(
-			(await current(lookalike)).syncStatus,
-			MailboxSyncStatus.synced,
-		);
-		assert.equal((await current(lookalike)).pendingPath, undefined);
-	});
-
-	it("records the path the RENAME carries, `$` patterns and all", async () => {
-		const parent = await folder("Work");
-		const child = await folder("Work/2026");
-
-		await rename(parent, "Q1$&Q2");
-
-		assert.equal((await current(child)).pendingPath, "Q1$&Q2/2026");
-		assert.deepEqual(
-			queue.map((event) => event.body.newPath),
-			["Q1$&Q2"],
-		);
-	});
-
-	it("records a retry from a failed rename onto the same row", async () => {
-		const parent = await folder("Work", {
-			syncStatus: MailboxSyncStatus.failed,
-			pendingPath: "Projects",
-		});
-
-		await rename(parent, "Projects");
-
-		const retried = await current(parent);
-		assert.equal(retried.syncStatus, MailboxSyncStatus.pending);
-		assert.equal(retried.pendingPath, "Projects");
-	});
-
-	it("refuses the whole subtree with a 409 naming the descendant that blocks it", async () => {
-		const parent = await folder("Archive");
-		await folder("Archive/2025/Receipts", {
-			syncStatus: MailboxSyncStatus.pending,
-			pendingPath: "Archive/2025/Bonnen",
-		});
-
-		await assert.rejects(
-			rename(parent, "Archief"),
-			rejectsWith409(
-				'A rename is in progress for "Archive/2025/Receipts", inside this folder.',
-			),
-		);
-
-		assert.equal((await current(parent)).syncStatus, MailboxSyncStatus.synced);
-		assert.equal(queue.length, 0);
-	});
-
-	it("refuses with a 409 naming the folder's own delete", async () => {
-		const parent = await folder("Archive", {
-			syncStatus: MailboxSyncStatus.deleting,
-		});
-
-		await assert.rejects(
-			rename(parent, "Archief"),
-			rejectsWith409('A delete is already in progress for "Archive".'),
-		);
-	});
-
-	it("answers 404 when the folder went between the read and the intent", async () => {
-		const parent = await folder("Work");
-		beforeNext(store.mailbox, "transitionSubtree", () =>
-			store.mailbox.delete(account.accountId, parent.mailboxId),
-		);
-
-		await assert.rejects(
-			rename(parent, "Projects"),
-			(error: unknown) => (error as Error).name === "NotFoundError",
-		);
-	});
-});
-
-describe("MailboxQueueService.dismissMailboxIntent", () => {
-	it("clears a failed rename over its whole subtree and enqueues nothing", async () => {
-		const parent = await folder("Work", {
-			syncStatus: MailboxSyncStatus.failed,
-			pendingPath: "Projects",
-		});
-		const child = await folder("Work/2026", {
-			syncStatus: MailboxSyncStatus.failed,
-			pendingPath: "Projects/2026",
-		});
-		const other = await folder("Other", {
-			syncStatus: MailboxSyncStatus.failed,
-			pendingPath: "Projects/Old",
-		});
-
-		const dismissed = await dismiss(parent);
-
-		assert.equal(dismissed.syncStatus, MailboxSyncStatus.synced);
-		for (const mailbox of [parent, child]) {
-			const row = await current(mailbox);
-			assert.equal(row.syncStatus, MailboxSyncStatus.synced);
-			assert.equal(row.pendingPath, undefined);
-		}
-		assert.equal((await current(other)).pendingPath, "Projects/Old");
-		assert.equal(queue.length, 0);
-	});
-
-	it("dismisses a failed delete on the named folder alone", async () => {
-		const parent = await folder("Work", {
-			syncStatus: MailboxSyncStatus.failed,
-		});
-		const child = await folder("Work/2026", {
-			syncStatus: MailboxSyncStatus.failed,
-		});
-
-		await dismiss(parent);
-
-		assert.equal((await current(parent)).syncStatus, MailboxSyncStatus.synced);
-		assert.equal((await current(child)).syncStatus, MailboxSyncStatus.failed);
-	});
-
-	it("leaves a folder with nothing to dismiss as it is", async () => {
-		const work = await folder("Work");
-
-		assert.equal((await dismiss(work)).syncStatus, MailboxSyncStatus.synced);
-	});
-
-	it("refuses with a 409 while a mutation is still in flight", async () => {
-		const work = await folder("Work", {
-			syncStatus: MailboxSyncStatus.pending,
-			pendingPath: "Projects",
-		});
-
-		await assert.rejects(
-			dismiss(work),
-			rejectsWith409('A rename is in progress for "Work".'),
-		);
-	});
-});