@remit/mailbox-service 0.0.1

package/src/mailbox-management.ts

@@ -0,0 +1,235 @@
+import type { IMailboxRepository } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import type { IImapConnection } from "./types.js";
+
+/**
+ * Input for creating a mailbox
+ */
+export interface CreateMailboxInput {
+	accountId: string;
+	path: string;
+	subscribe?: boolean;
+}
+
+/**
+ * Input for renaming a mailbox
+ */
+export interface RenameMailboxInput {
+	mailboxId: string;
+	newPath: string;
+}
+
+/**
+ * Input for deleting a mailbox
+ */
+export interface DeleteMailboxInput {
+	mailboxId: string;
+	force?: boolean;
+}
+
+/**
+ * Result of syncing mailbox operation to IMAP
+ */
+export interface MailboxManagementSyncResult {
+	success: boolean;
+	error?: string;
+}
+
+/**
+ * Logger interface for MailboxManagementService
+ */
+export interface MailboxManagementLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
+}
+
+const noopLogger: MailboxManagementLogger = {
+	info: () => {},
+	error: () => {},
+};
+
+/**
+ * Parse a mailbox path to extract name and parent path
+ */
+export const parseMailboxPath = (
+	path: string,
+	delimiter = "/",
+): { name: string; parent: string | null; depth: number } => {
+	const parts = path.split(delimiter);
+	return {
+		name: parts[parts.length - 1],
+		parent: parts.length > 1 ? parts.slice(0, -1).join(delimiter) : null,
+		depth: parts.length,
+	};
+};
+
+/**
+ * Validate mailbox path for invalid characters and operations
+ */
+export const validateMailboxPath = (path: string): void => {
+	if (!path || path.trim().length === 0) {
+		throw new Error("Mailbox path cannot be empty");
+	}
+
+	// Check for double delimiters
+	if (path.includes("//")) {
+		throw new Error("Mailbox path cannot contain empty hierarchy levels");
+	}
+
+	// Check for leading/trailing delimiters
+	if (path.startsWith("/") || path.endsWith("/")) {
+		throw new Error(
+			"Mailbox path cannot start or end with hierarchy delimiter",
+		);
+	}
+};
+
+/**
+ * Validate that an operation can be performed on a mailbox path
+ */
+export const validateMailboxOperation = (
+	operation: "delete" | "rename",
+	path: string,
+): void => {
+	if (path.toUpperCase() === "INBOX" && operation === "delete") {
+		throw new Error("Cannot delete INBOX");
+	}
+};
+
+/**
+ * Service for managing mailbox operations (create, rename, delete).
+ *
+ * Implements an optimistic local-first pattern:
+ * 1. Updates are applied locally first (DynamoDB)
+ * 2. Changes are queued for IMAP sync via SQS
+ * 3. Worker processes queue and syncs to IMAP server
+ */
+export class MailboxManagementService {
+	private log: MailboxManagementLogger;
+
+	constructor(
+		private mailboxService: IMailboxRepository,
+		logger?: MailboxManagementLogger,
+	) {
+		this.log = logger ?? noopLogger;
+	}
+
+	/**
+	 * Sync a CREATE operation to IMAP.
+	 * Called by worker after dequeuing MAILBOX_CREATE event.
+	 *
+	 * @param accountId - Account that owns the mailbox (tenant scope)
+	 * @param mailboxId - ID of the mailbox to create
+	 * @param path - Path of the mailbox to create
+	 * @param getConnection - Factory to get IMAP connection
+	 * @param subscribe - Whether to subscribe after creation
+	 */
+	syncCreate = async (
+		accountId: string,
+		mailboxId: string,
+		path: string,
+		getConnection: () => Promise<IImapConnection>,
+		subscribe?: boolean,
+	): Promise<MailboxManagementSyncResult> => {
+		const connection = await getConnection();
+
+		const result = await connection.createMailbox(path);
+
+		this.log.info(
+			{ mailboxId, path, created: result.created },
+			"Created mailbox on IMAP server",
+		);
+
+		if (subscribe) {
+			await connection.subscribeMailbox(path);
+			this.log.info({ mailboxId, path }, "Subscribed to mailbox");
+		}
+
+		// Refresh mailbox list to get UIDVALIDITY and other attributes
+		const mailboxes = await connection.listMailboxes();
+		const mailboxInfo = mailboxes.find((m) => m.fullPath === path);
+
+		if (mailboxInfo) {
+			// Open the mailbox to get UIDVALIDITY and other status info
+			const status = await connection.openBox(path, true);
+
+			await this.mailboxService.update(accountId, mailboxId, {
+				uidValidity: status.uidvalidity,
+				uidNext: status.uidnext,
+				messageCount: status.messages.total,
+				syncStatus: MailboxSyncStatus.synced,
+			});
+
+			await connection.closeBox();
+		} else {
+			// Mark as synced even if we couldn't get full info
+			await this.mailboxService.update(accountId, mailboxId, {
+				syncStatus: MailboxSyncStatus.synced,
+			});
+		}
+
+		return { success: true };
+	};
+
+	/**
+	 * Sync a RENAME operation to IMAP.
+	 * Called by worker after dequeuing MAILBOX_RENAME event.
+	 *
+	 * @param accountId - Account that owns the mailbox (tenant scope)
+	 * @param mailboxId - ID of the mailbox to rename
+	 * @param oldPath - Current path of the mailbox
+	 * @param newPath - New path for the mailbox
+	 * @param getConnection - Factory to get IMAP connection
+	 */
+	syncRename = async (
+		accountId: string,
+		mailboxId: string,
+		oldPath: string,
+		newPath: string,
+		getConnection: () => Promise<IImapConnection>,
+	): Promise<MailboxManagementSyncResult> => {
+		const connection = await getConnection();
+
+		await connection.renameMailbox(oldPath, newPath);
+
+		this.log.info(
+			{ mailboxId, oldPath, newPath },
+			"Renamed mailbox on IMAP server",
+		);
+
+		// Clear oldPath and mark as synced
+		await this.mailboxService.update(accountId, mailboxId, {
+			oldPath: undefined,
+			syncStatus: MailboxSyncStatus.synced,
+		});
+
+		return { success: true };
+	};
+
+	/**
+	 * Sync a DELETE operation to IMAP.
+	 * Called by worker after dequeuing MAILBOX_DELETE event.
+	 *
+	 * @param accountId - Account that owns the mailbox (tenant scope)
+	 * @param mailboxId - ID of the mailbox to delete
+	 * @param path - Path of the mailbox to delete
+	 * @param getConnection - Factory to get IMAP connection
+	 */
+	syncDelete = async (
+		accountId: string,
+		mailboxId: string,
+		path: string,
+		getConnection: () => Promise<IImapConnection>,
+	): Promise<MailboxManagementSyncResult> => {
+		const connection = await getConnection();
+
+		await connection.deleteMailbox(path);
+
+		this.log.info({ mailboxId, path }, "Deleted mailbox on IMAP server");
+
+		// Delete the mailbox entity from DynamoDB
+		await this.mailboxService.delete(accountId, mailboxId);
+
+		return { success: true };
+	};
+}

