@civitas-cerebrum/email-client 0.0.5 → 0.0.7

package/README.md

@@ -182,7 +182,7 @@ const allEmails = await client.receiveAll({
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `filters` | `EmailFilter[]` | — | **Required.** Array of filters (AND logic) |
-| `folder` | `string` | `'INBOX'` | IMAP folder to search |
+| `folder` | `string` | `'INBOX'` | IMAP folder to search. Accepts a literal path or a `specialUse` role (e.g. `'\\Sent'`, `'\\Trash'`) |
 | `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 |
@@ -216,11 +216,11 @@ await client.mark({
     filters: [{ type: EmailFilterType.SUBJECT, value: 'Welcome' }]
 });
 
-// Move emails to an archive folder
+// Move emails to an archive folder (using specialUse role — works across all locales)
 await client.mark({
     action: EmailMarkAction.ARCHIVED,
     filters: [{ type: EmailFilterType.FROM, value: 'spam@example.com' }],
-    archiveFolder: 'Archive' // Note: This must match the server's localized folder name
+    archiveFolder: '\\Trash' // Resolves to the server's actual Trash path at runtime
 });
 
 // Apply custom IMAP flags
@@ -244,6 +244,26 @@ await client.clean({
 await client.clean();
 ```
 
+#### 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.
+
+| Role | Description |
+|---|---|
+| `\All` | All Mail |
+| `\Trash` | Trash / Deleted Items |
+| `\Sent` | Sent Mail |
+| `\Drafts` | Drafts |
+| `\Junk` | Spam |
+| `\Flagged` | Starred / Flagged |
+| `\Inbox` | Inbox |
+
+```ts
+// These are equivalent on a Turkish Gmail account:
+await client.clean({ folder: '[Gmail]/Çöp kutusu' }); // literal path
+await client.clean({ folder: '\\Trash' });             // specialUse role (locale-independent)
+```
+
 -----
 
 ### The `ReceivedEmail` Object

package/dist/EmailClient.d.ts

@@ -88,6 +88,13 @@ export declare class EmailClient {
      * Helper to scrape mailbox paths for better error reporting
      */
     private _listAvailableFolders;
+    /**
+     * Resolves a folder name to its actual IMAP path using `specialUse` metadata.
+     * Accepts either a literal path (e.g. '[Gmail]/Trash') or a specialUse role
+     * (e.g. '\\Trash', '\\All', '\\Sent', '\\Flagged', '\\Drafts', '\\Junk').
+     * Returns the original value if no specialUse match is found.
+     */
+    private _resolveFolder;
     /** Instantiates an ImapFlow client using the provided credentials. */
     private createImapClient;
     /** Logs standard IMAP connection details. */

package/dist/EmailClient.js

@@ -168,8 +168,12 @@ export class EmailClient {
                     log('Action UNFLAGGED applied to %d email(s) in "%s"', uids.length, folder);
                     break;
                 case EmailMarkAction.ARCHIVED:
-                    await client.messageMove(uids, archiveFolder, { uid: true });
-                    log('Archived %d email(s) from "%s" to "%s"', uids.length, folder, archiveFolder);
+                    const resolvedArchive = await this._resolveFolder(client, archiveFolder);
+                    const moveResult = await client.messageMove(uids, resolvedArchive, { uid: true });
+                    if (!moveResult) {
+                        throw new Error(`Failed to move ${uids.length} email(s) to "${resolvedArchive}". The server rejected the move.`);
+                    }
+                    log('Archived %d email(s) from "%s" to "%s"', uids.length, folder, resolvedArchive);
                     break;
             }
         });
@@ -230,8 +234,9 @@ export class EmailClient {
         try {
             await client.connect();
             this.logImapConnection();
+            const resolvedFolder = await this._resolveFolder(client, folder);
             while (Date.now() < deadline) {
-                await client.mailboxOpen(folder);
+                await client.mailboxOpen(resolvedFolder);
                 const candidates = await this.fetchNewCandidates(client, filters, seenUids, downloadDir, maxFetchLimit);
                 const newMatches = this.applyFilters(candidates, filters);
                 accumulatedMatches.push(...newMatches);
@@ -251,7 +256,7 @@ export class EmailClient {
                 }
                 await new Promise(resolve => setTimeout(resolve, pollInterval));
             }
-            throw new Error(`Found ${accumulatedMatches.length}/${expectedCount} emails within ${waitTimeout}ms. Searched in "${folder}" for: ${this.formatFilterSummary(filters)}`);
+            throw new Error(`Found ${accumulatedMatches.length}/${expectedCount} emails within ${waitTimeout}ms. Searched in "${resolvedFolder}" for: ${this.formatFilterSummary(filters)}`);
         }
         finally {
             try {
@@ -271,13 +276,14 @@ export class EmailClient {
         try {
             await client.connect();
             this.logImapConnection();
+            const resolvedFolder = await this._resolveFolder(client, folder);
             try {
-                await client.mailboxOpen(folder);
+                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 "${folder}".\n` +
+                    throw new Error(`Failed to open folder "${resolvedFolder}".\n` +
                         `Available folders on this server: [${available.join(', ')}]\n` +
                         `Check your ARCHIVE_FOLDER or folder settings.`);
                 }
@@ -286,7 +292,7 @@ export class EmailClient {
             const searchCriteria = filters && filters.length > 0
                 ? this.buildSearchCriteria(filters)
                 : { all: true };
-            const uids = await client.search(searchCriteria);
+            const uids = await client.search(searchCriteria, { uid: true });
             if (!uids || uids.length === 0) {
                 log('No emails to %s in "%s"', actionName, folder);
                 return 0;
@@ -329,6 +335,25 @@ export class EmailClient {
         }
         return folders;
     }
+    /**
+     * Resolves a folder name to its actual IMAP path using `specialUse` metadata.
+     * Accepts either a literal path (e.g. '[Gmail]/Trash') or a specialUse role
+     * (e.g. '\\Trash', '\\All', '\\Sent', '\\Flagged', '\\Drafts', '\\Junk').
+     * Returns the original value if no specialUse match is found.
+     */
+    async _resolveFolder(client, folder) {
+        if (!folder.startsWith('\\'))
+            return folder;
+        const list = await client.list();
+        for (const entry of list) {
+            if (entry.specialUse === folder) {
+                log('Resolved specialUse "%s" to folder "%s"', folder, entry.path);
+                return entry.path;
+            }
+        }
+        throw new Error(`No folder with specialUse "${folder}" found on this server. ` +
+            `Available folders: [${list.map((f) => `${f.path} (${f.specialUse || 'none'})`).join(', ')}]`);
+    }
     /** Instantiates an ImapFlow client using the provided credentials. */
     createImapClient() {
         const imap = this.requireImap();
@@ -400,7 +425,7 @@ export class EmailClient {
     /** Fetches unread/unseen messages from IMAP that match the search criteria. */
     async fetchNewCandidates(client, filters, seenUids, downloadDir, maxFetchLimit = 50) {
         const searchCriteria = this.buildSearchCriteria(filters);
-        const uids = await client.search(searchCriteria);
+        const uids = await client.search(searchCriteria, { uid: true });
         if (!uids || uids.length === 0)
             return [];
         const newUids = uids.filter(uid => !seenUids.has(uid));
@@ -414,7 +439,7 @@ export class EmailClient {
             newUids.slice(0, -maxFetchLimit).forEach(uid => seenUids.add(uid));
         }
         const candidates = [];
-        for await (const msg of client.fetch(limitedUids, { source: true, uid: true })) {
+        for await (const msg of client.fetch(limitedUids, { source: true }, { uid: true })) {
             seenUids.add(msg.uid);
             candidates.push(await this.parseMessage(msg, downloadDir));
         }

package/dist/types.d.ts

@@ -102,7 +102,7 @@ export interface EmailSendOptions {
 export interface EmailReceiveOptions {
     /** Array of filters to apply when searching for emails. All filters are combined (AND logic). */
     filters: EmailFilter[];
-    /** IMAP folder to search. Defaults to 'INBOX'. */
+    /** IMAP folder to search. Accepts a literal path or a specialUse role (e.g. '\\Sent', '\\Trash'). Defaults to 'INBOX'. */
     folder?: string;
     /** How long to poll for a matching email (ms). Defaults to 30000. */
     waitTimeout?: number;
@@ -150,8 +150,8 @@ export interface EmailMarkOptions {
     action: EmailMarkAction | string[];
     /** Filters to identify which emails should be marked. If omitted, applies to all emails in the folder. */
     filters?: EmailFilter[];
-    /** The target mailbox folder to perform the action in. Defaults to 'INBOX'. */
+    /** The target mailbox folder. Accepts a literal path or a specialUse role (e.g. '\\Trash', '\\Sent'). Defaults to 'INBOX'. */
     folder?: string;
-    /** The destination folder used when the `ARCHIVED` action is triggered. Defaults to 'Archive'. */
+    /** 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.5",
+  "version": "0.0.7",
   "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",
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "debug": "^4.4.3",
-    "imapflow": "^1.2.16",
-    "mailparser": "^3.9.5",
-    "nodemailer": "^8.0.3"
+    "imapflow": "^1.3.1",
+    "mailparser": "^3.9.8",
+    "nodemailer": "^8.0.5"
   },
   "devDependencies": {
     "@civitas-cerebrum/test-coverage": "^0.0.8",
@@ -39,8 +39,8 @@
     "dotenv": "^17.3.1",
     "jsdom": "^25.0.1",
     "typescript": "^5.0.0",
-    "vite": "^6.0.1",
-    "vitest": "^2.1.5"
+    "vite": "^6.4.2",
+    "vitest": "^4.1.4"
   },
   "publishConfig": {
     "access": "public",