mails 0.0.8 → 1.0.0

package/dist/index.js

@@ -0,0 +1,411 @@
+// @bun
+// src/core/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_DIR = join(homedir(), ".mails");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+var DEFAULT_CONFIG = {
+  mode: "hosted",
+  domain: "mails.dev",
+  mailbox: "",
+  send_provider: "resend",
+  storage_provider: "sqlite"
+};
+function ensureDir() {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+}
+function loadConfig() {
+  ensureDir();
+  if (!existsSync(CONFIG_FILE)) {
+    return { ...DEFAULT_CONFIG };
+  }
+  const raw = readFileSync(CONFIG_FILE, "utf-8");
+  return { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+}
+function saveConfig(config) {
+  ensureDir();
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + `
+`);
+}
+function getConfigValue(key) {
+  const config = { ...loadConfig() };
+  return config[key];
+}
+function setConfigValue(key, value) {
+  const config = { ...loadConfig() };
+  config[key] = value;
+  saveConfig(config);
+}
+
+// src/providers/send/resend.ts
+function createResendProvider(apiKey) {
+  return {
+    name: "resend",
+    async send(options) {
+      const body = {
+        from: options.from,
+        to: options.to,
+        subject: options.subject
+      };
+      if (options.text)
+        body.text = options.text;
+      if (options.html)
+        body.html = options.html;
+      if (options.replyTo)
+        body.reply_to = options.replyTo;
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) {
+        const err = await res.json();
+        throw new Error(`Resend error: ${err.message}`);
+      }
+      const data = await res.json();
+      return { id: data.id, provider: "resend" };
+    }
+  };
+}
+
+// src/core/send.ts
+function resolveProvider() {
+  const config = loadConfig();
+  switch (config.send_provider) {
+    case "resend": {
+      if (!config.resend_api_key) {
+        throw new Error("resend_api_key not configured. Run: mails config set resend_api_key <key>");
+      }
+      return createResendProvider(config.resend_api_key);
+    }
+    default:
+      throw new Error(`Unknown send provider: ${config.send_provider}`);
+  }
+}
+async function send(options) {
+  const config = loadConfig();
+  const provider = resolveProvider();
+  const from = options.from ?? config.default_from;
+  if (!from) {
+    throw new Error('No "from" address. Set default_from or pass --from');
+  }
+  const to = Array.isArray(options.to) ? options.to : [options.to];
+  if (!options.text && !options.html) {
+    throw new Error("Either text or html body is required");
+  }
+  return provider.send({
+    from,
+    to,
+    subject: options.subject,
+    text: options.text,
+    html: options.html,
+    replyTo: options.replyTo
+  });
+}
+// src/providers/storage/sqlite.ts
+import { Database } from "bun:sqlite";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS emails (
+  id TEXT PRIMARY KEY,
+  mailbox TEXT NOT NULL,
+  from_address TEXT NOT NULL,
+  from_name TEXT DEFAULT '',
+  to_address TEXT NOT NULL,
+  subject TEXT DEFAULT '',
+  body_text TEXT DEFAULT '',
+  body_html TEXT DEFAULT '',
+  code TEXT,
+  headers TEXT DEFAULT '{}',
+  metadata TEXT DEFAULT '{}',
+  direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+  status TEXT DEFAULT 'received' CHECK (status IN ('received', 'sent', 'failed', 'queued')),
+  received_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_emails_mailbox ON emails(mailbox, received_at DESC);
+CREATE INDEX IF NOT EXISTS idx_emails_code ON emails(mailbox) WHERE code IS NOT NULL;
+`;
+function createSqliteProvider(dbPath) {
+  const dir = join2(homedir2(), ".mails");
+  if (!existsSync2(dir))
+    mkdirSync2(dir, { recursive: true });
+  const path = dbPath ?? join2(dir, "mails.db");
+  let db;
+  return {
+    name: "sqlite",
+    async init() {
+      db = new Database(path);
+      db.exec("PRAGMA journal_mode=WAL;");
+      db.exec(SCHEMA);
+    },
+    async saveEmail(email) {
+      db.prepare(`
+        INSERT OR REPLACE INTO emails (id, mailbox, from_address, from_name, to_address, subject, body_text, body_html, code, headers, metadata, direction, status, received_at, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(email.id, email.mailbox, email.from_address, email.from_name, email.to_address, email.subject, email.body_text, email.body_html, email.code, JSON.stringify(email.headers), JSON.stringify(email.metadata), email.direction, email.status, email.received_at, email.created_at);
+    },
+    async getEmails(mailbox, options) {
+      const limit = options?.limit ?? 20;
+      const offset = options?.offset ?? 0;
+      let query = "SELECT * FROM emails WHERE mailbox = ?";
+      const params = [mailbox];
+      if (options?.direction) {
+        query += " AND direction = ?";
+        params.push(options.direction);
+      }
+      query += " ORDER BY received_at DESC LIMIT ? OFFSET ?";
+      params.push(limit, offset);
+      const rows = db.prepare(query).all(...params);
+      return rows.map(rowToEmail);
+    },
+    async getEmail(id) {
+      const row = db.prepare("SELECT * FROM emails WHERE id = ?").get(id);
+      return row ? rowToEmail(row) : null;
+    },
+    async getCode(mailbox, options) {
+      const timeout = (options?.timeout ?? 30) * 1000;
+      const since = options?.since;
+      const deadline = Date.now() + timeout;
+      while (Date.now() < deadline) {
+        let query = "SELECT code, from_address, subject FROM emails WHERE mailbox = ? AND code IS NOT NULL";
+        const params = [mailbox];
+        if (since) {
+          query += " AND received_at > ?";
+          params.push(since);
+        }
+        query += " ORDER BY received_at DESC LIMIT 1";
+        const row = db.prepare(query).get(...params);
+        if (row) {
+          return { code: row.code, from: row.from_address, subject: row.subject };
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+      return null;
+    }
+  };
+}
+function rowToEmail(row) {
+  return {
+    id: row.id,
+    mailbox: row.mailbox,
+    from_address: row.from_address,
+    from_name: row.from_name ?? "",
+    to_address: row.to_address,
+    subject: row.subject ?? "",
+    body_text: row.body_text ?? "",
+    body_html: row.body_html ?? "",
+    code: row.code ?? null,
+    headers: safeJsonParse(row.headers, {}),
+    metadata: safeJsonParse(row.metadata, {}),
+    direction: row.direction,
+    status: row.status,
+    received_at: row.received_at,
+    created_at: row.created_at
+  };
+}
+function safeJsonParse(str, fallback) {
+  if (!str)
+    return fallback;
+  try {
+    return JSON.parse(str);
+  } catch {
+    return fallback;
+  }
+}
+
+// src/providers/storage/db9.ts
+var SCHEMA2 = `
+CREATE TABLE IF NOT EXISTS emails (
+  id TEXT PRIMARY KEY,
+  mailbox TEXT NOT NULL,
+  from_address TEXT NOT NULL,
+  from_name TEXT DEFAULT '',
+  to_address TEXT NOT NULL,
+  subject TEXT DEFAULT '',
+  body_text TEXT DEFAULT '',
+  body_html TEXT DEFAULT '',
+  code TEXT,
+  headers JSONB DEFAULT '{}',
+  metadata JSONB DEFAULT '{}',
+  direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+  status TEXT DEFAULT 'received' CHECK (status IN ('received', 'sent', 'failed', 'queued')),
+  received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_emails_mailbox ON emails(mailbox, received_at DESC);
+CREATE INDEX IF NOT EXISTS idx_emails_code ON emails(mailbox) WHERE code IS NOT NULL;
+`;
+function createDb9Provider(token, databaseId) {
+  const baseUrl = "https://api.db9.ai";
+  async function sql(query) {
+    const res = await fetch(`${baseUrl}/customer/databases/${databaseId}/sql`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ query })
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`db9 error (${res.status}): ${text}`);
+    }
+    return await res.json();
+  }
+  function rowsToEmails(result) {
+    return result.rows.map((row) => {
+      const obj = {};
+      result.columns.forEach((col, i) => {
+        obj[col] = row[i];
+      });
+      return {
+        id: obj.id,
+        mailbox: obj.mailbox,
+        from_address: obj.from_address,
+        from_name: obj.from_name ?? "",
+        to_address: obj.to_address,
+        subject: obj.subject ?? "",
+        body_text: obj.body_text ?? "",
+        body_html: obj.body_html ?? "",
+        code: obj.code ?? null,
+        headers: typeof obj.headers === "string" ? JSON.parse(obj.headers) : obj.headers ?? {},
+        metadata: typeof obj.metadata === "string" ? JSON.parse(obj.metadata) : obj.metadata ?? {},
+        direction: obj.direction,
+        status: obj.status,
+        received_at: obj.received_at,
+        created_at: obj.created_at
+      };
+    });
+  }
+  return {
+    name: "db9",
+    async init() {
+      await sql(SCHEMA2);
+    },
+    async saveEmail(email) {
+      const esc = (s) => s.replace(/'/g, "''");
+      await sql(`
+        INSERT INTO emails (id, mailbox, from_address, from_name, to_address, subject, body_text, body_html, code, headers, metadata, direction, status, received_at, created_at)
+        VALUES (
+          '${esc(email.id)}', '${esc(email.mailbox)}', '${esc(email.from_address)}', '${esc(email.from_name)}',
+          '${esc(email.to_address)}', '${esc(email.subject)}', '${esc(email.body_text)}', '${esc(email.body_html)}',
+          ${email.code ? `'${esc(email.code)}'` : "NULL"},
+          '${esc(JSON.stringify(email.headers))}'::jsonb,
+          '${esc(JSON.stringify(email.metadata))}'::jsonb,
+          '${esc(email.direction)}', '${esc(email.status)}',
+          '${esc(email.received_at)}', '${esc(email.created_at)}'
+        )
+        ON CONFLICT (id) DO UPDATE SET
+          status = EXCLUDED.status,
+          metadata = EXCLUDED.metadata
+      `);
+    },
+    async getEmails(mailbox, options) {
+      const limit = options?.limit ?? 20;
+      const offset = options?.offset ?? 0;
+      const esc = (s) => s.replace(/'/g, "''");
+      let query = `SELECT * FROM emails WHERE mailbox = '${esc(mailbox)}'`;
+      if (options?.direction) {
+        query += ` AND direction = '${esc(options.direction)}'`;
+      }
+      query += ` ORDER BY received_at DESC LIMIT ${limit} OFFSET ${offset}`;
+      const result = await sql(query);
+      return rowsToEmails(result);
+    },
+    async getEmail(id) {
+      const esc = (s) => s.replace(/'/g, "''");
+      const result = await sql(`SELECT * FROM emails WHERE id = '${esc(id)}' LIMIT 1`);
+      const emails = rowsToEmails(result);
+      return emails[0] ?? null;
+    },
+    async getCode(mailbox, options) {
+      const timeout = (options?.timeout ?? 30) * 1000;
+      const since = options?.since;
+      const esc = (s) => s.replace(/'/g, "''");
+      const deadline = Date.now() + timeout;
+      while (Date.now() < deadline) {
+        let query = `SELECT code, from_address, subject FROM emails WHERE mailbox = '${esc(mailbox)}' AND code IS NOT NULL`;
+        if (since) {
+          query += ` AND received_at > '${esc(since)}'`;
+        }
+        query += " ORDER BY received_at DESC LIMIT 1";
+        const result = await sql(query);
+        if (result.row_count > 0) {
+          const row = result.rows[0];
+          const codeIdx = result.columns.indexOf("code");
+          const fromIdx = result.columns.indexOf("from_address");
+          const subIdx = result.columns.indexOf("subject");
+          return {
+            code: row[codeIdx],
+            from: row[fromIdx],
+            subject: row[subIdx]
+          };
+        }
+        await new Promise((r) => setTimeout(r, 2000));
+      }
+      return null;
+    }
+  };
+}
+
+// src/core/storage.ts
+var _provider = null;
+async function getStorage() {
+  if (_provider)
+    return _provider;
+  const config = loadConfig();
+  switch (config.storage_provider) {
+    case "db9": {
+      if (!config.db9_token) {
+        throw new Error("db9_token not configured. Run: mails config set db9_token <token>");
+      }
+      if (!config.db9_database_id) {
+        throw new Error("db9_database_id not configured. Run: mails config set db9_database_id <id>");
+      }
+      _provider = createDb9Provider(config.db9_token, config.db9_database_id);
+      break;
+    }
+    case "sqlite":
+    default: {
+      _provider = createSqliteProvider();
+      break;
+    }
+  }
+  await _provider.init();
+  return _provider;
+}
+
+// src/core/receive.ts
+async function getInbox(mailbox, options) {
+  const storage = await getStorage();
+  return storage.getEmails(mailbox, options);
+}
+async function getEmail(id) {
+  const storage = await getStorage();
+  return storage.getEmail(id);
+}
+async function waitForCode(mailbox, options) {
+  const storage = await getStorage();
+  return storage.getCode(mailbox, options);
+}
+export {
+  waitForCode,
+  setConfigValue,
+  send,
+  saveConfig,
+  loadConfig,
+  getStorage,
+  getInbox,
+  getEmail,
+  getConfigValue,
+  createSqliteProvider,
+  createResendProvider,
+  createDb9Provider
+};

package/package.json

@@ -1,34 +1,47 @@
 {
   "name": "mails",
-  "version": "0.0.8",
-  "description": "send beautiful emails made easy, with sexy templates built in.",
-  "main": "index.js",
-  "author": "turing",
-  "license": "MIT",
-  "bin": "./bin/cli",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+  "version": "1.0.0",
+  "description": "Email infrastructure for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mails": "dist/cli.js"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/turingou/mails.git"
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/cli/index.ts --outfile dist/cli.js --target bun && bun build src/index.ts --outfile dist/index.js --target bun",
+    "build:compile": "bun build src/cli/index.ts --compile --outfile mails",
+    "dev": "bun run src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test test/unit test/e2e/flow.test.ts",
+    "test:coverage": "bun test --coverage test/unit test/e2e/flow.test.ts",
+    "test:live": "bun test test/e2e/live.test.ts",
+    "test:all": "bun test"
   },
+  "files": [
+    "dist",
+    "skill.md"
+  ],
   "keywords": [
+    "email",
     "mail",
-    "mails",
-    "email"
+    "agent",
+    "ai",
+    "resend",
+    "cloudflare",
+    "cli"
   ],
-  "bugs": {
-    "url": "https://github.com/turingou/mails/issues"
-  },
-  "dependencies": {
-    "tao": "0.0.2",
-    "exeq": "~0.4.0",
-    "juice": "~0.4.0",
-    "optimist": "*",
-    "consoler": "*",
-    "mails-default": "*",
-    "nodemailer": "~0.5.7",
-    "pkghub-render": "*"
+  "author": "turing <o.u.turing@gmail.com>",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^5.7.0"
   }
-}
+}

package/skill.md

@@ -0,0 +1,213 @@
+# mails — Email for AI Agents
+
+Send and receive emails programmatically. Supports custom domains (self-hosted) or zero-config `@mails.dev` addresses (hosted).
+
+## Quick Start
+
+```bash
+# Install
+npm install -g mails    # or: bunx mails
+
+# Configure
+mails config set resend_api_key re_YOUR_KEY
+mails config set default_from "Agent <agent@yourdomain.com>"
+
+# Send
+mails send --to user@example.com --subject "Hello" --body "World"
+```
+
+## Configuration
+
+Config lives at `~/.mails/config.json`. Set values via CLI:
+
+```bash
+mails config set <key> <value>
+mails config get <key>
+mails config          # show all
+```
+
+### Required Keys
+
+| Key | Description |
+|-----|-------------|
+| `resend_api_key` | Your Resend API key (get one at resend.com) |
+| `default_from` | Default sender, e.g. `"Agent <agent@yourdomain.com>"` |
+
+### Optional Keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `mode` | `hosted` | `hosted` (use @mails.dev) or `selfhosted` (custom domain) |
+| `domain` | `mails.dev` | Your email domain |
+| `mailbox` | | Your receiving address |
+| `storage_provider` | `sqlite` | `sqlite` (local) or `db9` (db9.ai cloud) |
+| `db9_token` | | db9.ai API token |
+| `db9_database_id` | | db9.ai database ID |
+
+## Sending Emails
+
+### CLI
+
+```bash
+# Plain text
+mails send --to user@example.com --subject "Report" --body "Here is your report."
+
+# HTML
+mails send --to user@example.com --subject "Report" --html "<h1>Report</h1><p>Details...</p>"
+
+# Custom sender
+mails send --from "Bot <bot@mydomain.com>" --to user@example.com --subject "Hi" --body "Hello"
+```
+
+### Programmatic (SDK)
+
+```typescript
+import { send } from 'mails'
+
+const result = await send({
+  to: 'user@example.com',
+  subject: 'Hello from agent',
+  text: 'This is a test email.',
+})
+console.log(result.id) // Resend message ID
+```
+
+### Programmatic (Direct Provider)
+
+```typescript
+import { createResendProvider } from 'mails'
+
+const provider = createResendProvider('re_YOUR_KEY')
+const result = await provider.send({
+  from: 'Agent <agent@yourdomain.com>',
+  to: ['user@example.com'],
+  subject: 'Hello',
+  text: 'Direct provider usage.',
+})
+```
+
+## Receiving Emails
+
+Requires a Cloudflare Email Routing Worker or the mails.dev hosted service. Once configured:
+
+```bash
+# List inbox
+mails inbox
+mails inbox --mailbox agent@yourdomain.com
+
+# Wait for verification code (long-poll)
+mails code --to agent@yourdomain.com --timeout 30
+```
+
+### SDK
+
+```typescript
+import { getInbox, waitForCode } from 'mails'
+
+// List recent emails
+const emails = await getInbox('agent@yourdomain.com', { limit: 10 })
+
+// Wait for a verification code
+const result = await waitForCode('agent@yourdomain.com', { timeout: 30 })
+if (result) {
+  console.log(result.code) // "123456"
+}
+```
+
+## Cloud API (mails.dev)
+
+For agents that need email without local CLI setup. Pay per use with USDC via x402.
+
+```
+Base URL: https://api.mails.dev
+
+POST /v1/send          Send an email ($0.001/email)
+GET  /v1/inbox?to=...  List received emails (free)
+GET  /v1/code?to=...   Wait for verification code (free)
+```
+
+### Send via API
+
+```bash
+curl -X POST https://api.mails.dev/v1/send \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": "agent@mails.dev",
+    "to": ["user@example.com"],
+    "subject": "Hello",
+    "text": "Sent via mails.dev cloud API"
+  }'
+```
+
+If no payment header is present, the API returns HTTP 402 with payment instructions.
+Attach an `X-PAYMENT` header with a signed USDC payment to complete the request.
+
+### Query Inbox
+
+```bash
+# List inbox (free)
+curl "https://api.mails.dev/v1/inbox?to=myagent@mails.dev&limit=10"
+
+# Wait for verification code (free, long-poll up to 55s)
+curl "https://api.mails.dev/v1/code?to=myagent@mails.dev&timeout=30"
+```
+
+## Self-Hosted Setup
+
+For custom domains, run the interactive setup:
+
+```bash
+mails setup
+```
+
+This opens a browser-based wizard at `mails.dev/setup` that guides you through:
+1. Cloudflare API token configuration
+2. DNS record setup (MX, SPF, DKIM, DMARC)
+3. Email Worker deployment
+4. Send provider (Resend) configuration
+5. Storage provider selection
+
+## Storage Providers
+
+### SQLite (default)
+Local database at `~/.mails/mails.db`. Zero config. Good for development and single-agent use.
+
+### db9.ai
+Cloud PostgreSQL for agents. Enables multi-agent access to shared mailboxes.
+
+```bash
+mails config set storage_provider db9
+mails config set db9_token YOUR_TOKEN
+mails config set db9_database_id YOUR_DB_ID
+```
+
+## Email Schema
+
+All storage providers use this schema:
+
+```sql
+CREATE TABLE emails (
+  id TEXT PRIMARY KEY,
+  mailbox TEXT NOT NULL,
+  from_address TEXT NOT NULL,
+  from_name TEXT DEFAULT '',
+  to_address TEXT NOT NULL,
+  subject TEXT DEFAULT '',
+  body_text TEXT DEFAULT '',
+  body_html TEXT DEFAULT '',
+  code TEXT,
+  headers TEXT DEFAULT '{}',
+  metadata TEXT DEFAULT '{}',
+  direction TEXT NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+  status TEXT DEFAULT 'received' CHECK (status IN ('received', 'sent', 'failed', 'queued')),
+  received_at TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX idx_emails_mailbox ON emails(mailbox, received_at DESC);
+```
+
+## Links
+
+- Website: https://mails.dev
+- npm: https://www.npmjs.com/package/mails
+- GitHub: https://github.com/user/mails

package/.npmignore

@@ -1,7 +0,0 @@
-.DS_*
-node_modules
-*.sublime*
-psd
-thumb
-*.log
-demo