Merge pull request #13 from civitas-cerebrum/expunge-fix

Expunge fix

Author: Umutayb

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-lock.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",

package.json

@@ -201,8 +201,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;
             }
         });
@@ -272,8 +276,10 @@ export class EmailClient {
             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);
@@ -298,7 +304,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 { await client.logout(); } catch (err) { log('IMAP logout failed (ignored): %o', err); }
         }
@@ -320,13 +326,15 @@ export class EmailClient {
             await client.connect();
             this.logImapConnection();
 
+            const resolvedFolder = await this._resolveFolder(client, folder);
+
             try {
-                await client.mailboxOpen(folder);
+                await client.mailboxOpen(resolvedFolder);
             } catch (err: any) {
                 if (err.serverResponseCode === 'NONEXISTENT' || err.message.includes('Unknown Mailbox')) {
                     const available = await this._listAvailableFolders(client);
                     throw new Error(
-                        `Failed to open folder "${folder}".\n` +
+                        `Failed to open folder "${resolvedFolder}".\n` +
                         `Available folders on this server: [${available.join(', ')}]\n` +
                         `Check your ARCHIVE_FOLDER or folder settings.`
                     );
@@ -338,7 +346,7 @@ export class EmailClient {
                 ? 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);
@@ -380,6 +388,29 @@ 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.
+     */
+    private async _resolveFolder(client: ImapFlow, folder: string): Promise<string> {
+        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 as any[]).map((f: any) => `${f.path} (${f.specialUse || 'none'})`).join(', ')}]`
+        );
+    }
+
     /** Instantiates an ImapFlow client using the provided credentials. */
     private createImapClient(): ImapFlow {
         const imap = this.requireImap();
@@ -448,7 +479,7 @@ export class EmailClient {
         maxFetchLimit: number = 50
     ): Promise<ReceivedEmail[]> {
         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));
@@ -464,7 +495,7 @@ export class EmailClient {
         }
 
         const candidates: ReceivedEmail[] = [];
-        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));
         }

src/EmailClient.ts

@@ -109,7 +109,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;
@@ -160,8 +160,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;
 }

src/types.ts

@@ -2,8 +2,35 @@ import { describe, test, expect, beforeAll } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
+import { ImapFlow } from 'imapflow';
 import { EmailClient, EmailFilterType, EmailMarkAction } from '../src';
 
+/** Opens a raw ImapFlow connection and returns the flags for emails matching the given subject. */
+async function getImapFlags(subject: string): Promise<Set<string>[]> {
+    const client = new ImapFlow({
+        host: 'imap.gmail.com',
+        port: 993,
+        secure: true,
+        auth: { user: process.env.RECEIVER_EMAIL!, pass: process.env.RECEIVER_PASSWORD! },
+        logger: false,
+    });
+
+    try {
+        await client.connect();
+        await client.mailboxOpen('INBOX');
+        const uids = await client.search({ subject }, { uid: true });
+        if (!uids || uids.length === 0) return [];
+
+        const results: Set<string>[] = [];
+        for await (const msg of client.fetch(uids, { flags: true }, { uid: true })) {
+            results.push(msg.flags);
+        }
+        return results;
+    } finally {
+        try { await client.logout(); } catch { /* ignore */ }
+    }
+}
+
 describe('EmailClient Integration Workflows', () => {
     let emailClient: EmailClient;
     const TIMEOUT = 120000;
@@ -225,6 +252,51 @@ describe('EmailClient Integration Workflows', () => {
         await emailClient.clean({ filters: filterCriteria });
     });
 
+    test('should verify mark() actually modifies the correct email flags on the server', { timeout: 180000 }, async () => {
+        const uniqueSubject = `Mark Verify Flags ${Date.now()}`;
+        const recipient = process.env.RECEIVER_EMAIL!;
+
+        await emailClient.send({
+            to: recipient,
+            subject: uniqueSubject,
+            text: 'Verifying flags are applied to the correct email.',
+        });
+
+        await emailClient.receive({
+            filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+            waitTimeout: TIMEOUT,
+            pollInterval: POLLING,
+        });
+
+        const filterCriteria = [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }];
+
+        // Mark as READ and verify \\Seen flag is present
+        await emailClient.mark({ action: EmailMarkAction.READ, filters: filterCriteria });
+        let flags = await getImapFlags(uniqueSubject);
+        expect(flags).toHaveLength(1);
+        expect(flags[0].has('\\Seen')).toBe(true);
+
+        // Mark as UNREAD and verify \\Seen flag is removed
+        await emailClient.mark({ action: EmailMarkAction.UNREAD, filters: filterCriteria });
+        flags = await getImapFlags(uniqueSubject);
+        expect(flags).toHaveLength(1);
+        expect(flags[0].has('\\Seen')).toBe(false);
+
+        // Mark as FLAGGED and verify \\Flagged is present
+        await emailClient.mark({ action: EmailMarkAction.FLAGGED, filters: filterCriteria });
+        flags = await getImapFlags(uniqueSubject);
+        expect(flags).toHaveLength(1);
+        expect(flags[0].has('\\Flagged')).toBe(true);
+
+        // Mark as UNFLAGGED and verify \\Flagged is removed
+        await emailClient.mark({ action: EmailMarkAction.UNFLAGGED, filters: filterCriteria });
+        flags = await getImapFlags(uniqueSubject);
+        expect(flags).toHaveLength(1);
+        expect(flags[0].has('\\Flagged')).toBe(false);
+
+        await emailClient.clean({ filters: filterCriteria });
+    });
+
     test('should apply custom IMAP string flags using mark()', async () => {
         const uniqueSubject = `Mark Custom Flags Test ${Date.now()}`;
         const recipient = process.env.RECEIVER_EMAIL!;
@@ -418,6 +490,33 @@ describe('EmailClient Integration Workflows', () => {
             ).rejects.toThrow(/Failed to open folder "Trash"/i);
         });
 
+        test('should verify emails are permanently removed after clean()', async () => {
+            const uniqueSubject = `CleanVerify-${Date.now()}`;
+            const recipient = process.env.RECEIVER_EMAIL!;
+
+            await emailClient.send({ to: recipient, subject: uniqueSubject, text: 'This email should be deleted.' });
+
+            await emailClient.receive({
+                filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+                waitTimeout: TIMEOUT,
+                pollInterval: POLLING,
+            });
+
+            const deletedCount = await emailClient.clean({
+                filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+            });
+            expect(deletedCount).toBe(1);
+
+            // Verify the email is actually gone by attempting to receive it again
+            await expect(
+                emailClient.receive({
+                    filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+                    waitTimeout: 15000,
+                    pollInterval: POLLING,
+                })
+            ).rejects.toThrow(/within 15000ms/);
+        });
+
         test('should delete ALL emails in INBOX when called with no options', async () => {
             const batchId = `CleanAll-${Date.now()}`;
             const recipient = process.env.RECEIVER_EMAIL!;
@@ -471,7 +570,7 @@ describe('EmailClient Integration Workflows', () => {
                 const uniqueSubject = `Mark ARCHIVED Test ${Date.now()}`;
                 const recipient = process.env.RECEIVER_EMAIL!;
 
-                const testArchiveFolder = '[Gmail]/Taslaklar';
+                const testArchiveFolder = '\\Flagged';
 
                 await emailClient.send({ to: recipient, subject: uniqueSubject, text: 'archive test' });
                 await emailClient.receive({
@@ -487,6 +586,24 @@ describe('EmailClient Integration Workflows', () => {
 
                 expect(count).toBe(1);
 
+                // Verify the email is no longer in INBOX
+                await expect(
+                    emailClient.receive({
+                        filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+                        waitTimeout: 15000,
+                        pollInterval: POLLING,
+                    })
+                ).rejects.toThrow(/within 15000ms/);
+
+                // Verify the email arrived in the archive folder
+                const archived = await emailClient.receive({
+                    filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
+                    folder: testArchiveFolder,
+                    waitTimeout: TIMEOUT,
+                    pollInterval: POLLING,
+                });
+                expect(archived.subject).toContain(uniqueSubject);
+
                 await emailClient.clean({
                     filters: [{ type: EmailFilterType.SUBJECT, value: uniqueSubject }],
                     folder: testArchiveFolder,