@remit/mailbox-service 0.0.111 → 0.0.113

package/src/types.ts

@@ -1,371 +0,0 @@
-/**
- * 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) as decimal digits of an unsigned 64-bit value. "0" if the server does not support CONDSTORE. */
-	highestModseq: string;
-	/** 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;
-	/**
-	 * Per-message MODSEQ (RFC 7162) as decimal digits of an unsigned 64-bit
-	 * value. Absent when the session has no CONDSTORE.
-	 */
-	modseq?: string;
-}
-
-/**
- * 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[]>;
-	/**
-	 * True when the session negotiated CONDSTORE (RFC 7162) AND the currently
-	 * open mailbox keeps persistent mod-sequences. A mailbox that answered
-	 * NOMODSEQ on SELECT reports false, as does any server that never
-	 * advertised the extension. Requires a mailbox to be open.
-	 */
-	supportsCondstore(): boolean;
-	/**
-	 * FETCH every message in the open mailbox whose MODSEQ is strictly greater
-	 * than `sinceModseq` (RFC 7162 CHANGEDSINCE) — both messages that arrived
-	 * and messages whose metadata changed. Requires a mailbox to be open.
-	 *
-	 * Throws when CONDSTORE is unavailable: the underlying client drops the
-	 * modifier in that case, which would silently turn the call into a fetch of
-	 * the entire mailbox.
-	 */
-	fetchMessagesChangedSince(sinceModseq: bigint): 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 | null>;
-	/**
-	 * 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-adversarial-e2e/01-octet-stream-pdf.eml

@@ -1,21 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 01 octet-stream PDF (Odido shape, #394)
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-01-octet-stream-pdf@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv01_="
-
---=_adv01_=
-Content-Type: text/html; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-<html><body><p>Your contract PDF is attached.</p></body></html>
---=_adv01_=
-Content-Type: application/octet-stream; name="contract.pdf"
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="contract.pdf"
-
-JVBERi0xLjQKJWZha2UgcGRmIGZvciBhZHZlcnNhcmlhbCBmaXh0dXJlIDAxIG9j
-dGV0LXN0cmVhbQolRU9GCg==
---=_adv01_=--

package/test/fixtures/mime-adversarial-e2e/02-nested-related-cid-image.eml

@@ -1,31 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 02 nested related html + cid image
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-02-nested-related@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv02_outer_="
-
---=_adv02_outer_=
-Content-Type: multipart/related; boundary="=_adv02_inner_="; type="text/html"
-
---=_adv02_inner_=
-Content-Type: text/html; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-<html><body><p>Hi bob,</p><p>Inline logo: <img src="cid:logo@example.com" alt="logo"></p><p>-- alice</p></body></html>
---=_adv02_inner_=
-Content-Type: image/png; name="logo.png"
-Content-Transfer-Encoding: base64
-Content-Disposition: inline; filename="logo.png"
-Content-ID: <logo@example.com>
-
-iVBORw0KGgpmaXh0dXJlMDJjaWRpbWFnZWJ5dGVz
---=_adv02_inner_=--
---=_adv02_outer_=
-Content-Type: application/pdf; name="invoice.pdf"
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="invoice.pdf"
-
-JVBERi0xLjQKJWFkdiAwMiBmaXh0dXJlIGludm9pY2UKJUVPRgo=
---=_adv02_outer_=--

package/test/fixtures/mime-adversarial-e2e/03-calendar-invite.eml

@@ -1,33 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 03 calendar invite + html
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-03-calendar@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv03_="
-
---=_adv03_=
-Content-Type: text/html; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-<html><body><p>Hi bob,</p><p>Meeting invite for our sync on Monday is attached.</p><p>-- alice</p></body></html>
---=_adv03_=
-Content-Type: text/calendar; method=REQUEST; charset=us-ascii; name="invite.ics"
-Content-Transfer-Encoding: 7bit
-Content-Disposition: attachment; filename="invite.ics"
-
-BEGIN:VCALENDAR
-VERSION:2.0
-PRODID:-//Remit//Adversarial Fixture 03//EN
-METHOD:REQUEST
-BEGIN:VEVENT
-UID:adv-03-event@example.com
-DTSTAMP:20260529T090000Z
-DTSTART:20260601T140000Z
-DTEND:20260601T150000Z
-SUMMARY:Adversarial fixture 03 sync
-ORGANIZER:mailto:alice@example.com
-ATTENDEE:mailto:bob@example.com
-END:VEVENT
-END:VCALENDAR
---=_adv03_=--

package/test/fixtures/mime-adversarial-e2e/04-forwarded-rfc822-with-attachments.eml

@@ -1,42 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 04 forwarded rfc822 with inner attachment
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-04-forwarded@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv04_outer_="
-
---=_adv04_outer_=
-Content-Type: text/plain; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-Hi bob,
-
-Forwarding the message below for your records. Note the original carries its own attachment.
-
--- alice
---=_adv04_outer_=
-Content-Type: message/rfc822
-Content-Disposition: attachment; filename="forwarded.eml"
-
-From: carol@example.com
-To: alice@example.com
-Subject: Original message with attachment for fixture 04
-Date: Thu, 28 May 2026 12:00:00 +0000
-Message-Id: <adv-04-inner@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv04_inner_="
-
---=_adv04_inner_=
-Content-Type: text/plain; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-Original message body before forwarding.
---=_adv04_inner_=
-Content-Type: application/pdf; name="original.pdf"
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="original.pdf"
-
-JVBERi0xLjQKJWFkdiAwNCBpbm5lciBwZGYKJUVPRgo=
---=_adv04_inner_=--
---=_adv04_outer_=--

package/test/fixtures/mime-adversarial-e2e/05-tnef-winmail.eml

@@ -1,25 +0,0 @@
-X-Remit-Fixture-Note: Synthetic TNEF stub for fixture 05. mailparser surfaces this as an application/ms-tnef attachment with filename "winmail.dat" — which is the #402 contract. The trailing BODYSTRUCTURE round-trip via imapflow is skipped for this shape (see EXPECTATIONS in adversarial-mime.e2e.test.ts). TODO(#402): replace with a real-world winmail.dat capture once we have one to ship.
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 05 Outlook TNEF winmail.dat
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-05-tnef@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/mixed; boundary="=_adv05_="
-
---=_adv05_=
-Content-Type: text/plain; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-Hi bob,
-
-This message carries the Microsoft TNEF (winmail.dat) shape that some Outlook senders still produce. Remit should list the attachment without crashing the body sync.
-
--- alice
---=_adv05_=
-Content-Type: application/ms-tnef; name="winmail.dat"
-Content-Transfer-Encoding: base64
-Content-Disposition: attachment; filename="winmail.dat"
-
-eJ8+IgEAAAABAAAACAAAAAAAAAA=
---=_adv05_=--

package/test/fixtures/mime-adversarial-e2e/06-8bit-non-ascii.eml

@@ -1,15 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: =?UTF-8?B?Q2Fmw6kgZmHDp2FkZSAtIGFkdmVyc2FyaWFsIGZpeHR1cmUgMDY=?=
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-06-8bit@example.com>
-MIME-Version: 1.0
-Content-Type: text/plain; charset=utf-8
-Content-Transfer-Encoding: 8bit
-
-Hallo bob,
-
-De café op de hoek heeft een prachtige façade. We’ll meet there — ben je vrij?
-
-Groetjes,
-alice

package/test/fixtures/mime-adversarial-e2e/07-quoted-printable-soft-breaks.eml

@@ -1,17 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 07 quoted-printable with soft line breaks
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-07-qp@example.com>
-MIME-Version: 1.0
-Content-Type: text/plain; charset=utf-8
-Content-Transfer-Encoding: quoted-printable
-
-Hi bob,
-
-This paragraph deliberately uses quoted-printable soft line breaks so a sing=
-le logical line is wrapped across multiple physical lines without inserting=
- a real newline. The body-sync pipeline must reassemble it back into one l=
-ogical line when rendering.
-
-Also includes a non-ASCII token: caf=C3=A9 r=C3=A9union =E2=80=94 alice

package/test/fixtures/mime-adversarial-e2e/08-alternative-empty-text.eml

@@ -1,18 +0,0 @@
-From: alice@example.com
-To: bob@example.com
-Subject: Adversarial fixture 08 alternative with empty text/plain
-Date: Fri, 29 May 2026 09:00:00 +0000
-Message-Id: <adv-08-empty-text-alt@example.com>
-MIME-Version: 1.0
-Content-Type: multipart/alternative; boundary="=_adv08_="
-
---=_adv08_=
-Content-Type: text/plain; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
---=_adv08_=
-Content-Type: text/html; charset=us-ascii
-Content-Transfer-Encoding: 7bit
-
-<html><body><p>Hi bob,</p><p>The text/plain sibling of this multipart/alternative is intentionally empty. The HTML part must still render.</p><p>-- alice</p></body></html>
---=_adv08_=--

package/tsconfig.json

@@ -1,8 +0,0 @@
-{
-	"extends": "../../tsconfig.json",
-	"compilerOptions": {
-		"outDir": "dist",
-		"rootDir": "src"
-	},
-	"include": ["src/**/*.ts"]
-}