package/src/mailbox-queue.ts

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
+import type {
+	CreateMailboxInput,
+	IMailboxRepository,
+	MailboxItem,
+} from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { createQueueProducer } from "@remit/sqs-client/producer";
+
+/**
+ * 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 DynamoDB 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
+	 */
+	createMailbox = async (
+		input: CreateMailboxQueueInput,
+		accountId: string,
+		subscribe?: boolean,
+	): Promise<MailboxItem> => {
+		// Create local mailbox with pending status
+		const mailbox = await this.mailboxService.create({
+			...input,
+			syncStatus: MailboxSyncStatus.pending,
+		});
+
+		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 mailbox;
+	};
+
+	/**
+	 * Rename a mailbox.
+	 * Updates local state (including children) and enqueues IMAP RENAME.
+	 *
+	 * @param mailboxId - The mailbox to rename
+	 * @param newPath - The new path for the mailbox
+	 * @param accountId - The account ID for the IMAP sync event
+	 * @returns The updated mailbox
+	 */
+	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;
+
+		// Update the mailbox path and set syncStatus to pending
+		const updated = await this.mailboxService.update(accountId, mailboxId, {
+			fullPath: newPath,
+			syncStatus: MailboxSyncStatus.pending,
+		});
+
+		// Update child mailbox paths
+		await this.mailboxService.renameChildPaths(
+			mailbox.accountId,
+			oldPath,
+			newPath,
+			mailbox.hierarchyDelimiter,
+		);
+
+		this.log.info({ mailboxId, oldPath, newPath }, "Renamed mailbox (local)");
+
+		// Enqueue IMAP sync
+		await this.enqueueEvent({
+			type: "MAILBOX_RENAME",
+			eventId: randomUUID(),
+			timestamp: Date.now(),
+			accountId,
+			mailboxId,
+			oldPath,
+			newPath,
+		});
+
+		return updated;
+	};
+
+	/**
+	 * Delete a mailbox.
+	 * Marks for deletion (syncStatus=deleting) and enqueues IMAP DELETE.
+	 *
+	 * @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);
+
+		// Mark as deleting (soft delete - worker will do actual delete after IMAP sync)
+		await this.mailboxService.update(accountId, mailboxId, {
+			syncStatus: MailboxSyncStatus.deleting,
+		});
+
+		this.log.info(
+			{ mailboxId, path: mailbox.fullPath },
+			"Marked mailbox for deletion (local)",
+		);
+
+		// 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-sync.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IMailboxRepository,
+	IMailboxSpecialUseRepository,
+} from "@remit/data-ports";
+import { MailboxCursorState, MailboxSpecialUse } from "@remit/domain-enums";
+import { parseImapAttributes } from "./attribute-mapper.js";
+import { MailboxSyncService } from "./mailbox-sync.js";
+import type { IImapConnection, ImapNamespaces } from "./types.js";
+
+describe("parseImapAttributes – locale invariance (#194)", () => {
+	it("recognizes \\Sent regardless of folder name", () => {
+		const dutch = parseImapAttributes(["\\HasNoChildren", "\\Sent"]);
+		assert.deepEqual(dutch.specialUse, [MailboxSpecialUse.Sent]);
+
+		const english = parseImapAttributes(["\\Sent"]);
+		assert.deepEqual(english.specialUse, [MailboxSpecialUse.Sent]);
+	});
+
+	it("recognizes \\Drafts on a localized 'Concepten' folder", () => {
+		// IMAP server tells us the flag — the folder name is irrelevant.
+		const parsed = parseImapAttributes(["\\Drafts"]);
+		assert.deepEqual(parsed.specialUse, [MailboxSpecialUse.Drafts]);
+	});
+
+	it("returns an empty list when no flag is present", () => {
+		// A real user folder like Outlook NL's "Nieuwsbrieven" carries no
+		// SPECIAL-USE attributes — leave it untouched downstream.
+		const parsed = parseImapAttributes(["\\HasNoChildren"]);
+		assert.deepEqual(parsed.specialUse, []);
+	});
+
+	it("normalizes case: \\sent is treated the same as \\Sent", () => {
+		const parsed = parseImapAttributes(["\\sent"]);
+		assert.deepEqual(parsed.specialUse, [MailboxSpecialUse.Sent]);
+	});
+});
+
+describe("MailboxSyncService.syncMailboxes — UIDVALIDITY cursor detection (#1272)", () => {
+	const namespaces: ImapNamespaces = {
+		personal: [{ prefix: "", delimiter: "/" }],
+		other: [],
+		shared: [],
+	};
+
+	const buildConnection = (uidValidity: number): IImapConnection =>
+		({
+			getNamespaces: async () => namespaces,
+			listMailboxes: async () => [
+				{
+					fullPath: "INBOX",
+					name: "INBOX",
+					delimiter: "/",
+					attributes: [],
+					parentPath: null,
+				},
+			],
+			getMailboxStatus: async () => ({
+				messages: 5,
+				recent: 0,
+				unseen: 1,
+				uidNext: 100,
+				uidValidity,
+				highestModseq: 0,
+				deletedCount: 0,
+			}),
+		}) as unknown as IImapConnection;
+
+	const buildServices = (
+		existingUidValidity: number,
+		existingCursorState?: string,
+	) => {
+		const updateCalls: Array<Record<string, unknown>> = [];
+		const mailboxService = {
+			listByAccount: async () => ({
+				items: [
+					{
+						mailboxId: "mbx-1",
+						fullPath: "INBOX",
+						uidNext: 100,
+						uidValidity: existingUidValidity,
+						messageCount: 5,
+						unseenCount: 1,
+						deletedCount: 0,
+						highestModseq: 0,
+						specialUse: undefined,
+						cursorState: existingCursorState,
+					},
+				],
+				continuationToken: undefined,
+			}),
+			update: async (
+				_accountId: string,
+				_mailboxId: string,
+				patch: Record<string, unknown>,
+			) => {
+				updateCalls.push(patch);
+				return {};
+			},
+			delete: async () => undefined,
+			create: async () => ({}),
+		} as unknown as IMailboxRepository;
+
+		const specialUseService = {
+			listByMailboxId: async () => [],
+			deleteByMailboxId: async () => undefined,
+			createMany: async () => undefined,
+		} as unknown as IMailboxSpecialUseRepository;
+
+		return { mailboxService, specialUseService, updateCalls };
+	};
+
+	it("trips cursor_invalid when the STATUS sweep observes a changed UIDVALIDITY", async () => {
+		const { mailboxService, specialUseService, updateCalls } = buildServices(1);
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+		const connection = buildConnection(2);
+
+		await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+		const uidValidityUpdate = updateCalls.find((c) => "uidValidity" in c);
+		assert.ok(uidValidityUpdate, "expected the sweep to write the mailbox");
+		assert.equal(
+			uidValidityUpdate?.cursorState,
+			MailboxCursorState.cursor_invalid,
+		);
+	});
+
+	it("does not write anything when UIDVALIDITY (and everything else) is unchanged", async () => {
+		const { mailboxService, specialUseService, updateCalls } = buildServices(1);
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+		const connection = buildConnection(1);
+
+		await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+		assert.equal(updateCalls.length, 0);
+	});
+
+	it("does not re-trip (no cursorState write) when the mailbox is already cursor_invalid", async () => {
+		const { mailboxService, specialUseService, updateCalls } = buildServices(
+			1,
+			MailboxCursorState.cursor_invalid,
+		);
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+		const connection = buildConnection(2);
+
+		await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+		const uidValidityUpdate = updateCalls.find((c) => "uidValidity" in c);
+		assert.ok(uidValidityUpdate);
+		assert.equal("cursorState" in (uidValidityUpdate ?? {}), false);
+	});
+});