carlyemail 0.2.0 → 0.4.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
-npx carlyemail signup --human-email you@example.com --username my-agent
+npm install carlyemail
 ```
 
-That returns a working address and an API key. Confirm the emailed code and it
-can send:
+```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
+```
+
+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,14 @@ npx carlyemail send \
   --text "Sent by an agent with its own address."
 ```
 
-Install it properly if you use it often:
+Load the saved key and its first inbox into the current shell before starting
+LangChain, the Claude Agent SDK, Eve, Mastra, or another framework:
+
+```bash
+eval "$(npx carlyemail env)"
+```
+
+Install it if you use it often:
 
 ```bash
 npm install -g carlyemail
@@ -31,6 +82,7 @@ npm install -g carlyemail
 | `signup --human-email <e> --username <u>` | Create an account and an inbox |
 | `verify <code>` | Confirm the owner email |
 | `whoami` | Identity and scope of the current key |
+| `env` | Print `CARLYEMAIL_API_KEY` and `CARLYEMAIL_INBOX` shell exports |
 | `inboxes` | List inboxes |
 | `create --username <u>` | Create an inbox |
 | `delete <inbox> --yes` | Delete an inbox and its mail |
@@ -82,10 +134,10 @@ rather than a login.
 
 ## Notes
 
-**Sign-up is idempotent by owner email, and rotates the key.** Running it again
-for an address that already has an account issues a new key and **revokes the
-previous one**. It is how you recover a lost key; it is not a way to add a
-second inbox. Use `create` for that.
+**An owner email is not a login.** Running sign-up again for an existing address
+returns `account_exists` and leaves every key untouched. Recover access with an
+emailed code at https://console.carlyemail.com; use `create` from an
+authenticated CLI session to add another inbox.
 
 **`delete` requires `--yes`.** It removes the inbox and every message in it,
 and there is no undo.
@@ -108,6 +160,22 @@ Node 18 or newer. No dependencies — this is one file that uses Node's built-in
 `fetch`, so `npx` never resolves a tree and never fails for a reason unrelated
 to the thing you asked for.
 
+## Inbound email in a Worker
+
+The dependency-free webhook helper uses Web Crypto, so the same verified
+`onEmail` callback runs in Cloudflare Workers, Node, and other edge runtimes:
+
+```js
+import { createEmailHandler } from "carlyemail/webhooks";
+
+const handleEmail = createEmailHandler({
+  secret: env.CARLYEMAIL_WEBHOOK_SECRET,
+  async onEmail(event) {
+    console.log(event.message);
+  },
+});
+```
+
 ## Licence
 
 MIT — see `LICENSE`. That covers **this CLI only**. The CarlyEmail service it

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.2.0";
+export const VERSION = "0.4.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");
@@ -39,6 +40,11 @@ export function maskKey(key) {
   return `${key.slice(0, 9)}${"·".repeat(8)}${key.slice(-4)}`;
 }
 
+/** Quote one value for POSIX shells. `env` is designed to be used with eval. */
+export function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
 // ---------------------------------------------------------------- config
 
 /**
@@ -108,7 +114,12 @@ class UsageError extends Error {}
 
 // ---------------------------------------------------------------- transport
 
-export async function request(config, method, path, { body, auth = true, fetchImpl = fetch } = {}) {
+export async function request(
+  config,
+  method,
+  path,
+  { body, auth = true, raw = false, fetchImpl = fetch } = {}
+) {
   const headers = { accept: "application/json" };
   if (body !== undefined) headers["content-type"] = "application/json";
   if (auth) {
@@ -145,7 +156,9 @@ export async function request(config, method, path, { body, auth = true, fetchIm
     }
   }
   if (!response.ok) throw new ApiError(response.status, parsed);
-  return parsed;
+  // The zone file is text/plain, not our envelope. Parsing it returns null,
+  // which is how it silently printed nothing.
+  return raw ? text : parsed;
 }
 
 // ---------------------------------------------------------------- arguments
@@ -211,13 +224,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 +370,11 @@ 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}`)}`);
     }
   });
 });
@@ -406,16 +444,39 @@ define("threads", "List conversations in an inbox", "carlyemail threads me@carly
   });
 });
 
-define("reply", "Reply to a message", 'carlyemail reply me@x.com "<id@host>" --text "On it"', async (ctx) => {
-  const [inbox, id] = ctx.positional;
-  if (!inbox || !id) throw new UsageError("carlyemail reply <inbox> <message-id> --text ...");
+/** 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.
@@ -481,6 +542,33 @@ define("send-draft", "Send a draft that was written earlier", "carlyemail send-d
   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, () => {
@@ -495,6 +583,74 @@ define("webhooks", "List webhook endpoints", "carlyemail webhooks", async (ctx)
   });
 });
 
+/** Print a domain's records with each one's status. */
+function printRecords(ctx, domain) {
+  for (const r of domain.records || []) {
+    // The per-record status is the whole point: a stuck domain needs to say
+    // which record is wrong, not that something is.
+    const mark = r.status === "VALID" ? paint(32, "✓") : dim("·");
+    const priority = r.priority ? dim(` (priority ${r.priority})`) : "";
+    ctx.print(`  ${mark} ${dim(r.type.padEnd(5))} ${r.name}`);
+    ctx.print(`      ${dim("→")} ${r.value}${priority}`);
+  }
+}
+
+define(
+  "domain",
+  "Add a custom sending domain, or re-check one",
+  "carlyemail domain mail.yourcompany.com [--subdomains] [--check] [--zone]",
+  async (ctx) => {
+    const name = ctx.positional[0];
+    if (!name) throw new UsageError("carlyemail domain <name> [--check]");
+
+    /** `verify` and the zone file take an id; a person has a name. */
+    const findId = async () => {
+      const out = await request(ctx.config, "GET", "/v0/domains");
+      const found = (out.domains || []).find((d) => d.domain === name);
+      if (!found) throw new UsageError(`${name} is not on this account`);
+      return found.domain_id;
+    };
+
+    if (ctx.flags.zone) {
+      // Straight to stdout with nothing around it, so it can be redirected into
+      // a file and handed to a DNS provider's import button.
+      const id = await findId();
+      ctx.print(await request(ctx.config, "GET", `/v0/domains/${id}/zone-file`, { raw: true }));
+      return;
+    }
+
+    let domain = ctx.flags.check
+      ? await request(ctx.config, "POST", `/v0/domains/${await findId()}/verify`)
+      // `domain`, not `name`. The docs said `name` for months, which 422s.
+      : await request(ctx.config, "POST", "/v0/domains", {
+          body: { domain: name, subdomains_enabled: Boolean(ctx.flags.subdomains) },
+        });
+
+    // Create is idempotent and returns an existing domain unchanged. Make the
+    // flag useful there too: `domain example.com --subdomains` means enabled
+    // whether this is the first run or the fifth.
+    if (ctx.flags.subdomains && !domain.subdomains_enabled) {
+      domain = await request(ctx.config, "PATCH", `/v0/domains/${domain.domain_id}`, {
+        body: { subdomains_enabled: true },
+      });
+    }
+
+    emit(ctx, domain, () => {
+      const verified = domain.status === "VERIFIED";
+      ctx.print(`${verified ? paint(32, "✓") : dim("…")} ${bold(name)}  ${dim(domain.status)}`);
+      if (verified) {
+        ctx.print(dim(`  carlyemail create --username hello --domain ${name}`));
+        return;
+      }
+      ctx.print("");
+      printRecords(ctx, domain);
+      ctx.print("");
+      ctx.print(dim(`  publish these, then: carlyemail domain ${name} --check`));
+      ctx.print(dim(`  or take the file:    carlyemail domain ${name} --zone > ${name}.zone`));
+    });
+  }
+);
+
 define("domains", "List custom sending domains", "carlyemail domains", async (ctx) => {
   const out = await request(ctx.config, "GET", "/v0/domains");
   emit(ctx, out, () => {
@@ -566,6 +722,25 @@ define("mcp", "Print the MCP endpoint for Claude and other clients", "carlyemail
   ctx.print(dim("An API key works too: Authorization: Bearer <key>"));
 });
 
+define(
+  "env",
+  "Export this account for an agent framework",
+  'eval "$(carlyemail env)"',
+  async (ctx) => {
+    // Resolve the inbox through the active key instead of trusting saved CLI
+    // state. CARLYEMAIL_API_KEY may intentionally point at a different account,
+    // pod, or inbox than ~/.carlyemail/config.json.
+    const out = await request(ctx.config, "GET", "/v0/inboxes?limit=1&ascending=true");
+    const inbox = out?.inboxes?.[0]?.email;
+    if (!inbox) throw new UsageError("This key cannot see an inbox to export.");
+
+    // This command is the explicit escape hatch from the 0600 CLI config into
+    // a process environment. Normal commands continue to mask the credential.
+    ctx.print(`export CARLYEMAIL_API_KEY=${shellQuote(ctx.config.api_key)}`);
+    ctx.print(`export CARLYEMAIL_INBOX=${shellQuote(inbox)}`);
+  }
+);
+
 // ---------------------------------------------------------------- help
 
 export function helpText() {
@@ -583,8 +758,9 @@ export function helpText() {
   lines.push(
     "",
     bold("Getting started"),
-    "  carlyemail signup --human-email you@example.com --username my-agent",
+    "  carlyemail signup",
     "  carlyemail verify 123456",
+    '  eval "$(carlyemail env)"' + dim("  # load the key and inbox into this shell"),
     "  carlyemail send --from my-agent@agents.carlyemail.com \\",
     '      --to someone@example.com --subject Hi --text "Hello from an agent"',
     "",
@@ -603,7 +779,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();
 
@@ -629,7 +825,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,7 +1,7 @@
 {
   "name": "carlyemail",
-  "version": "0.2.0",
-  "description": "Real email inboxes your agent can send, receive and reply from.",
+  "version": "0.4.0",
+  "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",
     "agent",
@@ -24,9 +24,18 @@
   "bin": {
     "carlyemail": "./carlyemail.js"
   },
-  "exports": "./carlyemail.js",
+  "types": "./sdk.d.ts",
+  "exports": {
+    ".": "./sdk.js",
+    "./webhooks": "./webhooks.js",
+    "./cli": "./carlyemail.js"
+  },
   "files": [
     "carlyemail.js",
+    "sdk.js",
+    "sdk.d.ts",
+    "webhooks.js",
+    "webhooks.d.ts",
     "README.md",
     "LICENSE"
   ],