@zaddy6/agentemail 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaac David
+
+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.

package/README.md

@@ -0,0 +1,106 @@
+# agent-email
+
+`agent-email` is a Bun CLI for AI agents that need access to a disposable email inbox powered by [Mail.tm](https://mail.tm).
+
+## Open Source
+
+This project is open source under the [MIT License](./LICENSE).
+
+Community docs:
+
+- [Contributing](./CONTRIBUTING.md)
+- [Code of Conduct](./CODE_OF_CONDUCT.md)
+- [Security Policy](./SECURITY.md)
+
+## Install
+
+```bash
+npm install -g @zaddy6/agentemail
+# or
+bun install -g @zaddy6/agentemail
+```
+
+## Quick Start
+
+Create an inbox with one command (no flags):
+
+```bash
+agent-email create
+```
+
+Read latest emails:
+
+```bash
+agent-email read <email>
+```
+
+All commands return JSON by default.
+
+## Commands
+
+- `agent-email create`
+- `agent-email read <email|alias> [--limit <n>] [--full] [--wait <seconds>] [--interval <seconds>]`
+- `agent-email show <email|alias> <messageId>`
+- `agent-email delete <email|alias> <messageId>`
+- `agent-email accounts list`
+- `agent-email accounts add <email> --password <pwd> [--set-default]`
+- `agent-email accounts remove <email|alias>`
+- `agent-email use <email|alias>`
+- `agent-email config path`
+- `agent-email about`
+
+Aliases for account selection:
+
+- `default`
+- `active`
+- `me`
+
+Use human-readable output if needed:
+
+```bash
+agent-email --human accounts list
+```
+
+## Config
+
+Credentials are stored in:
+
+- `~/.config/agent-email/config.json`
+
+Override path with:
+
+- `AGENT_EMAIL_CONFIG=/custom/path/config.json`
+
+The tool enforces `0600` permissions for the config file on Unix.
+
+## Development
+
+```bash
+bun install
+bun run check
+```
+
+Run live Mail.tm smoke test (opt-in):
+
+```bash
+AGENT_EMAIL_LIVE_TESTS=1 bun run test:live
+```
+
+## API and Attribution
+
+This project uses [Mail.tm API](https://api.mail.tm). If you use the API, follow Mail.tm terms and attribution requirements.
+
+## Release / Publish
+
+Local publish flow:
+
+```bash
+bun run check
+npm login
+npm publish --access public
+```
+
+GitHub Actions workflows are included for CI and release publishing:
+
+- `.github/workflows/ci.yml`
+- `.github/workflows/publish.yml` (requires `NPM_TOKEN` repository secret)

package/bin/agent-email.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import("../dist/cli.js")
+  .then(async (mod) => {
+    await mod.main(process.argv);
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  });

package/dist/auth.js

@@ -0,0 +1,64 @@
+import { toCliError } from "./output.js";
+import { CliError } from "./types.js";
+export function resolveAccountIdentifier(config, identifier) {
+    const normalized = identifier.trim().toLowerCase();
+    if (["default", "active", "me"].includes(normalized)) {
+        if (!config.activeEmail) {
+            throw new CliError({
+                code: "NO_ACTIVE_ACCOUNT",
+                message: "No active account is configured.",
+                hint: "Create an account or run `agent-email use <email>`.",
+            });
+        }
+        return config.activeEmail;
+    }
+    if (config.accounts[identifier]) {
+        return identifier;
+    }
+    throw new CliError({
+        code: "ACCOUNT_NOT_FOUND",
+        message: `Account '${identifier}' is not configured.`,
+        hint: "Run `agent-email accounts list` to inspect known inboxes.",
+    });
+}
+export async function withAccountSession(store, client, identifier, fn) {
+    const config = await store.load();
+    const accountEmail = resolveAccountIdentifier(config, identifier);
+    const configuredAccount = config.accounts[accountEmail];
+    if (!configuredAccount) {
+        throw new CliError({
+            code: "ACCOUNT_NOT_FOUND",
+            message: `Account '${accountEmail}' is not configured.`,
+        });
+    }
+    let account = configuredAccount;
+    const refreshToken = async () => {
+        const tokenResp = await client.createToken(account.email, account.password);
+        account = {
+            ...account,
+            token: tokenResp.token,
+            tokenUpdatedAt: new Date().toISOString(),
+            accountId: tokenResp.id || account.accountId,
+        };
+        config.accounts[accountEmail] = account;
+        await store.save(config);
+    };
+    const session = {
+        accountEmail,
+        getAccount: () => account,
+        run: async (request) => {
+            try {
+                return await request(account.token);
+            }
+            catch (error) {
+                const cliError = toCliError(error);
+                if (cliError.status !== 401) {
+                    throw cliError;
+                }
+                await refreshToken();
+                return request(account.token);
+            }
+        },
+    };
+    return fn(session);
+}

package/dist/cli.js

@@ -0,0 +1,144 @@
+import { Command } from "commander";
+import { ConfigStore } from "./config-store.js";
+import { handleAccountsAdd, handleAccountsList, handleAccountsRemove, handleUse, } from "./commands/accounts.js";
+import { handleCreate } from "./commands/create.js";
+import { handleDelete } from "./commands/delete.js";
+import { handleAbout, handleConfigPath } from "./commands/meta.js";
+import { handleRead } from "./commands/read.js";
+import { handleShow } from "./commands/show.js";
+import { MailTmClient } from "./mailtm-client.js";
+import { runCommand } from "./runner.js";
+function parsePositiveInt(value, optionName) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${optionName} must be a positive number.`);
+    }
+    return Math.floor(parsed);
+}
+async function buildContext(cmd) {
+    const opts = cmd.optsWithGlobals();
+    const store = new ConfigStore();
+    const cfg = await store.load();
+    return {
+        format: opts.human ? "human" : "json",
+        store,
+        client: new MailTmClient(cfg.apiBaseUrl),
+    };
+}
+function getActionCommand(args) {
+    const cmd = args.at(-1);
+    if (!cmd || typeof cmd.optsWithGlobals !== "function") {
+        throw new Error("Failed to resolve command context.");
+    }
+    return cmd;
+}
+export async function main(argv = process.argv) {
+    const program = new Command();
+    program
+        .name("agent-email")
+        .description("Disposable inbox CLI for AI agents (Mail.tm)")
+        .version("0.1.0")
+        .option("--human", "Print human-readable output instead of JSON")
+        .showHelpAfterError();
+    program
+        .command("create")
+        .description("Create a new random inbox and persist credentials")
+        .action(async (...args) => {
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("create", ctx.format, async () => handleCreate(ctx));
+    });
+    program
+        .command("read")
+        .description("Read latest emails from an inbox")
+        .argument("<emailOrAlias>", "Email address or alias (default|active|me)")
+        .option("--limit <n>", "Max messages to return (default 10)", (v) => parsePositiveInt(v, "--limit"))
+        .option("--full", "Fetch full message payloads")
+        .option("--wait <seconds>", "Poll until a message arrives or timeout", (v) => parsePositiveInt(v, "--wait"))
+        .option("--interval <seconds>", "Polling interval in seconds (default 2)", (v) => parsePositiveInt(v, "--interval"))
+        .action(async (...args) => {
+        const [emailOrAlias, options] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("read", ctx.format, async () => handleRead(ctx, emailOrAlias, {
+            limit: options.limit,
+            full: options.full,
+            waitSeconds: options.wait,
+            intervalSeconds: options.interval,
+        }));
+    });
+    program
+        .command("show")
+        .description("Show a single message")
+        .argument("<emailOrAlias>", "Email address or alias")
+        .argument("<messageId>", "Message id")
+        .action(async (...args) => {
+        const [emailOrAlias, messageId] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("show", ctx.format, async () => handleShow(ctx, emailOrAlias, messageId));
+    });
+    program
+        .command("delete")
+        .description("Delete a message")
+        .argument("<emailOrAlias>", "Email address or alias")
+        .argument("<messageId>", "Message id")
+        .action(async (...args) => {
+        const [emailOrAlias, messageId] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("delete", ctx.format, async () => handleDelete(ctx, emailOrAlias, messageId));
+    });
+    const accounts = program.command("accounts").description("Manage locally stored accounts");
+    accounts
+        .command("list")
+        .description("List configured accounts")
+        .action(async (...args) => {
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("accounts list", ctx.format, async () => handleAccountsList(ctx));
+    });
+    accounts
+        .command("add")
+        .description("Add an existing mailbox credentials")
+        .argument("<email>", "Email address")
+        .requiredOption("--password <password>", "Mailbox password")
+        .option("--set-default", "Set account as active default")
+        .action(async (...args) => {
+        const [email, options] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("accounts add", ctx.format, async () => handleAccountsAdd(ctx, email, options.password, Boolean(options.setDefault)));
+    });
+    accounts
+        .command("remove")
+        .description("Remove a local account profile")
+        .argument("<emailOrAlias>", "Email address or alias")
+        .action(async (...args) => {
+        const [emailOrAlias] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("accounts remove", ctx.format, async () => handleAccountsRemove(ctx, emailOrAlias));
+    });
+    program
+        .command("use")
+        .description("Set the active default account")
+        .argument("<emailOrAlias>", "Email address or alias")
+        .action(async (...args) => {
+        const [emailOrAlias] = args;
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("use", ctx.format, async () => handleUse(ctx, emailOrAlias));
+    });
+    const config = program.command("config").description("Configuration helpers");
+    config
+        .command("path")
+        .description("Show config file path")
+        .action(async (...args) => {
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("config path", ctx.format, async () => handleConfigPath(ctx));
+    });
+    program
+        .command("about")
+        .description("Show project info and attribution")
+        .action(async (...args) => {
+        const ctx = await buildContext(getActionCommand(args));
+        await runCommand("about", ctx.format, async () => handleAbout(ctx));
+    });
+    await program.parseAsync(argv);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    void main();
+}

package/dist/commands/accounts.js

@@ -0,0 +1,74 @@
+import { resolveAccountIdentifier } from "../auth.js";
+export async function handleAccountsList(ctx) {
+    const cfg = await ctx.store.load();
+    const emails = Object.keys(cfg.accounts).sort();
+    return {
+        activeEmail: cfg.activeEmail,
+        total: emails.length,
+        accounts: emails.map((email) => {
+            const acct = cfg.accounts[email];
+            return {
+                email,
+                accountId: acct.accountId,
+                createdAt: acct.createdAt,
+                tokenUpdatedAt: acct.tokenUpdatedAt,
+                isActive: cfg.activeEmail === email,
+            };
+        }),
+    };
+}
+export async function handleAccountsAdd(ctx, email, password, setDefault) {
+    const tokenResp = await ctx.client.createToken(email, password);
+    const now = new Date().toISOString();
+    let accountId = tokenResp.id;
+    try {
+        const me = await ctx.client.getMe(tokenResp.token);
+        accountId = me.id || accountId;
+    }
+    catch {
+        // Keep the ID from /token if /me is unavailable.
+    }
+    const cfg = await ctx.store.update((config) => {
+        const existing = config.accounts[email];
+        config.accounts[email] = {
+            email,
+            password,
+            token: tokenResp.token,
+            tokenUpdatedAt: now,
+            accountId,
+            createdAt: existing?.createdAt ?? now,
+        };
+        if (setDefault || !config.activeEmail) {
+            config.activeEmail = email;
+        }
+    });
+    return {
+        email,
+        accountId,
+        activeEmail: cfg.activeEmail,
+        added: true,
+    };
+}
+export async function handleAccountsRemove(ctx, identifier) {
+    const cfg = await ctx.store.load();
+    const email = resolveAccountIdentifier(cfg, identifier);
+    delete cfg.accounts[email];
+    if (cfg.activeEmail === email) {
+        const next = Object.keys(cfg.accounts)[0] ?? null;
+        cfg.activeEmail = next;
+    }
+    await ctx.store.save(cfg);
+    return {
+        removed: email,
+        activeEmail: cfg.activeEmail,
+    };
+}
+export async function handleUse(ctx, identifier) {
+    const cfg = await ctx.store.load();
+    const email = resolveAccountIdentifier(cfg, identifier);
+    cfg.activeEmail = email;
+    await ctx.store.save(cfg);
+    return {
+        activeEmail: email,
+    };
+}

package/dist/commands/create.js

@@ -0,0 +1,61 @@
+import { CliError } from "../types.js";
+import { generatePassword24, generateRandomLocalPart } from "../utils.js";
+const MAX_CREATE_RETRIES = 5;
+export async function handleCreate(ctx) {
+    const domains = await ctx.client.getDomains();
+    const selected = domains["hydra:member"].find((domain) => domain.isActive && !domain.isPrivate);
+    if (!selected) {
+        throw new CliError({
+            code: "NO_ACTIVE_DOMAIN",
+            message: "No active public Mail.tm domain is available.",
+            hint: "Retry later when a domain is available.",
+        });
+    }
+    const password = generatePassword24();
+    let createdEmail = "";
+    let accountId = "";
+    let token = "";
+    for (let attempt = 0; attempt < MAX_CREATE_RETRIES; attempt += 1) {
+        const address = `${generateRandomLocalPart()}@${selected.domain}`;
+        try {
+            const accountResp = await ctx.client.createAccount(address, password);
+            const tokenResp = await ctx.client.createToken(address, password);
+            createdEmail = address;
+            accountId = tokenResp.id || accountResp.id;
+            token = tokenResp.token;
+            break;
+        }
+        catch (error) {
+            if (error instanceof CliError && error.status === 422 && attempt < MAX_CREATE_RETRIES - 1) {
+                continue;
+            }
+            throw error;
+        }
+    }
+    if (!createdEmail || !accountId || !token) {
+        throw new CliError({
+            code: "ACCOUNT_CREATION_FAILED",
+            message: "Failed to create an account after multiple attempts.",
+        });
+    }
+    const now = new Date().toISOString();
+    const cfg = await ctx.store.update((config) => {
+        config.accounts[createdEmail] = {
+            email: createdEmail,
+            password,
+            token,
+            tokenUpdatedAt: now,
+            accountId,
+            createdAt: now,
+        };
+        if (!config.activeEmail) {
+            config.activeEmail = createdEmail;
+        }
+    });
+    return {
+        email: createdEmail,
+        password,
+        accountId,
+        activeEmail: cfg.activeEmail,
+    };
+}

package/dist/commands/delete.js

@@ -0,0 +1,11 @@
+import { withAccountSession } from "../auth.js";
+export async function handleDelete(ctx, identifier, messageId) {
+    return withAccountSession(ctx.store, ctx.client, identifier, async (session) => {
+        await session.run((token) => ctx.client.deleteMessage(token, messageId));
+        return {
+            email: session.getAccount().email,
+            deleted: true,
+            messageId,
+        };
+    });
+}

package/dist/commands/meta.js

@@ -0,0 +1,12 @@
+export async function handleConfigPath(ctx) {
+    return { path: ctx.store.path };
+}
+export async function handleAbout(_) {
+    return {
+        name: "agent-email",
+        description: "CLI for disposable Mail.tm inboxes designed for AI agents.",
+        api: "https://api.mail.tm",
+        attribution: "Powered by Mail.tm. Include attribution when integrating this API.",
+        docs: "https://docs.mail.tm",
+    };
+}

package/dist/commands/read.js

@@ -0,0 +1,33 @@
+import { withAccountSession } from "../auth.js";
+import { clamp, sleep } from "../utils.js";
+export async function handleRead(ctx, identifier, options) {
+    const limit = clamp(options.limit ?? 10, 1, 30);
+    const full = options.full ?? false;
+    const waitSeconds = Math.max(0, options.waitSeconds ?? 0);
+    const intervalSeconds = Math.max(1, options.intervalSeconds ?? 2);
+    return withAccountSession(ctx.store, ctx.client, identifier, async (session) => {
+        const started = Date.now();
+        const deadline = started + waitSeconds * 1000;
+        let summaries = [];
+        do {
+            const list = await session.run((token) => ctx.client.listMessages(token, 1));
+            summaries = list["hydra:member"].slice(0, limit);
+            if (summaries.length > 0 || waitSeconds === 0 || Date.now() >= deadline) {
+                break;
+            }
+            await sleep(intervalSeconds * 1000);
+        } while (true);
+        let messages = summaries;
+        if (full) {
+            messages = await Promise.all(summaries.map((summary) => session.run((token) => ctx.client.getMessage(token, summary.id))));
+        }
+        const waitedSecondsActual = Math.round((Date.now() - started) / 100) / 10;
+        return {
+            email: session.getAccount().email,
+            count: messages.length,
+            timedOut: messages.length === 0 && waitSeconds > 0,
+            waitedSeconds: waitedSecondsActual,
+            messages,
+        };
+    });
+}

package/dist/commands/show.js

@@ -0,0 +1,29 @@
+import { withAccountSession } from "../auth.js";
+import { extractResourceId } from "../utils.js";
+export async function handleShow(ctx, identifier, messageId) {
+    return withAccountSession(ctx.store, ctx.client, identifier, async (session) => {
+        const message = await session.run((token) => ctx.client.getMessage(token, messageId));
+        let markedSeen = false;
+        if (!message.seen) {
+            await session.run((token) => ctx.client.patchMessageSeen(token, messageId, true));
+            message.seen = true;
+            markedSeen = true;
+        }
+        const sourceId = extractResourceId(message.sourceUrl, "sources");
+        let source;
+        if (sourceId) {
+            try {
+                source = await session.run((token) => ctx.client.getSource(token, sourceId));
+            }
+            catch {
+                source = undefined;
+            }
+        }
+        return {
+            email: session.getAccount().email,
+            message,
+            markedSeen,
+            source,
+        };
+    });
+}

package/dist/config-store.js

@@ -0,0 +1,142 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CliError } from "./types.js";
+export const DEFAULT_API_BASE_URL = "https://api.mail.tm";
+function defaultConfig() {
+    return {
+        version: 1,
+        apiBaseUrl: DEFAULT_API_BASE_URL,
+        activeEmail: null,
+        accounts: {},
+    };
+}
+export function resolveConfigPath(explicitPath) {
+    if (explicitPath) {
+        return explicitPath;
+    }
+    if (process.env.AGENT_EMAIL_CONFIG) {
+        return process.env.AGENT_EMAIL_CONFIG;
+    }
+    return path.join(os.homedir(), ".config", "agent-email", "config.json");
+}
+function isStoredAccount(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const v = value;
+    return (typeof v.email === "string" &&
+        typeof v.password === "string" &&
+        typeof v.token === "string" &&
+        typeof v.tokenUpdatedAt === "string" &&
+        typeof v.accountId === "string" &&
+        typeof v.createdAt === "string");
+}
+function validateConfig(parsed) {
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new CliError({
+            code: "CONFIG_INVALID",
+            message: "Config file is not a JSON object.",
+            hint: "Delete the file or fix its structure.",
+            exitCode: 2,
+        });
+    }
+    const cfg = parsed;
+    if (cfg.version !== 1) {
+        throw new CliError({
+            code: "CONFIG_VERSION_UNSUPPORTED",
+            message: "Config version is unsupported.",
+            hint: "Delete the config file and run `agent-email create` again.",
+            exitCode: 2,
+        });
+    }
+    if (typeof cfg.apiBaseUrl !== "string") {
+        throw new CliError({
+            code: "CONFIG_INVALID",
+            message: "Config is missing `apiBaseUrl`.",
+            exitCode: 2,
+        });
+    }
+    if (!(cfg.activeEmail === null || typeof cfg.activeEmail === "string")) {
+        throw new CliError({
+            code: "CONFIG_INVALID",
+            message: "Config has invalid `activeEmail`.",
+            exitCode: 2,
+        });
+    }
+    if (typeof cfg.accounts !== "object" || cfg.accounts === null) {
+        throw new CliError({
+            code: "CONFIG_INVALID",
+            message: "Config has invalid `accounts` map.",
+            exitCode: 2,
+        });
+    }
+    for (const [email, account] of Object.entries(cfg.accounts)) {
+        if (!isStoredAccount(account) || account.email !== email) {
+            throw new CliError({
+                code: "CONFIG_INVALID_ACCOUNT",
+                message: `Config account entry for ${email} is invalid.`,
+                exitCode: 2,
+            });
+        }
+    }
+    return cfg;
+}
+async function ensurePermission0600(filePath) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const stat = await fs.stat(filePath);
+    if ((stat.mode & 0o077) !== 0) {
+        throw new CliError({
+            code: "CONFIG_PERMISSIONS",
+            message: "Config file permissions are too open.",
+            hint: `Run: chmod 600 ${filePath}`,
+            exitCode: 2,
+        });
+    }
+}
+export class ConfigStore {
+    path;
+    constructor(explicitPath) {
+        this.path = resolveConfigPath(explicitPath);
+    }
+    async load() {
+        try {
+            const raw = await fs.readFile(this.path, "utf8");
+            await ensurePermission0600(this.path);
+            const parsed = JSON.parse(raw);
+            return validateConfig(parsed);
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return defaultConfig();
+            }
+            if (error instanceof SyntaxError) {
+                throw new CliError({
+                    code: "CONFIG_PARSE_ERROR",
+                    message: "Failed to parse config JSON.",
+                    hint: "Fix the JSON format or delete the file and recreate it.",
+                    exitCode: 2,
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    async save(config) {
+        const dir = path.dirname(this.path);
+        await fs.mkdir(dir, { recursive: true });
+        const payload = `${JSON.stringify(config, null, 2)}\n`;
+        await fs.writeFile(this.path, payload, { mode: 0o600 });
+        if (process.platform !== "win32") {
+            await fs.chmod(this.path, 0o600);
+        }
+    }
+    async update(mutator) {
+        const cfg = await this.load();
+        mutator(cfg);
+        await this.save(cfg);
+        return cfg;
+    }
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/mailtm-client.js

@@ -0,0 +1,203 @@
+import { DEFAULT_API_BASE_URL } from "./config-store.js";
+import { CliError, } from "./types.js";
+import { sleep } from "./utils.js";
+function statusHint(status) {
+    if (status === 401) {
+        return "Credentials may be stale. Re-authenticate the mailbox account.";
+    }
+    if (status === 404) {
+        return "The requested resource does not exist.";
+    }
+    if (status === 422) {
+        return "Check payload fields (address, domain, or message id).";
+    }
+    if (status === 429) {
+        return "Rate limit exceeded. Retry shortly.";
+    }
+    return undefined;
+}
+function statusCode(status) {
+    if (status === 401) {
+        return "AUTH_REQUIRED";
+    }
+    if (status === 404) {
+        return "RESOURCE_NOT_FOUND";
+    }
+    if (status === 422) {
+        return "VALIDATION_ERROR";
+    }
+    if (status === 429) {
+        return "RATE_LIMITED";
+    }
+    return "API_ERROR";
+}
+export class MailTmClient {
+    fetchLike;
+    baseUrl;
+    constructor(baseUrl = DEFAULT_API_BASE_URL, fetchLike = fetch) {
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.fetchLike = fetchLike;
+    }
+    async getDomains() {
+        const payload = await this.requestJson("/domains");
+        return this.normalizeCollection(payload, "domains");
+    }
+    async createAccount(address, password) {
+        return this.requestJson("/accounts", {
+            method: "POST",
+            body: { address, password },
+        });
+    }
+    async createToken(address, password) {
+        return this.requestJson("/token", {
+            method: "POST",
+            body: { address, password },
+        });
+    }
+    async getMe(token) {
+        return this.requestJson("/me", { token });
+    }
+    async listMessages(token, page = 1) {
+        const payload = await this.requestJson(`/messages?page=${page}`, { token });
+        return this.normalizeCollection(payload, "messages");
+    }
+    async getMessage(token, id) {
+        return this.requestJson(`/messages/${id}`, { token });
+    }
+    async patchMessageSeen(token, id, seen = true) {
+        return this.requestJson(`/messages/${id}`, {
+            token,
+            method: "PATCH",
+            body: { seen },
+        });
+    }
+    async deleteMessage(token, id) {
+        await this.requestJson(`/messages/${id}`, {
+            token,
+            method: "DELETE",
+            expectNoContent: true,
+        });
+    }
+    async getSource(token, id) {
+        return this.requestJson(`/sources/${id}`, { token });
+    }
+    async deleteAccount(token, id) {
+        await this.requestJson(`/accounts/${id}`, {
+            token,
+            method: "DELETE",
+            expectNoContent: true,
+        });
+    }
+    async requestJson(path, options = {}) {
+        const max429Retries = options.max429Retries ?? 4;
+        for (let attempt = 0;; attempt += 1) {
+            const headers = new Headers({
+                Accept: "application/ld+json, application/json;q=0.9",
+            });
+            if (options.body !== undefined) {
+                headers.set("Content-Type", "application/json");
+            }
+            if (options.token) {
+                headers.set("Authorization", `Bearer ${options.token}`);
+            }
+            let response;
+            try {
+                response = await this.fetchLike(`${this.baseUrl}${path}`, {
+                    method: options.method ?? "GET",
+                    headers,
+                    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+                });
+            }
+            catch (error) {
+                throw new CliError({
+                    code: "NETWORK_ERROR",
+                    message: "Request to Mail.tm failed.",
+                    hint: "Check internet connectivity and retry.",
+                    cause: error,
+                });
+            }
+            const textBody = await response.text();
+            const parsedBody = this.tryParseBody(textBody);
+            if (response.ok) {
+                if (options.expectNoContent || response.status === 204 || textBody.length === 0) {
+                    return undefined;
+                }
+                return parsedBody;
+            }
+            if (response.status === 429 && attempt < max429Retries) {
+                const delayMs = this.computeRetryDelayMs(response, attempt);
+                await sleep(delayMs);
+                continue;
+            }
+            const message = this.extractErrorMessage(parsedBody, response.statusText);
+            throw new CliError({
+                code: statusCode(response.status),
+                message,
+                status: response.status,
+                hint: statusHint(response.status),
+                details: parsedBody,
+            });
+        }
+    }
+    tryParseBody(textBody) {
+        if (!textBody) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(textBody);
+        }
+        catch {
+            return textBody;
+        }
+    }
+    extractErrorMessage(parsedBody, fallback) {
+        if (typeof parsedBody === "object" && parsedBody !== null) {
+            const obj = parsedBody;
+            if (typeof obj.message === "string") {
+                return obj.message;
+            }
+            if (typeof obj["hydra:description"] === "string") {
+                return obj["hydra:description"];
+            }
+            if (typeof obj.detail === "string") {
+                return obj.detail;
+            }
+        }
+        if (typeof parsedBody === "string" && parsedBody.length > 0) {
+            return parsedBody;
+        }
+        return fallback || "Mail.tm request failed.";
+    }
+    normalizeCollection(payload, resourceName) {
+        if (Array.isArray(payload)) {
+            return {
+                "hydra:member": payload,
+                "hydra:totalItems": payload.length,
+            };
+        }
+        if (typeof payload === "object" && payload !== null) {
+            const obj = payload;
+            if (Array.isArray(obj["hydra:member"])) {
+                return payload;
+            }
+        }
+        throw new CliError({
+            code: "API_RESPONSE_INVALID",
+            message: `Unexpected ${resourceName} response shape from Mail.tm.`,
+            hint: "Retry the command. If this persists, the upstream API format may have changed.",
+            details: payload,
+        });
+    }
+    computeRetryDelayMs(response, attempt) {
+        const retryAfter = response.headers.get("retry-after");
+        if (retryAfter) {
+            const seconds = Number(retryAfter);
+            if (Number.isFinite(seconds) && seconds > 0) {
+                return Math.round(seconds * 1000);
+            }
+        }
+        const base = 250 * (2 ** attempt);
+        const jitter = Math.floor(Math.random() * 250);
+        return Math.min(base + jitter, 5000);
+    }
+}

package/dist/output.js

@@ -0,0 +1,57 @@
+import { inspect } from "node:util";
+import { CliError } from "./types.js";
+export function toCliError(error) {
+    if (error instanceof CliError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new CliError({
+            code: "UNEXPECTED_ERROR",
+            message: error.message,
+            cause: error,
+        });
+    }
+    return new CliError({
+        code: "UNEXPECTED_ERROR",
+        message: "Unexpected failure.",
+        details: error,
+    });
+}
+export function buildSuccessEnvelope(command, data) {
+    return {
+        ok: true,
+        command,
+        data,
+    };
+}
+export function buildErrorEnvelope(command, error) {
+    return {
+        ok: false,
+        command,
+        error: {
+            code: error.code,
+            message: error.message,
+            status: error.status,
+            hint: error.hint,
+            details: error.details,
+        },
+    };
+}
+export function printEnvelope(envelope, format) {
+    if (format === "json") {
+        console.log(JSON.stringify(envelope, null, 2));
+        return;
+    }
+    if (envelope.ok) {
+        console.log(`${envelope.command}: ok`);
+        console.log(inspect(envelope.data, { depth: null, colors: false, compact: false }));
+        return;
+    }
+    console.error(`${envelope.command}: error [${envelope.error.code}] ${envelope.error.message}`);
+    if (envelope.error.status !== undefined) {
+        console.error(`status: ${envelope.error.status}`);
+    }
+    if (envelope.error.hint) {
+        console.error(`hint: ${envelope.error.hint}`);
+    }
+}

package/dist/runner.js

@@ -0,0 +1,12 @@
+import { buildErrorEnvelope, buildSuccessEnvelope, printEnvelope, toCliError } from "./output.js";
+export async function runCommand(command, format, action) {
+    try {
+        const data = await action();
+        printEnvelope(buildSuccessEnvelope(command, data), format);
+    }
+    catch (error) {
+        const cliError = toCliError(error);
+        printEnvelope(buildErrorEnvelope(command, cliError), format);
+        process.exitCode = cliError.exitCode;
+    }
+}

package/dist/types.js

@@ -0,0 +1,16 @@
+export class CliError extends Error {
+    code;
+    status;
+    hint;
+    exitCode;
+    details;
+    constructor(params) {
+        super(params.message, { cause: params.cause });
+        this.name = "CliError";
+        this.code = params.code;
+        this.status = params.status;
+        this.hint = params.hint;
+        this.exitCode = params.exitCode ?? 1;
+        this.details = params.details;
+    }
+}

package/dist/utils.js

@@ -0,0 +1,30 @@
+import { randomBytes } from "node:crypto";
+export function generateRandomLocalPart() {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const bytes = randomBytes(12);
+    let body = "";
+    for (const byte of bytes) {
+        body += alphabet[byte % alphabet.length];
+    }
+    return `ae${body}`;
+}
+export function generatePassword24() {
+    return randomBytes(18).toString("base64url");
+}
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function extractResourceId(resourceUrl, resourceName) {
+    if (!resourceUrl) {
+        return null;
+    }
+    const marker = `/${resourceName}/`;
+    const idx = resourceUrl.lastIndexOf(marker);
+    if (idx === -1) {
+        return null;
+    }
+    return resourceUrl.slice(idx + marker.length) || null;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@zaddy6/agentemail",
+  "version": "0.1.0",
+  "description": "Mail.tm CLI for AI agents",
+  "private": false,
+  "packageManager": "bun@1.0.29",
+  "type": "module",
+  "bin": {
+    "agent-email": "bin/agent-email.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "bun --watch src/cli.ts",
+    "check": "bun run build && bun run test",
+    "test": "vitest run",
+    "test:live": "AGENT_EMAIL_LIVE_TESTS=1 vitest run tests/live.test.ts",
+    "prepublishOnly": "bun run check"
+  },
+  "keywords": [
+    "email",
+    "cli",
+    "mail.tm",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "Isaac David",
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.0.29"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zaddy6/agent-email.git"
+  },
+  "bugs": {
+    "url": "https://github.com/zaddy6/agent-email/issues"
+  },
+  "homepage": "https://github.com/zaddy6/agent-email#readme",
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}