@remit/mailbox-service 0.0.111 → 0.0.113

package/dist/calendar-parts.d.ts

@@ -0,0 +1,23 @@
+import { CalendarSuggestionSource } from "@remit/domain-enums";
+import type { ParsedMail } from "mailparser";
+/**
+ * One `text/calendar` part of a message, and where it sat.
+ *
+ * The distinction between an inline part and an attached one is not cosmetic:
+ * a scheduling client sends the invitation inline as part of a
+ * `multipart/alternative`, while a client that cannot speak iTIP attaches an
+ * `.ics` file. Both carry the same bytes, and a card says which it read.
+ */
+export interface CalendarPart {
+    partPath: string;
+    source: typeof CalendarSuggestionSource.IcalendarPart | typeof CalendarSuggestionSource.IcalendarAttachment;
+    icalData: string;
+}
+/**
+ * Every `text/calendar` part of a parsed message, in declaration order.
+ *
+ * Reads mailparser's `attachments[]`, which is where every non-`text/plain`,
+ * non-`text/html` leaf lands — the same list the header classifier already
+ * looks at to route an invitation to `transactional`.
+ */
+export declare const calendarParts: (parsed: ParsedMail) => CalendarPart[];

package/dist/calendar-parts.js

@@ -0,0 +1,18 @@
+/// <reference path="./types/mailparser-augment.d.ts" />
+import { ROOT_PART_PATH } from "@remit/data-ports/id";
+import { CalendarSuggestionSource } from "@remit/domain-enums";
+const isCalendar = (attachment) => (attachment.contentType ?? "").toLowerCase().startsWith("text/calendar");
+/**
+ * Every `text/calendar` part of a parsed message, in declaration order.
+ *
+ * Reads mailparser's `attachments[]`, which is where every non-`text/plain`,
+ * non-`text/html` leaf lands — the same list the header classifier already
+ * looks at to route an invitation to `transactional`.
+ */
+export const calendarParts = (parsed) => (parsed.attachments ?? []).filter(isCalendar).map((attachment) => ({
+    partPath: attachment.partId ?? ROOT_PART_PATH,
+    source: attachment.contentDisposition === "attachment"
+        ? CalendarSuggestionSource.IcalendarAttachment
+        : CalendarSuggestionSource.IcalendarPart,
+    icalData: attachment.content.toString("utf8"),
+}));

package/dist/classification-backfill.d.ts

