@bencibro/tempmail-mcp 0.0.1

package/README.md

@@ -0,0 +1,308 @@
+# TempMail MCP
+
+**[English](./README.md)** | [中文](./README.zh-CN.md)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that provides **temporary email** services for AI agents, enabling closed-loop verification of email-based registration flows.
+
+> **For AI agents:** Read the [AI Guide](./GUIDE.md) for tool-by-tool instructions, decision trees, and workflow patterns.  
+> **AI 代理指南：** 阅读 [中文指南](./GUIDE.zh-CN.md) 获取工具使用说明、决策树和工作流模式。
+
+## Features
+
+- **Multi-provider aggregation** — 6 temp-mail providers behind one unified interface
+- **No API key required** for 4 out of 6 providers (Mail.tm, Guerrilla Mail, 1secmail, Catchmail)
+- **Auto-registration** — automatically obtain MailDrop and mail.cx API keys via pure HTTP API calls (no browser needed)
+- **Verification code extraction** — automatically extracts OTP/verification codes from incoming emails
+- **Wait-for-email** — blocking/long-poll until a matching email arrives
+- **Session management** — tracks created mailboxes in-memory for the MCP session
+- **Zero heavy dependencies** — no Puppeteer, no Playwright, just Node.js built-in modules
+
+## Supported Providers
+
+| Provider | API Key | Free Tier | Special Features |
+|----------|---------|-----------|-------------------|
+| **Mail.tm** | No | 8 QPS | Full REST API, account-based |
+| **Guerrilla Mail** | No | Unlimited | Session-based, 60-min expiry, custom username |
+| **1secmail** | No | Unlimited | Simplest API, implicit mailbox |
+| **Catchmail** | No | 1 req/s | Custom domains via MX records |
+| **MailDrop** | Yes (auto-obtainable) | 300 req/day | Claim-based mailboxes, RSA pubkey auth |
+| **Mail.cx** | Yes (auto-obtainable) | 500 req/day | Long-poll, SSE push, magic-link auth |
+
+> **Tip:** Use the `auto_register` tool to automatically obtain MailDrop and mail.cx API keys — no manual signup needed.
+
+## Installation
+
+### From npm (when published)
+
+```bash
+npm install -g tempmail-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/your-username/tempmail-mcp.git
+cd tempmail-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MAILDROP_API_KEY` | No | API key for MailDrop. Auto-obtainable via `auto_register` tool. |
+| `MAILCX_API_TOKEN` | No | API token for Mail.cx. Auto-obtainable via `auto_register` tool. |
+
+### Claude Desktop / Cursor / MCP Client Config
+
+Add to your MCP client configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "tempmail": {
+      "command": "npx",
+      "args": ["-y", "tempmail-mcp"],
+      "env": {
+        "MAILDROP_API_KEY": "your-maildrop-api-key",
+        "MAILCX_API_TOKEN": "your-mailcx-api-token"
+      }
+    }
+  }
+}
+```
+
+If you only need the free providers (no API keys), simply omit the `env` block.
+
+**Don't have an API key?** Use the `auto_register` tool to automatically obtain a free MailDrop or mail.cx API key — **no browser needed**, pure HTTP API calls. See [Auto-Register](#auto_register) below.
+
+## Available Tools
+
+### `list_providers`
+
+List all available temporary email providers and their capabilities.
+
+### `get_domains`
+
+Get the list of available email domains for a given provider.
+
+- **provider** (optional, default `"mail.tm"`): Provider name.
+
+### `create_mailbox`
+
+Create a new temporary email mailbox.
+
+- **provider** (optional, default `"mail.tm"`): Provider name.
+- **username** (optional): Preferred username (local part).
+- **domain** (optional): Preferred domain.
+
+### `get_messages`
+
+Get the list of received emails for a mailbox.
+
+- **address**: The temporary email address.
+
+### `get_message`
+
+Get the full content of a specific email.
+
+- **address**: The temporary email address.
+- **messageId**: The message ID (from `get_messages`).
+
+### `wait_for_email`
+
+Block until a matching email arrives. Returns the first matching message.
+
+- **address**: The temporary email address.
+- **subjectContains** (optional): Filter by subject substring.
+- **fromContains** (optional): Filter by sender substring.
+- **timeoutMs** (optional, default `60000`): Timeout in ms.
+- **pollIntervalMs** (optional, default `3000`): Poll interval in ms.
+
+### `get_verification_code`
+
+Wait for a verification email and automatically extract the verification code.
+
+- **address**: The temporary email address.
+- **subjectContains** (optional): Filter (e.g. `"verification"`, `"confirm"`, `"code"`).
+- **fromContains** (optional): Filter by sender.
+- **timeoutMs** (optional, default `60000`): Timeout in ms.
+
+### `list_mailboxes`
+
+List all temporary mailboxes created in this session.
+
+### `delete_mailbox`
+
+Delete a temporary mailbox and all its messages.
+
+- **address**: The temporary email address.
+
+### `auto_register`
+
+Automatically register an account and obtain an API key/token for a provider. **Pure HTTP API — no browser, no Puppeteer.**
+
+#### `maildrop`
+
+Uses RSA key generation + HTTP API:
+
+1. Generates an RSA 2048 keypair (Node.js `crypto` module)
+2. `POST /api/register.php` with the public key
+3. Signs `timestamp-username` to create a passcode
+4. `POST /api/login.php` to authenticate
+5. `POST /api/account/keys.php` to create an API key (`md_...`)
+
+#### `mail.cx`
+
+Uses magic-link sign-in flow:
+
+1. Creates a temp mailbox via mail.tm (no API key needed)
+2. `POST /v1/auth/magic-link/request` to send a magic link to the temp email
+3. Polls mail.tm for the magic link email
+4. `POST /v1/auth/magic-link/verify` with the token — **returns the API token directly** (`tm_live_...`)
+
+**Parameters:**
+
+- **provider** (required): `"maildrop"` or `"mail.cx"`
+- **tokenName** (optional, default `"tempmail-mcp"`): Name for the token (mail.cx only).
+- **username** (optional): Username for the account (maildrop only).
+- **timeoutMs** (optional, default `120000`): Overall timeout in milliseconds.
+
+Returns the API key/token and automatically registers the provider in the current session. To make it permanent, set the corresponding environment variable (`MAILDROP_API_KEY` or `MAILCX_API_TOKEN`).
+
+## Usage Examples
+
+### Auto-Register to Get a Free API Key
+
+**MailDrop** (fast, ~2 seconds):
+
+```
+1. auto_register (provider: "maildrop")
+   → { apiKey: "md_...", email: "tmp_xxx@maildrop.cc", ... }
+
+2. [Set MAILDROP_API_KEY=md_... in your MCP config]
+
+3. list_providers
+   → Now includes "maildrop" in the provider list!
+```
+
+**mail.cx** (~15-30 seconds, waits for email):
+
+```
+1. auto_register (provider: "mail.cx")
+   → { apiKey: "tm_live_...", email: "abc@emalupe.com", ... }
+
+2. [Set MAILCX_API_TOKEN=tm_live_... in your MCP config]
+
+3. list_providers
+   → Now includes "mail.cx" in the provider list!
+```
+
+Both providers are automatically available in the current session after registration — no restart needed.
+
+### Typical Registration Verification Flow
+
+```
+1. create_mailbox (provider: "mail.tm")
+   → { address: "abc123@somedomain.com", ... }
+
+2. [Register on target website using the temp email address]
+
+3. get_verification_code (address: "abc123@somedomain.com", subjectContains: "verification")
+   → { code: "829451", from: "noreply@example.com", subject: "Your verification code", ... }
+
+4. [Enter the code on the target website to complete registration]
+
+5. delete_mailbox (address: "abc123@somedomain.com")
+```
+
+### Manual Email Checking
+
+```
+1. create_mailbox (provider: "guerrillamail", username: "mytest")
+   → { address: "mytest@guerrillamailblock.com", ... }
+
+2. get_messages (address: "mytest@guerrillamailblock.com")
+   → { count: 2, messages: [{ id: "1", from: "...", subject: "..." }, ...] }
+
+3. get_message (address: "mytest@guerrillamailblock.com", messageId: "1")
+   → { id: "1", from: "...", subject: "...", bodyText: "...", bodyHtml: "..." }
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+node dist/index.js
+
+# Watch mode
+npm run dev
+
+# Test auto-registration
+node test-auto-register-api.mjs maildrop   # Test MailDrop only
+node test-auto-register-api.mjs mailcx     # Test mail.cx only
+node test-auto-register-api.mjs all        # Test both
+```
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  MCP Client (Claude)                   │
+│                      │                                │
+│             stdio / Streamable HTTP                    │
+│                      ▼                                │
+│          ┌──────────────────────┐                      │
+│          │  TempMail MCP Server  │                      │
+│          │                      │                      │
+│          │  ┌─── Tools ───────┐ │                      │
+│          │  │ create_mailbox   │ │                      │
+│          │  │ get_messages     │ │                      │
+│          │  │ wait_for_email   │ │                      │
+│          │  │ get_verification │ │                      │
+│          │  │ auto_register    │ │                      │
+│          │  │ ...              │ │                      │
+│          │  └──────────────────┘ │                      │
+│          └──────────┬───────────┘                      │
+│                     │                                  │
+│          ┌──────────▼───────────┐                      │
+│          │  Provider Manager     │                      │
+│          │  (adapter pattern)    │                      │
+│          └──────────┬───────────┘                      │
+│                     │                                  │
+│   ┌────────┬────────┼────────┬──────────┐              │
+│   ▼        ▼        ▼        ▼          ▼              │
+│ Mail.tm  Guerrilla 1secmail  Catchmail  MailDrop        │
+│          Mail                            Mail.cx        │
+└──────────────────────────────────────────────────────┘
+
+Auto-Register Flow (pure HTTP, no browser):
+  ┌───────────────┐                    ┌───────────────┐
+  │  MailDrop     │                    │  mail.cx       │
+  │               │                    │                │
+  │  RSA keygen   │                    │  mail.tm temp  │
+  │  ↓            │                    │  mailbox       │
+  │  POST register│                    │  ↓             │
+  │  ↓            │                    │  POST magic    │
+  │  RSA sign     │                    │  link request  │
+  │  ↓            │                    │  ↓             │
+  │  POST login   │                    │  Poll for email│
+  │  ↓            │                    │  ↓             │
+  │  POST create  │                    │  POST verify   │
+  │  API key      │                    │  → API token  │
+  │  → md_...     │                    │  → tm_live_... │
+  └───────────────┘                    └───────────────┘
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,308 @@
+# TempMail MCP
+
+[English](./README.md) | **[中文](./README.zh-CN.md)**
+
+一个 [Model Context Protocol](https://modelcontextprotocol.io) 服务器，为 AI 代理提供**临时邮箱**服务，实现邮件注册验证的闭环。
+
+> **AI 代理指南：** 阅读 [中文指南](./GUIDE.zh-CN.md) 获取工具使用说明、决策树和工作流模式。  
+> **For AI agents:** Read the [AI Guide](./GUIDE.md) for tool-by-tool instructions, decision trees, and workflow patterns.
+
+## 特性
+
+- **多服务商聚合** — 6 个临时邮箱服务商统一接口
+- **4 个免费服务商无需 API Key**（Mail.tm、Guerrilla Mail、1secmail、Catchmail）
+- **自动注册** — 通过纯 HTTP API 调用自动获取 MailDrop 和 mail.cx 的 API Key（无需浏览器）
+- **验证码提取** — 自动从收到的邮件中提取 OTP/验证码
+- **等待邮件** — 阻塞/长轮询直到收到匹配的邮件
+- **会话管理** — 在内存中跟踪当前会话创建的邮箱
+- **零重型依赖** — 无 Puppeteer、无 Playwright，仅使用 Node.js 内置模块
+
+## 支持的服务商
+
+| 服务商 | 需要 API Key | 免费额度 | 特性 |
+|----------|---------|-----------|-------------------|
+| **Mail.tm** | 否 | 8 QPS | 完整 REST API，基于账号 |
+| **Guerrilla Mail** | 否 | 无限制 | 基于会话，60 分钟过期，自定义用户名 |
+| **1secmail** | 否 | 无限制 | 最简 API，隐式邮箱 |
+| **Catchmail** | 否 | 1 req/s | 通过 MX 记录自定义域名 |
+| **MailDrop** | 是（可自动获取） | 300 次/天 | 认领式邮箱，RSA 公钥认证 |
+| **Mail.cx** | 是（可自动获取） | 500 次/天 | 长轮询，SSE 推送，magic-link 认证 |
+
+> **提示：** 使用 `auto_register` 工具自动获取 MailDrop 和 mail.cx 的 API Key — 无需手动注册。
+
+## 安装
+
+### 从 npm 安装（发布后）
+
+```bash
+npm install -g tempmail-mcp
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/your-username/tempmail-mcp.git
+cd tempmail-mcp
+npm install
+npm run build
+```
+
+## 配置
+
+### 环境变量
+
+| 变量 | 是否必需 | 说明 |
+|----------|----------|-------------|
+| `MAILDROP_API_KEY` | 否 | MailDrop 的 API Key。可通过 `auto_register` 工具自动获取。 |
+| `MAILCX_API_TOKEN` | 否 | Mail.cx 的 API Token。可通过 `auto_register` 工具自动获取。 |
+
+### Claude Desktop / Cursor / MCP 客户端配置
+
+将以下内容添加到你的 MCP 客户端配置中（如 `claude_desktop_config.json`）：
+
+```json
+{
+  "mcpServers": {
+    "tempmail": {
+      "command": "npx",
+      "args": ["-y", "tempmail-mcp"],
+      "env": {
+        "MAILDROP_API_KEY": "你的-maildrop-api-key",
+        "MAILCX_API_TOKEN": "你的-mailcx-api-token"
+      }
+    }
+  }
+}
+```
+
+如果只需要免费服务商（无需 API Key），直接省略 `env` 块即可。
+
+**没有 API Key？** 使用 `auto_register` 工具自动获取免费的 MailDrop 或 mail.cx API Key — **无需浏览器**，纯 HTTP API 调用。参见下方的[自动注册](#auto_register)。
+
+## 可用工具
+
+### `list_providers`
+
+列出所有可用的临时邮箱服务商及其能力。
+
+### `get_domains`
+
+获取指定服务商的可用邮箱域名列表。
+
+- **provider**（可选，默认 `"mail.tm"`）：服务商名称。
+
+### `create_mailbox`
+
+创建一个新的临时邮箱。
+
+- **provider**（可选，默认 `"mail.tm"`）：服务商名称。
+- **username**（可选）：首选用户名（邮箱本地部分）。
+- **domain**（可选）：首选域名。
+
+### `get_messages`
+
+获取邮箱收到的邮件列表。
+
+- **address**：临时邮箱地址。
+
+### `get_message`
+
+获取特定邮件的完整内容。
+
+- **address**：临时邮箱地址。
+- **messageId**：邮件 ID（来自 `get_messages`）。
+
+### `wait_for_email`
+
+阻塞直到收到匹配的邮件。返回第一条匹配的邮件。
+
+- **address**：临时邮箱地址。
+- **subjectContains**（可选）：按邮件主题子串过滤。
+- **fromContains**（可选）：按发件人子串过滤。
+- **timeoutMs**（可选，默认 `60000`）：超时时间（毫秒）。
+- **pollIntervalMs**（可选，默认 `3000`）：轮询间隔（毫秒）。
+
+### `get_verification_code`
+
+等待验证邮件并自动提取验证码。
+
+- **address**：临时邮箱地址。
+- **subjectContains**（可选）：过滤器（如 `"verification"`、`"confirm"`、`"code"`）。
+- **fromContains**（可选）：按发件人过滤。
+- **timeoutMs**（可选，默认 `60000`）：超时时间（毫秒）。
+
+### `list_mailboxes`
+
+列出当前会话中创建的所有临时邮箱。
+
+### `delete_mailbox`
+
+删除临时邮箱及其所有邮件。
+
+- **address**：临时邮箱地址。
+
+### `auto_register`
+
+自动注册账号并获取服务商的 API Key/Token。**纯 HTTP API — 无浏览器、无 Puppeteer。**
+
+#### `maildrop`
+
+使用 RSA 密钥生成 + HTTP API：
+
+1. 生成 RSA 2048 密钥对（Node.js `crypto` 模块）
+2. `POST /api/register.php` 提交公钥注册账号
+3. 签名 `timestamp-username` 生成 passcode
+4. `POST /api/login.php` 登录认证
+5. `POST /api/account/keys.php` 创建 API Key（`md_...`）
+
+#### `mail.cx`
+
+使用 magic-link 登录流程：
+
+1. 通过 mail.tm 创建临时邮箱（无需 API Key）
+2. `POST /v1/auth/magic-link/request` 发送 magic link 到临时邮箱
+3. 轮询 mail.tm 等待 magic link 邮件
+4. `POST /v1/auth/magic-link/verify` 提交 token — **直接返回 API Token**（`tm_live_...`）
+
+**参数：**
+
+- **provider**（必填）：`"maildrop"` 或 `"mail.cx"`
+- **tokenName**（可选，默认 `"tempmail-mcp"`）：Token 名称（仅 mail.cx）。
+- **username**（可选）：账号用户名（仅 maildrop）。
+- **timeoutMs**（可选，默认 `120000`）：总超时时间（毫秒）。
+
+返回 API Key/Token 并在当前会话中自动注册该服务商。要永久生效，请设置对应的环境变量（`MAILDROP_API_KEY` 或 `MAILCX_API_TOKEN`）。
+
+## 使用示例
+
+### 自动注册获取免费 API Key
+
+**MailDrop**（快速，约 2 秒）：
+
+```
+1. auto_register (provider: "maildrop")
+   → { apiKey: "md_...", email: "tmp_xxx@maildrop.cc", ... }
+
+2. [在 MCP 配置中设置 MAILDROP_API_KEY=md_...]
+
+3. list_providers
+   → 服务商列表中现在包含 "maildrop"！
+```
+
+**mail.cx**（约 15-30 秒，需要等待邮件）：
+
+```
+1. auto_register (provider: "mail.cx")
+   → { apiKey: "tm_live_...", email: "abc@emalupe.com", ... }
+
+2. [在 MCP 配置中设置 MAILCX_API_TOKEN=tm_live_...]
+
+3. list_providers
+   → 服务商列表中现在包含 "mail.cx"！
+```
+
+注册后两个服务商在当前会话中立即可用 — 无需重启。
+
+### 典型注册验证流程
+
+```
+1. create_mailbox (provider: "mail.tm")
+   → { address: "abc123@somedomain.com", ... }
+
+2. [在目标网站上使用临时邮箱地址注册]
+
+3. get_verification_code (address: "abc123@somedomain.com", subjectContains: "verification")
+   → { code: "829451", from: "noreply@example.com", subject: "Your verification code", ... }
+
+4. [在目标网站上输入验证码完成注册]
+
+5. delete_mailbox (address: "abc123@somedomain.com")
+```
+
+### 手动查看邮件
+
+```
+1. create_mailbox (provider: "guerrillamail", username: "mytest")
+   → { address: "mytest@guerrillamailblock.com", ... }
+
+2. get_messages (address: "mytest@guerrillamailblock.com")
+   → { count: 2, messages: [{ id: "1", from: "...", subject: "..." }, ...] }
+
+3. get_message (address: "mytest@guerrillamailblock.com", messageId: "1")
+   → { id: "1", from: "...", subject: "...", bodyText: "...", bodyHtml: "..." }
+```
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 编译
+npm run build
+
+# 本地运行
+node dist/index.js
+
+# 监听模式
+npm run dev
+
+# 测试自动注册
+node test-auto-register-api.mjs maildrop   # 仅测试 MailDrop
+node test-auto-register-api.mjs mailcx     # 仅测试 mail.cx
+node test-auto-register-api.mjs all        # 测试全部
+```
+
+## 架构
+
+```
+┌──────────────────────────────────────────────────────┐
+│                  MCP 客户端 (Claude)                   │
+│                      │                                │
+│             stdio / Streamable HTTP                    │
+│                      ▼                                │
+│          ┌──────────────────────┐                      │
+│          │  TempMail MCP 服务器  │                      │
+│          │                      │                      │
+│          │  ┌─── 工具 ────────┐ │                      │
+│          │  │ create_mailbox   │ │                      │
+│          │  │ get_messages     │ │                      │
+│          │  │ wait_for_email   │ │                      │
+│          │  │ get_verification  │ │                      │
+│          │  │ auto_register    │ │                      │
+│          │  │ ...              │ │                      │
+│          │  └──────────────────┘ │                      │
+│          └──────────┬───────────┘                      │
+│                     │                                  │
+│          ┌──────────▼───────────┐                      │
+│          │  服务商管理器          │                      │
+│          │  (适配器模式)          │                      │
+│          └──────────┬───────────┘                      │
+│                     │                                  │
+│   ┌────────┬────────┼────────┬──────────┐              │
+│   ▼        ▼        ▼        ▼          ▼              │
+│ Mail.tm  Guerrilla 1secmail  Catchmail  MailDrop        │
+│          Mail                            Mail.cx        │
+└──────────────────────────────────────────────────────┘
+
+自动注册流程（纯 HTTP，无浏览器）：
+  ┌───────────────┐                    ┌───────────────┐
+  │  MailDrop     │                    │  mail.cx       │
+  │               │                    │                │
+  │  RSA 密钥生成  │                    │  mail.tm 临时   │
+  │  ↓            │                    │  邮箱           │
+  │  POST 注册    │                    │  ↓             │
+  │  ↓            │                    │  POST magic    │
+  │  RSA 签名     │                    │  link 请求     │
+  │  ↓            │                    │  ↓             │
+  │  POST 登录    │                    │  轮询等待邮件   │
+  │  ↓            │                    │  ↓             │
+  │  POST 创建    │                    │  POST verify   │
+  │  API Key      │                    │  → API Token  │
+  │  → md_...     │                    │  → tm_live_... │
+  └───────────────┘                    └───────────────┘
+```
+
+## 许可证
+
+MIT

