shellmail 1.0.0

package/dist/api.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ShellMail API Client
+ */
+export interface CreateAddressResponse {
+    address: string;
+    token: string;
+    note: string;
+}
+export interface EmailSummary {
+    id: string;
+    from_addr: string;
+    from_name: string | null;
+    subject: string;
+    received_at: string;
+    is_read: boolean;
+    otp_code?: string | null;
+    otp_link?: string | null;
+}
+export interface EmailDetail extends EmailSummary {
+    body_text: string | null;
+    body_html: string | null;
+    is_archived: boolean;
+}
+export interface InboxResponse {
+    address: string;
+    unread_count: number;
+    emails: EmailSummary[];
+}
+export interface OtpResponse {
+    found: boolean;
+    email_id?: string;
+    from?: string;
+    subject?: string;
+    code?: string | null;
+    link?: string | null;
+    received_at?: string;
+    message?: string;
+}
+export interface WebhookResponse {
+    configured: boolean;
+    url: string | null;
+    has_secret: boolean;
+}
+export interface WebhookSetResponse {
+    ok: boolean;
+    url: string;
+    secret: string;
+    note: string;
+}
+export declare class ShellMailAPI {
+    private token;
+    constructor(token?: string);
+    private request;
+    createAddress(local: string, recoveryEmail: string): Promise<CreateAddressResponse>;
+    inbox(unreadOnly?: boolean, limit?: number): Promise<InboxResponse>;
+    read(emailId: string): Promise<EmailDetail>;
+    markRead(emailId: string): Promise<{
+        ok: boolean;
+    }>;
+    archive(emailId: string): Promise<{
+        ok: boolean;
+    }>;
+    delete(emailId: string): Promise<{
+        ok: boolean;
+    }>;
+    otp(options?: {
+        timeout?: number;
+        from?: string;
+        since?: string;
+    }): Promise<OtpResponse>;
+    search(options: {
+        q?: string;
+        from?: string;
+        hasOtp?: boolean;
+        limit?: number;
+    }): Promise<{
+        count: number;
+        emails: EmailSummary[];
+    }>;
+    getWebhook(): Promise<WebhookResponse>;
+    setWebhook(url: string, secret?: string): Promise<WebhookSetResponse>;
+    deleteWebhook(): Promise<{
+        ok: boolean;
+    }>;
+    health(): Promise<{
+        service: string;
+        status: string;
+        domain: string;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,90 @@
+/**
+ * ShellMail API Client
+ */
+const API_BASE = process.env.SHELLMAIL_API_URL || "https://shellmail.ai";
+export class ShellMailAPI {
+    token;
+    constructor(token) {
+        this.token = token || process.env.SHELLMAIL_TOKEN || null;
+    }
+    async request(method, path, body, requireAuth = true) {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (requireAuth) {
+            if (!this.token) {
+                throw new Error("No token configured. Run 'shellmail setup' first.");
+            }
+            headers["Authorization"] = `Bearer ${this.token}`;
+        }
+        const response = await fetch(`${API_BASE}${path}`, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            throw new Error(data.error || `Request failed: ${response.status}`);
+        }
+        return data;
+    }
+    async createAddress(local, recoveryEmail) {
+        return this.request("POST", "/api/addresses", { local, recovery_email: recoveryEmail }, false);
+    }
+    async inbox(unreadOnly = false, limit = 20) {
+        const params = new URLSearchParams();
+        if (unreadOnly)
+            params.set("unread", "true");
+        params.set("limit", limit.toString());
+        return this.request("GET", `/api/mail?${params}`);
+    }
+    async read(emailId) {
+        return this.request("GET", `/api/mail/${emailId}`);
+    }
+    async markRead(emailId) {
+        return this.request("PATCH", `/api/mail/${emailId}`, { is_read: true });
+    }
+    async archive(emailId) {
+        return this.request("PATCH", `/api/mail/${emailId}`, { is_archived: true });
+    }
+    async delete(emailId) {
+        return this.request("DELETE", `/api/mail/${emailId}`);
+    }
+    async otp(options) {
+        const params = new URLSearchParams();
+        if (options?.timeout)
+            params.set("timeout", options.timeout.toString());
+        if (options?.from)
+            params.set("from", options.from);
+        if (options?.since)
+            params.set("since", options.since);
+        return this.request("GET", `/api/mail/otp?${params}`);
+    }
+    async search(options) {
+        const params = new URLSearchParams();
+        if (options.q)
+            params.set("q", options.q);
+        if (options.from)
+            params.set("from", options.from);
+        if (options.hasOtp)
+            params.set("has_otp", "true");
+        if (options.limit)
+            params.set("limit", options.limit.toString());
+        return this.request("GET", `/api/mail/search?${params}`);
+    }
+    async getWebhook() {
+        return this.request("GET", "/api/webhook");
+    }
+    async setWebhook(url, secret) {
+        return this.request("PUT", "/api/webhook", {
+            url,
+            secret,
+        });
+    }
+    async deleteWebhook() {
+        return this.request("DELETE", "/api/webhook");
+    }
+    async health() {
+        return this.request("GET", "/health", undefined, false);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration management for ShellMail CLI
+ */
+export interface ShellMailConfig {
+    token?: string;
+    address?: string;
+    apiUrl?: string;
+}
+export declare function loadConfig(): ShellMailConfig;
+export declare function saveConfig(config: ShellMailConfig): void;
+export declare function clearConfig(): void;
+export declare function getToken(): string | undefined;

package/dist/config.js

@@ -0,0 +1,45 @@
+/**
+ * Configuration management for ShellMail CLI
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const CONFIG_DIR = join(homedir(), ".shellmail");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+export function loadConfig() {
+    // Environment variables take precedence
+    if (process.env.SHELLMAIL_TOKEN) {
+        return {
+            token: process.env.SHELLMAIL_TOKEN,
+            address: process.env.SHELLMAIL_ADDRESS,
+            apiUrl: process.env.SHELLMAIL_API_URL,
+        };
+    }
+    // Try to load from config file
+    if (existsSync(CONFIG_FILE)) {
+        try {
+            const data = readFileSync(CONFIG_FILE, "utf-8");
+            return JSON.parse(data);
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+export function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), {
+        mode: 0o600, // Only owner can read/write
+    });
+}
+export function clearConfig() {
+    if (existsSync(CONFIG_FILE)) {
+        writeFileSync(CONFIG_FILE, "{}", { mode: 0o600 });
+    }
+}
+export function getToken() {
+    return process.env.SHELLMAIL_TOKEN || loadConfig().token;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * ShellMail CLI
+ * Email for AI agents — in 30 seconds
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,433 @@
+#!/usr/bin/env node
+/**
+ * ShellMail CLI
+ * Email for AI agents — in 30 seconds
+ */
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import inquirer from "inquirer";
+import { ShellMailAPI } from "./api.js";
+import { loadConfig, saveConfig, clearConfig, getToken } from "./config.js";
+const program = new Command();
+program
+    .name("shellmail")
+    .description("Email for AI agents — create addresses, check mail, extract OTPs")
+    .version("1.0.0");
+// ── Setup Command ────────────────────────────────────────
+program
+    .command("setup")
+    .description("Create a new ShellMail address interactively")
+    .option("-l, --local <name>", "Local part of email address")
+    .option("-r, --recovery <email>", "Recovery email address")
+    .action(async (options) => {
+    console.log(chalk.bold("\n📧 ShellMail Setup\n"));
+    let local = options.local;
+    let recoveryEmail = options.recovery;
+    if (!local) {
+        const answers = await inquirer.prompt([
+            {
+                type: "input",
+                name: "local",
+                message: "Choose your email address:",
+                suffix: chalk.gray("@shellmail.ai"),
+                validate: (input) => {
+                    if (!input || input.length < 2)
+                        return "Must be at least 2 characters";
+                    if (!/^[a-z0-9][a-z0-9._-]*[a-z0-9]$/i.test(input) && input.length > 2) {
+                        return "Only letters, numbers, dots, hyphens, underscores allowed";
+                    }
+                    return true;
+                },
+            },
+        ]);
+        local = answers.local;
+    }
+    if (!recoveryEmail) {
+        const answers = await inquirer.prompt([
+            {
+                type: "input",
+                name: "recovery",
+                message: "Recovery email (for token recovery):",
+                validate: (input) => {
+                    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input)) {
+                        return "Enter a valid email address";
+                    }
+                    return true;
+                },
+            },
+        ]);
+        recoveryEmail = answers.recovery;
+    }
+    const spinner = ora("Creating address...").start();
+    try {
+        const api = new ShellMailAPI();
+        const result = await api.createAddress(local, recoveryEmail);
+        spinner.succeed(chalk.green("Address created!"));
+        console.log("\n" + chalk.bold("Your ShellMail address:"));
+        console.log(chalk.cyan(`  ${result.address}\n`));
+        console.log(chalk.bold("Your API token:"));
+        console.log(chalk.yellow(`  ${result.token}\n`));
+        console.log(chalk.gray("⚠️  Save this token! It won't be shown again.\n"));
+        // Save to config
+        const { save } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "save",
+                message: "Save token to ~/.shellmail/config.json?",
+                default: true,
+            },
+        ]);
+        if (save) {
+            saveConfig({
+                token: result.token,
+                address: result.address,
+            });
+            console.log(chalk.green("\n✓ Config saved! You can now use other shellmail commands.\n"));
+        }
+        else {
+            console.log(chalk.gray("\nSet SHELLMAIL_TOKEN env var to use the CLI:\n"));
+            console.log(chalk.cyan(`  export SHELLMAIL_TOKEN="${result.token}"\n`));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to create address"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Inbox Command ────────────────────────────────────────
+program
+    .command("inbox")
+    .description("List emails in your inbox")
+    .option("-u, --unread", "Show only unread emails")
+    .option("-n, --limit <number>", "Number of emails to show", "10")
+    .action(async (options) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const spinner = ora("Fetching inbox...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        const result = await api.inbox(options.unread, parseInt(options.limit));
+        spinner.stop();
+        console.log(chalk.bold(`\n📬 ${result.address}`));
+        console.log(chalk.gray(`   ${result.unread_count} unread\n`));
+        if (result.emails.length === 0) {
+            console.log(chalk.gray("   No emails.\n"));
+            return;
+        }
+        for (const email of result.emails) {
+            const unread = !email.is_read ? chalk.blue("●") : " ";
+            const from = email.from_name || email.from_addr.split("@")[0];
+            const date = new Date(email.received_at).toLocaleString();
+            const otp = email.otp_code ? chalk.yellow(` [OTP: ${email.otp_code}]`) : "";
+            console.log(`${unread} ${chalk.bold(from.slice(0, 20).padEnd(20))} ${email.subject?.slice(0, 40) || "(no subject)"}${otp}`);
+            console.log(chalk.gray(`  ${email.id}  ${date}\n`));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to fetch inbox"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Read Command ─────────────────────────────────────────
+program
+    .command("read <id>")
+    .description("Read a specific email")
+    .option("-m, --mark-read", "Mark as read after viewing", true)
+    .action(async (id, options) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const spinner = ora("Fetching email...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        const email = await api.read(id);
+        if (options.markRead && !email.is_read) {
+            await api.markRead(id);
+        }
+        spinner.stop();
+        console.log("\n" + chalk.bold("From: ") + (email.from_name ? `${email.from_name} <${email.from_addr}>` : email.from_addr));
+        console.log(chalk.bold("Subject: ") + (email.subject || "(no subject)"));
+        console.log(chalk.bold("Date: ") + new Date(email.received_at).toLocaleString());
+        console.log(chalk.gray("─".repeat(60)) + "\n");
+        if (email.body_text) {
+            // Clean up quoted-printable encoding
+            const body = email.body_text
+                .replace(/=\r?\n/g, "")
+                .replace(/=([0-9A-F]{2})/gi, (_, hex) => String.fromCharCode(parseInt(hex, 16)));
+            console.log(body);
+        }
+        else if (email.body_html) {
+            // Strip HTML tags for terminal display
+            const text = email.body_html
+                .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+                .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+                .replace(/<[^>]+>/g, " ")
+                .replace(/\s+/g, " ")
+                .trim();
+            console.log(text);
+        }
+        else {
+            console.log(chalk.gray("(no content)"));
+        }
+        console.log("\n");
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to read email"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── OTP Command ──────────────────────────────────────────
+program
+    .command("otp")
+    .description("Get the latest OTP/verification code")
+    .option("-w, --wait <seconds>", "Wait for OTP to arrive (max 30s)")
+    .option("-f, --from <domain>", "Filter by sender domain")
+    .action(async (options) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const timeout = options.wait ? Math.min(parseInt(options.wait) * 1000, 30000) : 0;
+    const spinner = timeout
+        ? ora(`Waiting for OTP (${options.wait}s timeout)...`).start()
+        : ora("Checking for OTP...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        const result = await api.otp({
+            timeout,
+            from: options.from,
+        });
+        if (result.found) {
+            spinner.succeed(chalk.green("OTP found!"));
+            console.log("\n" + chalk.bold.yellow(`  ${result.code || result.link}\n`));
+            console.log(chalk.gray(`  From: ${result.from}`));
+            console.log(chalk.gray(`  Subject: ${result.subject}`));
+            console.log(chalk.gray(`  Received: ${new Date(result.received_at).toLocaleString()}\n`));
+            // Output just the code for piping
+            if (process.stdout.isTTY === false) {
+                process.stdout.write(result.code || result.link || "");
+            }
+        }
+        else {
+            spinner.warn(chalk.yellow(result.message || "No OTP found"));
+            console.log(chalk.gray("\n  Tip: Send a verification email to your address, then try again.\n"));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to check OTP"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Search Command ───────────────────────────────────────
+program
+    .command("search")
+    .description("Search emails")
+    .option("-q, --query <text>", "Search text in subject/body/sender")
+    .option("-f, --from <domain>", "Filter by sender")
+    .option("--otp", "Only show emails with OTP codes")
+    .option("-n, --limit <number>", "Number of results", "10")
+    .action(async (options) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    if (!options.query && !options.from && !options.otp) {
+        console.error(chalk.red("Provide at least one search option: --query, --from, or --otp"));
+        process.exit(1);
+    }
+    const spinner = ora("Searching...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        const result = await api.search({
+            q: options.query,
+            from: options.from,
+            hasOtp: options.otp,
+            limit: parseInt(options.limit),
+        });
+        spinner.stop();
+        console.log(chalk.bold(`\n🔍 ${result.count} result(s)\n`));
+        for (const email of result.emails) {
+            const from = email.from_name || email.from_addr.split("@")[0];
+            const otp = email.otp_code ? chalk.yellow(` [OTP: ${email.otp_code}]`) : "";
+            console.log(`${chalk.bold(from.slice(0, 20).padEnd(20))} ${email.subject?.slice(0, 40) || "(no subject)"}${otp}`);
+            console.log(chalk.gray(`  ${email.id}\n`));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Search failed"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Webhook Command ──────────────────────────────────────
+program
+    .command("webhook")
+    .description("Configure webhook notifications")
+    .option("-s, --set <url>", "Set webhook URL")
+    .option("-d, --delete", "Remove webhook configuration")
+    .action(async (options) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const api = new ShellMailAPI(token);
+    if (options.delete) {
+        const spinner = ora("Removing webhook...").start();
+        try {
+            await api.deleteWebhook();
+            spinner.succeed(chalk.green("Webhook removed"));
+        }
+        catch (err) {
+            spinner.fail(chalk.red("Failed to remove webhook"));
+            console.error(chalk.red(`  ${err.message}\n`));
+            process.exit(1);
+        }
+        return;
+    }
+    if (options.set) {
+        const spinner = ora("Configuring webhook...").start();
+        try {
+            const result = await api.setWebhook(options.set);
+            spinner.succeed(chalk.green("Webhook configured!"));
+            console.log("\n" + chalk.bold("URL: ") + result.url);
+            console.log(chalk.bold("Secret: ") + chalk.yellow(result.secret));
+            console.log(chalk.gray("\n⚠️  Save the secret! Use it to verify webhook signatures.\n"));
+        }
+        catch (err) {
+            spinner.fail(chalk.red("Failed to configure webhook"));
+            console.error(chalk.red(`  ${err.message}\n`));
+            process.exit(1);
+        }
+        return;
+    }
+    // Show current config
+    const spinner = ora("Fetching webhook config...").start();
+    try {
+        const result = await api.getWebhook();
+        spinner.stop();
+        if (result.configured) {
+            console.log(chalk.bold("\n🔔 Webhook configured"));
+            console.log(chalk.bold("URL: ") + result.url);
+            console.log(chalk.bold("Secret: ") + (result.has_secret ? chalk.green("configured") : chalk.yellow("not set")));
+        }
+        else {
+            console.log(chalk.gray("\nNo webhook configured."));
+            console.log(chalk.gray("Use 'shellmail webhook --set <url>' to configure.\n"));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to fetch webhook config"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Delete Command ───────────────────────────────────────
+program
+    .command("delete <id>")
+    .description("Delete an email")
+    .action(async (id) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const spinner = ora("Deleting email...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        await api.delete(id);
+        spinner.succeed(chalk.green("Email deleted"));
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to delete email"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Archive Command ──────────────────────────────────────
+program
+    .command("archive <id>")
+    .description("Archive an email")
+    .action(async (id) => {
+    const token = getToken();
+    if (!token) {
+        console.error(chalk.red("No token configured. Run 'shellmail setup' first."));
+        process.exit(1);
+    }
+    const spinner = ora("Archiving email...").start();
+    try {
+        const api = new ShellMailAPI(token);
+        await api.archive(id);
+        spinner.succeed(chalk.green("Email archived"));
+    }
+    catch (err) {
+        spinner.fail(chalk.red("Failed to archive email"));
+        console.error(chalk.red(`  ${err.message}\n`));
+        process.exit(1);
+    }
+});
+// ── Logout Command ───────────────────────────────────────
+program
+    .command("logout")
+    .description("Clear saved configuration")
+    .action(async () => {
+    const { confirm } = await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "confirm",
+            message: "This will remove your saved token. Continue?",
+            default: false,
+        },
+    ]);
+    if (confirm) {
+        clearConfig();
+        console.log(chalk.green("\n✓ Configuration cleared.\n"));
+    }
+});
+// ── Status Command ───────────────────────────────────────
+program
+    .command("status")
+    .description("Check ShellMail service status and current config")
+    .action(async () => {
+    const config = loadConfig();
+    const api = new ShellMailAPI();
+    console.log(chalk.bold("\n📧 ShellMail Status\n"));
+    // Check service health
+    const spinner = ora("Checking service...").start();
+    try {
+        const health = await api.health();
+        spinner.succeed(chalk.green(`Service: ${health.status}`));
+    }
+    catch {
+        spinner.fail(chalk.red("Service: unreachable"));
+    }
+    // Show config
+    if (config.token) {
+        console.log(chalk.green("✓ Token: configured"));
+        if (config.address) {
+            console.log(chalk.green(`✓ Address: ${config.address}`));
+        }
+    }
+    else if (process.env.SHELLMAIL_TOKEN) {
+        console.log(chalk.green("✓ Token: set via SHELLMAIL_TOKEN"));
+    }
+    else {
+        console.log(chalk.yellow("✗ Token: not configured"));
+        console.log(chalk.gray("  Run 'shellmail setup' to create an address"));
+    }
+    console.log("");
+});
+program.parse();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "shellmail",
+  "version": "1.0.0",
+  "description": "CLI for ShellMail - Email for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "shellmail": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "email",
+    "ai",
+    "agents",
+    "cli",
+    "shellmail"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aaronbatchelder/shellmail"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.15",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ]
+}