@@ -0,0 +1,91 @@
+import type { IAccountConfigRepository, IAccountRepository, IAddressRepository, IMessageRepository, IThreadMessageRepository } from "@remit/data-ports";
+import type { StorageService } from "@remit/storage-service";
+import { type FolderPlacementLookup } from "./folder-placement.js";
+/**
+ * Where the full-corpus pass left off: the identity of the account it was
+ * working through, and the page cursor within that account. Resuming looks the
+ * account up by id and re-opens it at its saved cursor, rather than re-scanning
+ * the whole corpus from the top after an interruption. A checkpoint naming no
+ * configured account restarts the pass.
+ */
+export interface ClassificationBackfillCheckpoint {
+    accountConfigId: string;
+    continuationToken?: string;
+}
+/**
+ * Persistence for {@link ClassificationBackfillCheckpoint}, injected so the
+ * pass stays testable with an in-memory fake; the real entrypoint backs it
+ * with a file. `clear()` runs once the whole corpus has been scanned, so a
+ * later run starts fresh rather than reading a stale finished-run checkpoint.
+ */
+export interface ClassificationBackfillCheckpointStore {
+    load(): Promise<ClassificationBackfillCheckpoint | undefined>;
+    save(checkpoint: ClassificationBackfillCheckpoint): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface ClassificationBackfillDeps {
+    accountConfigService: Pick<IAccountConfigRepository, "listAll">;
+    accountService: Pick<IAccountRepository, "listAllByAccountConfig">;
+    mailboxSpecialUseService: FolderPlacementLookup;
+    /** Reads the sender's `Address.flags.category` override (issue #299). */
+    addressService: Pick<IAddressRepository, "getAddress">;
+    threadMessageService: Pick<IThreadMessageRepository, "listByAccount" | "findAllByMessageId" | "update">;
+    messageService: Pick<IMessageRepository, "get" | "update">;
+    storageService: Pick<StorageService, "retrieve">;
+}
+export interface ClassificationBackfillLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error?(obj: Record<string, unknown>, msg: string): void;
+}
+export interface ClassificationBackfillTotals {
+    scanned: number;
+    alreadyExamined: number;
+    alreadyCategorized: number;
+    skippedNoBody: number;
+    backfilled: number;
+    failed: number;
+}
+export interface ClassificationBackfillResult extends ClassificationBackfillTotals {
+    failedThreadMessageIds: string[];
+}
+export interface ClassificationBackfillProgress extends ClassificationBackfillTotals {
+    accountConfigId: string;
+}
+export interface ClassificationBackfillOptions {
+    /** Rows fetched per `listByAccount` page. */
+    batchSize?: number;
+    checkpointStore?: ClassificationBackfillCheckpointStore;
+    logger?: ClassificationBackfillLogger;
+    /** Called once per page, after that page's rows are settled. */
+    onProgress?: (progress: ClassificationBackfillProgress) => void;
+}
+/**
+ * One-time, resumable pass that classifies the stored-body cohort the
+ * classifier has never examined (issue #1197): rows whose bodies were synced
+ * before the classifier reached them, which carry the `NotExamined` sentinel
+ * on `Message.classificationState` and so stay `uncategorized` in the list —
+ * the field is what selects the cohort, and nothing on the sync path selects
+ * it. Read-only against the stored raw source: it never opens IMAP, and it
+ * has no placement or filter side effects — the same bounds the in-sync
+ * backfill #1173 removed had. Index-time moves and filter actions are
+ * decisions that already ran (or were declined) when the body first landed;
+ * re-running them would move mail the user has since filed by hand.
+ *
+ * A row is a candidate when its Message carries `NotExamined` — the named
+ * pending state, never inferred from `category` or from `bodyStorageKey` —
+ * and has a `bodyStorageKey`; a candidate without a stored body has nothing
+ * local to read, and the ordinary sync path will classify it once the body
+ * lands. A candidate whose category is already decided is marked `Examined`
+ * without re-deriving anything: those rows were classified by a pass that
+ * predates the field, and RFC 034 Decision 3.1's write-once category must not
+ * be recomputed (#355). The classification itself is
+ * {@link classifyParsedMessage} — the same rule table, and the same sender
+ * override, the body-store path classifies with.
+ *
+ * Chunked by `listByAccount`'s existing keyset pagination, one account at a
+ * time in account-id order, so an interrupted run and its resume walk the
+ * same sequence. A failure reading, parsing, or classifying one message is
+ * contained to that message — logged, counted, and the pass continues: one
+ * unreadable object must not strand the rest of the corpus.
+ */
+export declare const backfillClassifications: (deps: ClassificationBackfillDeps, options?: ClassificationBackfillOptions) => Promise<ClassificationBackfillResult>;

package/dist/classification-backfill.js

