@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/text/normalizer.js

@@ -0,0 +1,102 @@
+/**
+ * Multilingual text normalizer for email processing.
+ *
+ * Uses franc for language detection, natural for stemming,
+ * and stopword for stopword removal.
+ */
+/// <reference path="../types/natural-porter-stemmer.d.ts" />
+import { franc } from "franc";
+// Import each Porter stemmer file directly instead of the `natural` package
+// root or its `stemmers` submodule barrel: the root barrel
+// (`natural/lib/natural/index.js`) loads WordNet and the Brill POS tagger,
+// which pull in `mongoose` and — via its Postgres storage plugin —
+// `pg`/`dotenv` (`dotenv.config()` at module scope on every cold start, see
+// #1244/#1247); the `stemmers` barrel is CJS and unconditionally requires
+// every stemmer it lists, including Japanese (which drags in its own
+// tokenizer) and Indonesian, neither used here. This module only needs the
+// seven Porter stemmers below — see
+// ../types/natural-porter-stemmer.d.ts for their (hand-written, since
+// `natural` ships none for individual files) type declarations.
+import PorterStemmer from "natural/lib/natural/stemmers/porter_stemmer.js";
+import PorterStemmerDe from "natural/lib/natural/stemmers/porter_stemmer_de.js";
+import PorterStemmerEs from "natural/lib/natural/stemmers/porter_stemmer_es.js";
+import PorterStemmerFr from "natural/lib/natural/stemmers/porter_stemmer_fr.js";
+import PorterStemmerIt from "natural/lib/natural/stemmers/porter_stemmer_it.js";
+import PorterStemmerNl from "natural/lib/natural/stemmers/porter_stemmer_nl.js";
+import PorterStemmerPt from "natural/lib/natural/stemmers/porter_stemmer_pt.js";
+import { deu, eng, fra, ita, nld, por, removeStopwords, spa } from "stopword";
+// ISO 639-3 (franc) → ISO 639-1 (our SupportedLanguage)
+const iso3ToIso1 = {
+    eng: "en",
+    deu: "de",
+    fra: "fr",
+    nld: "nl",
+    spa: "es",
+    ita: "it",
+    por: "pt",
+};
+// Restrict franc to only detect languages we can stem
+const supportedIso3 = Object.keys(iso3ToIso1);
+const stemmers = {
+    en: PorterStemmer,
+    de: PorterStemmerDe,
+    fr: PorterStemmerFr,
+    es: PorterStemmerEs,
+    it: PorterStemmerIt,
+    nl: PorterStemmerNl,
+    pt: PorterStemmerPt,
+};
+const stopwordLists = {
+    en: eng,
+    de: deu,
+    fr: fra,
+    es: spa,
+    it: ita,
+    nl: nld,
+    pt: por,
+};
+export const createTextNormalizer = () => ({
+    detectLanguage: (text) => {
+        // Use franc with trigram analysis, restricted to supported languages
+        const detected = franc(text, { only: supportedIso3, minLength: 10 });
+        // Map to our language codes, default to English
+        return iso3ToIso1[detected] ?? "en";
+    },
+    normalize: (text, options = {}) => {
+        const { language = "en", stem = true, removeStopwords: removeStop = true, } = options;
+        // Normalize unicode and lowercase
+        let normalized = text.normalize("NFKC").toLowerCase();
+        // Keep Unicode letters and numbers, remove punctuation
+        normalized = normalized.replace(/[^\p{L}\p{N}\s]/gu, " ");
+        // Tokenize
+        let words = normalized.split(/\s+/).filter((w) => w.length > 0);
+        // Remove stopwords
+        if (removeStop) {
+            const list = stopwordLists[language] ?? eng;
+            words = removeStopwords(words, list);
+        }
+        // Stem
+        if (stem) {
+            const stemmer = stemmers[language] ?? stemmers.en;
+            words = words.map((w) => stemmer.stem(w));
+        }
+        // Dedupe consecutive words
+        return words.filter((w, i, arr) => i === 0 || w !== arr[i - 1]).join(" ");
+    },
+    tokenize: (text) => {
+        return text
+            .normalize("NFKC")
+            .toLowerCase()
+            .replace(/[^\p{L}\p{N}\s]/gu, " ")
+            .split(/\s+/)
+            .filter((w) => w.length > 0);
+    },
+    stem: (word, language = "en") => {
+        const stemmer = stemmers[language] ?? stemmers.en;
+        return stemmer.stem(word.toLowerCase());
+    },
+    removeStopwords: (words, language = "en") => {
+        const list = stopwordLists[language] ?? eng;
+        return removeStopwords(words, list);
+    },
+});

