mails 0.0.8 → 1.0.0

package/README.ja.md

@@ -0,0 +1,146 @@
+# mails
+
+AIエージェント向けのメールインフラ。プログラムでメールの送受信ができます。
+
+[![npm](https://img.shields.io/npm/v/mails)](https://www.npmjs.com/package/mails)
+[![license](https://img.shields.io/npm/l/mails)](LICENSE)
+
+[English](README.md) | [中文](README.zh.md)
+
+## テストカバレッジ
+
+```
+全ファイル: 100.00% Functions | 100.00% Lines
+ユニットテスト 78件 + ライブ E2E テスト 8件（実際の Resend + Cloudflare Email Routing）
+```
+
+## 特徴
+
+- **メール送信** — Resend経由（他のプロバイダーも追加予定）
+- **メール受信** — Cloudflare Email Routing Worker経由
+- **認証コード自動抽出** — メールから認証コードを自動検出（英語/中国語/日本語/韓国語対応）
+- **ストレージプロバイダー** — ローカルSQLite（デフォルト）または [db9.ai](https://db9.ai) クラウドPostgreSQL
+- **依存関係ゼロ** — Resendプロバイダーは `fetch()` を直接使用、SDKは不要
+- **エージェントファースト** — `skill.md` 統合ガイド付きのAIエージェント向け設計
+- **クラウドサービス** — `@mails.dev` アドレス、x402マイクロペイメント対応（近日公開）
+
+## インストール
+
+```bash
+npm install -g mails
+# または
+bun install -g mails
+# または直接実行
+npx mails
+```
+
+## クイックスタート
+
+```bash
+# 設定
+mails config set resend_api_key re_YOUR_KEY
+mails config set default_from "Agent <agent@yourdomain.com>"
+
+# メール送信
+mails send --to user@example.com --subject "Hello" --body "World"
+```
+
+## CLIリファレンス
+
+### 送信
+
+```bash
+mails send --to <email> --subject <subject> --body <text>
+mails send --to <email> --subject <subject> --html "<h1>Hello</h1>"
+mails send --from "Name <email>" --to <email> --subject <subject> --body <text>
+```
+
+### 受信箱
+
+```bash
+mails inbox                           # 最近のメール一覧
+mails inbox --mailbox agent@test.com  # 特定メールボックス
+mails inbox <id>                      # メール詳細表示
+```
+
+### 認証コード
+
+```bash
+mails code --to agent@test.com              # コード待機（デフォルト30秒）
+mails code --to agent@test.com --timeout 60 # タイムアウト指定
+```
+
+コードは標準出力に出力されるため、パイプで利用可能: `CODE=$(mails code --to agent@test.com)`
+
+### 設定
+
+```bash
+mails config                    # 全設定表示
+mails config set <key> <value>  # 値を設定
+mails config get <key>          # 値を取得
+mails config path               # 設定ファイルのパス表示
+```
+
+## SDK
+
+```typescript
+import { send, getInbox, waitForCode } from 'mails'
+
+// 送信
+const result = await send({
+  to: 'user@example.com',
+  subject: 'Hello',
+  text: 'World',
+})
+
+// 受信箱一覧
+const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
+
+// 認証コード待機
+const code = await waitForCode('agent@yourdomain.com', { timeout: 30 })
+if (code) console.log(code.code) // "123456"
+```
+
+## メールワーカー
+
+`worker/` ディレクトリにCloudflare Email Routing Workerが含まれています。
+
+### セットアップ
+
+```bash
+cd worker
+bun install
+# wrangler.toml を編集 — D1データベースIDを設定
+wrangler d1 create mails
+wrangler d1 execute mails --file=schema.sql
+wrangler deploy
+```
+
+その後、Cloudflare Email Routingでこのワーカーへの転送を設定します。
+
+## ストレージプロバイダー
+
+### SQLite（デフォルト）
+
+`~/.mails/mails.db` のローカルデータベース。設定不要。
+
+### db9.ai
+
+AIエージェント向けクラウドPostgreSQL。
+
+```bash
+mails config set storage_provider db9
+mails config set db9_token YOUR_TOKEN
+mails config set db9_database_id YOUR_DB_ID
+```
+
+## テスト
+
+```bash
+bun test              # 全テスト実行
+bun test --coverage   # カバレッジレポート付き
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,148 +1,196 @@
-## ![logo](http://ww2.sinaimg.cn/large/61ff0de3gw1eajmy0wdikj2014014wea.jpg) mails ![npm](https://badge.fury.io/js/mails.png)
-
-mails 使发送邮件变得更简单与优雅，提高模板复用率。
-
-使用 mails 内建的标准模板 `mails-default` 来发送邮件，或者快速发布自己的邮件主题，mails 推荐您把邮件主题发布到 NPM
-
-mails 内建的标准邮件模板由 [ink](http://zurb.com/ink) 改造而来，对二次开发表现友好，也对各个终端的兼容表现优秀。稍作修改，亦可以适配智能手机等小屏幕终端。
-
-### 如何安装
-````
-$ npm install mails
-````
-
-### 快速指引
-
-mails 包括三个部分：
-
-- 一个邮件模板加载器和发送工具（基于 Nodemailer 的 SMTP 服务）  
-- 一个支持实时编辑（live reload）的邮件模板设计工具（CLI）  
-- 一个快速生成邮件主题项目文件的脚手架工具（CLI）  
-
-如果你是邮件主题开发者，希望分享自己的主题，或者将他们发布到 NPM，你可能会想要使用到第二个与第三个工具；
-如果你只是使用 mails 发送邮件的程序员，并不需要了解后两者如何运作，只需了解API的使用方法即可：
-
-### 范例代码
-最快上手使用 mails，我们来看一段渲染邮件的代码：
-````javascript
-var mails = require('mails'); // 引用 mails
-
-// 使用 mails-default/basic 别名渲染邮件模板，并填入对应的变量:
-mails.render('mails-default/basic', {
-    name: 'The First Email To You',
-    banner: 'http://mysite.com/banner.jpg'
-}, function(err,html){
-    // 得到最终的邮件 html 代码
-    if (err) return console.log(err)
-    console.log(html);
-});
-
-// 如果不需要使用渲染后的片段做其他用途，
-// mails 推荐您直接使用 mails.send 发送邮件。
-mails.send('mails-default/basic', {
-    from: 'xxx <xxx@qq.com>', // 来自您的邮箱
-    to: 'abc@qq.com', // 接受者邮箱
-    subject: 'hi,abc', // 邮件标题
-    // 用做渲染的模板变量
-    name: 'mySite',
-    banner: 'http://mysite.com/banner.jpg',
-    // 用做发送的 smtp 配置
-    host: 'smtp.qq.com',
-    port: 25,
-    use_authentication: true,
-    auth: {
-        user: "xxx@qq.com",
-        pass: 'yourpassword'
-    }
-}, function(err, response) { ...... });
-````
-
-### 加载 NPM 模块作为主题
-你可以将 mails 提供的标准邮件主题进行简单的二次开发，然后发布到 NPM 作为您的邮件主题，使他人获益。
-
-在这个例子中，我们使用 `mails-flat` 模块中的 `message` 主题进行邮件渲染：
-````javascript
-var mails = require('mails');
-
-mails.render('mails-flat/message', { ...... }, function(err, html){
-    console.log(html);
-});
-````
-#### 如何进行主题的二次开发
-
-1. 首先，将 mails 作为全局模块安装：
-
-````
-$ [sudo] npm install mails -g
-````
-
-2. 建立新项目文件夹，初始化邮件主题：
-
-````
-$ mkdir my-mails-theme && cd my-mails-theme
-$ mails init
-````
-
-3. 编辑 `package.json`，这个文件定义了模板引擎的配置，也保存了调试所需要的变量，确保此文件中有正确的 `view engine` 字段：
-
-````
-$ vi ./package.json
-$ { "view engine": "swig" } // 比如使用swig作为模板引擎
-````
-
-4. 使用 live reload 设计工具进行开发
-
-````
-// ./package.json 也是存放模板变量的文件
-$ mails watch ./package.json [-p] [port] 
-````
-使用 mails 提供的 live reload 工具进行开发，程序会监听当前文件夹下文件的变动，包括样式表文件，模板文件和提供模板变量的 json 文件。打开相应的端口服务，指定相应文件的url即可访问，比如：
-````
-$ GET http://localhost:3001/message.html
-````
-
-
-#### 如何发布主题到 NPM
-在使用 `npm publish` 发布到社区之前，确认以下几项：
-- 确保你的项目中 `package.json` 符合 NPM 社区规范
-- 确保 `package.json` 文件中有 `view engine` 字段并且符合邮件模板引擎
-- 确保填写了相应的依赖模块名
-- 建议在 readme.md 中附上一张模板最终渲染效果的截图
-
-### API
-查看这个文件: `index.js`
-
-### 贡献我的代码
-- Fork this repo
-- Clone your repo
-- Install dependencies
-- Checkout a feature branch
-- Feel free to add your features
-- Make sure your features are fully tested
-- Open a pull request, and enjoy <3
-
-### MIT license
-Copyright (c) 2013 turing
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
-
-
----
-![docor](https://cdn1.iconfinder.com/data/icons/windows8_icons_iconpharm/26/doctor.png)
-generated using [docor](https://github.com/turingou/docor.git) @ 0.1.0. brought to you by [turingou](https://github.com/turingou)
+# mails
+
+Email infrastructure for AI agents. Send and receive emails programmatically.
+
+[![npm](https://img.shields.io/npm/v/mails)](https://www.npmjs.com/package/mails)
+[![license](https://img.shields.io/npm/l/mails)](LICENSE)
+
+[日本語](README.ja.md) | [中文](README.zh.md)
+
+## Test Coverage
+
+```
+---------------------------------|---------|---------|
+File                             | % Funcs | % Lines |
+---------------------------------|---------|---------|
+All files                        |  100.00 |  100.00 |
+ src/cli/commands/help.ts        |  100.00 |  100.00 |
+ src/core/config.ts              |  100.00 |  100.00 |
+ src/core/send.ts                |  100.00 |  100.00 |
+ src/core/types.ts               |  100.00 |  100.00 |
+ src/providers/send/resend.ts    |  100.00 |  100.00 |
+ src/providers/storage/db9.ts    |  100.00 |  100.00 |
+ src/providers/storage/sqlite.ts |  100.00 |  100.00 |
+ worker/src/extract-code.ts      |  100.00 |  100.00 |
+---------------------------------|---------|---------|
+
+78 unit tests + 8 live E2E tests (real Resend + Cloudflare Email Routing)
+```
+
+## Features
+
+- **Send emails** via Resend (more providers coming)
+- **Receive emails** via Cloudflare Email Routing Worker
+- **Verification code extraction** — auto-extracts codes from emails (EN/ZH/JA/KO)
+- **Storage providers** — local SQLite (default) or [db9.ai](https://db9.ai) cloud PostgreSQL
+- **Zero dependencies** — Resend provider uses raw `fetch()`, no SDK needed
+- **Agent-first** — designed for AI agents with `skill.md` integration guide
+- **Cloud service** — `@mails.dev` addresses with x402 micropayments (coming soon)
+
+## Install
+
+```bash
+npm install -g mails
+# or
+bun install -g mails
+# or use directly
+npx mails
+```
+
+## Quick Start
+
+```bash
+# Configure
+mails config set resend_api_key re_YOUR_KEY
+mails config set default_from "Agent <agent@yourdomain.com>"
+
+# Send an email
+mails send --to user@example.com --subject "Hello" --body "World"
+```
+
+## CLI Reference
+
+### Send
+
+```bash
+mails send --to <email> --subject <subject> --body <text>
+mails send --to <email> --subject <subject> --html "<h1>Hello</h1>"
+mails send --from "Name <email>" --to <email> --subject <subject> --body <text>
+```
+
+### Inbox
+
+```bash
+mails inbox                           # List recent emails
+mails inbox --mailbox agent@test.com  # Specific mailbox
+mails inbox <id>                      # View email details
+```
+
+### Verification Code
+
+```bash
+mails code --to agent@test.com              # Wait for code (default 30s)
+mails code --to agent@test.com --timeout 60 # Custom timeout
+```
+
+The code is printed to stdout for easy piping: `CODE=$(mails code --to agent@test.com)`
+
+### Config
+
+```bash
+mails config                    # Show all config
+mails config set <key> <value>  # Set a value
+mails config get <key>          # Get a value
+mails config path               # Show config file path
+```
+
+## SDK Usage
+
+```typescript
+import { send, getInbox, waitForCode } from 'mails'
+
+// Send
+const result = await send({
+  to: 'user@example.com',
+  subject: 'Hello',
+  text: 'World',
+})
+
+// List inbox
+const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
+
+// Wait for verification code
+const code = await waitForCode('agent@yourdomain.com', { timeout: 30 })
+if (code) console.log(code.code) // "123456"
+```
+
+### Direct Provider Usage
+
+```typescript
+import { createResendProvider } from 'mails'
+
+const resend = createResendProvider('re_YOUR_KEY')
+await resend.send({
+  from: 'Agent <agent@yourdomain.com>',
+  to: ['user@example.com'],
+  subject: 'Hello',
+  text: 'Direct provider usage',
+})
+```
+
+## Email Worker
+
+The `worker/` directory contains a Cloudflare Email Routing Worker for receiving emails.
+
+### Setup
+
+```bash
+cd worker
+bun install
+# Edit wrangler.toml — set your D1 database ID
+wrangler d1 create mails
+wrangler d1 execute mails --file=schema.sql
+wrangler deploy
+```
+
+Then configure Cloudflare Email Routing to forward to this worker.
+
+### Worker API
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/inbox?to=<addr>&limit=20` | List emails |
+| `GET /api/code?to=<addr>&timeout=30` | Long-poll for verification code |
+| `GET /api/email?id=<id>` | Get email by ID |
+| `GET /health` | Health check |
+
+## Storage Providers
+
+### SQLite (default)
+
+Local database at `~/.mails/mails.db`. Zero config.
+
+### db9.ai
+
+Cloud PostgreSQL for AI agents.
+
+```bash
+mails config set storage_provider db9
+mails config set db9_token YOUR_TOKEN
+mails config set db9_database_id YOUR_DB_ID
+```
+
+## Config Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `mode` | `hosted` | `hosted` or `selfhosted` |
+| `domain` | `mails.dev` | Email domain |
+| `mailbox` | | Your receiving address |
+| `send_provider` | `resend` | Send provider |
+| `storage_provider` | `sqlite` | `sqlite` or `db9` |
+| `resend_api_key` | | Resend API key |
+| `default_from` | | Default sender address |
+| `db9_token` | | db9.ai API token |
+| `db9_database_id` | | db9.ai database ID |
+
+## Testing
+
+```bash
+bun test              # Run all tests
+bun test --coverage   # With coverage report
+```
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,160 @@
+# mails
+
+面向 AI Agent 的邮件基础设施。通过编程方式收发邮件。
+
+[![npm](https://img.shields.io/npm/v/mails)](https://www.npmjs.com/package/mails)
+[![license](https://img.shields.io/npm/l/mails)](LICENSE)
+
+[English](README.md) | [日本語](README.ja.md)
+
+## 测试覆盖率
+
+```
+全部文件: 100.00% Functions | 100.00% Lines
+78 个单元测试 + 8 个 Live E2E 测试（真实 Resend + Cloudflare Email Routing）
+```
+
+## 特性
+
+- **发送邮件** — 通过 Resend（更多 Provider 即将支持）
+- **接收邮件** — 通过 Cloudflare Email Routing Worker
+- **验证码自动提取** — 自动从邮件中提取验证码（支持中/英/日/韩）
+- **存储 Provider** — 本地 SQLite（默认）或 [db9.ai](https://db9.ai) 云端 PostgreSQL
+- **零依赖** — Resend Provider 直接使用 `fetch()`，无需 SDK
+- **Agent 优先** — 为 AI Agent 设计，附带 `skill.md` 接入指南
+- **云服务** — `@mails.dev` 邮箱地址，x402 微支付（即将上线）
+
+## 安装
+
+```bash
+npm install -g mails
+# 或
+bun install -g mails
+# 或直接使用
+npx mails
+```
+
+## 快速开始
+
+```bash
+# 配置
+mails config set resend_api_key re_YOUR_KEY
+mails config set default_from "Agent <agent@yourdomain.com>"
+
+# 发送邮件
+mails send --to user@example.com --subject "Hello" --body "World"
+```
+
+## CLI 参考
+
+### 发送
+
+```bash
+mails send --to <email> --subject <subject> --body <text>
+mails send --to <email> --subject <subject> --html "<h1>Hello</h1>"
+mails send --from "Name <email>" --to <email> --subject <subject> --body <text>
+```
+
+### 收件箱
+
+```bash
+mails inbox                           # 最近邮件列表
+mails inbox --mailbox agent@test.com  # 指定邮箱
+mails inbox <id>                      # 查看邮件详情
+```
+
+### 验证码
+
+```bash
+mails code --to agent@test.com              # 等待验证码（默认 30 秒）
+mails code --to agent@test.com --timeout 60 # 自定义超时
+```
+
+验证码输出到 stdout，方便管道使用：`CODE=$(mails code --to agent@test.com)`
+
+### 配置
+
+```bash
+mails config                    # 显示所有配置
+mails config set <key> <value>  # 设置值
+mails config get <key>          # 获取值
+mails config path               # 显示配置文件路径
+```
+
+## SDK 用法
+
+```typescript
+import { send, getInbox, waitForCode } from 'mails'
+
+// 发送
+const result = await send({
+  to: 'user@example.com',
+  subject: 'Hello',
+  text: 'World',
+})
+
+// 收件箱列表
+const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
+
+// 等待验证码
+const code = await waitForCode('agent@yourdomain.com', { timeout: 30 })
+if (code) console.log(code.code) // "123456"
+```
+
+## 邮件 Worker
+
+`worker/` 目录包含 Cloudflare Email Routing Worker，用于接收邮件。
+
+### 部署
+
+```bash
+cd worker
+bun install
+# 编辑 wrangler.toml — 设置你的 D1 数据库 ID
+wrangler d1 create mails
+wrangler d1 execute mails --file=schema.sql
+wrangler deploy
+```
+
+然后在 Cloudflare Email Routing 中配置转发到此 Worker。
+
+## 存储 Provider
+
+### SQLite（默认）
+
+本地数据库 `~/.mails/mails.db`，无需配置。
+
+### db9.ai
+
+面向 AI Agent 的云端 PostgreSQL。
+
+```bash
+mails config set storage_provider db9
+mails config set db9_token YOUR_TOKEN
+mails config set db9_database_id YOUR_DB_ID
+```
+
+## 配置项
+
+| 键 | 默认值 | 说明 |
+|---|--------|------|
+| `mode` | `hosted` | `hosted` 或 `selfhosted` |
+| `domain` | `mails.dev` | 邮件域名 |
+| `mailbox` | | 接收邮箱地址 |
+| `send_provider` | `resend` | 发送 Provider |
+| `storage_provider` | `sqlite` | `sqlite` 或 `db9` |
+| `resend_api_key` | | Resend API 密钥 |
+| `default_from` | | 默认发件人地址 |
+| `db9_token` | | db9.ai API Token |
+| `db9_database_id` | | db9.ai 数据库 ID |
+
+## 测试
+
+```bash
+bun test              # 运行所有测试
+bun test --coverage   # 带覆盖率报告
+```
+
+## 许可证
+
+MIT