@@ -0,0 +1,180 @@
+import { MessageClassificationState } from "@remit/domain-enums";
+import { parseMessageBody } from "./body-parse.js";
+import { extractSnippet } from "./body-sync.js";
+import { classifyParsedMessage } from "./classify-message.js";
+import { extractListId } from "./filters/list-id.js";
+import { resolveAccountFolderPlacements, } from "./folder-placement.js";
+import { denormalizeMessageCategory, hasDecidedCategory, } from "./message-category.js";
+const DEFAULT_BATCH_SIZE = 200;
+const emptyTotals = () => ({
+    scanned: 0,
+    alreadyExamined: 0,
+    alreadyCategorized: 0,
+    skippedNoBody: 0,
+    backfilled: 0,
+    failed: 0,
+});
+/**
+ * Read the stored raw source, classify it once, and record that the
+ * classifier ran. Kept as its own function (rather than inline in a try/catch)
+ * so the caller can contain a failure with `.then(fulfilled, rejected)`
+ * instead of a block catch, which keeps the `try` around the one call whose
+ * failure this contains.
+ *
+ * The ThreadMessage rows are denormalized BEFORE the Message update, for the
+ * same reason the deleted in-sync backfill did it that way (issue #320): the
+ * signal this pass selects by — `classificationState` — is written in the
+ * Message update, so a failure between the two writes leaves both undone and
+ * the rerun redoes them. Writing the Message first would strand the
+ * denormalized rows at `uncategorized` forever — the row reads as examined and
+ * the retry returns early.
+ */
+const classifyAndApply = async (deps, accountConfigId, row, bodyStorageKey, placement) => {
+    const body = await deps.storageService.retrieve(bodyStorageKey);
+    const parsed = await parseMessageBody(body);
+    const classification = await classifyParsedMessage(deps.addressService, accountConfigId, parsed, placement);
+    // The same denormalized fields the body-store path writes (see
+    // `applyPostStoreSteps`), not just the category: the snippet and `List-Id`
+    // are derived from the same bytes already in hand, and the rows this pass
+    // reaches never got them — the pass that stored the body is the pass that
+    // classifies, and it never ran for this cohort.
+    await denormalizeMessageCategory({ threadMessageService: deps.threadMessageService }, accountConfigId, row.messageId, {
+        category: classification.category,
+        snippet: extractSnippet(parsed),
+        listId: extractListId(parsed),
+    });
+    await deps.messageService.update(row.messageId, {
+        ...classification,
+        classificationState: MessageClassificationState.Examined,
+    });
+};
+/**
+ * One-time, resumable pass that classifies the stored-body cohort the
+ * classifier has never examined (issue #1197): rows whose bodies were synced
+ * before the classifier reached them, which carry the `NotExamined` sentinel
+ * on `Message.classificationState` and so stay `uncategorized` in the list —
+ * the field is what selects the cohort, and nothing on the sync path selects
+ * it. Read-only against the stored raw source: it never opens IMAP, and it
+ * has no placement or filter side effects — the same bounds the in-sync
+ * backfill #1173 removed had. Index-time moves and filter actions are
+ * decisions that already ran (or were declined) when the body first landed;
+ * re-running them would move mail the user has since filed by hand.
+ *
+ * A row is a candidate when its Message carries `NotExamined` — the named
+ * pending state, never inferred from `category` or from `bodyStorageKey` —
+ * and has a `bodyStorageKey`; a candidate without a stored body has nothing
+ * local to read, and the ordinary sync path will classify it once the body
+ * lands. A candidate whose category is already decided is marked `Examined`
+ * without re-deriving anything: those rows were classified by a pass that
+ * predates the field, and RFC 034 Decision 3.1's write-once category must not
+ * be recomputed (#355). The classification itself is
+ * {@link classifyParsedMessage} — the same rule table, and the same sender
+ * override, the body-store path classifies with.
+ *
+ * Chunked by `listByAccount`'s existing keyset pagination, one account at a
+ * time in account-id order, so an interrupted run and its resume walk the
+ * same sequence. A failure reading, parsing, or classifying one message is
+ * contained to that message — logged, counted, and the pass continues: one
+ * unreadable object must not strand the rest of the corpus.
+ */
+export const backfillClassifications = async (deps, options = {}) => {
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const { logger, checkpointStore } = options;
+    const accounts = [...(await deps.accountConfigService.listAll())].sort((left, right) => left.accountConfigId.localeCompare(right.accountConfigId));
+    const startingCheckpoint = await checkpointStore?.load();
+    const checkpointedIndex = startingCheckpoint
+        ? accounts.findIndex((account) => account.accountConfigId === startingCheckpoint.accountConfigId)
+        : -1;
+    if (startingCheckpoint && checkpointedIndex === -1) {
+        logger?.info({ accountConfigId: startingCheckpoint.accountConfigId }, "Classification backfill checkpoint names no configured account; restarting the pass");
+    }
+    const startIndex = checkpointedIndex === -1 ? 0 : checkpointedIndex;
+    const startContinuationToken = checkpointedIndex === -1
+        ? undefined
+        : startingCheckpoint?.continuationToken;
+    const totals = emptyTotals();
+    const failedThreadMessageIds = [];
+    // Messages settled this run. More than one ThreadMessage row can index one
+    // Message, and the candidate fact lives on the Message, so without this a
+    // second row would re-read the same body and re-classify it within the
+    // same page — idempotent in outcome, wasteful in storage reads.
+    const examinedMessageIds = new Set();
+    for (let accountIndex = startIndex; accountIndex < accounts.length; accountIndex++) {
+        const account = accounts[accountIndex];
+        let continuationToken = accountIndex === startIndex ? startContinuationToken : undefined;
+        const mailAccounts = await deps.accountService.listAllByAccountConfig(account.accountConfigId);
+        const placements = await resolveAccountFolderPlacements(deps.mailboxSpecialUseService, mailAccounts.map((mailAccount) => mailAccount.accountId));
+        do {
+            const page = await deps.threadMessageService.listByAccount(account.accountConfigId, { limit: batchSize, continuationToken });
+            totals.scanned += page.items.length;
+            if (page.items.length > 0) {
+                const messages = await deps.messageService.get(page.items.map((row) => row.messageId));
+                const messageByMessageId = new Map(messages.map((message) => [message.messageId, message]));
+                for (const row of page.items) {
+                    const message = messageByMessageId.get(row.messageId);
+                    if (!message?.bodyStorageKey) {
+                        totals.skippedNoBody++;
+                        continue;
+                    }
+                    if (message.classificationState !==
+                        MessageClassificationState.NotExamined ||
+                        examinedMessageIds.has(row.messageId)) {
+                        totals.alreadyExamined++;
+                        continue;
+                    }
+                    // Classified by a pass that predates the field: record that it
+                    // ran, and touch nothing else — the write-once category is not
+                    // recomputed (#355), and the derived fields that pass wrote are
+                    // already on the row.
+                    if (hasDecidedCategory(message.category)) {
+                        const outcome = await deps.messageService
+                            .update(row.messageId, {
+                            classificationState: MessageClassificationState.Examined,
+                        })
+                            .then(() => null, (error) => error);
+                        if (outcome !== null) {
+                            totals.failed++;
+                            failedThreadMessageIds.push(row.threadMessageId);
+                            logger?.error?.({
+                                threadMessageId: row.threadMessageId,
+                                messageId: row.messageId,
+                                error: outcome instanceof Error
+                                    ? outcome.message
+                                    : String(outcome),
+                            }, "Classification backfill failed to record an already-categorized message; leaving it for a later pass");
+                            continue;
+                        }
+                        examinedMessageIds.add(row.messageId);
+                        totals.alreadyCategorized++;
+                        continue;
+                    }
+                    const outcome = await classifyAndApply(deps, account.accountConfigId, row, message.bodyStorageKey, placements.get(row.mailboxId) ?? "other").then(() => null, (error) => error);
+                    if (outcome !== null) {
+                        totals.failed++;
+                        failedThreadMessageIds.push(row.threadMessageId);
+                        logger?.error?.({
+                            threadMessageId: row.threadMessageId,
+                            messageId: row.messageId,
+                            error: outcome instanceof Error ? outcome.message : String(outcome),
+                        }, "Classification backfill failed for a message; leaving it for a later pass");
+                        continue;
+                    }
+                    examinedMessageIds.add(row.messageId);
+                    totals.backfilled++;
+                }
+            }
+            continuationToken = page.continuationToken;
+            await checkpointStore?.save({
+                accountConfigId: account.accountConfigId,
+                continuationToken,
+            });
+            logger?.info({ accountConfigId: account.accountConfigId, ...totals }, "Classification backfill progress");
+            options.onProgress?.({
+                accountConfigId: account.accountConfigId,
+                ...totals,
+            });
+        } while (continuationToken);
+    }
+    await checkpointStore?.clear();
+    return { ...totals, failedThreadMessageIds };
+};

