@remit/imap-worker 0.0.15 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -20,7 +20,7 @@
     "bundle": "esbuild src/index.ts --sourcemap --bundle --platform=node --format=esm --outfile=dist/index.js",
     "cli": "node --env-file=../../localhost-dev-aws.env src/cli.ts",
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=70 --test 'src/**/*.test.ts'",
+    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=75 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run",
     "dev": "node --import tsx src/e2e-processor-shim.ts"
   },

package/src/handlers/append-sent-message.test.ts

@@ -0,0 +1,216 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import type { AppendSentMessageEvent } from "../events.js";
+import {
+	type AppendSentMessageDeps,
+	handleAppendSentMessage,
+} from "./append-sent-message.js";
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	fatal: () => {},
+	trace: () => {},
+	child: () => noopLog,
+} as unknown as Logger;
+
+interface Call {
+	method: string;
+	args: unknown[];
+}
+
+interface Harness {
+	calls: Call[];
+	account: {
+		accountId: string;
+		accountConfigId: string;
+		deletedAt?: number;
+	};
+	outbox: Record<string, unknown>;
+	specialUseSent: { mailboxId: string; fullPath: string } | null;
+	mailboxes: { mailboxId: string; fullPath: string }[];
+	append: (
+		path: string,
+		raw: Buffer,
+		flags: string[],
+	) => Promise<{ uid: number; uidValidity: number }>;
+	disconnectCount: number;
+}
+
+let h: Harness;
+
+const record =
+	(method: string) =>
+	async (...args: unknown[]) => {
+		h.calls.push({ method, args });
+	};
+
+const fresh = (): Harness => ({
+	calls: [],
+	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
+	outbox: {
+		status: "sent",
+		fromName: "Alice",
+		fromAddress: "alice@example.com",
+		toAddresses: ["bob@example.com"],
+		ccAddresses: ["carol@example.com"],
+		subject: "Quarterly numbers",
+		textBody: "See attached.",
+		messageIdValue: "generated-id@example.com",
+		references: ["parent@example.com"],
+		inReplyTo: "parent@example.com",
+		sentAt: 1700000000000,
+	},
+	specialUseSent: { mailboxId: "sent-mbx", fullPath: "Sent" },
+	mailboxes: [
+		{ mailboxId: "inbox-mbx", fullPath: "INBOX" },
+		{ mailboxId: "sent-items-mbx", fullPath: "Sent Items" },
+	],
+	append: async (path, raw, flags) => {
+		h.calls.push({ method: "connection.append", args: [path, raw, flags] });
+		return { uid: 55, uidValidity: 7 };
+	},
+	disconnectCount: 0,
+});
+
+const deps = (): AppendSentMessageDeps =>
+	({
+		getClient: async () => ({
+			account: {
+				get: async (accountId: string) => {
+					h.calls.push({ method: "account.get", args: [accountId] });
+					return h.account;
+				},
+			},
+			outboxMessage: {
+				get: async () => h.outbox,
+				delete: record("outboxMessage.delete"),
+			},
+			mailboxSpecialUse: {
+				findBySpecialUse: async () => h.specialUseSent,
+			},
+			mailbox: {
+				listByAccount: async () => ({ items: h.mailboxes }),
+			},
+			secrets: {},
+		}),
+		buildLifecycleDeps: () => ({}),
+		withOAuthLifecycle: async (
+			_deps: unknown,
+			_account: unknown,
+			_log: unknown,
+			cb: (credentials: unknown) => Promise<void>,
+		) => cb({}),
+		createConnectionScope: () => ({
+			getConnection: async () => ({
+				append: (path: string, raw: Buffer, flags: string[]) =>
+					h.append(path, raw, flags),
+			}),
+			disconnect: async () => {
+				h.disconnectCount += 1;
+			},
+		}),
+	}) as unknown as AppendSentMessageDeps;
+
+const event: AppendSentMessageEvent = {
+	type: "APPEND_SENT_MESSAGE",
+	accountId: "acc-1",
+	outboxMessageId: "out-1",
+} as AppendSentMessageEvent;
+
+const called = (method: string): Call[] =>
+	h.calls.filter((c) => c.method === method);
+
+describe("handleAppendSentMessage", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("appends a seen RFC822 copy to the Sent folder and drops the outbox row", async () => {
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		const append = called("connection.append")[0];
+		assert.equal(append?.args[0], "Sent");
+		assert.deepEqual(append?.args[2], ["\\Seen"]);
+		assert.deepEqual(called("outboxMessage.delete")[0]?.args, [
+			"cfg-1",
+			"out-1",
+		]);
+		assert.equal(h.disconnectCount, 1);
+	});
+
+	it("builds the message from the outbox row's own headers", async () => {
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		const raw = String(called("connection.append")[0]?.args[1] as Buffer);
+		assert.match(raw, /^From: Alice <alice@example\.com>$/m);
+		assert.match(raw, /^To: bob@example\.com$/m);
+		assert.match(raw, /^Cc: carol@example\.com$/m);
+		assert.match(raw, /^Subject: Quarterly numbers$/m);
+		assert.match(raw, /^Message-ID: <generated-id@example\.com>$/m);
+		assert.match(raw, /^In-Reply-To: <parent@example\.com>$/m);
+		assert.ok(raw.includes("See attached."));
+	});
+
+	it("uses a bare address when the outbox row carries no display name", async () => {
+		h.outbox = { ...h.outbox, fromName: undefined };
+
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		const raw = String(called("connection.append")[0]?.args[1] as Buffer);
+		assert.match(raw, /^From: alice@example\.com$/m);
+	});
+
+	it("falls back to a conventionally-named Sent folder when no special-use flag is set", async () => {
+		h.specialUseSent = null;
+
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		assert.equal(called("connection.append")[0]?.args[0], "Sent Items");
+	});
+
+	it("skips the append when the account has no Sent folder at all", async () => {
+		h.specialUseSent = null;
+		h.mailboxes = [{ mailboxId: "inbox-mbx", fullPath: "INBOX" }];
+
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		assert.equal(called("connection.append").length, 0);
+		assert.equal(called("outboxMessage.delete").length, 0);
+	});
+
+	it("skips the append while the outbox row is not yet sent", async () => {
+		h.outbox = { ...h.outbox, status: "pending" };
+
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		assert.equal(called("connection.append").length, 0);
+		assert.equal(called("outboxMessage.delete").length, 0);
+	});
+
+	it("returns early without touching the outbox when the account is soft-deleted", async () => {
+		h.account = { ...h.account, deletedAt: Date.now() };
+
+		await handleAppendSentMessage(event, noopLog, deps());
+
+		assert.equal(called("connection.append").length, 0);
+		assert.equal(called("outboxMessage.delete").length, 0);
+	});
+
+	it("keeps the outbox row when the APPEND fails so the send can be retried", async () => {
+		h.append = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			handleAppendSentMessage(event, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.equal(called("outboxMessage.delete").length, 0);
+		assert.equal(h.disconnectCount, 1);
+	});
+});

