@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/imapflow-connection.d.ts

@@ -0,0 +1,377 @@
+/**
+ * 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 type { FlatMailboxInfo, ImapBoxStatus, ImapConnectionConfig, ImapConnectionState, ImapEnvelopeSnapshot, ImapMailboxStatus, ImapMessage, ImapNamespaces } 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 declare const toIsoDateString: (value: unknown) => string;
+/**
+ * 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 declare const toInternalDate: (value: unknown) => Date | null;
+/**
+ * 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 declare const convertSearchCriteria: (criteria: unknown[]) => Record<string, unknown>;
+/**
+ * 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 declare class ImapFlowConnection {
+    private client;
+    private _state;
+    private config;
+    private currentMailbox;
+    constructor(config: ImapConnectionConfig);
+    /**
+     * Current connection state
+     */
+    get state(): ImapConnectionState;
+    /**
+     * Whether the connection is established and authenticated
+     */
+    get isConnected(): boolean;
+    /**
+     * 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: () => Promise<void>;
+    /**
+     * Single connection attempt
+     */
+    private attemptConnect;
+    /**
+     * Cleanup client state for retry
+     */
+    private cleanup;
+    /**
+     * Sleep for a specified duration
+     */
+    private sleep;
+    /**
+     * Disconnect from the IMAP server
+     */
+    disconnect: () => Promise<void>;
+    /**
+     * 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: () => Promise<ImapNamespaces>;
+    /**
+     * 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: (nsPrefix?: string) => Promise<FlatMailboxInfo[]>;
+    /**
+     * Convert ImapFlow flags Set to string array
+     */
+    private convertFlags;
+    /**
+     * 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: (mailboxPath: string, readOnly?: boolean) => Promise<ImapBoxStatus>;
+    /**
+     * Build an ImapBoxStatus from an imapflow MailboxObject.
+     */
+    private toBoxStatus;
+    /**
+     * Close the currently open mailbox
+     *
+     * @param _expunge - Whether to permanently remove deleted messages (not used in ImapFlow)
+     */
+    closeBox: (_expunge?: boolean) => Promise<void>;
+    /**
+     * 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: (criteria: unknown[]) => Promise<number[]>;
+    /**
+     * Fetch messages by UID
+     *
+     * Uses ImapFlow's native envelope parsing which works correctly
+     * with all IMAP servers including mokapi.
+     */
+    fetchMessages: (uids: number[]) => Promise<ImapMessage[]>;
+    /**
+     * 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;
+    /**
+     * 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: (sinceModseq: bigint) => Promise<ImapMessage[]>;
+    /**
+     * 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;
+    /**
+     * 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: (uids: number[]) => Promise<ImapEnvelopeSnapshot[]>;
+    /**
+     * 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: (uid: number) => Promise<Buffer | 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.
+     */
+    fetchMessageBodies(uids: number[]): AsyncGenerator<{
+        uid: number;
+        source: Readable;
+    }>;
+    /**
+     * Parse the References header from IMAP headers buffer.
+     * Returns an array of Message-IDs, with the first being the thread root.
+     */
+    private parseReferencesHeader;
+    /**
+     * Convert ImapFlow envelope to our ImapEnvelope format
+     */
+    private convertEnvelope;
+    /**
+     * 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: (uids: number[], flags: string[]) => Promise<void>;
+    /**
+     * 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: (uids: number[], flags: string[]) => Promise<void>;
+    /**
+     * 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: (uids: number[], flags: string[]) => Promise<void>;
+    /**
+     * 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: (path: string) => Promise<{
+        path: string;
+        created: boolean;
+    }>;
+    /**
+     * Delete a mailbox.
+     *
+     * @param path - Full path of the mailbox to delete
+     * @returns Object with the deleted path
+     */
+    deleteMailbox: (path: string) => Promise<{
+        path: string;
+    }>;
+    /**
+     * 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: (oldPath: string, newPath: string) => Promise<{
+        path: string;
+        newPath: string;
+    }>;
+    /**
+     * Subscribe to a mailbox.
+     *
+     * @param path - Full path of the mailbox to subscribe to
+     */
+    subscribeMailbox: (path: string) => Promise<void>;
+    /**
+     * Unsubscribe from a mailbox.
+     *
+     * @param path - Full path of the mailbox to unsubscribe from
+     */
+    unsubscribeMailbox: (path: string) => Promise<void>;
+    /**
+     * 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: (uids: number[], destination: string) => Promise<{
+        destination: string;
+        uidValidity: number;
+        uidMap: Map<number, number>;
+    }>;
+    /**
+     * 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: (uids: number[], destination: string) => Promise<{
+        destination: string;
+        uidValidity: number;
+        uidMap: Map<number, number>;
+    }>;
+    /**
+     * 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: (uids: number[]) => Promise<number>;
+    /**
+     * 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: (mailboxPath: string) => Promise<ImapMailboxStatus>;
+    /**
+     * 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;
+    /**
+     * 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: (mailbox: string, message: string | Buffer, flags?: string[]) => Promise<{
+        destination: string;
+        uidValidity: number;
+        uid: number;
+    }>;
+    /**
+     * Ensure the connection is established
+     */
+    private ensureConnected;
+}
+/**
+ * Create an ImapFlow connection from account data using password credentials.
+ */
+export declare const createImapFlowConnectionFromAccount: (account: {
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    username: string;
+}, password: string) => ImapFlowConnection;
+/**
+ * Create an ImapFlow connection using a credentials union (password or OAuth access token).
+ */
+export declare const createImapFlowConnectionWithCredentials: (account: {
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    username: string;
+}, credentials: import("./types.js").MailCredentials) => ImapFlowConnection;