package/dist/thread-message-rows.d.ts

@@ -0,0 +1,69 @@
+import type { ThreadMessageItem } from "@remit/data-ports";
+/**
+ * Build the `set` and `composites` payload for the ThreadMessage update on a
+ * MESSAGE_DELETE move-to-trash.
+ *
+ * The CURRENT row state goes in `composites`; the NEW values go in `set`.
+ * ElectroDB uses `composites` to run the conditional check on the existing row
+ * AND to compute the previous sort-key values needed to recompute the new ones.
+ * Passing the NEW values in `composites` makes the conditional check fail with
+ * ConditionalCheckFailedException, which ElectroDB wraps as NotFoundError, and
+ * the caller silently drops the update. Same root cause as PR #186 fixed for
+ * `flag-queue.ts`.
+ */
+export type ThreadMessageRowState = Pick<ThreadMessageItem, "sentDate" | "mailboxId" | "isRead" | "isDeleted" | "hasStars" | "hasAttachment">;
+export declare const buildThreadMessageTrashUpdate: (threadMessage: ThreadMessageRowState, newUid: number, destinationMailboxId: string) => {
+    set: {
+        uid: number;
+        mailboxId: string;
+        isDeleted: boolean;
+    };
+    composites: {
+        sentDate: number;
+        mailboxId: string;
+        isRead: boolean;
+        isDeleted: boolean;
+        hasStars: boolean;
+        hasAttachment: boolean;
+    };
+};
+/**
+ * The inverse payload: put the thread row back where the message still is on
+ * the server. The delete was recorded optimistically, so a delete that gives up
+ * with the message still at its source has to hand the row back rather than
+ * leave it claiming Trash — an invisible `failed` on a row the user cannot see
+ * is the shape of the incident this whole change is about.
+ */
+export declare const buildThreadMessageMoveRevert: (threadMessage: ThreadMessageRowState, sourceUid: number, sourceMailboxId: string) => {
+    set: {
+        uid: number;
+        mailboxId: string;
+        isDeleted: boolean;
+    };
+    composites: {
+        sentDate: number;
+        mailboxId: string;
+        isRead: boolean;
+        isDeleted: boolean;
+        hasStars: boolean;
+        hasAttachment: boolean;
+    };
+};
+/**
+ * Hand a row back after an abandoned expunge. The mail never left Trash, so
+ * only the deletion mark reverts — the uid and mailbox on the row are still
+ * where the server has it.
+ */
+export declare const buildThreadMessageUndelete: (threadMessage: ThreadMessageRowState) => {
+    set: {
+        isDeleted: boolean;
+    };
+    composites: {
+        sentDate: number;
+        mailboxId: string;
+        isRead: boolean;
+        isDeleted: boolean;
+        hasStars: boolean;
+        hasAttachment: boolean;
+    };
+};

package/dist/thread-message-rows.js