package/src/handlers/append-sent-message.ts

@@ -75,10 +75,32 @@ const buildRawMessage = async (outbox: OutboxMessageItem): Promise<Buffer> => {
 	return Buffer.concat(chunks);
 };
 
+export interface AppendSentMessageDeps {
+	getClient: typeof getClient;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	createConnectionScope: typeof createConnectionScopeWithCredentials;
+}
+
+const defaultDeps: AppendSentMessageDeps = {
+	getClient,
+	buildLifecycleDeps,
+	withOAuthLifecycle,
+	createConnectionScope: createConnectionScopeWithCredentials,
+};
+
 export const handleAppendSentMessage = async (
 	event: AppendSentMessageEvent,
 	log: Logger,
+	deps: AppendSentMessageDeps = defaultDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		outboxMessage: outboxMessageService,

package/src/handlers/empty-trash.test.ts

@@ -0,0 +1,220 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import type { EmptyTrashEvent } from "../events.js";
+import { type EmptyTrashDeps, handleEmptyTrash } from "./empty-trash.js";
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	fatal: () => {},
+	trace: () => {},
+	child: () => noopLog,
+} as unknown as Logger;
+
+interface Call {
+	method: string;
+	args: unknown[];
+}
+
+interface Connection {
+	openBox: (
+		path: string,
+		readOnly?: boolean,
+	) => Promise<{ uidvalidity: number }>;
+	search: (criteria: string[]) => Promise<number[]>;
+	deleteMessages: (uids: number[]) => Promise<void>;
+}
+
+interface Harness {
+	calls: Call[];
+	account: {
+		accountId: string;
+		accountConfigId: string;
+		deletedAt?: number;
+	} | null;
+	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
+	connection: Connection;
+	localMessages: { messageId: string }[];
+	threadMessage: { accountConfigId: string; threadMessageId: string } | null;
+	getConnectionCount: number;
+	disconnectCount: number;
+}
+
+let h: Harness;
+
+const record =
+	(method: string) =>
+	async (...args: unknown[]) => {
+		h.calls.push({ method, args });
+	};
+
+const buildConnection = (): Connection => ({
+	openBox: async () => ({ uidvalidity: 1 }),
+	search: async () => [10, 11],
+	deleteMessages: record(
+		"connection.deleteMessages",
+	) as Connection["deleteMessages"],
+});
+
+const fresh = (): Harness => ({
+	calls: [],
+	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
+	mailbox: { mailboxId: "trash-mbx", uidValidity: 1, cursorState: undefined },
+	connection: buildConnection(),
+	localMessages: [{ messageId: "msg-1" }, { messageId: "msg-2" }],
+	threadMessage: { accountConfigId: "cfg-1", threadMessageId: "tm-1" },
+	getConnectionCount: 0,
+	disconnectCount: 0,
+});
+
+const deps = (): EmptyTrashDeps =>
+	({
+		getClient: async () => ({
+			account: {
+				get: async (accountId: string) => {
+					h.calls.push({ method: "account.get", args: [accountId] });
+					return h.account;
+				},
+			},
+			message: {
+				listAllByMailbox: async () => h.localMessages,
+				delete: record("message.delete"),
+			},
+			threadMessage: {
+				findByMessageId: async () => h.threadMessage,
+				delete: record("threadMessage.delete"),
+			},
+			mailbox: {
+				get: async () => h.mailbox,
+				update: record("mailbox.update"),
+			},
+			secrets: {},
+		}),
+		buildLifecycleDeps: () => ({}),
+		withOAuthLifecycle: async (
+			_deps: unknown,
+			_account: unknown,
+			_log: unknown,
+			cb: (credentials: unknown) => Promise<void>,
+		) => cb({}),
+		createConnectionScope: () => ({
+			getConnection: async () => {
+				h.getConnectionCount += 1;
+				return h.connection;
+			},
+			disconnect: async () => {
+				h.disconnectCount += 1;
+			},
+		}),
+	}) as unknown as EmptyTrashDeps;
+
+const event: EmptyTrashEvent = {
+	type: "EMPTY_TRASH",
+	accountId: "acc-1",
+	trashMailboxId: "trash-mbx",
+	trashMailboxPath: "Trash",
+} as EmptyTrashEvent;
+
+const called = (method: string): Call[] =>
+	h.calls.filter((c) => c.method === method);
+
+describe("handleEmptyTrash", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("expunges every server uid and both local rows for each trashed message", async () => {
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.deepEqual(called("connection.deleteMessages")[0]?.args, [[10, 11]]);
+		assert.deepEqual(
+			called("message.delete").map((c) => c.args[0]),
+			["msg-1", "msg-2"],
+		);
+		assert.equal(called("threadMessage.delete").length, 2);
+		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
+	});
+
+	it("skips the IMAP expunge when the trash is already empty on the server", async () => {
+		h.connection.search = async () => [];
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(called("connection.deleteMessages").length, 0);
+		assert.equal(
+			called("message.delete").length,
+			2,
+			"local rows are still cleaned up",
+		);
+	});
+
+	it("deletes the message even when it has no thread row", async () => {
+		h.threadMessage = null;
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(called("message.delete").length, 2);
+		assert.equal(called("threadMessage.delete").length, 0);
+	});
+
+	it("returns early without connecting when the account is soft-deleted", async () => {
+		h.account = {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			deletedAt: Date.now(),
+		};
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+	});
+
+	it("throws when the account no longer exists", async () => {
+		h.account = null;
+
+		await assert.rejects(handleEmptyTrash(event, noopLog, deps()), /not found/);
+	});
+
+	it("skips without opening a connection when the cursor is rebuilding", async () => {
+		h.mailbox = {
+			mailboxId: "trash-mbx",
+			uidValidity: 1,
+			cursorState: "rebuilding",
+		};
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+		assert.equal(called("message.delete").length, 0);
+	});
+
+	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
+		h.connection.openBox = async () => ({ uidvalidity: 999 });
+
+		await handleEmptyTrash(event, noopLog, deps());
+
+		assert.equal(
+			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
+				?.cursorState,
+			"cursor_invalid",
+		);
+		assert.equal(called("message.delete").length, 0);
+		assert.equal(h.disconnectCount, 1);
+	});
+
+	it("rethrows an unclassified IMAP error so the event is retried", async () => {
+		h.connection.search = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			handleEmptyTrash(event, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.equal(h.disconnectCount, 1);
+	});
+});

