@civitas-cerebrum/email-client 0.0.1

package/README.md

@@ -0,0 +1,171 @@
+# @civitas-cerebrum/email-client
+
+[![NPM Version](https://img.shields.io/npm/v/@civitas-cerebrum/email-client?color=rgb(88%2C%20171%2C%2070))](https://www.npmjs.com/package/@civitas-cerebrum/email-client)
+
+A generic SMTP/IMAP email client for test automation. Send, receive, search, and clean emails with composable filters.
+
+- **Zero Playwright runtime dependency** — works with any test runner
+- **Composable filters** — combine subject, sender, content, date, and more with AND logic
+- **Two-phase matching** — exact match first, partial case-insensitive fallback
+- **Full inbox management** — send, receive, receive all, and clean
+
+## Installation
+
+```bash
+npm i @civitas-cerebrum/email-client
+```
+
+## Quick Start
+
+```ts
+import { EmailClient, EmailFilterType } from '@civitas-cerebrum/email-client';
+
+const client = new EmailClient({
+    senderEmail: 'sender@example.com',
+    senderPassword: 'app-password',
+    senderSmtpHost: 'smtp.example.com',
+    receiverEmail: 'receiver@example.com',
+    receiverPassword: 'app-password',
+});
+
+// Send an email
+await client.send({
+    to: 'user@example.com',
+    subject: 'Your OTP Code',
+    text: 'Your code is 123456',
+});
+
+// Receive the latest matching email
+const email = await client.receive({
+    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your OTP Code' }],
+});
+console.log(email.subject, email.text);
+```
+
+## API
+
+### Constructor
+
+```ts
+const client = new EmailClient(credentials: EmailCredentials);
+```
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `senderEmail` | `string` | — | SMTP sender email address |
+| `senderPassword` | `string` | — | SMTP sender password or app password |
+| `senderSmtpHost` | `string` | — | SMTP host (e.g. `'smtp.gmail.com'`) |
+| `senderSmtpPort` | `number` | `587` | SMTP port |
+| `receiverEmail` | `string` | — | IMAP receiver email address |
+| `receiverPassword` | `string` | — | IMAP receiver password or app password |
+| `receiverImapHost` | `string` | `'imap.gmail.com'` | IMAP host |
+| `receiverImapPort` | `number` | `993` | IMAP port |
+
+### Sending Emails
+
+```ts
+// Plain text
+await client.send({ to: 'user@example.com', subject: 'Test', text: 'Hello' });
+
+// Inline HTML
+await client.send({ to: 'user@example.com', subject: 'Report', html: '<h1>Results</h1>' });
+
+// HTML file template
+await client.send({ to: 'user@example.com', subject: 'Report', htmlFile: 'emails/report.html' });
+```
+
+### Receiving Emails
+
+Use composable filters to search for emails. Combine as many filters as needed — all filters are applied with AND logic. Filtering tries exact match first, then falls back to partial case-insensitive match (with a warning log).
+
+```ts
+// Single filter — get the latest matching email
+const email = await client.receive({
+    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your OTP' }],
+});
+
+// Multiple filters — combine subject, sender, and content
+const email2 = await client.receive({
+    filters: [
+        { type: EmailFilterType.SUBJECT, value: 'Verification' },
+        { type: EmailFilterType.FROM, value: 'noreply@example.com' },
+        { type: EmailFilterType.CONTENT, value: 'verification code' },
+    ],
+});
+
+// Get ALL matching emails
+const allEmails = await client.receiveAll({
+    filters: [
+        { type: EmailFilterType.FROM, value: 'alerts@example.com' },
+        { type: EmailFilterType.SINCE, value: new Date('2025-01-01') },
+    ],
+});
+```
+
+### Receive Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `filters` | `EmailFilter[]` | — | **Required.** Array of filters (AND logic) |
+| `folder` | `string` | `'INBOX'` | IMAP folder to search |
+| `waitTimeout` | `number` | `30000` | Max ms to poll for the email |
+| `pollInterval` | `number` | `3000` | Ms between poll attempts |
+| `downloadDir` | `string` | `os.tmpdir()/pw-emails` | Where to save downloaded HTML |
+
+### Filter Types
+
+| Type | Value | Description |
+|---|---|---|
+| `EmailFilterType.SUBJECT` | `string` | Filter by email subject |
+| `EmailFilterType.FROM` | `string` | Filter by sender address |
+| `EmailFilterType.TO` | `string` | Filter by recipient address |
+| `EmailFilterType.CONTENT` | `string` | Filter by email body (HTML or plain text) |
+| `EmailFilterType.SINCE` | `Date` | Only include emails after this date |
+
+### Cleaning the Inbox
+
+```ts
+// Delete emails matching filters
+await client.clean({
+    filters: [{ type: EmailFilterType.FROM, value: 'noreply@example.com' }],
+});
+
+// Delete all emails in the inbox
+await client.clean();
+```
+
+### Client-Side Filtering
+
+`applyFilters` is public — use it to filter already-fetched emails:
+
+```ts
+const filtered = client.applyFilters(emails, [
+    { type: EmailFilterType.SUBJECT, value: 'OTP' },
+]);
+```
+
+## ReceivedEmail
+
+Each received email is downloaded as an HTML file and returned as:
+
+| Field | Type | Description |
+|---|---|---|
+| `filePath` | `string` | Local path to the downloaded HTML file |
+| `subject` | `string` | Email subject |
+| `from` | `string` | Sender address |
+| `date` | `Date` | Date the email was sent |
+| `html` | `string` | Raw HTML content (empty string if plain-text only) |
+| `text` | `string` | Plain-text content |
+
+## Contributing
+
+```bash
+git clone https://github.com/Umutayb/email-client.git
+cd email-client
+npm install
+npm test
+```
+
+## License
+
+MIT

package/dist/EmailClient.d.ts

@@ -0,0 +1,26 @@
+import { EmailSendOptions, EmailReceiveOptions, EmailCredentials, ReceivedEmail, EmailFilter } from './types';
+export declare class EmailClient {
+    private credentials;
+    private smtpTransport;
+    constructor(credentials: EmailCredentials);
+    send(options: EmailSendOptions): Promise<void>;
+    receive(options: EmailReceiveOptions): Promise<ReceivedEmail>;
+    receiveAll(options: EmailReceiveOptions): Promise<ReceivedEmail[]>;
+    clean(options?: {
+        filters?: EmailFilter[];
+        folder?: string;
+    }): Promise<number>;
+    applyFilters(candidates: ReceivedEmail[], filters: EmailFilter[]): ReceivedEmail[];
+    private validateFilters;
+    private createImapClient;
+    private logImapConnection;
+    private buildSearchCriteria;
+    private fetchCandidates;
+    private matchesAllFilters;
+    private getEmailField;
+    private formatFilterSummary;
+    private parseMessage;
+    private getSmtpTransport;
+    extractHtmlFromSource(source: string): string;
+    extractTextFromSource(source: string): string;
+}

package/dist/EmailClient.js

@@ -0,0 +1,338 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailClient = void 0;
+const nodemailer = __importStar(require("nodemailer"));
+const imapflow_1 = require("imapflow");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const logger_1 = require("./logger");
+const types_1 = require("./types");
+const log = (0, logger_1.createLogger)('imap');
+const smtpLog = (0, logger_1.createLogger)('smtp');
+class EmailClient {
+    credentials;
+    smtpTransport = null;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    // ─── SMTP ────────────────────────────────────────────────────────────
+    async send(options) {
+        const transport = this.getSmtpTransport();
+        const { to, subject, text, html, htmlFile } = options;
+        let htmlContent = html;
+        if (htmlFile) {
+            const resolvedPath = path.resolve(htmlFile);
+            if (!fs.existsSync(resolvedPath)) {
+                throw new Error(`HTML file not found: ${resolvedPath}`);
+            }
+            htmlContent = fs.readFileSync(resolvedPath, 'utf-8');
+            smtpLog('Loaded HTML email body from %s (%d bytes)', resolvedPath, htmlContent.length);
+        }
+        const mailOptions = {
+            from: this.credentials.senderEmail,
+            to,
+            subject,
+            ...(htmlContent ? { html: htmlContent } : { text: text ?? '' })
+        };
+        const info = await transport.sendMail(mailOptions);
+        smtpLog('Email sent to %s — messageId: %s', to, info.messageId);
+    }
+    // ─── IMAP ────────────────────────────────────────────────────────────
+    async receive(options) {
+        const { filters, folder, waitTimeout, pollInterval, downloadDir } = options;
+        this.validateFilters(filters);
+        const timeout = waitTimeout ?? 30000;
+        const interval = pollInterval ?? 3000;
+        const mailbox = folder ?? 'INBOX';
+        const deadline = Date.now() + timeout;
+        const client = this.createImapClient();
+        try {
+            await client.connect();
+            this.logImapConnection();
+            while (Date.now() < deadline) {
+                await client.mailboxOpen(mailbox);
+                const candidates = await this.fetchCandidates(client, filters, downloadDir);
+                const result = this.applyFilters(candidates, filters);
+                if (result.length > 0) {
+                    return result[result.length - 1];
+                }
+                log('No matching email found yet, retrying in %dms...', interval);
+                await new Promise(resolve => setTimeout(resolve, interval));
+            }
+            throw new Error(`No email matching criteria found within ${timeout}ms. Searched in "${mailbox}" for: ${this.formatFilterSummary(filters)}`);
+        }
+        finally {
+            try {
+                await client.logout();
+            }
+            catch { /* already disconnected */ }
+        }
+    }
+    async receiveAll(options) {
+        const { filters, folder, waitTimeout, pollInterval, downloadDir } = options;
+        this.validateFilters(filters);
+        const timeout = waitTimeout ?? 30000;
+        const interval = pollInterval ?? 3000;
+        const mailbox = folder ?? 'INBOX';
+        const deadline = Date.now() + timeout;
+        const client = this.createImapClient();
+        try {
+            await client.connect();
+            this.logImapConnection();
+            while (Date.now() < deadline) {
+                await client.mailboxOpen(mailbox);
+                const candidates = await this.fetchCandidates(client, filters, downloadDir);
+                const results = this.applyFilters(candidates, filters);
+                if (results.length > 0) {
+                    log('Found %d matching email(s)', results.length);
+                    return results;
+                }
+                log('No matching emails found yet, retrying in %dms...', interval);
+                await new Promise(resolve => setTimeout(resolve, interval));
+            }
+            throw new Error(`No emails matching criteria found within ${timeout}ms. Searched in "${mailbox}" for: ${this.formatFilterSummary(filters)}`);
+        }
+        finally {
+            try {
+                await client.logout();
+            }
+            catch { /* already disconnected */ }
+        }
+    }
+    async clean(options) {
+        const filters = options?.filters;
+        const mailbox = options?.folder ?? 'INBOX';
+        const client = this.createImapClient();
+        try {
+            await client.connect();
+            this.logImapConnection();
+            await client.mailboxOpen(mailbox);
+            const searchCriteria = filters && filters.length > 0
+                ? this.buildSearchCriteria(filters)
+                : { all: true };
+            const uids = [];
+            for await (const msg of client.fetch({ ...searchCriteria }, { uid: true })) {
+                uids.push(msg.uid);
+            }
+            if (uids.length > 0) {
+                await client.messageDelete(uids, { uid: true });
+                log('Deleted %d email(s) from "%s"', uids.length, mailbox);
+            }
+            else {
+                log('No emails to delete in "%s"', mailbox);
+            }
+            await client.logout();
+            return uids.length;
+        }
+        catch (error) {
+            try {
+                await client.logout();
+            }
+            catch { /* already disconnected */ }
+            throw error;
+        }
+    }
+    // ─── Public filtering API ────────────────────────────────────────
+    applyFilters(candidates, filters) {
+        const stringFilters = filters.filter(f => f.type !== types_1.EmailFilterType.SINCE && f.type !== types_1.EmailFilterType.TO);
+        if (stringFilters.length === 0)
+            return candidates;
+        const exactMatches = candidates.filter(email => this.matchesAllFilters(email, stringFilters, true));
+        if (exactMatches.length > 0)
+            return exactMatches;
+        const partialMatches = candidates.filter(email => this.matchesAllFilters(email, stringFilters, false));
+        if (partialMatches.length > 0) {
+            log('No exact match found — falling back to partial case-insensitive match for: %s', this.formatFilterSummary(stringFilters));
+        }
+        return partialMatches;
+    }
+    // ─── Private helpers ─────────────────────────────────────────────
+    validateFilters(filters) {
+        if (!filters || filters.length === 0) {
+            throw new Error('At least one email filter is required. Use EmailFilterType to specify filter criteria.');
+        }
+    }
+    createImapClient() {
+        return new imapflow_1.ImapFlow({
+            host: this.credentials.receiverImapHost ?? 'imap.gmail.com',
+            port: this.credentials.receiverImapPort ?? 993,
+            secure: true,
+            auth: {
+                user: this.credentials.receiverEmail,
+                pass: this.credentials.receiverPassword
+            },
+            logger: false
+        });
+    }
+    logImapConnection() {
+        log('IMAP connected to %s as %s', this.credentials.receiverImapHost ?? 'imap.gmail.com', this.credentials.receiverEmail);
+    }
+    buildSearchCriteria(filters) {
+        const criteria = {};
+        for (const filter of filters) {
+            switch (filter.type) {
+                case types_1.EmailFilterType.SUBJECT:
+                    criteria.subject = filter.value;
+                    break;
+                case types_1.EmailFilterType.FROM:
+                    criteria.from = filter.value;
+                    break;
+                case types_1.EmailFilterType.TO:
+                    criteria.to = filter.value;
+                    break;
+                case types_1.EmailFilterType.CONTENT:
+                    criteria.body = filter.value;
+                    break;
+                case types_1.EmailFilterType.SINCE:
+                    criteria.since = filter.value;
+                    break;
+                default: throw new Error(`Unknown email filter type: ${filter.type}`);
+            }
+        }
+        return criteria;
+    }
+    async fetchCandidates(client, filters, downloadDir) {
+        const searchCriteria = this.buildSearchCriteria(filters);
+        const candidates = [];
+        for await (const msg of client.fetch({ ...searchCriteria }, { source: true, envelope: true })) {
+            candidates.push(this.parseMessage(msg, downloadDir));
+        }
+        return candidates;
+    }
+    matchesAllFilters(email, filters, exact) {
+        return filters.every(filter => {
+            const filterValue = filter.value;
+            const fieldValue = this.getEmailField(email, filter.type);
+            if (exact)
+                return fieldValue === filterValue;
+            return fieldValue.toLowerCase().includes(filterValue.toLowerCase());
+        });
+    }
+    getEmailField(email, filterType) {
+        switch (filterType) {
+            case types_1.EmailFilterType.SUBJECT: return email.subject;
+            case types_1.EmailFilterType.FROM: return email.from;
+            case types_1.EmailFilterType.TO: return '';
+            case types_1.EmailFilterType.CONTENT: return email.html || email.text;
+            default: return '';
+        }
+    }
+    formatFilterSummary(filters) {
+        return filters.map(f => `${f.type}: ${f.value instanceof Date ? f.value.toISOString() : f.value}`).join(', ');
+    }
+    parseMessage(msg, downloadDir) {
+        const source = msg.source?.toString('utf-8') ?? '';
+        const envelope = msg.envelope;
+        const htmlBody = this.extractHtmlFromSource(source);
+        const textBody = this.extractTextFromSource(source);
+        const outputDir = downloadDir ?? path.join(os.tmpdir(), 'pw-emails');
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        const sanitizedSubject = (envelope?.subject ?? 'email')
+            .replace(/[^a-zA-Z0-9-_]/g, '_')
+            .substring(0, 50);
+        const fileName = `${sanitizedSubject}-${Date.now()}.html`;
+        const filePath = path.join(outputDir, fileName);
+        const content = htmlBody || `<pre>${textBody}</pre>`;
+        fs.writeFileSync(filePath, content, 'utf-8');
+        log('Email downloaded to %s', filePath);
+        return {
+            filePath,
+            subject: envelope?.subject ?? '',
+            from: envelope?.from?.[0]?.address ?? '',
+            date: envelope?.date ?? new Date(),
+            html: htmlBody,
+            text: textBody
+        };
+    }
+    getSmtpTransport() {
+        if (!this.smtpTransport) {
+            this.smtpTransport = nodemailer.createTransport({
+                host: this.credentials.senderSmtpHost,
+                port: this.credentials.senderSmtpPort ?? 587,
+                secure: this.credentials.senderSmtpPort === 465,
+                auth: {
+                    user: this.credentials.senderEmail,
+                    pass: this.credentials.senderPassword
+                }
+            });
+        }
+        return this.smtpTransport;
+    }
+    extractHtmlFromSource(source) {
+        const sectionMatch = source.match(/(Content-Type:\s*text\/html[^\r\n]*(?:\r?\n(?![\r\n])[^\r\n]*)*)\r?\n\r?\n([\s\S]*?)(?:\r?\n--|\r?\n\.\r?\n|$)/i);
+        if (sectionMatch) {
+            const headers = sectionMatch[1];
+            let content = sectionMatch[2];
+            if (/Content-Transfer-Encoding:\s*base64/i.test(headers)) {
+                try {
+                    content = Buffer.from(content.replace(/\s/g, ''), 'base64').toString('utf-8');
+                }
+                catch { /* not base64 */ }
+            }
+            if (/Content-Transfer-Encoding:\s*quoted-printable/i.test(headers)) {
+                content = content
+                    .replace(/=\r?\n/g, '')
+                    .replace(/=([0-9A-F]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+            }
+            return content;
+        }
+        return '';
+    }
+    extractTextFromSource(source) {
+        const sectionMatch = source.match(/(Content-Type:\s*text\/plain[^\r\n]*(?:\r?\n(?![\r\n])[^\r\n]*)*)\r?\n\r?\n([\s\S]*?)(?:\r?\n--|\r?\n\.\r?\n|$)/i);
+        if (sectionMatch) {
+            const headers = sectionMatch[1];
+            let content = sectionMatch[2];
+            if (/Content-Transfer-Encoding:\s*base64/i.test(headers)) {
+                try {
+                    content = Buffer.from(content.replace(/\s/g, ''), 'base64').toString('utf-8');
+                }
+                catch { /* not base64 */ }
+            }
+            if (/Content-Transfer-Encoding:\s*quoted-printable/i.test(headers)) {
+                content = content
+                    .replace(/=\r?\n/g, '')
+                    .replace(/=([0-9A-F]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+            }
+            return content;
+        }
+        return '';
+    }
+}
+exports.EmailClient = EmailClient;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { EmailClient } from './EmailClient';
+export { EmailFilterType, EmailCredentials, EmailFilter, EmailSendOptions, EmailReceiveOptions, ReceivedEmail } from './types';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailFilterType = exports.EmailClient = void 0;
+var EmailClient_1 = require("./EmailClient");
+Object.defineProperty(exports, "EmailClient", { enumerable: true, get: function () { return EmailClient_1.EmailClient; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "EmailFilterType", { enumerable: true, get: function () { return types_1.EmailFilterType; } });

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+import debug from 'debug';
+/**
+ * Creates a namespaced debug logger for the email-client package.
+ * Enable with `DEBUG=email-client:*` environment variable.
+ */
+export declare function createLogger(namespace: string): debug.Debugger;

package/dist/logger.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const debug_1 = __importDefault(require("debug"));
+/**
+ * Creates a namespaced debug logger for the email-client package.
+ * Enable with `DEBUG=email-client:*` environment variable.
+ */
+function createLogger(namespace) {
+    return (0, debug_1.default)(`email-client:${namespace}`);
+}

package/dist/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Defines the type of filter to apply when searching for emails.
+ */
+export declare enum EmailFilterType {
+    /** Filter by email subject. */
+    SUBJECT = "subject",
+    /** Filter by sender address. */
+    FROM = "from",
+    /** Filter by recipient address. */
+    TO = "to",
+    /** Filter by email body content (HTML or plain text). */
+    CONTENT = "content",
+    /** Filter to only include emails received after a given date. Value must be a Date object. */
+    SINCE = "since"
+}
+/**
+ * A single email search filter. Combine multiple filters in an array
+ * to narrow down the search.
+ */
+export interface EmailFilter {
+    /** The filter type to apply. */
+    type: EmailFilterType;
+    /** The value to filter by. Use a string for SUBJECT/FROM/TO/CONTENT, or a Date for SINCE. */
+    value: string | Date;
+}
+/**
+ * SMTP and IMAP credentials for the email client.
+ */
+export interface EmailCredentials {
+    /** SMTP sender email address. */
+    senderEmail: string;
+    /** SMTP sender password or app password. */
+    senderPassword: string;
+    /** SMTP host (e.g. 'smtp-relay.sendinblue.com'). */
+    senderSmtpHost: string;
+    /** SMTP port. Defaults to 587. */
+    senderSmtpPort?: number;
+    /** IMAP receiver email address. */
+    receiverEmail: string;
+    /** IMAP receiver password or app password. */
+    receiverPassword: string;
+    /** IMAP host. Defaults to 'imap.gmail.com'. */
+    receiverImapHost?: string;
+    /** IMAP port. Defaults to 993. */
+    receiverImapPort?: number;
+}
+/**
+ * Options for sending an email.
+ * Provide `text` for plain-text, `html` for inline HTML, or `htmlFile` for an HTML template file.
+ */
+export interface EmailSendOptions {
+    /** Recipient email address. */
+    to: string;
+    /** Email subject line. */
+    subject: string;
+    /** Plain-text body. Used when neither `html` nor `htmlFile` is provided. */
+    text?: string;
+    /** Inline HTML body. Takes precedence over `text`. */
+    html?: string;
+    /** Path to an HTML file to use as the email body. Takes precedence over `html` and `text`. */
+    htmlFile?: string;
+}
+/**
+ * Options for receiving (searching and downloading) an email via IMAP.
+ */
+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'. */
+    folder?: string;
+    /** How long to poll for a matching email (ms). Defaults to 30000. */
+    waitTimeout?: number;
+    /** Interval between poll attempts (ms). Defaults to 3000. */
+    pollInterval?: number;
+    /** Directory to save downloaded email HTML. Defaults to os.tmpdir()/pw-emails. */
+    downloadDir?: string;
+}
+/**
+ * Represents a received email after download.
+ */
+export interface ReceivedEmail {
+    /** Local file path of the downloaded HTML. Open with `navigateTo('file://' + filePath)`. */
+    filePath: string;
+    /** Email subject. */
+    subject: string;
+    /** Sender address. */
+    from: string;
+    /** Date the email was sent. */
+    date: Date;
+    /** Raw HTML content (empty string if plain-text only). */
+    html: string;
+    /** Plain-text content. */
+    text: string;
+}

package/dist/types.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailFilterType = void 0;
+/**
+ * Defines the type of filter to apply when searching for emails.
+ */
+var EmailFilterType;
+(function (EmailFilterType) {
+    /** Filter by email subject. */
+    EmailFilterType["SUBJECT"] = "subject";
+    /** Filter by sender address. */
+    EmailFilterType["FROM"] = "from";
+    /** Filter by recipient address. */
+    EmailFilterType["TO"] = "to";
+    /** Filter by email body content (HTML or plain text). */
+    EmailFilterType["CONTENT"] = "content";
+    /** Filter to only include emails received after a given date. Value must be a Date object. */
+    EmailFilterType["SINCE"] = "since";
+})(EmailFilterType || (exports.EmailFilterType = EmailFilterType = {}));

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@civitas-cerebrum/email-client",
+  "version": "0.0.1",
+  "description": "A generic SMTP/IMAP email client for test automation. Send, receive, search, and clean emails with composable filters.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "test": "npx playwright test",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "debug": "^4.4.3",
+    "imapflow": "^1.2.16",
+    "nodemailer": "^8.0.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/debug": "^4.1.13",
+    "@types/node": "^20.0.0",
+    "@types/nodemailer": "^7.0.11",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/civitas-cerebrum/email-client.git"
+  },
+  "author": "Umut Ay Bora",
+  "license": "MIT",
+  "keywords": [
+    "email",
+    "smtp",
+    "imap",
+    "nodemailer",
+    "test-automation",
+    "email-filter"
+  ]
+}