carlyemail 0.1.0 → 0.3.0

package/README.md

@@ -1,13 +1,57 @@
 # carlyemail
 
-Real email inboxes your agent can send, receive and reply from.
+Real email inboxes your agent can send, receive and reply from. One package,
+two things: a typed client and a command line.
+
+## The client
+
+```bash
+npm install carlyemail
+```
+
+```javascript
+import { CarlyEmail } from "carlyemail";
+
+const carly = new CarlyEmail();          // reads CARLYEMAIL_API_KEY
+
+const inbox = await carly.inboxes.create({ username: "hello" });
+
+await carly.messages.send(inbox.email, {
+  to: ["you@example.com"],
+  subject: "Hello",
+  text: "From an agent.",
+});
+```
+
+Generated from the [OpenAPI spec](https://docs.carlyemail.com/openapi.json), so
+it cannot describe an endpoint the API does not serve. One `fetch` call per
+method and no dependencies, so it runs in Node, the browser, a worker and on the
+edge with no build step. Types ship with it.
+
+Errors carry the message, the fix and a documentation link:
+
+```javascript
+import { CarlyEmailError } from "carlyemail";
+
+try {
+  await carly.inboxes.create({ username: "hello" });
+} catch (error) {
+  if (error instanceof CarlyEmailError) {
+    console.log(error.status, error.code, error.fix, error.docs);
+  }
+}
+```
+
+There is a Python client too: `pip install carlyemail`.
+
+## The command line
 
 ```bash
-npx carlyemail signup --human-email you@example.com --username my-agent
+npx carlyemail signup
 ```
 
-That returns a working address and an API key. Confirm the emailed code and it
-can send:
+It asks for your email, offers an inbox name, and writes the key to
+`~/.carlyemail/config.json`. Confirm the emailed code and it can send:
 
 ```bash
 npx carlyemail verify 123456
@@ -18,7 +62,7 @@ npx carlyemail send \
   --text "Sent by an agent with its own address."
 ```
 
-Install it properly if you use it often:
+Install it if you use it often:
 
 ```bash
 npm install -g carlyemail
@@ -36,6 +80,15 @@ npm install -g carlyemail
 | `delete <inbox> --yes` | Delete an inbox and its mail |
 | `send --from <i> --to <a> --subject <s> --text <t>` | Send an email |
 | `messages <inbox>` | List messages |
+| `read <inbox> <id>` | Read one message in full |
+| `search <inbox> <text>` | Search messages |
+| `threads <inbox>` | List conversations |
+| `reply <inbox> <id> --text <t>` | Reply to the sender (`--all` to copy everyone) |
+| `drafts <inbox>` | List drafts |
+| `draft <inbox> --to <a> --text <t>` | Write a draft without sending |
+| `send-draft <inbox> <id>` | Send a draft written earlier |
+| `webhooks` | List webhook endpoints |
+| `domains` | List custom domains, with their DNS records |
 | `plan` | Current plan, with usage against every limit |
 | `upgrade <plan>` | A Stripe checkout link |
 | `billing` | Invoices, card changes, cancellation |

package/carlyemail.js

@@ -16,8 +16,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, realpath
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
 
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");
@@ -211,13 +212,34 @@ function emit(ctx, payload, render) {
   render();
 }
 
+/** A name to offer when somebody has no preference. Short enough to type again. */
+function suggestUsername() {
+  return `agent-${randomBytes(2).toString("hex")}`;
+}
+
 define(
   "signup",
   "Create an account and an inbox",
-  "carlyemail signup --human-email you@example.com --username my-agent",
+  "carlyemail signup   (or: --human-email you@example.com --username my-agent)",
   async (ctx) => {
-    const human_email = required(ctx.flags, "human-email");
-    const username = required(ctx.flags, "username");
+    // `signup` is the first command anybody runs, and refusing it with a usage
+    // error is a bad way to say hello. At a terminal, ask.
+    let human_email = ctx.flags["human-email"];
+    if (typeof human_email !== "string") {
+      const answer = await ctx.ask("Your email (for the confirmation code): ");
+      if (answer) human_email = answer;
+    }
+    if (!human_email) throw new UsageError("--human-email is required");
+
+    let username = ctx.flags.username;
+    if (typeof username !== "string") {
+      const suggested = suggestUsername();
+      const answer = await ctx.ask(`Inbox name [${suggested}]: `);
+      // null is "no terminal", which still has to fail. "" is a bare Enter,
+      // which means take the suggestion.
+      if (answer !== null) username = answer || suggested;
+    }
+    if (!username) throw new UsageError("--username is required");
 
     const out = await request(ctx.config, "POST", "/v0/agent/sign-up", {
       auth: false,
@@ -336,7 +358,236 @@ define("messages", "List messages in an inbox", "carlyemail messages me@carlyema
     for (const m of out.messages) {
       const when = (m.timestamp || "").slice(0, 16).replace("T", " ");
       ctx.print(`${dim(when)}  ${bold(m.subject || "(no subject)")}`);
-      ctx.print(`${" ".repeat(18)}${dim(`from ${m.from ?? m.from_address ?? "?"}`)}`);
+      // The id goes on screen because every other command takes one. Listing
+      // messages and then having to go to the API to find out what to call
+      // `read` or `reply` with was the gap people kept falling into.
+      const id = m.message_id ? `  ${m.message_id}` : "";
+      ctx.print(`${" ".repeat(18)}${dim(`from ${m.from ?? m.from_address ?? "?"}${id}`)}`);
+    }
+  });
+});
+
+define("read", "Read one message in full", "carlyemail read me@carlyemail.com '<id@host>'", async (ctx) => {
+  const [inbox, id] = ctx.positional;
+  if (!inbox || !id) throw new UsageError("carlyemail read <inbox> <message-id>");
+  const m = await request(
+    ctx.config,
+    "GET",
+    `/v0/inboxes/${encodeURIComponent(inbox)}/messages/${encodeURIComponent(id)}`
+  );
+  emit(ctx, m, () => {
+    ctx.print(`${dim("from")}     ${m.from ?? "?"}`);
+    ctx.print(`${dim("to")}       ${(m.to || []).join(", ")}`);
+    ctx.print(`${dim("date")}     ${(m.timestamp || "").replace("T", " ").slice(0, 19)}`);
+    ctx.print(`${dim("subject")}  ${bold(m.subject || "(no subject)")}`);
+    if (m.labels?.length) ctx.print(`${dim("labels")}   ${m.labels.join(", ")}`);
+    if (m.attachments?.length) {
+      ctx.print(`${dim("files")}    ${m.attachments.map((a) => a.filename ?? a.attachment_id).join(", ")}`);
+    }
+    ctx.print("");
+    // `text` is the body as sent; `extracted_text` has the quoted reply chain
+    // stripped. Print the full one — a person reading a single message asked
+    // for the message, not our opinion of the interesting part of it.
+    ctx.print(m.text || m.preview || dim("(no text body)"));
+  });
+});
+
+define("search", "Search messages in an inbox", 'carlyemail search me@carlyemail.com "invoice"', async (ctx) => {
+  const [inbox, ...terms] = ctx.positional;
+  const query = terms.join(" ") || ctx.flags.query;
+  if (!inbox || !query) throw new UsageError('carlyemail search <inbox> "what to look for"');
+  const out = await request(
+    ctx.config,
+    "GET",
+    // `q`, not `query` — the parameter name comes from the OpenAPI spec, and
+    // guessing it produced a 422 that looked like a CLI bug.
+    `/v0/inboxes/${encodeURIComponent(inbox)}/messages/search?q=${encodeURIComponent(query)}`
+  );
+  emit(ctx, out, () => {
+    if (!out.messages?.length) {
+      ctx.print(dim(`nothing matching ${JSON.stringify(query)}`));
+      return;
+    }
+    for (const m of out.messages) {
+      ctx.print(`${dim((m.timestamp || "").slice(0, 10))}  ${bold(m.subject || "(no subject)")}`);
+      ctx.print(`${" ".repeat(12)}${dim(m.message_id ?? "")}`);
+    }
+  });
+});
+
+define("threads", "List conversations in an inbox", "carlyemail threads me@carlyemail.com", async (ctx) => {
+  const inbox = ctx.positional[0];
+  if (!inbox) throw new UsageError("carlyemail threads <inbox>");
+  const out = await request(ctx.config, "GET", `/v0/inboxes/${encodeURIComponent(inbox)}/threads`);
+  emit(ctx, out, () => {
+    if (!out.threads?.length) {
+      ctx.print(dim("no conversations"));
+      return;
+    }
+    for (const t of out.threads) {
+      const count = t.message_count ? dim(` (${t.message_count})`) : "";
+      ctx.print(`${bold(t.subject || "(no subject)")}${count}`);
+      ctx.print(`  ${dim(t.thread_id)}  ${dim((t.senders || []).join(", "))}`);
+    }
+  });
+});
+
+/** The newest message in an inbox that the inbox did not itself send. */
+async function lastReceived(ctx, inbox) {
+  const out = await request(
+    ctx.config,
+    "GET",
+    `/v0/inboxes/${encodeURIComponent(inbox)}/messages?limit=10`
+  );
+  // Sent mail is stored in the inbox alongside what arrived, so the newest
+  // message is often the agent's own last reply. Replying to yourself is never
+  // what `--last` means.
+  const mine = inbox.toLowerCase();
+  const found = (out.messages || []).find(
+    (m) => !String(m.from ?? m.from_address ?? "").toLowerCase().includes(mine)
+  );
+  if (!found) throw new UsageError(`nothing to reply to in ${inbox}`);
+  return found.message_id;
+}
+
+define("reply", "Reply to a message", 'carlyemail reply me@x.com --last --text "On it"', async (ctx) => {
+  const [inbox, given] = ctx.positional;
+  if (!inbox) throw new UsageError("carlyemail reply <inbox> <message-id> --text ...");
+  if (!given && !ctx.flags.last) {
+    throw new UsageError("carlyemail reply <inbox> <message-id> --text ...  (or --last)");
+  }
+  const body = {
+    text: typeof ctx.flags.text === "string" ? ctx.flags.text : undefined,
+    html: typeof ctx.flags.html === "string" ? ctx.flags.html : undefined,
+  };
+  // Checked before `--last` costs a request, and long before anything is sent.
+  if (body.text === undefined && body.html === undefined) {
+    throw new UsageError("--text or --html is required");
+  }
+  const id = given || (await lastReceived(ctx, inbox));
+  // reply-all is opt-in. Quietly copying everyone on the original thread is
+  // the kind of default that sends an agent's message to people the caller
+  // never saw.
+  const route = ctx.flags["all"] ? "reply-all" : "reply";
+  const sent = await request(
+    ctx.config,
+    "POST",
+    `/v0/inboxes/${encodeURIComponent(inbox)}/messages/${encodeURIComponent(id)}/${route}`,
+    { body }
+  );
+  emit(ctx, sent, () => ctx.print(ok(`replied  ${dim(sent.message_id ?? "")}`)));
+});
+
+define("drafts", "List drafts in an inbox", "carlyemail drafts me@carlyemail.com", async (ctx) => {
+  const inbox = ctx.positional[0];
+  if (!inbox) throw new UsageError("carlyemail drafts <inbox>");
+  const out = await request(ctx.config, "GET", `/v0/inboxes/${encodeURIComponent(inbox)}/drafts`);
+  emit(ctx, out, () => {
+    if (!out.drafts?.length) {
+      ctx.print(dim("no drafts"));
+      return;
+    }
+    for (const d of out.drafts) {
+      ctx.print(`${bold(d.subject || "(no subject)")}  ${dim(`to ${(d.to || []).join(", ")}`)}`);
+      ctx.print(`  ${dim(d.draft_id)}`);
+    }
+  });
+});
+
+define(
+  "draft",
+  "Write a draft without sending it",
+  'carlyemail draft me@x.com --to you@y.com --subject Hi --text "..."',
+  async (ctx) => {
+    const inbox = ctx.positional[0];
+    if (!inbox) throw new UsageError("carlyemail draft <inbox> --to ... --text ...");
+    const body = {
+      to: required(ctx.flags, "to").split(",").map((s) => s.trim()),
+      subject: typeof ctx.flags.subject === "string" ? ctx.flags.subject : undefined,
+      text: typeof ctx.flags.text === "string" ? ctx.flags.text : undefined,
+    };
+    const d = await request(
+      ctx.config,
+      "POST",
+      `/v0/inboxes/${encodeURIComponent(inbox)}/drafts`,
+      { body }
+    );
+    emit(ctx, d, () => {
+      ctx.print(ok(`draft ${d.draft_id}`));
+      ctx.print(arrow(`send it with:  carlyemail send-draft ${inbox} ${d.draft_id}`));
+    });
+  }
+);
+
+define("send-draft", "Send a draft that was written earlier", "carlyemail send-draft me@x.com dft_123", async (ctx) => {
+  const [inbox, id] = ctx.positional;
+  if (!inbox || !id) throw new UsageError("carlyemail send-draft <inbox> <draft-id>");
+  const sent = await request(
+    ctx.config,
+    "POST",
+    `/v0/inboxes/${encodeURIComponent(inbox)}/drafts/${encodeURIComponent(id)}/send`
+  );
+  emit(ctx, sent, () => ctx.print(ok(`sent  ${dim(sent.message_id ?? "")}`)));
+});
+
+define(
+  "webhook",
+  "Create a webhook endpoint",
+  "carlyemail webhook https://you.example/mail --events message.received",
+  async (ctx) => {
+    const url = ctx.positional[0];
+    if (!url) throw new UsageError("carlyemail webhook <url> --events message.received");
+    const events =
+      typeof ctx.flags.events === "string"
+        ? ctx.flags.events.split(",").map((e) => e.trim()).filter(Boolean)
+        : ["message.received"];
+
+    const made = await request(ctx.config, "POST", "/v0/webhooks", {
+      body: { url, event_types: events },
+    });
+    emit(ctx, made, () => {
+      ctx.print(ok(`webhook  ${dim(made.webhook_id ?? "")}`));
+      // Returned once and never again. Printing it without saying so is how
+      // people end up recreating the webhook to get a secret back.
+      if (made.secret) {
+        ctx.print(`  secret  ${made.secret}`);
+        ctx.print(dim("  shown once — store it, you need it to verify deliveries"));
+      }
+    });
+  }
+);
+
+define("webhooks", "List webhook endpoints", "carlyemail webhooks", async (ctx) => {
+  const out = await request(ctx.config, "GET", "/v0/webhooks");
+  emit(ctx, out, () => {
+    if (!out.webhooks?.length) {
+      ctx.print(dim("no webhooks"));
+      return;
+    }
+    for (const w of out.webhooks) {
+      ctx.print(`${w.enabled === false ? dim("(disabled) ") : ""}${bold(w.url)}`);
+      ctx.print(`  ${dim(w.webhook_id)}  ${dim((w.event_types || []).join(", "))}`);
+    }
+  });
+});
+
+define("domains", "List custom sending domains", "carlyemail domains", async (ctx) => {
+  const out = await request(ctx.config, "GET", "/v0/domains");
+  emit(ctx, out, () => {
+    if (!out.domains?.length) {
+      ctx.print(dim("no custom domains — mail sends from carlyemail.com"));
+      return;
+    }
+    for (const d of out.domains) {
+      const mark = d.status === "VERIFIED" ? paint(32, "✓") : dim("…");
+      ctx.print(`${mark} ${bold(d.domain)}  ${dim(d.status)}`);
+      // Unverified domains are the common case people get stuck on, and the
+      // records are the whole answer, so print them rather than a doc link.
+      if (d.status !== "VERIFIED") {
+        for (const r of d.records || []) {
+          ctx.print(`    ${dim(r.type)}  ${r.name}  ${dim("→")}  ${r.value}`);
+        }
+      }
     }
   });
 });
@@ -408,7 +659,7 @@ export function helpText() {
   lines.push(
     "",
     bold("Getting started"),
-    "  carlyemail signup --human-email you@example.com --username my-agent",
+    "  carlyemail signup",
     "  carlyemail verify 123456",
     "  carlyemail send --from my-agent@agents.carlyemail.com \\",
     '      --to someone@example.com --subject Hi --text "Hello from an agent"',
@@ -428,7 +679,27 @@ export function helpText() {
 
 // ---------------------------------------------------------------- entry
 
-export async function main(argv, { env = process.env, print = console.log, configFile, configDir } = {}) {
+/**
+ * Read one line from the terminal.
+ *
+ * Returns null when there is no terminal — a CI job or a piped script must get
+ * the usage error it can act on, not a prompt nobody will ever answer.
+ */
+async function askTerminal(question) {
+  if (!process.stdin.isTTY) return null;
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function main(
+  argv,
+  { env = process.env, print = console.log, ask = askTerminal, configFile, configDir } = {}
+) {
   const { flags, positional } = parseArgs(argv);
   const name = positional.shift();
 
@@ -454,7 +725,7 @@ export async function main(argv, { env = process.env, print = console.log, confi
 
   const config = loadConfig(env, configFile);
   try {
-    await command.run({ config, flags, positional, print, configFile, configDir });
+    await command.run({ config, flags, positional, print, ask, configFile, configDir });
     return 0;
   } catch (error) {
     if (error instanceof ApiError) {

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "carlyemail",
-  "version": "0.1.0",
-  "description": "Real email inboxes your agent can send, receive and reply from.",
-  "keywords": ["email", "agent", "ai", "inbox", "smtp", "mcp", "cli"],
+  "version": "0.3.0",
+  "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
+  "keywords": [
+    "email",
+    "agent",
+    "ai",
+    "inbox",
+    "smtp",
+    "mcp",
+    "cli"
+  ],
   "homepage": "https://carlyemail.com",
   "bugs": "https://docs.carlyemail.com/support",
   "repository": {
@@ -16,8 +24,18 @@
   "bin": {
     "carlyemail": "./carlyemail.js"
   },
-  "exports": "./carlyemail.js",
-  "files": ["carlyemail.js", "README.md", "LICENSE"],
+  "types": "./sdk.d.ts",
+  "exports": {
+    ".": "./sdk.js",
+    "./cli": "./carlyemail.js"
+  },
+  "files": [
+    "carlyemail.js",
+    "sdk.js",
+    "sdk.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=18"
   },