@@ -0,0 +1,40 @@
+const currentComposites = (threadMessage) => ({
+    sentDate: threadMessage.sentDate,
+    mailboxId: threadMessage.mailboxId,
+    isRead: threadMessage.isRead,
+    isDeleted: threadMessage.isDeleted,
+    hasStars: threadMessage.hasStars,
+    hasAttachment: threadMessage.hasAttachment,
+});
+export const buildThreadMessageTrashUpdate = (threadMessage, newUid, destinationMailboxId) => ({
+    set: {
+        uid: newUid,
+        mailboxId: destinationMailboxId,
+        isDeleted: true,
+    },
+    composites: currentComposites(threadMessage),
+});
+/**
+ * The inverse payload: put the thread row back where the message still is on
+ * the server. The delete was recorded optimistically, so a delete that gives up
+ * with the message still at its source has to hand the row back rather than
+ * leave it claiming Trash — an invisible `failed` on a row the user cannot see
+ * is the shape of the incident this whole change is about.
+ */
+export const buildThreadMessageMoveRevert = (threadMessage, sourceUid, sourceMailboxId) => ({
+    set: {
+        uid: sourceUid,
+        mailboxId: sourceMailboxId,
+        isDeleted: false,
+    },
+    composites: currentComposites(threadMessage),
+});
+/**
+ * Hand a row back after an abandoned expunge. The mail never left Trash, so
+ * only the deletion mark reverts — the uid and mailbox on the row are still
+ * where the server has it.
+ */
+export const buildThreadMessageUndelete = (threadMessage) => ({
+    set: { isDeleted: false },
+    composites: currentComposites(threadMessage),
+});

package/dist/thread-root.d.ts

@@ -0,0 +1,7 @@
+import type { MessageReferenceInput } from "@remit/data-ports";
+import type { ImapEnvelope } from "./types.js";
+type ThreadingHeaders = Pick<ImapEnvelope, "messageId" | "inReplyTo">;
+export declare const threadRootOf: (envelope: ThreadingHeaders, references: readonly string[] | undefined, messageId: string) => string;
+export declare const parentOf: (envelope: ThreadingHeaders, references: readonly string[] | undefined) => string | undefined;
+export declare const messageReferencesOf: (envelope: ThreadingHeaders, references: readonly string[] | undefined) => MessageReferenceInput[];
+export {};

package/dist/thread-root.js

@@ -0,0 +1,25 @@
+import { bareMessageId, isValidMessageId, wireMessageId, } from "@remit/data-ports/id";
+import { ReferenceType } from "@remit/domain-enums";
+const firstUsable = (candidates) => {
+    const found = candidates.find(isValidMessageId);
+    return found === undefined ? undefined : wireMessageId(found);
+};
+export const threadRootOf = (envelope, references, messageId) => firstUsable([references?.[0], envelope.inReplyTo, envelope.messageId]) ??
+    messageId;
+export const parentOf = (envelope, references) => firstUsable([envelope.inReplyTo, references?.[references.length - 1]]);
+export const messageReferencesOf = (envelope, references) => [
+    ...(isValidMessageId(envelope.inReplyTo)
+        ? [
+            {
+                messageIdValue: bareMessageId(envelope.inReplyTo),
+                referenceType: ReferenceType.InReplyTo,
+                referenceOrder: 0,
+            },
+        ]
+        : []),
+    ...(references ?? []).filter(isValidMessageId).map((reference, index) => ({
+        messageIdValue: bareMessageId(reference),
+        referenceType: ReferenceType.References,
+        referenceOrder: index,
+    })),
+];

package/dist/types.d.ts

@@ -0,0 +1,343 @@
+/**
+ * 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 declare class MailConnectionError extends Error {
+    readonly kind: MailConnectionErrorKind;
+    constructor(kind: MailConnectionErrorKind, message: string, cause?: unknown);
+}
+/**
+ * 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/dist/types.js

@@ -0,0 +1,19 @@
+/**
+ * Types for the remit-mailbox-service
+ */
+/**
+ * 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 {
+    kind;
+    constructor(kind, message, cause) {
+        super(message, { cause });
+        this.name = "MailConnectionError";
+        this.kind = kind;
+    }
+}