@remit/mailbox-service 0.0.1

package/src/types.ts

@@ -0,0 +1,349 @@
+/**
+ * Types for the remit-mailbox-service
+ */
+
+import type { Readable } from "node:stream";
+
+/**
+ * Discriminated union of mail authentication credentials.
+ *
+ * Exactly one credential kind can be present at a time — the union makes
+ * "both password and accessToken simultaneously" unrepresentable.
+ */
+export type MailCredentials =
+	| { kind: "password"; password: string }
+	| { kind: "accessToken"; accessToken: string };
+
+/**
+ * Classification of mail connection errors.
+ */
+export type MailConnectionErrorKind = "auth" | "network";
+
+/**
+ * Typed error for IMAP/SMTP connection failures.
+ *
+ * `kind: "auth"` — authentication rejected (bad credentials / token expired).
+ * `kind: "network"` — transport-level failure (ECONNREFUSED, ETIMEDOUT, etc.).
+ *
+ * IMPORTANT: access tokens must NEVER appear in error messages or causes.
+ */
+export class MailConnectionError extends Error {
+	readonly kind: MailConnectionErrorKind;
+
+	constructor(kind: MailConnectionErrorKind, message: string, cause?: unknown) {
+		super(message, { cause });
+		this.name = "MailConnectionError";
+		this.kind = kind;
+	}
+}
+
+/**
+ * IMAP connection configuration
+ */
+export interface ImapConnectionConfig {
+	host: string;
+	port: number;
+	user: string;
+	credentials: MailCredentials;
+	tls: boolean;
+	tlsOptions?: {
+		rejectUnauthorized?: boolean;
+		servername?: string;
+	};
+	/** Connection timeout in milliseconds */
+	connTimeout?: number;
+	/** Authentication timeout in milliseconds */
+	authTimeout?: number;
+}
+
+/**
+ * IMAP connection state
+ */
+export type ImapConnectionState =
+	| "disconnected"
+	| "connecting"
+	| "connected"
+	| "authenticated"
+	| "error";
+
+/**
+ * Namespace structure from IMAP NAMESPACE command
+ */
+export interface ImapNamespace {
+	prefix: string;
+	delimiter: string | false;
+	extensions?: Array<{
+		name: string;
+		params: string[] | null;
+	}>;
+}
+
+/**
+ * IMAP namespaces grouped by type
+ */
+export interface ImapNamespaces {
+	personal: ImapNamespace[];
+	other: ImapNamespace[];
+	shared: ImapNamespace[];
+}
+
+/**
+ * IMAP mailbox status after opening
+ */
+export interface ImapBoxStatus {
+	name: string;
+	readOnly: boolean;
+	uidvalidity: number;
+	uidnext: number;
+	flags: string[];
+	permFlags: string[];
+	persistentUIDs: boolean;
+	messages: {
+		total: number;
+		new: number;
+	};
+	newKeywords: boolean;
+}
+
+/**
+ * IMAP mailbox status from STATUS command
+ */
+export interface ImapMailboxStatus {
+	messages: number;
+	recent: number;
+	unseen: number;
+	uidNext: number;
+	uidValidity: number;
+	/** Highest modification sequence (CONDSTORE). 0 if server doesn't support CONDSTORE. */
+	highestModseq: number;
+	/** Count of messages flagged \Deleted but not yet expunged. */
+	deletedCount: number;
+}
+
+/**
+ * Flattened mailbox info for processing
+ */
+export interface FlatMailboxInfo {
+	fullPath: string;
+	name: string;
+	delimiter: string;
+	attributes: string[];
+	parentPath: string | null;
+}
+
+export interface ImapAddress {
+	name?: string;
+	mailbox: string;
+	host: string;
+}
+
+export interface ImapEnvelope {
+	date: string;
+	subject: string;
+	from: ImapAddress[];
+	sender: ImapAddress[];
+	replyTo: ImapAddress[];
+	to: ImapAddress[];
+	cc: ImapAddress[];
+	bcc: ImapAddress[];
+	inReplyTo: string;
+	messageId: string;
+}
+
+/**
+ * Subset of imapflow's `MessageStructureObject` we depend on. Restated
+ * here so non-imapflow code (and tests) can build fixtures without pulling
+ * the imapflow types in.
+ */
+export interface ImapBodyStructure {
+	/** Dot-numbered MIME path; absent on the root node. */
+	part?: string;
+	/** Full Content-Type, e.g. "text/plain" or "multipart/mixed". */
+	type: string;
+	parameters?: Record<string, string>;
+	id?: string;
+	description?: string;
+	encoding?: string;
+	size?: number;
+	lineCount?: number;
+	md5?: string;
+	disposition?: string;
+	dispositionParameters?: Record<string, string>;
+	language?: string[];
+	location?: string;
+	childNodes?: ImapBodyStructure[];
+}
+
+/**
+ * One server message from the cheap envelope-only FETCH the UIDVALIDITY
+ * cursor rebuild uses (#1272): UID + Message-ID + INTERNALDATE, nothing
+ * else — no flags, no BODYSTRUCTURE, no body fetch.
+ */
+export interface ImapEnvelopeSnapshot {
+	uid: number;
+	/** Raw RFC 822 Message-ID header; empty string when absent/unparseable. */
+	messageId: string;
+	internalDate: Date;
+}
+
+export interface ImapMessage {
+	uid: number;
+	seq: number;
+	flags: string[];
+	internalDate: Date;
+	size: number;
+	envelope?: ImapEnvelope;
+	/**
+	 * References header from RFC 2822.
+	 * Contains Message-IDs of ancestor messages, with the first being the thread root.
+	 */
+	references?: string[];
+	/** Parsed BODYSTRUCTURE tree (RFC 9051 Section 7.5.2). */
+	bodyStructure?: ImapBodyStructure;
+}
+
+/**
+ * Result of a mailbox sync operation
+ */
+export interface MailboxSyncResult {
+	created: number;
+	updated: number;
+	deleted: number;
+}
+
+/**
+ * Common interface for IMAP connections
+ */
+export interface IImapConnection {
+	readonly state: ImapConnectionState;
+	readonly isConnected: boolean;
+	connect(): Promise<void>;
+	disconnect(): Promise<void>;
+	getNamespaces(): Promise<ImapNamespaces>;
+	listMailboxes(nsPrefix?: string): Promise<FlatMailboxInfo[]>;
+	openBox(mailboxPath: string, readOnly?: boolean): Promise<ImapBoxStatus>;
+	closeBox(expunge?: boolean): Promise<void>;
+	search(criteria: unknown[]): Promise<number[]>;
+	fetchMessages(uids: number[]): Promise<ImapMessage[]>;
+	/**
+	 * Cheap envelope-only pass for the UIDVALIDITY cursor rebuild (#1272): UID
+	 * + Message-ID + INTERNALDATE for every UID, no BODYSTRUCTURE, no flags,
+	 * no body. Requires a mailbox to be open.
+	 */
+	fetchEnvelopeSnapshots(uids: number[]): Promise<ImapEnvelopeSnapshot[]>;
+	fetchMessageBody(uid: number): Promise<Buffer>;
+	/**
+	 * Fetch full message bodies for many UIDs in ONE pipelined ranged UID FETCH.
+	 * Yields `{ uid, source }` per message; `source` is a readable stream the
+	 * caller must consume before requesting the next item. Requires a mailbox to
+	 * be open (one SELECT for the whole batch).
+	 */
+	fetchMessageBodies(
+		uids: number[],
+	): AsyncGenerator<{ uid: number; source: Readable }>;
+	/**
+	 * Add flags to messages by UID.
+	 * Requires mailbox to be open.
+	 */
+	addFlags(uids: number[], flags: string[]): Promise<void>;
+	/**
+	 * Remove flags from messages by UID.
+	 * Requires mailbox to be open.
+	 */
+	removeFlags(uids: number[], flags: string[]): Promise<void>;
+	/**
+	 * Replace all flags on messages by UID.
+	 * Requires mailbox to be open.
+	 */
+	setFlags(uids: number[], flags: string[]): Promise<void>;
+	/**
+	 * Create a new mailbox.
+	 */
+	createMailbox(path: string): Promise<{ path: string; created: boolean }>;
+	/**
+	 * Delete a mailbox.
+	 */
+	deleteMailbox(path: string): Promise<{ path: string }>;
+	/**
+	 * Rename a mailbox.
+	 */
+	renameMailbox(
+		oldPath: string,
+		newPath: string,
+	): Promise<{ path: string; newPath: string }>;
+	/**
+	 * Subscribe to a mailbox.
+	 */
+	subscribeMailbox(path: string): Promise<void>;
+	/**
+	 * Unsubscribe from a mailbox.
+	 */
+	unsubscribeMailbox(path: string): Promise<void>;
+	/**
+	 * Move messages to another mailbox.
+	 * Returns mapping of source UIDs to destination UIDs.
+	 * Requires mailbox to be open.
+	 *
+	 * @param uids - Array of message UIDs to move
+	 * @param destination - Destination mailbox path
+	 * @returns Object with destination path, uidValidity, and uidMap
+	 */
+	moveMessages(
+		uids: number[],
+		destination: string,
+	): Promise<{
+		destination: string;
+		uidValidity: number;
+		uidMap: Map<number, number>;
+	}>;
+	/**
+	 * Copy messages to another mailbox.
+	 * Returns mapping of source UIDs to destination UIDs.
+	 * Requires mailbox to be open.
+	 *
+	 * @param uids - Array of message UIDs to copy
+	 * @param destination - Destination mailbox path
+	 * @returns Object with destination path, uidValidity, and uidMap
+	 */
+	copyMessages(
+		uids: number[],
+		destination: string,
+	): Promise<{
+		destination: string;
+		uidValidity: number;
+		uidMap: Map<number, number>;
+	}>;
+	/**
+	 * Permanently delete messages (mark \Deleted + expunge).
+	 * Requires mailbox to be open.
+	 *
+	 * @param uids - Array of message UIDs to delete
+	 * @returns Number of messages deleted
+	 */
+	deleteMessages(uids: number[]): Promise<number>;
+	/**
+	 * Get mailbox status without opening it.
+	 * Uses IMAP STATUS command to get message counts.
+	 *
+	 * @param mailboxPath - Full path to the mailbox
+	 * @returns Mailbox status including unseen count
+	 */
+	getMailboxStatus(mailboxPath: string): Promise<ImapMailboxStatus>;
+	/**
+	 * Append a message to a mailbox via IMAP APPEND command.
+	 *
+	 * @param mailbox - Full path of the target mailbox
+	 * @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(
+		mailbox: string,
+		message: string | Buffer,
+		flags?: string[],
+	): Promise<{
+		destination: string;
+		uidValidity: number;
+		uid: number;
+	}>;
+}

package/test/fixtures/mime/01-flat-text-plain.bodyparts.json

@@ -0,0 +1,8 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "plain"
+  }
+]

package/test/fixtures/mime/01-flat-text-plain.eml

@@ -0,0 +1,10 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Flat text/plain fixture 01
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-01@example.org>
+MIME-Version: 1.0
+Content-Type: text/plain; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+Hello bob, this is a flat text/plain message.

package/test/fixtures/mime/01-flat-text-plain.expected.json

@@ -0,0 +1,10 @@
+{
+  "pairs": [
+    {
+      "partPath": "0",
+      "contentType": "text/plain",
+      "contentSha256": "55ac4ab155dd2b05e3d4ffb422c6fc2539484dfb07c7b5b5fac1d0035ac1f6db",
+      "contentLength": 46
+    }
+  ]
+}

package/test/fixtures/mime/02-flat-text-html.bodyparts.json

@@ -0,0 +1,8 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "html"
+  }
+]

package/test/fixtures/mime/02-flat-text-html.eml

@@ -0,0 +1,10 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Flat text/html fixture 02
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-02@example.org>
+MIME-Version: 1.0
+Content-Type: text/html; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+<html><body><p>Hello bob, this is a flat <b>text/html</b> message.</p></body></html>

package/test/fixtures/mime/02-flat-text-html.expected.json

@@ -0,0 +1,10 @@
+{
+  "pairs": [
+    {
+      "partPath": "0",
+      "contentType": "text/html",
+      "contentSha256": "4484f960dbbb61e252b8ac3dd516a3c651a90ed666781befe67c6e13d30f3b4e",
+      "contentLength": 85
+    }
+  ]
+}

package/test/fixtures/mime/03-alternative-text-html.bodyparts.json

@@ -0,0 +1,20 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": true,
+    "mediaType": "MULTIPART",
+    "mediaSubtype": "alternative"
+  },
+  {
+    "partPath": "1",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "plain"
+  },
+  {
+    "partPath": "2",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "html"
+  }
+]

package/test/fixtures/mime/03-alternative-text-html.eml

@@ -0,0 +1,19 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Alternative text+html fixture 03
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-03@example.org>
+MIME-Version: 1.0
+Content-Type: multipart/alternative; boundary="=_boundary_03_="
+
+--=_boundary_03_=
+Content-Type: text/plain; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+Hello bob, plain text body.
+--=_boundary_03_=
+Content-Type: text/html; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+<html><body><p>Hello bob, html body.</p></body></html>
+--=_boundary_03_=--

package/test/fixtures/mime/03-alternative-text-html.expected.json

@@ -0,0 +1,16 @@
+{
+  "pairs": [
+    {
+      "partPath": "1",
+      "contentType": "text/plain",
+      "contentSha256": "54178e683cea517723189e2851efd8449bac73f2b57c50bd81a0c8a6df4ce7c8",
+      "contentLength": 27
+    },
+    {
+      "partPath": "2",
+      "contentType": "text/html",
+      "contentSha256": "71744f8d83087de2acde32d5b9ec93ecfe1b5ba677f760655643dabfd0ce661d",
+      "contentLength": 54
+    }
+  ]
+}

package/test/fixtures/mime/04-mixed-html-pdf-attachment.bodyparts.json

@@ -0,0 +1,22 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": true,
+    "mediaType": "MULTIPART",
+    "mediaSubtype": "mixed"
+  },
+  {
+    "partPath": "1",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "html"
+  },
+  {
+    "partPath": "2",
+    "isMultipart": false,
+    "mediaType": "APPLICATION",
+    "mediaSubtype": "pdf",
+    "dispositionFilename": "invoice.pdf",
+    "disposition": "attachment"
+  }
+]

package/test/fixtures/mime/04-mixed-html-pdf-attachment.eml

@@ -0,0 +1,20 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Mixed html + pdf fixture 04
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-04@example.org>
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="=_boundary_04_="
+
+--=_boundary_04_=
+Content-Type: text/html; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+<html><body><p>See attached invoice.</p></body></html>
+--=_boundary_04_=
+Content-Type: application/pdf; name="invoice.pdf"
+Content-Transfer-Encoding: base64
+Content-Disposition: attachment; filename="invoice.pdf"
+
+JVBERi0xLjQKJWZha2UgcGRmIGZvciBmaXh0dXJlIDA0CiVFT0YK
+--=_boundary_04_=--

package/test/fixtures/mime/04-mixed-html-pdf-attachment.expected.json

@@ -0,0 +1,16 @@
+{
+  "pairs": [
+    {
+      "partPath": "1",
+      "contentType": "text/html",
+      "contentSha256": "d8d4d207e4f8d121a1d60fe74922da8b562ebada6a4a58b2d0f2b1bcac2ae5d7",
+      "contentLength": 54
+    },
+    {
+      "partPath": "2",
+      "contentType": "application/pdf",
+      "contentSha256": "1e82c5ee13ccddf36b4abc368c682a08ed1bc5671101c76062183c8e9914fb41",
+      "contentLength": 39
+    }
+  ]
+}

package/test/fixtures/mime/05-mixed-html-octet-stream-pdf.bodyparts.json

@@ -0,0 +1,22 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": true,
+    "mediaType": "MULTIPART",
+    "mediaSubtype": "mixed"
+  },
+  {
+    "partPath": "1",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "html"
+  },
+  {
+    "partPath": "2",
+    "isMultipart": false,
+    "mediaType": "APPLICATION",
+    "mediaSubtype": "octet-stream",
+    "dispositionFilename": "contract.pdf",
+    "disposition": "attachment"
+  }
+]

package/test/fixtures/mime/05-mixed-html-octet-stream-pdf.eml

@@ -0,0 +1,21 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Mixed html + octet-stream PDF fixture 05 (Odido bug)
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-05@example.org>
+MIME-Version: 1.0
+Content-Type: multipart/mixed; boundary="=_boundary_05_="
+
+--=_boundary_05_=
+Content-Type: text/html; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+<html><body><p>Your contract PDF is attached.</p></body></html>
+--=_boundary_05_=
+Content-Type: application/octet-stream; name="contract.pdf"
+Content-Transfer-Encoding: base64
+Content-Disposition: attachment; filename="contract.pdf"
+
+JVBERi0xLjQKJWZha2UgcGRmIGZvciBmaXh0dXJlIDA1IG9jdGV0LXN0cmVhbQol
+RU9GCg==
+--=_boundary_05_=--

package/test/fixtures/mime/05-mixed-html-octet-stream-pdf.expected.json

@@ -0,0 +1,16 @@
+{
+  "pairs": [
+    {
+      "partPath": "1",
+      "contentType": "text/html",
+      "contentSha256": "9fd8608290b5e5c88848e336235fbcf48d4797290c631b9f73bb9f13c7ce3515",
+      "contentLength": 63
+    },
+    {
+      "partPath": "2",
+      "contentType": "application/octet-stream",
+      "contentSha256": "649331fa0bcf7487ba5529a34be1b2629f76e7906548321283d9255ad4ef53eb",
+      "contentLength": 52
+    }
+  ]
+}

package/test/fixtures/mime/06-related-html-cid-image.bodyparts.json

@@ -0,0 +1,23 @@
+[
+  {
+    "partPath": "0",
+    "isMultipart": true,
+    "mediaType": "MULTIPART",
+    "mediaSubtype": "related"
+  },
+  {
+    "partPath": "1",
+    "isMultipart": false,
+    "mediaType": "TEXT",
+    "mediaSubtype": "html"
+  },
+  {
+    "partPath": "2",
+    "isMultipart": false,
+    "mediaType": "IMAGE",
+    "mediaSubtype": "png",
+    "contentId": "logo@example.org",
+    "dispositionFilename": "logo.png",
+    "disposition": "inline"
+  }
+]

package/test/fixtures/mime/06-related-html-cid-image.eml

@@ -0,0 +1,21 @@
+From: alice@example.org
+To: bob@example.org
+Subject: Related html + cid image fixture 06
+Date: Thu, 28 May 2026 09:00:00 +0000
+Message-Id: <fixture-06@example.org>
+MIME-Version: 1.0
+Content-Type: multipart/related; boundary="=_boundary_06_="; type="text/html"
+
+--=_boundary_06_=
+Content-Type: text/html; charset=us-ascii
+Content-Transfer-Encoding: 7bit
+
+<html><body><p>Inline image: <img src="cid:logo@example.org"></p></body></html>
+--=_boundary_06_=
+Content-Type: image/png; name="logo.png"
+Content-Transfer-Encoding: base64
+Content-Disposition: inline; filename="logo.png"
+Content-ID: <logo@example.org>
+
+iVBORw0KGgpmaXh0dXJlMDZwbmdieXRlcw==
+--=_boundary_06_=--

package/test/fixtures/mime/06-related-html-cid-image.expected.json

@@ -0,0 +1,16 @@
+{
+  "pairs": [
+    {
+      "partPath": "1",
+      "contentType": "text/html",
+      "contentSha256": "212c7f36413be9efaf441c588da97719f947a2210f76c98d05f21ad7480f1c8a",
+      "contentLength": 117
+    },
+    {
+      "partPath": "2",
+      "contentType": "image/png",
+      "contentSha256": "c5a79659b71cb6866a73f688ef63a29e163065f6dbb6aba3da932bc872e475d6",
+      "contentLength": 25
+    }
+  ]
+}