carlyemail 0.2.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

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.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,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 +432,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 +530,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, () => {
@@ -583,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"',
@@ -603,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();
 
@@ -629,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,7 +1,7 @@
 {
   "name": "carlyemail",
-  "version": "0.2.0",
-  "description": "Real email inboxes your agent can send, receive and reply from.",
+  "version": "0.3.0",
+  "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",
     "agent",
@@ -24,9 +24,15 @@
   "bin": {
     "carlyemail": "./carlyemail.js"
   },
-  "exports": "./carlyemail.js",
+  "types": "./sdk.d.ts",
+  "exports": {
+    ".": "./sdk.js",
+    "./cli": "./carlyemail.js"
+  },
   "files": [
     "carlyemail.js",
+    "sdk.js",
+    "sdk.d.ts",
     "README.md",
     "LICENSE"
   ],