package/dist/base-provider.d.ts

@@ -0,0 +1,21 @@
+import type { TempMailProvider, TempMailbox, EmailMessage, CreateMailboxParams, WaitForEmailOptions } from "./types.js";
+/**
+ * Abstract base class that implements the common waitForEmail polling logic.
+ * Provider adapters extend this and only need to implement the core methods.
+ */
+export declare abstract class BaseProvider implements TempMailProvider {
+    abstract name: string;
+    abstract description: string;
+    abstract requiresApiKey: boolean;
+    abstract getDomains(): Promise<string[]>;
+    abstract createMailbox(params: CreateMailboxParams): Promise<TempMailbox>;
+    abstract getMessages(mailbox: TempMailbox): Promise<EmailMessage[]>;
+    abstract getMessage(mailbox: TempMailbox, messageId: string): Promise<EmailMessage>;
+    deleteMailbox(mailbox: TempMailbox): Promise<void>;
+    /**
+     * Default implementation: poll getMessages until a matching email arrives
+     * or the timeout expires.
+     */
+    waitForEmail(mailbox: TempMailbox, options?: WaitForEmailOptions): Promise<EmailMessage>;
+}
+//# sourceMappingURL=base-provider.d.ts.map

package/dist/base-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.d.ts","sourceRoot":"","sources":["../src/base-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AACH,8BAAsB,YAAa,YAAW,gBAAgB;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IAEjC,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IACzE,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IACnE,QAAQ,CAAC,UAAU,CACjB,OAAO,EAAE,WAAW,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,YAAY,CAAC;IAElB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKxD;;;OAGG;IACG,YAAY,CAChB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,YAAY,CAAC;CA4BzB"}