package/dist/classify-message.d.ts

@@ -0,0 +1,31 @@
+import type { IAddressRepository, ThreadMessageItem, UpdateMessageInput } from "@remit/data-ports";
+import type { ParsedMail } from "mailparser";
+import type { FolderPlacement } from "./heuristics/classifyPlacement.js";
+type ThreadMessageCategory = ThreadMessageItem["category"];
+/**
+ * The From address the classifier reads, when there is one to read. Shared by
+ * every path that classifies or counts a sender (body-sync's classification,
+ * inbound counter and placement signals, and the classification backfill) so
+ * they all read the same address off the same bytes.
+ */
+export declare const extractPrimaryFromEmail: (parsed: ParsedMail) => string | null;
+/**
+ * Header classification, with the sender's `Address.flags.category` override
+ * (issue #299, RFC 039 Decision 3) substituted for the header-derived
+ * category when one is set. Returns the subset of the Message update that
+ * carries the derived fields; the caller folds it into a single UpdateItem
+ * alongside `bodyStorageKey` (body-sync) or `classificationState` (the
+ * classification backfill, issue #1197). Optional signals are omitted when
+ * absent so we never overwrite an existing value with `undefined`.
+ *
+ * The override wins outright rather than blending with the heuristic — RFC
+ * 039 Decision 3 treats a direct reclassification as final, the same as
+ * `flags.blocked`/`vip` already override placement. Every caller gates on
+ * `hasDecidedCategory` before this result reaches a write, so a message that
+ * already carries a real category is never re-touched regardless of what
+ * this returns.
+ */
+export declare const classifyParsedMessage: (addressService: Pick<IAddressRepository, "getAddress">, accountConfigId: string, parsed: ParsedMail, placement: FolderPlacement) => Promise<UpdateMessageInput & {
+    category: ThreadMessageCategory;
+}>;
+export {};