package/src/handlers/empty-trash.ts

@@ -11,6 +11,20 @@ import type { EmptyTrashEvent } from "../events.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 
+export interface EmptyTrashDeps {
+	getClient: typeof getClient;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	createConnectionScope: typeof createConnectionScopeWithCredentials;
+}
+
+const defaultDeps: EmptyTrashDeps = {
+	getClient,
+	buildLifecycleDeps,
+	withOAuthLifecycle,
+	createConnectionScope: createConnectionScopeWithCredentials,
+};
+
 /**
  * Handle EMPTY_TRASH events.
  * Permanently deletes all messages in the Trash mailbox.
@@ -18,7 +32,15 @@ import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 export const handleEmptyTrash = async (
 	event: EmptyTrashEvent,
 	log: Logger,
+	deps: EmptyTrashDeps = defaultDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		message: messageService,

package/src/handlers/mailbox-management.test.ts

@@ -0,0 +1,324 @@
+import assert from "node:assert/strict";
+import { beforeEach, describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import type {
+	MailboxCreateEvent,
+	MailboxDeleteEvent,
+	MailboxRenameEvent,
+} from "../events.js";
+import {
+	type MailboxManagementDeps,
+	processMailboxManagement,
+} from "./mailbox-management.js";
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	fatal: () => {},
+	trace: () => {},
+	child: () => noopLog,
+} as unknown as Logger;
+
+interface Call {
+	method: string;
+	args: unknown[];
+}
+
+interface Connection {
+	createMailbox: (path: string) => Promise<{ created: boolean }>;
+	subscribeMailbox: (path: string) => Promise<void>;
+	listMailboxes: () => Promise<{ fullPath: string }[]>;
+	openBox: (
+		path: string,
+		readOnly?: boolean,
+	) => Promise<{
+		uidvalidity: number;
+		uidnext: number;
+		messages: { total: number };
+	}>;
+	closeBox: () => Promise<void>;
+	renameMailbox: (oldPath: string, newPath: string) => Promise<void>;
+	deleteMailbox: (path: string) => Promise<void>;
+}
+
+interface Harness {
+	calls: Call[];
+	account: {
+		accountId: string;
+		accountConfigId: string;
+		deletedAt?: number;
+	} | null;
+	connection: Connection;
+	disconnectCount: number;
+}
+
+let h: Harness;
+
+const record =
+	(method: string) =>
+	async (...args: unknown[]) => {
+		h.calls.push({ method, args });
+	};
+
+const buildConnection = (): Connection => ({
+	createMailbox: async (path: string) => {
+		h.calls.push({ method: "connection.createMailbox", args: [path] });
+		return { created: true };
+	},
+	subscribeMailbox: record("connection.subscribeMailbox"),
+	listMailboxes: async () => [{ fullPath: "Archive" }],
+	openBox: async () => ({
+		uidvalidity: 7,
+		uidnext: 42,
+		messages: { total: 3 },
+	}),
+	closeBox: record("connection.closeBox"),
+	renameMailbox: record("connection.renameMailbox"),
+	deleteMailbox: record("connection.deleteMailbox"),
+});
+
+const fresh = (): Harness => ({
+	calls: [],
+	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
+	connection: buildConnection(),
+	disconnectCount: 0,
+});
+
+const deps = (): MailboxManagementDeps =>
+	({
+		getClient: async () => ({
+			account: {
+				get: async (accountId: string) => {
+					h.calls.push({ method: "account.get", args: [accountId] });
+					return h.account;
+				},
+			},
+			mailbox: {
+				update: record("mailbox.update"),
+				delete: record("mailbox.delete"),
+			},
+			secrets: {},
+		}),
+		buildLifecycleDeps: () => ({}),
+		withOAuthLifecycle: async (
+			_deps: unknown,
+			_account: unknown,
+			_log: unknown,
+			cb: (credentials: unknown) => Promise<void>,
+		) => cb({}),
+		createConnectionScope: () => ({
+			getConnection: async () => h.connection,
+			disconnect: async () => {
+				h.disconnectCount += 1;
+			},
+		}),
+	}) as unknown as MailboxManagementDeps;
+
+const createEvent: MailboxCreateEvent = {
+	type: "MAILBOX_CREATE",
+	accountId: "acc-1",
+	mailboxId: "mbx-1",
+	path: "Archive",
+} as MailboxCreateEvent;
+
+const renameEvent: MailboxRenameEvent = {
+	type: "MAILBOX_RENAME",
+	accountId: "acc-1",
+	mailboxId: "mbx-1",
+	oldPath: "Archive",
+	newPath: "Archive 2024",
+} as MailboxRenameEvent;
+
+const deleteEvent: MailboxDeleteEvent = {
+	type: "MAILBOX_DELETE",
+	accountId: "acc-1",
+	mailboxId: "mbx-1",
+	path: "Archive",
+} as MailboxDeleteEvent;
+
+const called = (method: string): Call[] =>
+	h.calls.filter((c) => c.method === method);
+
+const lastUpdate = (): Record<string, unknown> =>
+	(called("mailbox.update").at(-1)?.args[2] ?? {}) as Record<string, unknown>;
+
+describe("processMailboxManagement — MAILBOX_CREATE", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("creates the folder and writes back the server's UIDVALIDITY and counts", async () => {
+		await processMailboxManagement(createEvent, noopLog, deps());
+
+		assert.equal(called("connection.createMailbox")[0]?.args[0], "Archive");
+		assert.deepEqual(lastUpdate(), {
+			uidValidity: 7,
+			uidNext: 42,
+			messageCount: 3,
+			syncStatus: "synced",
+		});
+		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
+	});
+
+	it("subscribes only when the event asks for it", async () => {
+		await processMailboxManagement(createEvent, noopLog, deps());
+		assert.equal(called("connection.subscribeMailbox").length, 0);
+
+		h = fresh();
+		await processMailboxManagement(
+			{ ...createEvent, subscribe: true },
+			noopLog,
+			deps(),
+		);
+		assert.equal(called("connection.subscribeMailbox")[0]?.args[0], "Archive");
+	});
+
+	it("still marks the mailbox synced when the server does not list the new folder", async () => {
+		h.connection.listMailboxes = async () => [];
+
+		await processMailboxManagement(createEvent, noopLog, deps());
+
+		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+	});
+
+	it("treats an already-existing folder as success rather than a failure", async () => {
+		h.connection.createMailbox = async () => {
+			throw new Error("Mailbox already exists");
+		};
+
+		await processMailboxManagement(createEvent, noopLog, deps());
+
+		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+	});
+
+	it("marks the mailbox failed and rethrows on any other create error", async () => {
+		h.connection.createMailbox = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			processMailboxManagement(createEvent, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(h.disconnectCount, 1);
+	});
+
+	it("returns early without connecting when the account is soft-deleted", async () => {
+		h.account = {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			deletedAt: Date.now(),
+		};
+
+		await processMailboxManagement(createEvent, noopLog, deps());
+
+		assert.equal(called("connection.createMailbox").length, 0);
+	});
+
+	it("throws when the account no longer exists", async () => {
+		h.account = null;
+
+		await assert.rejects(
+			processMailboxManagement(createEvent, noopLog, deps()),
+			/not found/,
+		);
+	});
+});
+
+describe("processMailboxManagement — MAILBOX_RENAME", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("renames on the server and clears the pending oldPath", async () => {
+		await processMailboxManagement(renameEvent, noopLog, deps());
+
+		assert.deepEqual(called("connection.renameMailbox")[0]?.args, [
+			"Archive",
+			"Archive 2024",
+		]);
+		assert.deepEqual(lastUpdate(), {
+			oldPath: undefined,
+			syncStatus: "synced",
+		});
+	});
+
+	it("drops the local row when the source folder is gone on the server", async () => {
+		h.connection.renameMailbox = async () => {
+			throw new Error("Mailbox not found");
+		};
+
+		await processMailboxManagement(renameEvent, noopLog, deps());
+
+		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
+		assert.equal(called("mailbox.update").length, 0);
+	});
+
+	it("rolls the local path back and rethrows on any other rename error", async () => {
+		h.connection.renameMailbox = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			processMailboxManagement(renameEvent, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.deepEqual(lastUpdate(), {
+			fullPath: "Archive",
+			oldPath: undefined,
+			syncStatus: "failed",
+		});
+	});
+});
+
+describe("processMailboxManagement — MAILBOX_DELETE", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("deletes on the server and drops the local row", async () => {
+		await processMailboxManagement(deleteEvent, noopLog, deps());
+
+		assert.equal(called("connection.deleteMailbox")[0]?.args[0], "Archive");
+		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
+	});
+
+	it("drops the local row when the folder is already gone on the server", async () => {
+		h.connection.deleteMailbox = async () => {
+			throw new Error("Mailbox not found");
+		};
+
+		await processMailboxManagement(deleteEvent, noopLog, deps());
+
+		assert.equal(called("mailbox.delete").length, 1);
+	});
+
+	it("restores the mailbox and swallows the error when the server refuses to delete INBOX", async () => {
+		h.connection.deleteMailbox = async () => {
+			throw new Error("Cannot delete INBOX");
+		};
+
+		await processMailboxManagement(deleteEvent, noopLog, deps());
+
+		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(called("mailbox.delete").length, 0);
+	});
+
+	it("marks the mailbox failed and rethrows on any other delete error", async () => {
+		h.connection.deleteMailbox = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			processMailboxManagement(deleteEvent, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+	});
+});

package/src/handlers/mailbox-management.ts

@@ -13,13 +13,35 @@ import type {
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 
+export interface MailboxManagementDeps {
+	getClient: typeof getClient;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	createConnectionScope: typeof createConnectionScopeWithCredentials;
+}
+
+const defaultDeps: MailboxManagementDeps = {
+	getClient,
+	buildLifecycleDeps,
+	withOAuthLifecycle,
+	createConnectionScope: createConnectionScopeWithCredentials,
+};
+
 /**
  * Handle MAILBOX_CREATE event
  */
 const handleCreate = async (
 	event: MailboxCreateEvent,
 	log: Logger,
+	deps: MailboxManagementDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		mailbox: mailboxService,
@@ -93,7 +115,15 @@ const handleCreate = async (
 const handleRename = async (
 	event: MailboxRenameEvent,
 	log: Logger,
+	deps: MailboxManagementDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		mailbox: mailboxService,
@@ -171,7 +201,15 @@ const handleRename = async (
 const handleDelete = async (
 	event: MailboxDeleteEvent,
 	log: Logger,
+	deps: MailboxManagementDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		mailbox: mailboxService,
@@ -254,13 +292,14 @@ const handleDelete = async (
 export const processMailboxManagement = async (
 	event: MailboxManagementEvent,
 	log: Logger,
+	deps: MailboxManagementDeps = defaultDeps,
 ): Promise<void> => {
 	switch (event.type) {
 		case "MAILBOX_CREATE":
-			return handleCreate(event, log);
+			return handleCreate(event, log, deps);
 		case "MAILBOX_RENAME":
-			return handleRename(event, log);
+			return handleRename(event, log, deps);
 		case "MAILBOX_DELETE":
-			return handleDelete(event, log);
+			return handleDelete(event, log, deps);
 	}
 };

package/src/handlers/message-delete.test.ts

@@ -1,9 +1,13 @@
 import assert from "node:assert";
-import { describe, it, mock } from "node:test";
+import { beforeEach, describe, it, mock } from "node:test";
 import type { ThreadMessageItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger-lambda";
+import type { MessageDeleteEvent } from "../events.js";
 import {
 	buildThreadMessageTrashUpdate,
 	deleteAllThreadMessagesForMessage,
+	handleMessageDelete,
+	type MessageDeleteDeps,
 } from "./message-delete.js";
 
 const sourceMailboxId = "source-mailbox-id-aaaaaaaaa";
@@ -174,3 +178,288 @@ describe("deleteAllThreadMessagesForMessage (#212)", () => {
 		assert.equal(deleteRow.mock.calls.length, 0);
 	});
 });
+
+const noopLog = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {},
+	fatal: () => {},
+	trace: () => {},
+	child: () => noopLog,
+} as unknown as Logger;
+
+interface Call {
+	method: string;
+	args: unknown[];
+}
+
+interface Connection {
+	openBox: (
+		path: string,
+		readOnly?: boolean,
+	) => Promise<{ uidvalidity: number }>;
+	moveMessages: (
+		uids: number[],
+		dest: string,
+	) => Promise<{ uidMap: Map<number, number> }>;
+	deleteMessages: (uids: number[]) => Promise<void>;
+	createMailbox: (path: string) => Promise<void>;
+}
+
+interface Harness {
+	calls: Call[];
+	account: {
+		accountId: string;
+		accountConfigId: string;
+		deletedAt?: number;
+	} | null;
+	mailbox: { mailboxId: string; uidValidity: number; cursorState?: string };
+	connection: Connection;
+	threadMessage: Record<string, unknown> | null;
+	allThreadMessages: { accountConfigId: string; threadMessageId: string }[];
+	getConnectionCount: number;
+	disconnectCount: number;
+}
+
+let h: Harness;
+
+const record =
+	(method: string) =>
+	async (...args: unknown[]) => {
+		h.calls.push({ method, args });
+	};
+
+const buildConnection = (): Connection => ({
+	openBox: async () => ({ uidvalidity: 1 }),
+	moveMessages: async () => ({ uidMap: new Map([[10, 20]]) }),
+	deleteMessages: record(
+		"connection.deleteMessages",
+	) as Connection["deleteMessages"],
+	createMailbox: record(
+		"connection.createMailbox",
+	) as Connection["createMailbox"],
+});
+
+const fresh = (): Harness => ({
+	calls: [],
+	account: { accountId: "acc-1", accountConfigId: "cfg-1" },
+	mailbox: { mailboxId: "src-mbx", uidValidity: 1, cursorState: undefined },
+	connection: buildConnection(),
+	threadMessage: {
+		...baseThreadMessage,
+		accountConfigId: "cfg-1",
+		threadMessageId: "tm-1",
+	},
+	allThreadMessages: [
+		{ accountConfigId: "cfg-1", threadMessageId: "tm-1" },
+		{ accountConfigId: "cfg-1", threadMessageId: "tm-2" },
+	],
+	getConnectionCount: 0,
+	disconnectCount: 0,
+});
+
+const deps = (): MessageDeleteDeps =>
+	({
+		getClient: async () => ({
+			account: {
+				get: async (accountId: string) => {
+					h.calls.push({ method: "account.get", args: [accountId] });
+					return h.account;
+				},
+			},
+			message: {
+				updateUid: record("message.updateUid"),
+				update: record("message.update"),
+				delete: record("message.delete"),
+			},
+			threadMessage: {
+				findByMessageId: async () => h.threadMessage,
+				findAllByMessageId: async () => h.allThreadMessages,
+				update: record("threadMessage.update"),
+				delete: record("threadMessage.delete"),
+			},
+			mailbox: {
+				get: async () => h.mailbox,
+				update: record("mailbox.update"),
+			},
+			secrets: {},
+		}),
+		buildLifecycleDeps: () => ({}),
+		withOAuthLifecycle: async (
+			_deps: unknown,
+			_account: unknown,
+			_log: unknown,
+			cb: (credentials: unknown) => Promise<void>,
+		) => cb({}),
+		createConnectionScope: () => ({
+			getConnection: async () => {
+				h.getConnectionCount += 1;
+				return h.connection;
+			},
+			disconnect: async () => {
+				h.disconnectCount += 1;
+			},
+		}),
+	}) as unknown as MessageDeleteDeps;
+
+const moveEvent: MessageDeleteEvent = {
+	type: "MESSAGE_DELETE",
+	accountId: "acc-1",
+	messageId: "msg-1",
+	mailboxId: "src-mbx",
+	mailboxPath: "INBOX",
+	uid: 10,
+	operation: "move_to_trash",
+	destinationMailboxId: "trash-mbx",
+	destinationMailboxPath: "Trash",
+} as MessageDeleteEvent;
+
+const permanentEvent: MessageDeleteEvent = {
+	type: "MESSAGE_DELETE",
+	accountId: "acc-1",
+	messageId: "msg-1",
+	mailboxId: "src-mbx",
+	mailboxPath: "INBOX",
+	uid: 10,
+	operation: "permanent_delete",
+} as MessageDeleteEvent;
+
+const called = (method: string): Call[] =>
+	h.calls.filter((c) => c.method === method);
+
+describe("handleMessageDelete", () => {
+	beforeEach(() => {
+		h = fresh();
+	});
+
+	it("moves to trash, rewrites the uid, and flips the thread row to deleted", async () => {
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.deepEqual(called("message.updateUid")[0]?.args, [
+			"msg-1",
+			20,
+			"trash-mbx",
+		]);
+		const update = called("threadMessage.update")[0];
+		assert.deepEqual(update?.args[2], {
+			uid: 20,
+			mailboxId: "trash-mbx",
+			isDeleted: true,
+		});
+		assert.equal(h.disconnectCount, 1);
+	});
+
+	it("marks the message failed when the MOVE returns no new uid", async () => {
+		h.connection.moveMessages = async () => ({ uidMap: new Map() });
+
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(called("message.updateUid").length, 0);
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"failed",
+		);
+	});
+
+	it("expunges on the server and removes every thread row before the message row", async () => {
+		await handleMessageDelete(permanentEvent, noopLog, deps());
+
+		assert.deepEqual(called("connection.deleteMessages")[0]?.args, [[10]]);
+		assert.equal(called("threadMessage.delete").length, 2);
+		assert.ok(
+			h.calls.findIndex((c) => c.method === "threadMessage.delete") <
+				h.calls.findIndex((c) => c.method === "message.delete"),
+			"thread rows go first so no row outlives its message",
+		);
+	});
+
+	it("cleans up locally and swallows the error when the message is already gone on IMAP", async () => {
+		h.connection.deleteMessages = async () => {
+			throw new Error("NONEXISTENT uid");
+		};
+
+		await handleMessageDelete(permanentEvent, noopLog, deps());
+
+		assert.equal(called("message.delete").length, 1);
+		assert.equal(called("threadMessage.delete").length, 2);
+	});
+
+	it("creates the trash mailbox and rethrows on TRYCREATE", async () => {
+		h.connection.moveMessages = async () => {
+			throw new Error("TRYCREATE: no such mailbox");
+		};
+
+		await assert.rejects(
+			handleMessageDelete(moveEvent, noopLog, deps()),
+			/TRYCREATE/,
+		);
+
+		assert.equal(called("connection.createMailbox")[0]?.args[0], "Trash");
+		assert.equal(h.getConnectionCount, 2, "reconnects to create the mailbox");
+	});
+
+	it("marks failed and rethrows on an unclassified IMAP error", async () => {
+		h.connection.moveMessages = async () => {
+			throw new Error("server exploded");
+		};
+
+		await assert.rejects(
+			handleMessageDelete(moveEvent, noopLog, deps()),
+			/server exploded/,
+		);
+
+		assert.equal(
+			(called("message.update")[0]?.args[1] as { syncStatus?: string })
+				?.syncStatus,
+			"failed",
+		);
+	});
+
+	it("pauses quietly when openBox trips a UIDVALIDITY mismatch", async () => {
+		h.connection.openBox = async () => ({ uidvalidity: 999 });
+
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(
+			(called("mailbox.update")[0]?.args[2] as { cursorState?: string })
+				?.cursorState,
+			"cursor_invalid",
+		);
+		assert.equal(called("message.updateUid").length, 0);
+	});
+
+	it("skips without opening a connection when the cursor is rebuilding", async () => {
+		h.mailbox = {
+			mailboxId: "src-mbx",
+			uidValidity: 1,
+			cursorState: "rebuilding",
+		};
+
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+	});
+
+	it("returns early without connecting when the account is soft-deleted", async () => {
+		h.account = {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			deletedAt: Date.now(),
+		};
+
+		await handleMessageDelete(moveEvent, noopLog, deps());
+
+		assert.equal(h.getConnectionCount, 0);
+	});
+
+	it("throws when the account no longer exists", async () => {
+		h.account = null;
+
+		await assert.rejects(
+			handleMessageDelete(moveEvent, noopLog, deps()),
+			/not found/,
+		);
+	});
+});

package/src/handlers/message-delete.ts

@@ -83,6 +83,20 @@ export const buildThreadMessageTrashUpdate = (
 	},
 });
 
+export interface MessageDeleteDeps {
+	getClient: typeof getClient;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	createConnectionScope: typeof createConnectionScopeWithCredentials;
+}
+
+const defaultDeps: MessageDeleteDeps = {
+	getClient,
+	buildLifecycleDeps,
+	withOAuthLifecycle,
+	createConnectionScope: createConnectionScopeWithCredentials,
+};
+
 /**
  * Handle MESSAGE_DELETE events.
  * Either moves to Trash (IMAP MOVE) or permanently deletes (IMAP DELETE).
@@ -90,7 +104,15 @@ export const buildThreadMessageTrashUpdate = (
 export const handleMessageDelete = async (
 	event: MessageDeleteEvent,
 	log: Logger,
+	deps: MessageDeleteDeps = defaultDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+	} = deps;
+
 	const {
 		account: accountService,
 		message: messageService,