package/dist/base-provider.js

@@ -0,0 +1,36 @@
+import { sleep, mergeWaitOptions, messageMatches } from "./utils.js";
+/**
+ * Abstract base class that implements the common waitForEmail polling logic.
+ * Provider adapters extend this and only need to implement the core methods.
+ */
+export class BaseProvider {
+    async deleteMailbox(mailbox) {
+        // Default: no-op. Override in subclass if the provider supports deletion.
+        void mailbox;
+    }
+    /**
+     * Default implementation: poll getMessages until a matching email arrives
+     * or the timeout expires.
+     */
+    async waitForEmail(mailbox, options) {
+        const opts = mergeWaitOptions(options);
+        const deadline = Date.now() + opts.timeoutMs;
+        while (Date.now() < deadline) {
+            const messages = await this.getMessages(mailbox);
+            for (const msg of messages) {
+                if (messageMatches(msg, opts.subjectContains, opts.fromContains)) {
+                    // Fetch the full message body
+                    const full = await this.getMessage(mailbox, msg.id);
+                    if (messageMatches(full, opts.subjectContains, opts.fromContains)) {
+                        return full;
+                    }
+                }
+            }
+            await sleep(opts.pollIntervalMs);
+        }
+        throw new Error(`Timed out after ${opts.timeoutMs / 1000}s waiting for email` +
+            (opts.subjectContains ? ` matching subject "${opts.subjectContains}"` : "") +
+            (opts.fromContains ? ` from "${opts.fromContains}"` : ""));
+    }
+}
+//# sourceMappingURL=base-provider.js.map

package/dist/base-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-provider.js","sourceRoot":"","sources":["../src/base-provider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErE;;;GAGG;AACH,MAAM,OAAgB,YAAY;IAahC,KAAK,CAAC,aAAa,CAAC,OAAoB;QACtC,0EAA0E;QAC1E,KAAK,OAAO,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CAChB,OAAoB,EACpB,OAA6B;QAE7B,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAE7C,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAEjD,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;gBAC3B,IAAI,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;oBACjE,8BAA8B;oBAC9B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;oBACpD,IACE,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,YAAY,CAAC,EAC7D,CAAC;wBACD,OAAO,IAAI,CAAC;oBACd,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,CAAC,SAAS,GAAG,IAAI,qBAAqB;YAC3D,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,sBAAsB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAC5D,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}