package/dist/classify-message.js

@@ -0,0 +1,89 @@
+import { NotFoundError } from "@remit/data-ports/errors";
+import { deriveAddressId } from "@remit/data-ports/id";
+import { classifyByHeaders, extractAuthenticity, extractAuthResult, extractHasListUnsubscribe, extractProviderSpam, } from "./heuristics/classifyByHeaders.js";
+import { extractSenderMismatch } from "./heuristics/senderMismatch.js";
+/**
+ * The From address the classifier reads, when there is one to read. Shared by
+ * every path that classifies or counts a sender (body-sync's classification,
+ * inbound counter and placement signals, and the classification backfill) so
+ * they all read the same address off the same bytes.
+ */
+export const extractPrimaryFromEmail = (parsed) => {
+    const from = parsed.from;
+    if (!from || !from.value || from.value.length === 0)
+        return null;
+    const address = from.value[0]?.address;
+    if (!address)
+        return null;
+    return address.toLowerCase();
+};
+/**
+ * The one-sided half of `Address.flags.category` (issue #299, RFC 039
+ * Decision 3): a real value here overrides `classifyByHeaders` outright.
+ * Only a genuinely-absent Address is "no override" — any other failure
+ * (throttle, infra) propagates, because this feeds the write-once
+ * `Message.category` at the moment it is decided, where a masked infra
+ * failure would silently classify by headers when the user asked for
+ * something else.
+ */
+const resolveCategoryOverride = async (addressService, accountConfigId, fromEmail) => {
+    try {
+        const addressId = deriveAddressId(accountConfigId, fromEmail);
+        const address = await addressService.getAddress(accountConfigId, addressId);
+        return address.flags?.category?.value;
+    }
+    catch (err) {
+        if (!(err instanceof NotFoundError))
+            throw err;
+        return undefined;
+    }
+};
+/**
+ * Header classification, with the sender's `Address.flags.category` override
+ * (issue #299, RFC 039 Decision 3) substituted for the header-derived
+ * category when one is set. Returns the subset of the Message update that
+ * carries the derived fields; the caller folds it into a single UpdateItem
+ * alongside `bodyStorageKey` (body-sync) or `classificationState` (the
+ * classification backfill, issue #1197). Optional signals are omitted when
+ * absent so we never overwrite an existing value with `undefined`.
+ *
+ * The override wins outright rather than blending with the heuristic — RFC
+ * 039 Decision 3 treats a direct reclassification as final, the same as
+ * `flags.blocked`/`vip` already override placement. Every caller gates on
+ * `hasDecidedCategory` before this result reaches a write, so a message that
+ * already carries a real category is never re-touched regardless of what
+ * this returns.
+ */
+export const classifyParsedMessage = async (addressService, accountConfigId, parsed, placement) => {
+    const headerCategory = classifyByHeaders(parsed);
+    const authenticity = extractAuthenticity(parsed);
+    const authResult = extractAuthResult(parsed);
+    const providerSpam = extractProviderSpam(parsed);
+    const hasListUnsubscribe = extractHasListUnsubscribe(parsed);
+    // A passing SPF/DKIM/DMARC check proves the sending domain, not the
+    // identity the message claims — on a shared-tenant host the verified
+    // subdomain belongs to whoever signed up. These two comparisons say
+    // whether the claim holds, and run only over mail the provider already
+    // called spam or that sits in the Junk folder.
+    const senderMismatch = authenticity === null
+        ? {}
+        : extractSenderMismatch(parsed, {
+            fromDomain: authenticity.fromDomain,
+            providerSpamClassified: providerSpam?.classified === true,
+            placement,
+            bulkSender: hasListUnsubscribe,
+        });
+    const fromEmail = extractPrimaryFromEmail(parsed);
+    const categoryOverride = fromEmail
+        ? await resolveCategoryOverride(addressService, accountConfigId, fromEmail)
+        : undefined;
+    return {
+        category: categoryOverride ?? headerCategory,
+        hasListUnsubscribe,
+        ...(authenticity !== null
+            ? { authenticity: { ...authenticity, ...senderMismatch } }
+            : {}),
+        ...(authResult !== null ? { authResult } : {}),
+        ...(providerSpam !== null ? { providerSpam } : {}),
+    };
+};

