@remit/mailbox-service 0.0.111 → 0.0.113

package/src/imapflow-connection.ts

@@ -1,1475 +0,0 @@
-/**
- * ImapFlow-based IMAP connection
- *
- * Modern async/await replacement for the node-imap based ImapConnection.
- * Provides the same interface but uses ImapFlow under the hood.
- */
-
-import { Readable } from "node:stream";
-import { ImapFlow } from "imapflow";
-import { simpleParser } from "mailparser";
-import type {
-	FlatMailboxInfo,
-	ImapAddress,
-	ImapBoxStatus,
-	ImapConnectionConfig,
-	ImapConnectionState,
-	ImapEnvelopeSnapshot,
-	ImapMailboxStatus,
-	ImapMessage,
-	ImapNamespaces,
-	MailCredentials,
-} from "./types.js";
-import { MailConnectionError } from "./types.js";
-
-/**
- * Convert an envelope date into an ISO string, tolerating non-Date values.
- *
- * imapflow types `envelope.date` as a Date, but a malformed `Date:` header can
- * leave it as a string or other value at runtime. Returns "" for absent or
- * invalid dates so one bad header never poisons the whole fetch batch.
- */
-export const toIsoDateString = (value: unknown): string => {
-	if (value instanceof Date) {
-		return Number.isNaN(value.getTime()) ? "" : value.toISOString();
-	}
-	if (typeof value === "string" || typeof value === "number") {
-		const date = new Date(value);
-		return Number.isNaN(date.getTime()) ? "" : date.toISOString();
-	}
-	return "";
-};
-
-/**
- * Coerce an IMAP INTERNALDATE into a valid `Date`, tolerating malformed input.
- *
- * INTERNALDATE is the server's receive time and is almost always a clean Date.
- * But a broken server (or an unexpected imapflow runtime value) can yield a
- * string that `new Date` cannot parse, or a wholly unexpected type. Either way
- * `getTime()` would be `NaN`, which is the message's date-of-last-resort — it
- * is the fallback `parseHeaderDate` uses and is stored as the message's
- * `internalDate` — so a `NaN` here silently corrupts every downstream date and
- * gets rejected by ElectroDB, permanently failing the message.
- *
- * When the value cannot produce a valid Date we fall back to `now` so the
- * message still syncs with an approximate receive time rather than being
- * dropped. Returns `null` only for a genuinely absent value, which the caller
- * skips (a transient imapflow artifact, see #408 — not bad data).
- */
-export const toInternalDate = (value: unknown): Date | null => {
-	if (value == null) return null;
-	if (value instanceof Date) {
-		return Number.isNaN(value.getTime()) ? new Date() : value;
-	}
-	if (typeof value === "string" || typeof value === "number") {
-		const date = new Date(value);
-		return Number.isNaN(date.getTime()) ? new Date() : date;
-	}
-	return new Date();
-};
-
-const FLAG_CRITERIA: Record<string, Record<string, boolean>> = {
-	ALL: {},
-	SEEN: { seen: true },
-	UNSEEN: { seen: false },
-	FLAGGED: { flagged: true },
-	UNFLAGGED: { flagged: false },
-	DELETED: { deleted: true },
-	UNDELETED: { deleted: false },
-	ANSWERED: { answered: true },
-	UNANSWERED: { answered: false },
-	DRAFT: { draft: true },
-	UNDRAFT: { draft: false },
-};
-
-const VALUE_CRITERIA: Record<string, string> = {
-	UID: "uid",
-	FROM: "from",
-	TO: "to",
-	SUBJECT: "subject",
-	SINCE: "since",
-	BEFORE: "before",
-};
-
-const unsupported = (criterion: unknown): Error =>
-	new Error(
-		`Unsupported IMAP search criterion ${JSON.stringify(criterion)} — dropping it would widen the query to SEARCH ALL`,
-	);
-
-const applyValueCriterion = (
-	result: Record<string, unknown>,
-	header: Map<string, string>,
-	criterion: unknown[],
-): void => {
-	const [key, ...values] = criterion;
-	if (typeof key !== "string") throw unsupported(criterion);
-
-	if (key.toUpperCase() === "HEADER") {
-		const [name, value] = values;
-		if (values.length !== 2 || typeof name !== "string") {
-			throw unsupported(criterion);
-		}
-		if (typeof value !== "string" && value !== true) {
-			throw unsupported(criterion);
-		}
-		header.set(name.toLowerCase(), value === true ? "" : value);
-		return;
-	}
-
-	const field = VALUE_CRITERIA[key.toUpperCase()];
-	if (field === undefined || values.length !== 1) throw unsupported(criterion);
-	result[field] = values[0];
-};
-
-/**
- * Compile node-imap style search criteria into an ImapFlow search object.
- *
- * A criterion this does not understand throws, and so does an empty criteria
- * list. imapflow reads an empty object as `SEARCH ALL`
- * (`imapflow/lib/commands/search.js`), so quietly skipping one turns a narrow
- * probe into "every message in the mailbox" — the reconcile and move paths then
- * act on a stranger's UID (#912). Header names accumulate in a Map so that a
- * name like `__proto__` lands as a query term rather than hitting the
- * prototype setter and vanishing.
- *
- * Values travel as structured tokens, never interpolated into a criterion
- * string, so a quote or a CRLF in a header value cannot alter the query.
- */
-export const convertSearchCriteria = (
-	criteria: unknown[],
-): Record<string, unknown> => {
-	if (criteria.length === 0) {
-		throw new Error(
-			"Empty IMAP search criteria list — it would compile to SEARCH ALL",
-		);
-	}
-
-	const result: Record<string, unknown> = {};
-	const header = new Map<string, string>();
-
-	for (const criterion of criteria) {
-		if (typeof criterion === "string") {
-			const flags = FLAG_CRITERIA[criterion.toUpperCase()];
-			if (flags === undefined) throw unsupported(criterion);
-			Object.assign(result, flags);
-			continue;
-		}
-		if (Array.isArray(criterion)) {
-			applyValueCriterion(result, header, criterion);
-			continue;
-		}
-		throw unsupported(criterion);
-	}
-
-	if (header.size > 0) result.header = Object.fromEntries(header);
-	return result;
-};
-
-/**
- * ImapFlow-based IMAP connection
- *
- * Drop-in replacement for ImapConnection using the ImapFlow library.
- * Benefits:
- * - Native async/await API (no callback wrapping)
- * - Built-in envelope parsing that works with mokapi
- * - Proper IDLE support with events
- * - Built-in TypeScript types
- * - Active maintenance
- */
-export class ImapFlowConnection {
-	private client: ImapFlow | null = null;
-	private _state: ImapConnectionState = "disconnected";
-	private config: ImapConnectionConfig;
-	private currentMailbox: string | null = null;
-
-	constructor(config: ImapConnectionConfig) {
-		this.config = config;
-	}
-
-	/**
-	 * Current connection state
-	 */
-	get state(): ImapConnectionState {
-		return this._state;
-	}
-
-	/**
-	 * Whether the connection is established and authenticated
-	 */
-	get isConnected(): boolean {
-		return this._state === "authenticated";
-	}
-
-	/**
-	 * Connect to the IMAP server with retry logic.
-	 *
-	 * Retries up to 3 times with exponential backoff (1s, 2s, 4s) on connection errors.
-	 * Authentication errors are not retried.
-	 */
-	connect = async (): Promise<void> => {
-		if (this.client) {
-			throw new Error("Already connected");
-		}
-
-		const maxRetries = 3;
-		const baseDelayMs = 1000;
-
-		for (let attempt = 1; attempt <= maxRetries; attempt++) {
-			try {
-				await this.attemptConnect();
-				return;
-			} catch (error) {
-				const classified = classifyImapError(
-					error,
-					`${this.config.host}:${this.config.port}`,
-				);
-
-				// Auth errors won't fix themselves on retry — throw immediately.
-				if (classified?.kind === "auth") {
-					throw classified;
-				}
-
-				// Final attempt exhausted: throw the classified error if we have
-				// one (network failures), otherwise let the raw error bubble.
-				if (attempt === maxRetries) {
-					throw classified ?? error;
-				}
-
-				// Network and unknown errors fall through to retry-with-backoff.
-				// Exponential backoff: 1s, 2s, 4s
-				const delay = baseDelayMs * 2 ** (attempt - 1);
-				await this.sleep(delay);
-
-				// Reset state for retry
-				this.cleanup();
-			}
-		}
-	};
-
-	/**
-	 * Single connection attempt
-	 */
-	private attemptConnect = async (): Promise<void> => {
-		this._state = "connecting";
-
-		// Determine TLS options
-		// When secure is false, STARTTLS may still be used, so we need to handle self-signed certs
-		const tlsOptions = this.config.tlsOptions
-			? {
-					rejectUnauthorized: this.config.tlsOptions.rejectUnauthorized ?? true,
-				}
-			: !this.config.tls
-				? {
-						// Allow self-signed certs when TLS is disabled (for STARTTLS)
-						rejectUnauthorized: false,
-					}
-				: undefined;
-
-		const auth = buildImapAuth(this.config.user, this.config.credentials);
-
-		this.client = new ImapFlow({
-			host: this.config.host,
-			port: this.config.port,
-			secure: this.config.tls,
-			servername: this.config.tlsOptions?.servername,
-			auth,
-			tls: tlsOptions,
-			// Disable auto IDLE to work around servers that don't handle IDLE correctly
-			// This is equivalent to node-imap's forceNoop: true
-			disableAutoIdle: true,
-			logger: false, // Disable verbose logging
-		});
-
-		this.client.on("close", () => {
-			this._state = "disconnected";
-			this.client = null;
-			this.currentMailbox = null;
-		});
-
-		this.client.on("error", () => {
-			this._state = "error";
-		});
-
-		await this.client.connect();
-		this._state = "authenticated";
-	};
-
-	/**
-	 * Cleanup client state for retry
-	 */
-	private cleanup = (): void => {
-		if (this.client) {
-			this.client.close();
-			this.client = null;
-		}
-		this._state = "disconnected";
-		this.currentMailbox = null;
-	};
-
-	/**
-	 * Sleep for a specified duration
-	 */
-	private sleep = (ms: number): Promise<void> =>
-		new Promise((resolve) => setTimeout(resolve, ms));
-
-	/**
-	 * Disconnect from the IMAP server
-	 */
-	disconnect = async (): Promise<void> => {
-		if (!this.client) {
-			return;
-		}
-
-		const client = this.client;
-
-		// Use a timeout to avoid hanging on logout
-		const timeoutPromise = new Promise<void>((resolve) => {
-			setTimeout(() => {
-				// Force close if logout doesn't complete
-				client.close();
-				resolve();
-			}, 5000);
-		});
-
-		try {
-			await Promise.race([client.logout(), timeoutPromise]);
-		} catch {
-			// Ignore errors during disconnect, force close
-			client.close();
-		} finally {
-			this._state = "disconnected";
-			this.client = null;
-			this.currentMailbox = null;
-		}
-	};
-
-	/**
-	 * Get IMAP namespaces
-	 *
-	 * Note: ImapFlow doesn't expose namespaces directly, so we return
-	 * the default namespace. The mailbox listing works without explicit
-	 * namespace handling in ImapFlow.
-	 */
-	getNamespaces = async (): Promise<ImapNamespaces> => {
-		this.ensureConnected();
-
-		// ImapFlow doesn't expose NAMESPACE info, return defaults
-		// This is sufficient as ImapFlow handles namespaces internally
-		return {
-			personal: [{ prefix: "", delimiter: "/" }],
-			other: [],
-			shared: [],
-		};
-	};
-
-	/**
-	 * List all mailboxes as a flat list, preserving original paths from server.
-	 * This avoids path corruption from split/join operations.
-	 *
-	 * @param nsPrefix - Optional namespace prefix to filter mailboxes
-	 */
-	listMailboxes = async (nsPrefix?: string): Promise<FlatMailboxInfo[]> => {
-		this.ensureConnected();
-
-		const mailboxes = await this.client?.list();
-		if (!mailboxes) {
-			return [];
-		}
-		const result: FlatMailboxInfo[] = [];
-
-		for (const mailbox of mailboxes) {
-			// Filter by namespace prefix if provided
-			if (nsPrefix !== undefined && !mailbox.path.startsWith(nsPrefix)) {
-				continue;
-			}
-
-			// Extract name from path (last component)
-			const pathParts = mailbox.path.split(mailbox.delimiter);
-			const name = pathParts[pathParts.length - 1] || mailbox.path;
-			const parentPath =
-				pathParts.length > 1
-					? pathParts.slice(0, -1).join(mailbox.delimiter)
-					: null;
-
-			result.push({
-				fullPath: mailbox.path, // Use original path from server
-				name,
-				delimiter: mailbox.delimiter,
-				attributes: this.convertFlags(mailbox.flags),
-				parentPath,
-			});
-		}
-
-		return result;
-	};
-
-	/**
-	 * Convert ImapFlow flags Set to string array
-	 */
-	private convertFlags = (flags: Set<string> | undefined): string[] => {
-		if (!flags) return [];
-		return Array.from(flags);
-	};
-
-	/**
-	 * Open a mailbox for reading
-	 *
-	 * @param mailboxPath - Full path to the mailbox (e.g., "INBOX", "[Gmail]/Sent")
-	 * @param readOnly - Whether to open read-only (default: true)
-	 */
-	openBox = async (
-		mailboxPath: string,
-		readOnly = true,
-	): Promise<ImapBoxStatus> => {
-		this.ensureConnected();
-
-		// Idempotency guard: re-selecting the currently-open mailbox is a no-op
-		// SELECT on the wire. `mailbox` exposes the live, already-selected box, so
-		// we can return its status without paying for another round-trip — this is
-		// what lets a batch issue one SELECT and many fetches on the same box.
-		if (this.currentMailbox === mailboxPath && this.client?.mailbox) {
-			return this.toBoxStatus(this.client.mailbox, readOnly);
-		}
-
-		const mailbox = await this.client?.mailboxOpen(mailboxPath, {
-			readOnly,
-		});
-
-		if (!mailbox) {
-			throw new Error(`Failed to open mailbox: ${mailboxPath}`);
-		}
-
-		this.currentMailbox = mailboxPath;
-
-		return this.toBoxStatus(mailbox, readOnly);
-	};
-
-	/**
-	 * Build an ImapBoxStatus from an imapflow MailboxObject.
-	 */
-	private toBoxStatus = (
-		mailbox: {
-			path: string;
-			delimiter: string;
-			flags: Set<string>;
-			permanentFlags?: Set<string>;
-			uidValidity: bigint;
-			uidNext: number;
-			exists: number;
-			readOnly?: boolean;
-		},
-		readOnly: boolean,
-	): ImapBoxStatus => {
-		const pathParts = mailbox.path.split(mailbox.delimiter);
-		const name = pathParts[pathParts.length - 1] || mailbox.path;
-
-		return {
-			name,
-			readOnly: mailbox.readOnly ?? readOnly,
-			uidvalidity: Number(mailbox.uidValidity),
-			uidnext: mailbox.uidNext,
-			flags: Array.from(mailbox.flags || []),
-			permFlags: Array.from(mailbox.permanentFlags || []),
-			persistentUIDs: true, // ImapFlow assumes persistent UIDs
-			messages: {
-				total: mailbox.exists,
-				new: 0, // ImapFlow doesn't provide unseen count on open
-			},
-			newKeywords: mailbox.permanentFlags?.has("\\*") ?? false,
-		};
-	};
-
-	/**
-	 * Close the currently open mailbox
-	 *
-	 * @param _expunge - Whether to permanently remove deleted messages (not used in ImapFlow)
-	 */
-	closeBox = async (_expunge = false): Promise<void> => {
-		this.ensureConnected();
-
-		if (this.currentMailbox) {
-			await this.client?.mailboxClose();
-			this.currentMailbox = null;
-		}
-	};
-
-	/**
-	 * Search for messages, answering UIDs.
-	 *
-	 * imapflow answers a successful SEARCH with an array — empty when the
-	 * server matched nothing — and `false` when the command failed or no
-	 * mailbox was selected. Collapsing the two into `[]` makes a failed SEARCH
-	 * indistinguishable from an empty mailbox, and every caller here acts on
-	 * emptiness by deleting something: the cursor rebuild reads it as "every
-	 * local row is stale", and {@link isMessageGoneFromOpenMailbox} reads it as
-	 * "this message is gone". A failure therefore throws.
-	 */
-	search = async (criteria: unknown[]): Promise<number[]> => {
-		this.ensureConnected();
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		const searchQuery = convertSearchCriteria(criteria);
-
-		const result = await this.client?.search(searchQuery, { uid: true });
-		if (!Array.isArray(result)) {
-			throw new Error(`IMAP SEARCH failed in mailbox ${this.currentMailbox}`);
-		}
-		return result;
-	};
-
-	/**
-	 * Fetch messages by UID
-	 *
-	 * Uses ImapFlow's native envelope parsing which works correctly
-	 * with all IMAP servers including mokapi.
-	 */
-	fetchMessages = async (uids: number[]): Promise<ImapMessage[]> => {
-		this.ensureConnected();
-
-		if (uids.length === 0) {
-			return [];
-		}
-
-		return this.runMessageFetch(uids.join(","), {});
-	};
-
-	/**
-	 * True when this session negotiated CONDSTORE (RFC 7162) and the open
-	 * mailbox keeps persistent mod-sequences.
-	 *
-	 * Both halves matter. `enabled` reflects the ENABLE exchange, not merely
-	 * the advertised capability, and a server may still answer NOMODSEQ for an
-	 * individual mailbox — in which case RFC 7162 Section 3.1.2.2 requires it
-	 * to reject CHANGEDSINCE with a BAD response.
-	 */
-	supportsCondstore = (): boolean => {
-		const { client } = this;
-		if (!client?.mailbox) return false;
-		return client.enabled.has("CONDSTORE") && !client.mailbox.noModseq;
-	};
-
-	/**
-	 * FETCH everything in the open mailbox whose MODSEQ is strictly greater
-	 * than `sinceModseq` — new arrivals and metadata changes to messages
-	 * already synced, in one pass over the whole UID space.
-	 *
-	 * The CONDSTORE guard is load-bearing rather than defensive: imapflow drops
-	 * the CHANGEDSINCE modifier when the extension is unavailable, so the same
-	 * call would degrade into a fetch of every message in the mailbox.
-	 */
-	fetchMessagesChangedSince = async (
-		sinceModseq: bigint,
-	): Promise<ImapMessage[]> => {
-		this.ensureConnected();
-
-		if (!this.supportsCondstore()) {
-			throw new Error(
-				"CHANGEDSINCE requires CONDSTORE on both the session and the open mailbox",
-			);
-		}
-
-		return this.runMessageFetch("1:*", { changedSince: sinceModseq });
-	};
-
-	/**
-	 * One UID FETCH over `range`, mapped to {@link ImapMessage}. The shared
-	 * body of {@link fetchMessages} and {@link fetchMessagesChangedSince} —
-	 * both need identical message shapes and differ only in what they select.
-	 */
-	private runMessageFetch = async (
-		range: string,
-		options: { changedSince?: bigint },
-	): Promise<ImapMessage[]> => {
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		const messages: ImapMessage[] = [];
-
-		const fetchIterator = client.fetch(
-			range,
-			{
-				uid: true,
-				flags: true,
-				envelope: true,
-				bodyStructure: true,
-				internalDate: true,
-				size: true,
-				headers: ["references"],
-			},
-			{ uid: true, ...options },
-		);
-
-		// Connection may have been lost - fetch returns an async iterable
-		if (!fetchIterator) {
-			throw new Error(`IMAP connection lost while fetching messages: ${range}`);
-		}
-
-		for await (const msg of fetchIterator) {
-			// imapflow occasionally yields a row with undefined uid or internalDate
-			// on back-to-back FETCH calls (e.g. after a body-fetch on the same UID).
-			// See #408 for the investigation. This is the client library glitching,
-			// not the message being malformed, so the row is dropped rather than
-			// quarantined — recording it as a defective message would advance a
-			// cursor past mail that is fine (issue #72).
-			//
-			// Dropping it is only safe because the caller treats a requested UID
-			// with no row as unconsumed and holds its watermark below it. It used
-			// to advance regardless, which is how a transient client glitch turned
-			// into a message never fetched again.
-			if (msg.uid == null || msg.internalDate == null) {
-				continue;
-			}
-
-			// Coerce INTERNALDATE without ever throwing: a malformed value must not
-			// abort the whole fetch batch. A bad value falls back to now; an absent
-			// one cannot reach here, having been dropped above.
-			const internalDate = toInternalDate(msg.internalDate) ?? new Date();
-
-			// Parse References header if present
-			const references = await this.parseReferencesHeader(msg.headers);
-
-			messages.push({
-				uid: msg.uid,
-				seq: msg.seq,
-				flags: Array.from(msg.flags || []),
-				internalDate,
-				size: msg.size ?? 0,
-				envelope: this.convertEnvelope(msg.envelope),
-				references,
-				bodyStructure: msg.bodyStructure,
-				...(msg.modseq != null ? { modseq: msg.modseq.toString() } : {}),
-			});
-		}
-
-		return messages;
-	};
-
-	/**
-	 * Cheap envelope-only FETCH for the UIDVALIDITY cursor rebuild (#1272):
-	 * UID + Message-ID + INTERNALDATE only — no flags, no BODYSTRUCTURE, no
-	 * References header, no body. Deliberately lighter than {@link
-	 * fetchMessages} so a rebuild pass over a large mailbox stays cheap (epic
-	 * #1281 invariant 6).
-	 */
-	fetchEnvelopeSnapshots = async (
-		uids: number[],
-	): Promise<ImapEnvelopeSnapshot[]> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return [];
-		}
-
-		const uidRange = uids.join(",");
-
-		const fetchIterator = client.fetch(
-			uidRange,
-			{ uid: true, envelope: true, internalDate: true },
-			{ uid: true },
-		);
-
-		if (!fetchIterator) {
-			throw new Error(
-				`IMAP connection lost while fetching envelope snapshots: ${uidRange}`,
-			);
-		}
-
-		const snapshots: ImapEnvelopeSnapshot[] = [];
-
-		for await (const msg of fetchIterator) {
-			// Same defensive skip as fetchMessages (#408) — an occasional row
-			// with no uid/internalDate must not abort the whole batch.
-			if (msg.uid == null || msg.internalDate == null) {
-				continue;
-			}
-
-			const internalDate = toInternalDate(msg.internalDate);
-			if (internalDate === null) {
-				continue;
-			}
-
-			snapshots.push({
-				uid: msg.uid,
-				messageId: msg.envelope?.messageId ?? "",
-				internalDate,
-			});
-		}
-
-		return snapshots;
-	};
-
-	/**
-	 * Fetch the full message body (RFC822 source) for a single message by UID.
-	 *
-	 * @param uid - The UID of the message to fetch
-	 * @returns The raw message body, or null when the UID FETCH matched no message
-	 */
-	fetchMessageBody = async (uid: number): Promise<Buffer | null> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		const result = await client.download(String(uid), undefined, {
-			uid: true,
-		});
-
-		if (result?.content) {
-			const chunks: Buffer[] = [];
-			for await (const chunk of result.content) {
-				chunks.push(chunk);
-			}
-			return Buffer.concat(chunks);
-		}
-
-		if (!client.usable || !client.mailbox) {
-			throw new MailConnectionError(
-				"network",
-				`IMAP connection lost while downloading message UID ${uid}`,
-			);
-		}
-
-		return null;
-	};
-
-	/**
-	 * Fetch full message bodies (RFC822 source) for many UIDs in ONE pipelined
-	 * ranged UID FETCH on a single connection — the desktop-client pattern.
-	 *
-	 * Mirrors `fetchMessages`: one comma-joined UID range, one `client.fetch`,
-	 * one SELECT (the caller opens the box once for the whole batch). Yields
-	 * `{ uid, source }` as each message arrives so the caller can stream each
-	 * body straight to storage without buffering the whole batch.
-	 *
-	 * `source` is a readable stream over the message bytes — callers must
-	 * consume it (e.g. pipe to an upload) before requesting the next item.
-	 */
-	async *fetchMessageBodies(
-		uids: number[],
-	): AsyncGenerator<{ uid: number; source: Readable }> {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return;
-		}
-
-		const uidRange = uids.join(",");
-
-		const fetchIterator = client.fetch(
-			uidRange,
-			{ uid: true, source: true },
-			{ uid: true },
-		);
-
-		if (!fetchIterator) {
-			throw new MailConnectionError(
-				"network",
-				`IMAP connection lost while fetching message bodies: ${uidRange}`,
-			);
-		}
-
-		try {
-			for await (const msg of fetchIterator) {
-				// imapflow can yield a row with an undefined uid or no source on
-				// back-to-back FETCH calls; skip it rather than crash the batch — the
-				// caller treats any UID it never sees as failed and re-enqueues it.
-				// See #408.
-				if (msg.uid == null || msg.source == null) {
-					continue;
-				}
-
-				yield { uid: msg.uid, source: Readable.from(msg.source) };
-			}
-		} catch (error) {
-			// A mid-stream socket drop surfaces as imapflow's
-			// `new Error("Connection closed")` with code `EConnectionClosed` — a
-			// string the rest of the code never matches on. Re-throw it as the
-			// typed MailConnectionError so the caller's fail-fast path triggers and
-			// re-enqueues the not-yet-yielded UIDs instead of failing the record.
-			throw (
-				classifyImapError(error, `${this.config.host}:${this.config.port}`) ??
-				error
-			);
-		}
-	}
-
-	/**
-	 * Parse the References header from IMAP headers buffer.
-	 * Returns an array of Message-IDs, with the first being the thread root.
-	 */
-	private parseReferencesHeader = async (
-		headers: Buffer | undefined,
-	): Promise<string[] | undefined> => {
-		if (!headers) return undefined;
-
-		// Raw header bytes are untrusted. simpleParser is tolerant but can still
-		// throw on sufficiently broken input; a throw here would abort the whole
-		// fetch batch. Missing references just means "no thread parent", so on any
-		// parse failure treat the message as a thread root rather than crashing.
-		const parsed = await simpleParser(headers).catch(() => null);
-
-		if (!parsed?.references) return undefined;
-
-		// mailparser returns references as string or array
-		if (Array.isArray(parsed.references)) {
-			return parsed.references.length > 0 ? parsed.references : undefined;
-		}
-
-		// Single reference as string
-		return [parsed.references];
-	};
-
-	/**
-	 * Convert ImapFlow envelope to our ImapEnvelope format
-	 */
-	private convertEnvelope = (
-		envelope:
-			| {
-					date?: Date;
-					subject?: string;
-					from?: Array<{ name?: string; address?: string }>;
-					sender?: Array<{ name?: string; address?: string }>;
-					replyTo?: Array<{ name?: string; address?: string }>;
-					to?: Array<{ name?: string; address?: string }>;
-					cc?: Array<{ name?: string; address?: string }>;
-					bcc?: Array<{ name?: string; address?: string }>;
-					inReplyTo?: string;
-					messageId?: string;
-			  }
-			| undefined,
-	): ImapMessage["envelope"] => {
-		// An absent ENVELOPE stays absent. Synthesising an empty one here made
-		// every `if (!msg.envelope)` guard downstream unreachable, so a FETCH row
-		// that carried no envelope was saved as a row with no sender, no subject
-		// and no date, keyed by the `generated:` fallback — indistinguishable
-		// from a real message. The field is optional on `ImapMessage` precisely
-		// so callers can see the difference (issue #72).
-		if (!envelope) return undefined;
-
-		const convertAddresses = (
-			addrs?: Array<{ name?: string; address?: string }>,
-		): ImapAddress[] => {
-			if (!addrs) return [];
-			return addrs
-				.filter((a) => a.address)
-				.map((a) => {
-					const [mailbox, host] = (a.address || "").split("@");
-					return {
-						name: a.name || undefined,
-						mailbox: mailbox || "",
-						host: host || "",
-					};
-				});
-		};
-
-		return {
-			date: toIsoDateString(envelope.date),
-			subject: envelope.subject ?? "",
-			from: convertAddresses(envelope.from),
-			sender: convertAddresses(envelope.sender),
-			replyTo: convertAddresses(envelope.replyTo),
-			to: convertAddresses(envelope.to),
-			cc: convertAddresses(envelope.cc),
-			bcc: convertAddresses(envelope.bcc),
-			inReplyTo: envelope.inReplyTo ?? "",
-			messageId: envelope.messageId ?? "",
-		};
-	};
-
-	/**
-	 * Add flags to messages by UID.
-	 * Requires mailbox to be open (not read-only).
-	 *
-	 * @param uids - Array of message UIDs
-	 * @param flags - Array of flags to add (e.g., ["\\Seen", "\\Flagged"])
-	 */
-	addFlags = async (uids: number[], flags: string[]): Promise<void> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0 || flags.length === 0) {
-			return;
-		}
-
-		const uidRange = uids.join(",");
-		await client.messageFlagsAdd(uidRange, flags, { uid: true });
-	};
-
-	/**
-	 * Remove flags from messages by UID.
-	 * Requires mailbox to be open (not read-only).
-	 *
-	 * @param uids - Array of message UIDs
-	 * @param flags - Array of flags to remove (e.g., ["\\Seen", "\\Flagged"])
-	 */
-	removeFlags = async (uids: number[], flags: string[]): Promise<void> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0 || flags.length === 0) {
-			return;
-		}
-
-		const uidRange = uids.join(",");
-		await client.messageFlagsRemove(uidRange, flags, { uid: true });
-	};
-
-	/**
-	 * Replace all flags on messages by UID.
-	 * Requires mailbox to be open (not read-only).
-	 *
-	 * @param uids - Array of message UIDs
-	 * @param flags - Array of flags to set (replaces all existing flags)
-	 */
-	setFlags = async (uids: number[], flags: string[]): Promise<void> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return;
-		}
-
-		const uidRange = uids.join(",");
-		await client.messageFlagsSet(uidRange, flags, { uid: true });
-	};
-
-	/**
-	 * Create a new mailbox.
-	 *
-	 * @param path - Full path of the mailbox to create (e.g., "Projects/ClientA")
-	 * @returns Object with path and whether it was created (false if already exists)
-	 */
-	createMailbox = async (
-		path: string,
-	): Promise<{ path: string; created: boolean }> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		const result = await client.mailboxCreate(path);
-		return {
-			path: result.path,
-			created: result.created ?? true,
-		};
-	};
-
-	/**
-	 * Delete a mailbox.
-	 *
-	 * @param path - Full path of the mailbox to delete
-	 * @returns Object with the deleted path
-	 */
-	deleteMailbox = async (path: string): Promise<{ path: string }> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		// Cannot delete INBOX
-		if (path.toUpperCase() === "INBOX") {
-			throw new Error("Cannot delete INBOX");
-		}
-
-		const result = await client.mailboxDelete(path);
-		return { path: result.path };
-	};
-
-	/**
-	 * Rename a mailbox.
-	 *
-	 * @param oldPath - Current path of the mailbox
-	 * @param newPath - New path for the mailbox
-	 * @returns Object with old and new paths
-	 */
-	renameMailbox = async (
-		oldPath: string,
-		newPath: string,
-	): Promise<{ path: string; newPath: string }> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		const result = await client.mailboxRename(oldPath, newPath);
-		// `mailboxRename` resolves `undefined` when the connection is not
-		// AUTHENTICATED or SELECTED — RENAME was never issued. Dereferencing it
-		// raised a `TypeError` where the settle now reads the resolved path, and a
-		// `TypeError` is not an outcome the rename settle can classify.
-		if (!result) {
-			throw new Error(
-				`Rename of "${oldPath}" was not issued: the IMAP connection is not ready`,
-			);
-		}
-		return {
-			path: result.path,
-			newPath: result.newPath,
-		};
-	};
-
-	/**
-	 * Subscribe to a mailbox.
-	 *
-	 * @param path - Full path of the mailbox to subscribe to
-	 */
-	subscribeMailbox = async (path: string): Promise<void> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		await client.mailboxSubscribe(path);
-	};
-
-	/**
-	 * Unsubscribe from a mailbox.
-	 *
-	 * @param path - Full path of the mailbox to unsubscribe from
-	 */
-	unsubscribeMailbox = async (path: string): Promise<void> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		await client.mailboxUnsubscribe(path);
-	};
-
-	/**
-	 * Move messages to another mailbox.
-	 * Uses ImapFlow's messageMove which wraps UID MOVE command.
-	 * Returns mapping of source UIDs to destination UIDs from COPYUID response.
-	 *
-	 * @param uids - Array of message UIDs to move
-	 * @param destination - Destination mailbox path
-	 * @returns Object with destination path, uidValidity, and uidMap
-	 */
-	moveMessages = async (
-		uids: number[],
-		destination: string,
-	): Promise<{
-		destination: string;
-		uidValidity: number;
-		uidMap: Map<number, number>;
-	}> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return { destination, uidValidity: 0, uidMap: new Map() };
-		}
-
-		const uidRange = uids.join(",");
-		const result = await client.messageMove(uidRange, destination, {
-			uid: true,
-		});
-
-		// messageMove returns false if no messages were moved
-		if (result === false) {
-			return { destination, uidValidity: 0, uidMap: new Map() };
-		}
-
-		return {
-			destination: result.destination,
-			uidValidity: Number(result.uidValidity ?? 0),
-			uidMap: result.uidMap ?? new Map(),
-		};
-	};
-
-	/**
-	 * Copy messages to another mailbox.
-	 * Uses ImapFlow's messageCopy which wraps UID COPY command.
-	 * Returns mapping of source UIDs to destination UIDs from COPYUID response.
-	 *
-	 * @param uids - Array of message UIDs to copy
-	 * @param destination - Destination mailbox path
-	 * @returns Object with destination path, uidValidity, and uidMap
-	 */
-	copyMessages = async (
-		uids: number[],
-		destination: string,
-	): Promise<{
-		destination: string;
-		uidValidity: number;
-		uidMap: Map<number, number>;
-	}> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return { destination, uidValidity: 0, uidMap: new Map() };
-		}
-
-		const uidRange = uids.join(",");
-		const result = await client.messageCopy(uidRange, destination, {
-			uid: true,
-		});
-
-		// messageCopy returns false if no messages were copied
-		if (result === false) {
-			return { destination, uidValidity: 0, uidMap: new Map() };
-		}
-
-		return {
-			destination: result.destination,
-			uidValidity: Number(result.uidValidity ?? 0),
-			uidMap: result.uidMap ?? new Map(),
-		};
-	};
-
-	/**
-	 * Permanently delete messages (mark \Deleted + expunge).
-	 * Uses ImapFlow's messageDelete which wraps STORE +FLAGS.SILENT \Deleted
-	 * followed by UID EXPUNGE.
-	 *
-	 * @param uids - Array of message UIDs to delete
-	 * @returns Number of messages deleted
-	 */
-	deleteMessages = async (uids: number[]): Promise<number> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		if (!this.currentMailbox) {
-			throw new Error("No mailbox selected");
-		}
-
-		if (uids.length === 0) {
-			return 0;
-		}
-
-		const uidRange = uids.join(",");
-		const result = await client.messageDelete(uidRange, { uid: true });
-
-		// messageDelete returns boolean or deleted count
-		if (typeof result === "number") {
-			return result;
-		}
-		return result ? uids.length : 0;
-	};
-
-	/**
-	 * Get mailbox status.
-	 *
-	 * Message/unseen counts come from the IMAP STATUS command (no SELECT). The
-	 * \Deleted count is not part of imapflow's typed STATUS query (there is no
-	 * IMAP4rev2 STATUS=DELETED in the API), so it is derived by selecting the
-	 * mailbox read-only and running SEARCH \Deleted — a projection re-read from
-	 * the server, never a locally computed value.
-	 *
-	 * @param mailboxPath - Full path to the mailbox
-	 * @returns Mailbox status including unseen and deleted counts
-	 */
-	getMailboxStatus = async (
-		mailboxPath: string,
-	): Promise<ImapMailboxStatus> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		const status = await client.status(mailboxPath, {
-			messages: true,
-			recent: true,
-			unseen: true,
-			uidNext: true,
-			uidValidity: true,
-			highestModseq: true,
-		});
-
-		const deletedCount = await this.countDeleted(mailboxPath);
-
-		return {
-			messages: status.messages ?? 0,
-			recent: status.recent ?? 0,
-			unseen: status.unseen ?? 0,
-			uidNext: status.uidNext ?? 0,
-			uidValidity: Number(status.uidValidity ?? 0),
-			highestModseq: (status.highestModseq ?? 0n).toString(),
-			deletedCount,
-		};
-	};
-
-	/**
-	 * Count messages flagged \Deleted but not yet expunged.
-	 *
-	 * Selects the mailbox read-only (no state change) and counts SEARCH \Deleted
-	 * hits. Read-only SELECT is idempotent against an already-open mailbox.
-	 */
-	private countDeleted = async (mailboxPath: string): Promise<number> => {
-		await this.openBox(mailboxPath, true);
-		const deletedUids = await this.search(["DELETED"]);
-		return deletedUids.length;
-	};
-
-	/**
-	 * Append a message to a mailbox.
-	 * Used primarily for testing to seed messages.
-	 *
-	 * @param mailbox - Mailbox path to append to
-	 * @param message - RFC 822 message content
-	 * @param flags - Optional flags to set on the message
-	 * @returns Object with destination path, uidValidity, and uid of the appended message
-	 */
-	append = async (
-		mailbox: string,
-		message: string | Buffer,
-		flags?: string[],
-	): Promise<{
-		destination: string;
-		uidValidity: number;
-		uid: number;
-	}> => {
-		this.ensureConnected();
-		const { client } = this;
-
-		if (!client) {
-			throw new Error("Not connected to IMAP server");
-		}
-
-		const result = await client.append(mailbox, message, flags);
-
-		// append returns false if the message could not be appended
-		if (result === false) {
-			throw new Error(`Failed to append message to ${mailbox}`);
-		}
-
-		return {
-			destination: result.destination,
-			uidValidity: Number(result.uidValidity ?? 0),
-			uid: result.uid ?? 0,
-		};
-	};
-
-	/**
-	 * Ensure the connection is established
-	 */
-	private ensureConnected = (): void => {
-		if (!this.client || this._state !== "authenticated") {
-			throw new Error("Not connected to IMAP server");
-		}
-	};
-}
-
-/**
- * Create an ImapFlow connection from account data using password credentials.
- */
-export const createImapFlowConnectionFromAccount = (
-	account: {
-		imapHost: string;
-		imapPort: number;
-		imapTls: boolean;
-		username: string;
-	},
-	password: string,
-): ImapFlowConnection => {
-	return new ImapFlowConnection({
-		host: account.imapHost,
-		port: account.imapPort,
-		tls: account.imapTls,
-		user: account.username,
-		credentials: { kind: "password", password },
-	});
-};
-
-/**
- * Create an ImapFlow connection using a credentials union (password or OAuth access token).
- */
-export const createImapFlowConnectionWithCredentials = (
-	account: {
-		imapHost: string;
-		imapPort: number;
-		imapTls: boolean;
-		username: string;
-	},
-	credentials: import("./types.js").MailCredentials,
-): ImapFlowConnection => {
-	return new ImapFlowConnection({
-		host: account.imapHost,
-		port: account.imapPort,
-		tls: account.imapTls,
-		user: account.username,
-		credentials,
-	});
-};
-
-/**
- * Build the imapflow auth object from mail credentials.
- *
- * IMPORTANT: never include access-token values in error messages.
- */
-const buildImapAuth = (
-	user: string,
-	credentials: MailCredentials,
-): { user: string; pass: string } | { user: string; accessToken: string } => {
-	if (credentials.kind === "password") {
-		return { user, pass: credentials.password };
-	}
-	if (credentials.kind === "accessToken") {
-		return { user, accessToken: credentials.accessToken };
-	}
-	// Exhaustiveness check — fails to compile if a new credential kind is added
-	// without handling it here.
-	const _exhaustive: never = credentials;
-	throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
-};
-
-/**
- * The server's own words for the failure: the text of the tagged NO/BAD, which
- * imapflow hangs off the error as `responseText`. It is the server's side of
- * the exchange only — never the command we sent, so no credential can ride out
- * on it. "SmtpClientAuthentication is disabled" and "User is authenticated but
- * not connected" arrive this way, and neither is fixed by re-authenticating, so
- * dropping the text leaves the account card telling the user to do the one
- * thing that cannot help.
- */
-const serverResponseText = (error: Error): string => {
-	const text = (error as { responseText?: unknown }).responseText;
-	return typeof text === "string" ? text.trim() : "";
-};
-
-/**
- * Classify a raw IMAP error into a MailConnectionError, or return null if
- * the error is not recognisable (let it bubble as-is).
- *
- * IMPORTANT: never include access-token values in error messages.
- */
-const classifyImapError = (
-	error: unknown,
-	endpoint?: string,
-): MailConnectionError | null => {
-	if (!(error instanceof Error)) {
-		return null;
-	}
-
-	const msg = error.message;
-	const code = (error as NodeJS.ErrnoException).code ?? "";
-
-	// Authentication failures
-	if (
-		msg.includes("Invalid credentials") ||
-		msg.includes("Authentication failed") ||
-		msg.includes("AUTHENTICATIONFAILED") ||
-		msg.includes("AUTHENTICATE") ||
-		(error as { authenticationFailed?: boolean }).authenticationFailed === true
-	) {
-		const serverText = serverResponseText(error);
-		return new MailConnectionError(
-			"auth",
-			serverText
-				? `IMAP authentication failed: ${serverText}`
-				: "IMAP authentication failed",
-		);
-	}
-
-	// Network-level failures — NEVER include the original message as it may
-	// echo back tokens in some server implementations. The endpoint (host:port)
-	// is safe and makes DNS/connect failures self-describing.
-	if (
-		code === "ECONNREFUSED" ||
-		code === "ETIMEDOUT" ||
-		code === "ENOTFOUND" ||
-		code === "ECONNRESET" ||
-		code === "EHOSTUNREACH" ||
-		// imapflow raises these when the socket is gone mid-command.
-		code === "EConnectionClosed" ||
-		code === "NoConnection"
-	) {
-		const where = endpoint ? ` (${endpoint})` : "";
-		return new MailConnectionError(
-			"network",
-			`IMAP connection failed: ${code}${where}`,
-		);
-	}
-
-	return null;
-};