@civitas-cerebrum/email-client 0.0.7 → 0.0.9

package/README.md

@@ -183,12 +183,46 @@ const allEmails = await client.receiveAll({
 |---|---|---|---|
 | `filters` | `EmailFilter[]` | — | **Required.** Array of filters (AND logic) |
 | `folder` | `string` | `'INBOX'` | IMAP folder to search. Accepts a literal path or a `specialUse` role (e.g. `'\\Sent'`, `'\\Trash'`) |
+| `folders` | `string[]` | — | Several folders to search at once. Takes precedence over `folder`. See [Searching multiple folders](#searching-multiple-folders) |
 | `waitTimeout` | `number` | `30000` | Max milliseconds to poll before throwing an error |
 | `pollInterval` | `number` | `3000` | Milliseconds to wait between IMAP fetch attempts |
 | `expectedCount` | `number` | `1` | Number of matching emails required before returning |
 | `downloadDir` | `string` | `os.tmpdir()` | Directory to save downloaded `.html` copies |
 | `maxFetchLimit` | `number` | `50` | Max emails to fetch per polling cycle (memory protection) |
 
+#### Searching multiple folders
+
+A message does not always arrive where you expect it. Mail from a new or
+low-reputation sending domain is routinely filed as spam by the receiving
+server, and a spam-filed message is never found by an inbox-only search — no
+matter how long you wait for it.
+
+Pass `folders` to search several mailboxes in one call. Every folder is searched
+on every polling cycle and the matches are pooled, so the wait ends as soon as
+the message shows up anywhere in the set:
+
+```ts
+const email = await client.receive({
+    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your verification code' }],
+    folders: ['INBOX', '[Gmail]/Spam'],   // or ['INBOX', '\\Junk'] to stay portable
+    waitTimeout: 60000,
+});
+```
+
+`folders` is accepted by `receive`, `receiveAll`, `clean` and `mark`, and takes
+precedence over `folder` when both are given. For `clean` and `mark` the action
+is applied in each folder in turn and the returned count is the total.
+
+**Missing folders.** A single folder is strict — naming one that does not exist
+throws, listing the folders the server does have. A folder *list* is tolerant:
+an absent folder is skipped so a portable set works against servers that lack
+one of them. If none of the listed folders can be opened, the call still throws.
+
+> **Do not reach for `\All` as a shortcut.** All Mail also contains sent,
+> archived and recently-deleted copies, so a search across it will keep finding
+> a message you have already moved or deleted. Name the folders you actually
+> mean.
+
 #### Available Filters (`EmailFilterType`)
 
 | Type | Value Type | Description |
@@ -240,10 +274,24 @@ await client.clean({
     filters: [{ type: EmailFilterType.FROM, value: 'noreply@example.com' }],
 });
 
-// Nuke the entire inbox (Use with caution!)
-await client.clean();
+// Delete across several folders in one call
+await client.clean({
+    filters: [{ type: EmailFilterType.SUBJECT, value: 'my-test-run-42' }],
+    folders: ['INBOX', '[Gmail]/Spam'],
+});
+
+// Nuke an entire folder (Use with caution!)
+await client.clean();                       // every message in INBOX
+await client.clean({ folder: 'scratch' });  // every message in "scratch"
 ```
 
+> **Sharing a mailbox?** `clean()` with no filters deletes everything in the
+> target folder, including messages another process put there. If more than one
+> test run can touch the same mailbox, stamp a unique per-run token into every
+> subject you send and always pass a filter selecting it — then a cleanup can
+> only ever remove its own mail. Reserve the unfiltered form for a folder your
+> run created and owns.
+
 #### Folder Resolution
 
 Any `folder` or `archiveFolder` option accepts either a **literal path** (e.g. `'[Gmail]/Trash'`) or a **`specialUse` role** prefixed with `\`. The client resolves roles to the correct server path at runtime using IMAP LIST metadata, so your code works regardless of the mail server's language or naming conventions.

package/dist/EmailClient.d.ts

@@ -1,4 +1,4 @@
-import { EmailSendOptions, EmailReceiveOptions, EmailCredentials, ReceivedEmail, EmailFilter, EmailMarkOptions, EmailClientConfig } from './types.js';
+import { EmailSendOptions, EmailReceiveOptions, EmailCredentials, ReceivedEmail, EmailFilter, EmailMarkOptions, EmailClientConfig, EmailCleanOptions } from './types.js';
 /**
  * A comprehensive client for handling SMTP sending and IMAP polling/management.
  * Provides unified APIs for interacting with mail servers using robust polling mechanisms.
@@ -40,14 +40,11 @@ export declare class EmailClient {
     receiveAll(options: EmailReceiveOptions): Promise<ReceivedEmail[]>;
     /**
      * Deletes emails from the mailbox based on the provided filters.
-     * If no filters are provided, it deletes ALL emails in the specified folder.
-     * @param options Filtering criteria and the target folder.
+     * If no filters are provided, it deletes ALL emails in the specified folder(s).
+     * @param options Filtering criteria and the target folder(s).
      * @returns The number of emails successfully deleted.
      */
-    clean(options?: {
-        filters?: EmailFilter[];
-        folder?: string;
-    }): Promise<number>;
+    clean(options?: EmailCleanOptions): Promise<number>;
     /**
      * Modifies the state or flags of emails in the mailbox (e.g., Read, Unread, Flagged, Archived).
      * @param options Action details, filtering criteria, and target folder configuration.
@@ -84,6 +81,22 @@ export declare class EmailClient {
      * Safely wraps IMAP connection, UID searching, custom action execution, and logout.
      */
     private _executeImapAction;
+    /**
+     * Resolves a requested folder list to the subset that actually exists on the server.
+     *
+     * A single requested folder is strict — a missing folder throws the diagnostic
+     * "Failed to open folder" error, which is what a caller naming one folder wants.
+     * A multi-folder request is tolerant: an absent folder is skipped with a log line
+     * so a portable set (e.g. `['INBOX', '\\Junk']`) works on servers that lack one of
+     * them. If nothing in the list can be opened, that is still an error.
+     */
+    private _openableFolders;
+    /**
+     * Collapses the `folder` / `folders` option pair into the folder list to operate on.
+     * `folders` wins when both are supplied; the default remains a lone 'INBOX', so
+     * every existing single-folder caller keeps its exact behaviour.
+     */
+    private normalizeFolders;
     /**
      * Helper to scrape mailbox paths for better error reporting
      */

package/dist/EmailClient.js

@@ -118,13 +118,13 @@ export class EmailClient {
     // ════════════════════════════════════════════════════════════════════════
     /**
      * Deletes emails from the mailbox based on the provided filters.
-     * If no filters are provided, it deletes ALL emails in the specified folder.
-     * @param options Filtering criteria and the target folder.
+     * If no filters are provided, it deletes ALL emails in the specified folder(s).
+     * @param options Filtering criteria and the target folder(s).
      * @returns The number of emails successfully deleted.
      */
     async clean(options) {
-        const folder = options?.folder ?? 'INBOX';
-        return this._executeImapAction(folder, options?.filters, 'delete', async (client, uids) => {
+        const folders = this.normalizeFolders(options?.folder, options?.folders);
+        return this._executeImapAction(folders, options?.filters, 'delete', async (client, uids, folder) => {
             await client.messageDelete(uids, { uid: true });
             log('Deleted %d email(s) from "%s"', uids.length, folder);
         });
@@ -135,12 +135,13 @@ export class EmailClient {
      * @returns The number of emails successfully modified.
      */
     async mark(options) {
-        const { action, filters, folder = 'INBOX', archiveFolder = 'Archive' } = options;
+        const { action, filters, folder, folders: folderList, archiveFolder = 'Archive' } = options;
         const isValidAction = Array.isArray(action) || Object.values(EmailMarkAction).includes(action);
         if (!isValidAction) {
             throw new Error(`Unsupported mark action: ${action}`);
         }
-        return this._executeImapAction(folder, filters, 'mark', async (client, uids) => {
+        const folders = this.normalizeFolders(folder, folderList);
+        return this._executeImapAction(folders, filters, 'mark', async (client, uids, folder) => {
             if (uids.length === 0)
                 return;
             // Handle Custom Flags
@@ -225,21 +226,27 @@ export class EmailClient {
      * Manages IMAP connection, continuous retry logic, timeout enforcement, and cleanup.
      */
     async _pollMailbox(options, returnAll) {
-        const { filters, folder = 'INBOX', waitTimeout = 30000, pollInterval = 3000, downloadDir, expectedCount = 1, maxFetchLimit = 50 } = options;
+        const { filters, folder, folders: folderList, waitTimeout = 30000, pollInterval = 3000, downloadDir, expectedCount = 1, maxFetchLimit = 50 } = options;
         this.validateFilters(filters);
+        const requestedFolders = this.normalizeFolders(folder, folderList);
         const deadline = Date.now() + waitTimeout;
         const client = this.createImapClient();
+        // UIDs are scoped to a mailbox, not to the account, so the same UID can name
+        // a different message in each searched folder. Key the seen-set by folder.
         const seenUids = new Set();
         const accumulatedMatches = []; // Track across polling cycles
         try {
             await client.connect();
             this.logImapConnection();
-            const resolvedFolder = await this._resolveFolder(client, folder);
+            const openableFolders = await this._openableFolders(client, requestedFolders);
+            const searchedIn = openableFolders.join(', ');
             while (Date.now() < deadline) {
-                await client.mailboxOpen(resolvedFolder);
-                const candidates = await this.fetchNewCandidates(client, filters, seenUids, downloadDir, maxFetchLimit);
-                const newMatches = this.applyFilters(candidates, filters);
-                accumulatedMatches.push(...newMatches);
+                for (const resolvedFolder of openableFolders) {
+                    await client.mailboxOpen(resolvedFolder);
+                    const candidates = await this.fetchNewCandidates(client, resolvedFolder, filters, seenUids, downloadDir, maxFetchLimit);
+                    const newMatches = this.applyFilters(candidates, filters);
+                    accumulatedMatches.push(...newMatches);
+                }
                 if (accumulatedMatches.length >= expectedCount) {
                     if (returnAll) {
                         return accumulatedMatches;
@@ -256,7 +263,7 @@ export class EmailClient {
                 }
                 await new Promise(resolve => setTimeout(resolve, pollInterval));
             }
-            throw new Error(`Found ${accumulatedMatches.length}/${expectedCount} emails within ${waitTimeout}ms. Searched in "${resolvedFolder}" for: ${this.formatFilterSummary(filters)}`);
+            throw new Error(`Found ${accumulatedMatches.length}/${expectedCount} emails within ${waitTimeout}ms. Searched in "${searchedIn}" for: ${this.formatFilterSummary(filters)}`);
         }
         finally {
             try {
@@ -271,44 +278,37 @@ export class EmailClient {
      * Core execution engine used by `clean()` and `mark()`.
      * Safely wraps IMAP connection, UID searching, custom action execution, and logout.
      */
-    async _executeImapAction(folder, filters, actionName, actionFn) {
+    async _executeImapAction(folders, filters, actionName, actionFn) {
         const client = this.createImapClient();
         try {
             await client.connect();
             this.logImapConnection();
-            const resolvedFolder = await this._resolveFolder(client, folder);
-            try {
+            const openableFolders = await this._openableFolders(client, folders);
+            let affected = 0;
+            for (const resolvedFolder of openableFolders) {
                 await client.mailboxOpen(resolvedFolder);
-            }
-            catch (err) {
-                if (err.serverResponseCode === 'NONEXISTENT' || err.message.includes('Unknown Mailbox')) {
-                    const available = await this._listAvailableFolders(client);
-                    throw new Error(`Failed to open folder "${resolvedFolder}".\n` +
-                        `Available folders on this server: [${available.join(', ')}]\n` +
-                        `Check your ARCHIVE_FOLDER or folder settings.`);
+                const searchCriteria = filters && filters.length > 0
+                    ? this.buildSearchCriteria(filters)
+                    : { all: true };
+                const uids = await client.search(searchCriteria, { uid: true });
+                if (!uids || uids.length === 0) {
+                    log('No emails to %s in "%s"', actionName, resolvedFolder);
+                    continue;
                 }
-                throw err;
-            }
-            const searchCriteria = filters && filters.length > 0
-                ? this.buildSearchCriteria(filters)
-                : { all: true };
-            const uids = await client.search(searchCriteria, { uid: true });
-            if (!uids || uids.length === 0) {
-                log('No emails to %s in "%s"', actionName, folder);
-                return 0;
-            }
-            try {
-                await actionFn(client, uids);
-            }
-            catch (err) {
-                if (err.message.includes('NONEXISTENT') || err.message.includes('Unknown Mailbox')) {
-                    const available = await this._listAvailableFolders(client);
-                    throw new Error(`Action "${actionName}" failed. A target folder (${folder}) does not exist.\n` +
-                        `Available folders: [${available.join(', ')}]`);
+                try {
+                    await actionFn(client, uids, resolvedFolder);
                 }
-                throw err;
+                catch (err) {
+                    if (err.message.includes('NONEXISTENT') || err.message.includes('Unknown Mailbox')) {
+                        const available = await this._listAvailableFolders(client);
+                        throw new Error(`Action "${actionName}" failed. A target folder (${resolvedFolder}) does not exist.\n` +
+                            `Available folders: [${available.join(', ')}]`);
+                    }
+                    throw err;
+                }
+                affected += uids.length;
             }
-            return uids.length;
+            return affected;
         }
         finally {
             try {
@@ -319,6 +319,64 @@ export class EmailClient {
             }
         }
     }
+    /**
+     * Resolves a requested folder list to the subset that actually exists on the server.
+     *
+     * A single requested folder is strict — a missing folder throws the diagnostic
+     * "Failed to open folder" error, which is what a caller naming one folder wants.
+     * A multi-folder request is tolerant: an absent folder is skipped with a log line
+     * so a portable set (e.g. `['INBOX', '\\Junk']`) works on servers that lack one of
+     * them. If nothing in the list can be opened, that is still an error.
+     */
+    async _openableFolders(client, folders) {
+        const strict = folders.length === 1;
+        const openable = [];
+        for (const folder of folders) {
+            let resolved;
+            try {
+                resolved = await this._resolveFolder(client, folder);
+            }
+            catch (err) {
+                if (strict)
+                    throw err;
+                log('Skipping folder "%s" — it could not be resolved on this server: %o', folder, err);
+                continue;
+            }
+            try {
+                await client.mailboxOpen(resolved);
+                openable.push(resolved);
+            }
+            catch (err) {
+                const missing = err.serverResponseCode === 'NONEXISTENT' || String(err.message).includes('Unknown Mailbox');
+                if (!missing)
+                    throw err;
+                if (strict) {
+                    const available = await this._listAvailableFolders(client);
+                    throw new Error(`Failed to open folder "${resolved}".\n` +
+                        `Available folders on this server: [${available.join(', ')}]\n` +
+                        `Check your ARCHIVE_FOLDER or folder settings.`);
+                }
+                log('Skipping folder "%s" — it does not exist on this server', resolved);
+            }
+        }
+        if (openable.length === 0) {
+            const available = await this._listAvailableFolders(client);
+            throw new Error(`Failed to open folder "${folders.join(', ')}".\n` +
+                `Available folders on this server: [${available.join(', ')}]\n` +
+                `Check your ARCHIVE_FOLDER or folder settings.`);
+        }
+        return openable;
+    }
+    /**
+     * Collapses the `folder` / `folders` option pair into the folder list to operate on.
+     * `folders` wins when both are supplied; the default remains a lone 'INBOX', so
+     * every existing single-folder caller keeps its exact behaviour.
+     */
+    normalizeFolders(folder, folders) {
+        if (folders && folders.length > 0)
+            return [...folders];
+        return [folder ?? 'INBOX'];
+    }
     /**
      * Helper to scrape mailbox paths for better error reporting
      */
@@ -423,12 +481,13 @@ export class EmailClient {
         return criteria;
     }
     /** Fetches unread/unseen messages from IMAP that match the search criteria. */
-    async fetchNewCandidates(client, filters, seenUids, downloadDir, maxFetchLimit = 50) {
+    async fetchNewCandidates(client, folder, filters, seenUids, downloadDir, maxFetchLimit = 50) {
+        const key = (uid) => `${folder}:${uid}`;
         const searchCriteria = this.buildSearchCriteria(filters);
         const uids = await client.search(searchCriteria, { uid: true });
         if (!uids || uids.length === 0)
             return [];
-        const newUids = uids.filter(uid => !seenUids.has(uid));
+        const newUids = uids.filter(uid => !seenUids.has(key(uid)));
         if (newUids.length === 0)
             return [];
         // Safety measure: Prevent memory spikes by capping the raw MIME fetch.
@@ -436,11 +495,11 @@ export class EmailClient {
         if (newUids.length > maxFetchLimit) {
             log('Warning: Found %d matching emails. Capping fetch limit to the %d most recent to conserve memory.', newUids.length, maxFetchLimit);
             // Add the omitted UIDs to 'seen' so we don't fetch them in the next polling cycle
-            newUids.slice(0, -maxFetchLimit).forEach(uid => seenUids.add(uid));
+            newUids.slice(0, -maxFetchLimit).forEach(uid => seenUids.add(key(uid)));
         }
         const candidates = [];
         for await (const msg of client.fetch(limitedUids, { source: true }, { uid: true })) {
-            seenUids.add(msg.uid);
+            seenUids.add(key(msg.uid));
             candidates.push(await this.parseMessage(msg, downloadDir));
         }
         return candidates;

package/dist/types.d.ts

@@ -104,6 +104,18 @@ export interface EmailReceiveOptions {
     filters: EmailFilter[];
     /** IMAP folder to search. Accepts a literal path or a specialUse role (e.g. '\\Sent', '\\Trash'). Defaults to 'INBOX'. */
     folder?: string;
+    /**
+     * Multiple IMAP folders to search in one call, each accepting a literal path or a
+     * specialUse role. Every folder is searched on every polling cycle and the matches
+     * are pooled, so a message the receiving server filed somewhere other than the
+     * inbox (spam, for instance) is still found. Takes precedence over `folder`.
+     *
+     * A folder in this list that does not exist on the server is skipped with a log
+     * line rather than throwing, so a portable folder set (e.g. `['INBOX', '\\Junk']`)
+     * works against servers that lack one of them. If NONE of the listed folders can be
+     * opened, the call throws. A single-folder search still throws on a missing folder.
+     */
+    folders?: string[];
     /** How long to poll for a matching email (ms). Defaults to 30000. */
     waitTimeout?: number;
     /** Interval between poll attempts (ms). Defaults to 3000. */
@@ -132,6 +144,22 @@ export interface ReceivedEmail {
     /** Plain-text content. */
     text: string;
 }
+/**
+ * Options for deleting emails from the mailbox.
+ */
+export interface EmailCleanOptions {
+    /** Filters identifying which emails to delete. If omitted, EVERY email in the target folder(s) is deleted. */
+    filters?: EmailFilter[];
+    /** The target mailbox folder. Accepts a literal path or a specialUse role. Defaults to 'INBOX'. */
+    folder?: string;
+    /**
+     * Multiple target folders, each accepting a literal path or a specialUse role.
+     * The delete is applied to each folder in turn and the returned count is the total.
+     * Takes precedence over `folder`. Missing folders are skipped (see
+     * {@link EmailReceiveOptions.folders}).
+     */
+    folders?: string[];
+}
 /**
  * Predefined actions for modifying email flags or state.
  */
@@ -152,6 +180,13 @@ export interface EmailMarkOptions {
     filters?: EmailFilter[];
     /** The target mailbox folder. Accepts a literal path or a specialUse role (e.g. '\\Trash', '\\Sent'). Defaults to 'INBOX'. */
     folder?: string;
+    /**
+     * Multiple source folders to mark across, each accepting a literal path or a
+     * specialUse role. The action is applied in each folder in turn and the returned
+     * count is the total. Takes precedence over `folder`. Missing folders are skipped
+     * (see {@link EmailReceiveOptions.folders}).
+     */
+    folders?: string[];
     /** The destination folder for the `ARCHIVED` action. Accepts a literal path or a specialUse role (e.g. '\\Flagged', '\\All'). Defaults to 'Archive'. */
     archiveFolder?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitas-cerebrum/email-client",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A generic SMTP/IMAP email client for test automation. Send, receive, search, and clean emails with composable filters.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,7 @@
   "scripts": {
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc",
-    "test": "vitest run tests/mime-parsing.spec.ts tests/unit-tests.spec.ts",
+    "test": "vitest run tests/mime-parsing.spec.ts tests/unit-tests.spec.ts tests/run-isolation.spec.ts",
     "test:e2e": "vitest run tests/email-integration.spec.ts",
     "test:all": "vitest run tests",
     "test:coverage": "npx test-coverage --format github-table",
@@ -26,9 +26,13 @@
   ],
   "dependencies": {
     "debug": "^4.4.3",
-    "imapflow": "^1.3.1",
-    "mailparser": "^3.9.8",
-    "nodemailer": "^8.0.5"
+    "imapflow": "^1.3.4",
+    "mailparser": "^3.9.13",
+    "nodemailer": "^9.0.1"
+  },
+  "overrides": {
+    "nodemailer": "^9.0.1",
+    "ip-address": ">=10.3.1"
   },
   "devDependencies": {
     "@civitas-cerebrum/test-coverage": "^0.0.8",