package/dist/connection-factory.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Connection factory for IMAP implementations
+ *
+ * Uses ImapFlow for all IMAP connections.
+ */
+import type { IImapConnection, ImapConnectionConfig, MailCredentials } from "./types.js";
+/**
+ * Create an IMAP connection
+ */
+export declare const createConnection: (config: ImapConnectionConfig) => IImapConnection;
+/**
+ * Create an IMAP connection from account data using password credentials.
+ */
+export declare const createConnectionFromAccount: (account: {
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    username: string;
+}, password: string) => IImapConnection;
+/**
+ * Create an IMAP connection from account data using a MailCredentials union.
+ * Use this instead of createConnectionFromAccount for OAuth accounts.
+ */
+export declare const createConnectionWithCredentials: (account: {
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    username: string;
+}, credentials: MailCredentials) => IImapConnection;
+/**
+ * Managed connection factory that caches and reuses a single connection.
+ *
+ * The factory handles connection lifecycle - callers should not disconnect.
+ * Call close() on the factory to disconnect when done.
+ */
+export interface ManagedConnectionFactory {
+    /** Get the cached connection (creates on first call) */
+    getConnection(): IImapConnection;
+    /** Disconnect and cleanup */
+    close(): Promise<void>;
+}
+/**
+ * Create a managed connection factory that caches a single connection.
+ *
+ * @example
+ * ```typescript
+ * const factory = createManagedConnectionFactory(config);
+ * const conn = factory.getConnection();
+ * await conn.connect();
+ * // ... reuse conn via factory.getConnection() ...
+ * await factory.close(); // Disconnect when done
+ * ```
+ */
+export declare const createManagedConnectionFactory: (config: ImapConnectionConfig) => ManagedConnectionFactory;

package/dist/connection-factory.js

@@ -0,0 +1,54 @@
+/**
+ * Connection factory for IMAP implementations
+ *
+ * Uses ImapFlow for all IMAP connections.
+ */
+import { createImapFlowConnectionFromAccount, createImapFlowConnectionWithCredentials, ImapFlowConnection, } from "./imapflow-connection.js";
+/**
+ * Create an IMAP connection
+ */
+export const createConnection = (config) => {
+    return new ImapFlowConnection(config);
+};
+/**
+ * Create an IMAP connection from account data using password credentials.
+ */
+export const createConnectionFromAccount = (account, password) => {
+    return createImapFlowConnectionFromAccount(account, password);
+};
+/**
+ * Create an IMAP connection from account data using a MailCredentials union.
+ * Use this instead of createConnectionFromAccount for OAuth accounts.
+ */
+export const createConnectionWithCredentials = (account, credentials) => {
+    return createImapFlowConnectionWithCredentials(account, credentials);
+};
+/**
+ * Create a managed connection factory that caches a single connection.
+ *
+ * @example
+ * ```typescript
+ * const factory = createManagedConnectionFactory(config);
+ * const conn = factory.getConnection();
+ * await conn.connect();
+ * // ... reuse conn via factory.getConnection() ...
+ * await factory.close(); // Disconnect when done
+ * ```
+ */
+export const createManagedConnectionFactory = (config) => {
+    let connection = null;
+    return {
+        getConnection: () => {
+            if (!connection) {
+                connection = new ImapFlowConnection(config);
+            }
+            return connection;
+        },
+        close: async () => {
+            if (connection) {
+                await connection.disconnect();
+                connection = null;
+            }
+        },
+    };
+};

package/dist/connection-test.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Connection testing utilities for IMAP and SMTP servers
+ *
+ * Used to validate credentials before saving account configuration.
+ */
+import type { MailCredentials } from "./types.js";
+export interface TestResult {
+    success: boolean;
+    error?: string;
+}
+export interface ImapTestConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    startTls?: boolean;
+    credentials: MailCredentials;
+    user: string;
+}
+export interface SmtpTestConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    credentials: MailCredentials;
+    user: string;
+}
+/**
+ * Test IMAP connection with provided credentials.
+ *
+ * Uses a raw socket to send AUTH PLAIN directly — bypasses the CAPABILITY
+ * round-trip that IMAP clients typically perform first, avoiding deadlocks
+ * with servers that pipeline their tagged responses.
+ *
+ * Supports plaintext, direct TLS (secure: true), and STARTTLS (startTls: true).
+ */
+export declare const testImapConnection: (config: ImapTestConfig) => Promise<TestResult>;
+/**
+ * Test SMTP connection with provided credentials
+ *
+ * Uses nodemailer's verify() method to test authentication.
+ */
+export declare const testSmtpConnection: (config: SmtpTestConfig) => Promise<TestResult>;