carlyemail 0.3.0 → 0.4.0

package/README.md

@@ -62,6 +62,13 @@ npx carlyemail send \
   --text "Sent by an agent with its own address."
 ```
 
+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
@@ -75,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 |
@@ -126,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.
@@ -152,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

@@ -18,7 +18,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");
@@ -40,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
 
 /**
@@ -109,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) {
@@ -146,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
@@ -571,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, () => {
@@ -642,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() {
@@ -661,6 +760,7 @@ export function helpText() {
     bold("Getting started"),
     "  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"',
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carlyemail",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",
@@ -27,12 +27,15 @@
   "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"
   ],

package/sdk.d.ts

@@ -1,5 +1,23 @@
 // Generated by scripts/build_sdk.py from the OpenAPI spec. Do not edit.
 
+export interface AgentSigninRequest {
+  human_email: string;
+}
+
+export interface AgentSigninResponse {
+  accepted?: boolean;
+}
+
+export interface AgentSigninVerifyRequest {
+  human_email: string;
+  otp_code: string;
+}
+
+export interface AgentSigninVerifyResponse {
+  organization_id: string;
+  api_key: string;
+}
+
 export interface AgentSignupRequest {
   human_email: string;
   username: string;
@@ -127,6 +145,7 @@ export interface CreateInboxWebhookRequest {
   url: string;
   event_types?: Array<string> | null;
   client_id?: string | null;
+  headers?: Record<string, string> | null;
 }
 
 export interface CreateListEntryRequest {
@@ -145,6 +164,7 @@ export interface CreateWebhookRequest {
   client_id?: string | null;
   inbox_ids?: Array<string> | null;
   pod_ids?: Array<string> | null;
+  headers?: Record<string, string> | null;
 }
 
 export interface DomainOut {
@@ -537,6 +557,11 @@ export interface UpdateThreadResponse {
   labels: Array<string>;
 }
 
+export interface UpdateWebhookHeadersRequest {
+  headers?: Record<string, string> | null;
+  remove_headers?: Array<string> | null;
+}
+
 export interface UpdateWebhookRequest {
   event_types?: Array<string> | null;
   add_inbox_ids?: Array<string> | null;
@@ -561,6 +586,10 @@ export interface VerificationRecord {
   priority?: number | null;
 }
 
+export interface WebhookHeadersResponse {
+  header_names: Array<string>;
+}
+
 export interface WebhookOut {
   webhook_id: string;
   url: string;
@@ -590,6 +619,8 @@ export interface ClientOptions {
 
 export declare class Agent {
   signUp(body: AgentSignupRequest): Promise<AgentSignupResponse>;
+  signIn(body: AgentSigninRequest): Promise<AgentSigninResponse>;
+  verifySignIn(body: AgentSigninVerifyRequest): Promise<AgentSigninVerifyResponse>;
   verify(body: AgentVerifyRequest): Promise<AgentVerifyResponse>;
 }
 
@@ -727,6 +758,8 @@ export declare class Pods {
   getWebhook(webhookId: string, podId: string): Promise<WebhookOut>;
   updateWebhook(webhookId: string, podId: string, body: UpdateWebhookRequest): Promise<WebhookOut>;
   deleteWebhook(webhookId: string, podId: string): Promise<void>;
+  getWebhookHeaders(webhookId: string, podId: string): Promise<WebhookHeadersResponse>;
+  updateWebhookHeaders(webhookId: string, podId: string, body: UpdateWebhookHeadersRequest): Promise<void>;
   listApiKeys(podId: string, query?: { limit?: number | null; pageToken?: string | null }): Promise<ListApiKeysResponse>;
   createApiKey(podId: string, body: CreateApiKeyRequest): Promise<CreateApiKeyResponse>;
   deleteApiKey(apiKeyId: string, podId: string): Promise<void>;
@@ -748,11 +781,15 @@ export declare class Webhooks {
   get(webhookId: string): Promise<WebhookOut>;
   update(webhookId: string, body: UpdateWebhookRequest): Promise<WebhookOut>;
   delete(webhookId: string): Promise<void>;
+  getWebhookHeaders(webhookId: string): Promise<WebhookHeadersResponse>;
+  updateWebhookHeaders(webhookId: string, body: UpdateWebhookHeadersRequest): Promise<void>;
   listInbox(inboxId: string, query?: { limit?: number | null; pageToken?: string | null; ascending?: boolean }): Promise<ListWebhooksResponse>;
   createInbox(inboxId: string, body: CreateInboxWebhookRequest): Promise<WebhookOut>;
   getInbox(inboxId: string, webhookId: string): Promise<WebhookOut>;
   updateInbox(inboxId: string, webhookId: string, body: UpdateInboxWebhookRequest): Promise<WebhookOut>;
   deleteInbox(inboxId: string, webhookId: string): Promise<void>;
+  getInboxWebhookHeaders(inboxId: string, webhookId: string): Promise<WebhookHeadersResponse>;
+  updateInboxWebhookHeaders(inboxId: string, webhookId: string, body: UpdateWebhookHeadersRequest): Promise<void>;
 }
 
 export declare class CarlyEmail {

package/sdk.js

@@ -22,18 +22,19 @@ const DEFAULT_BASE_URL = "https://api.carlyemail.com";
 
 class Transport {
   constructor(options = {}) {
-    const key =
+    // No key is a legal state: `agent.signUp` is how you get one, and demanding
+    // one to call it would be circular. Methods that need a key say so.
+    this.apiKey =
       options.apiKey ??
       (typeof process !== "undefined" ? process.env?.CARLYEMAIL_API_KEY : undefined);
-    if (!key) {
-      throw new Error("No API key. Pass { apiKey } or set CARLYEMAIL_API_KEY.");
-    }
-    this.apiKey = key;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.fetch = options.fetch ?? globalThis.fetch;
   }
 
-  async request(method, path, { query, body } = {}) {
+  async request(method, path, { query, body, auth = true } = {}) {
+    if (auth && !this.apiKey) {
+      throw new Error("No API key. Pass { apiKey } or set CARLYEMAIL_API_KEY.");
+    }
     const url = new URL(this.baseUrl + path);
     for (const [name, value] of Object.entries(query ?? {})) {
       if (value === undefined || value === null) continue;
@@ -47,7 +48,7 @@ class Transport {
     const response = await this.fetch(url, {
       method,
       headers: {
-        authorization: `Bearer ${this.apiKey}`,
+        ...(this.apiKey && auth ? { authorization: `Bearer ${this.apiKey}` } : {}),
         ...(body === undefined ? {} : { "content-type": "application/json" }),
       },
       body: body === undefined ? undefined : JSON.stringify(body),
@@ -74,7 +75,17 @@ class Agent {
 
   /** Sign Up */
   signUp(body) {
-    return this.$.request("POST", `/v0/agent/sign-up`, { body });
+    return this.$.request("POST", `/v0/agent/sign-up`, { body, auth: false });
+  }
+
+  /** Sign In */
+  signIn(body) {
+    return this.$.request("POST", `/v0/agent/sign-in`, { body, auth: false });
+  }
+
+  /** Verify Sign In */
+  verifySignIn(body) {
+    return this.$.request("POST", `/v0/agent/sign-in/verify`, { body, auth: false });
   }
 
   /** Verify */
@@ -663,6 +674,16 @@ class Pods {
     return this.$.request("DELETE", `/v0/pods/${encode(podId)}/webhooks/${encode(webhookId)}`);
   }
 
+  /** Get Webhook Headers */
+  getWebhookHeaders(webhookId, podId) {
+    return this.$.request("GET", `/v0/pods/${encode(podId)}/webhooks/${encode(webhookId)}/headers`);
+  }
+
+  /** Update Webhook Headers */
+  updateWebhookHeaders(webhookId, podId, body) {
+    return this.$.request("PATCH", `/v0/pods/${encode(podId)}/webhooks/${encode(webhookId)}/headers`, { body });
+  }
+
   /** List Api Keys */
   listApiKeys(podId, query = {}) {
     return this.$.request("GET", `/v0/pods/${encode(podId)}/api-keys`, { query: { "limit": query.limit, "page_token": query.pageToken } });
@@ -741,6 +762,16 @@ class Webhooks {
     return this.$.request("DELETE", `/v0/webhooks/${encode(webhookId)}`);
   }
 
+  /** Get Webhook Headers */
+  getWebhookHeaders(webhookId) {
+    return this.$.request("GET", `/v0/webhooks/${encode(webhookId)}/headers`);
+  }
+
+  /** Update Webhook Headers */
+  updateWebhookHeaders(webhookId, body) {
+    return this.$.request("PATCH", `/v0/webhooks/${encode(webhookId)}/headers`, { body });
+  }
+
   /** List Inbox Webhooks */
   listInbox(inboxId, query = {}) {
     return this.$.request("GET", `/v0/inboxes/${encode(inboxId)}/webhooks`, { query: { "limit": query.limit, "page_token": query.pageToken, "ascending": query.ascending } });
@@ -765,6 +796,16 @@ class Webhooks {
   deleteInbox(inboxId, webhookId) {
     return this.$.request("DELETE", `/v0/inboxes/${encode(inboxId)}/webhooks/${encode(webhookId)}`);
   }
+
+  /** Get Inbox Webhook Headers */
+  getInboxWebhookHeaders(inboxId, webhookId) {
+    return this.$.request("GET", `/v0/inboxes/${encode(inboxId)}/webhooks/${encode(webhookId)}/headers`);
+  }
+
+  /** Update Inbox Webhook Headers */
+  updateInboxWebhookHeaders(inboxId, webhookId, body) {
+    return this.$.request("PATCH", `/v0/inboxes/${encode(inboxId)}/webhooks/${encode(webhookId)}/headers`, { body });
+  }
 }
 
 export class CarlyEmail {

package/webhooks.d.ts

@@ -0,0 +1,35 @@
+export interface CarlyEmailEvent {
+  type: "event";
+  event_type: string;
+  event_id: string;
+  message?: Record<string, unknown>;
+  thread?: Record<string, unknown>;
+  send?: Record<string, unknown>;
+  delivery?: Record<string, unknown>;
+  bounce?: Record<string, unknown>;
+  complaint?: Record<string, unknown>;
+  reject?: Record<string, unknown>;
+  domain?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface VerifyWebhookOptions {
+  toleranceSeconds?: number;
+  /** Unix timestamp in seconds; intended for deterministic tests. */
+  now?: number;
+}
+
+export declare class WebhookVerificationError extends Error {}
+
+export declare function verifyWebhook(
+  secret: string,
+  body: string | Uint8Array | ArrayBuffer,
+  headers: Headers | Record<string, string>,
+  options?: VerifyWebhookOptions,
+): Promise<CarlyEmailEvent>;
+
+export declare function createEmailHandler(options: {
+  secret: string;
+  onEmail: (event: CarlyEmailEvent, request: Request) => unknown | Promise<unknown>;
+  toleranceSeconds?: number;
+}): (request: Request) => Promise<Response>;

package/webhooks.js

@@ -0,0 +1,110 @@
+// Webhook verification and an email-channel handler for Workers, Node, and edge
+// runtimes. Web Crypto only; no Node-specific imports and no dependencies.
+
+export class WebhookVerificationError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "WebhookVerificationError";
+  }
+}
+
+function header(headers, name) {
+  if (typeof headers?.get === "function") return headers.get(name);
+  const wanted = name.toLowerCase();
+  const found = Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === wanted);
+  return found?.[1];
+}
+
+function bytes(value) {
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  throw new TypeError("webhook body must be a string, Uint8Array, or ArrayBuffer");
+}
+
+function decodeBase64(value, label) {
+  try {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  } catch (error) {
+    throw new WebhookVerificationError(`${label} is not valid base64`, { cause: error });
+  }
+}
+
+/**
+ * Verify a CarlyEmail/Svix webhook and return its parsed event body.
+ *
+ * The unmodified raw body is required. A framework-parsed JSON object cannot be
+ * reconstructed byte-for-byte and will fail the signature by design.
+ */
+export async function verifyWebhook(secret, body, headers, options = {}) {
+  const messageId = header(headers, "webhook-id") ?? header(headers, "svix-id");
+  const timestamp = header(headers, "webhook-timestamp") ?? header(headers, "svix-timestamp");
+  const signatures =
+    header(headers, "webhook-signature") ?? header(headers, "svix-signature");
+  if (!messageId || !timestamp || !signatures) {
+    throw new WebhookVerificationError("missing webhook signature headers");
+  }
+
+  const sentAt = Number(timestamp);
+  if (!Number.isSafeInteger(sentAt)) {
+    throw new WebhookVerificationError("webhook timestamp is not an integer");
+  }
+  const now = options.now ?? Math.floor(Date.now() / 1000);
+  const toleranceSeconds = options.toleranceSeconds ?? 300;
+  if (Math.abs(now - sentAt) > toleranceSeconds) {
+    throw new WebhookVerificationError("webhook timestamp is outside the allowed window");
+  }
+
+  const rawBody = bytes(body);
+  const prefix = new TextEncoder().encode(`${messageId}.${timestamp}.`);
+  const signed = new Uint8Array(prefix.length + rawBody.length);
+  signed.set(prefix);
+  signed.set(rawBody, prefix.length);
+  const keyBytes = decodeBase64(secret.replace(/^whsec_/, ""), "webhook secret");
+  const key = await crypto.subtle.importKey(
+    "raw",
+    keyBytes,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"],
+  );
+
+  for (const candidate of signatures.split(/\s+/)) {
+    const [version, encoded] = candidate.split(",", 2);
+    if (version !== "v1" || !encoded) continue;
+    const signature = decodeBase64(encoded, "webhook signature");
+    if (await crypto.subtle.verify("HMAC", key, signature, signed)) {
+      return JSON.parse(new TextDecoder().decode(rawBody));
+    }
+  }
+  throw new WebhookVerificationError("webhook signature does not match");
+}
+
+/**
+ * Build a fetch-compatible handler with a Cloudflare-style `onEmail(event)`
+ * callback. Handler errors are allowed through so the delivery gets a 5xx and
+ * retries; only verification errors are turned into terminal 400 responses.
+ */
+export function createEmailHandler({ secret, onEmail, toleranceSeconds = 300 }) {
+  if (!secret) throw new Error("createEmailHandler requires a webhook secret");
+  if (typeof onEmail !== "function") throw new TypeError("createEmailHandler requires onEmail");
+
+  return async function handle(request) {
+    const body = new Uint8Array(await request.arrayBuffer());
+    let event;
+    try {
+      event = await verifyWebhook(secret, body, request.headers, { toleranceSeconds });
+    } catch (error) {
+      if (error instanceof WebhookVerificationError) {
+        return new Response(error.message, { status: 400 });
+      }
+      throw error;
+    }
+
+    if (event.event_type?.startsWith("message.received")) {
+      await onEmail(event, request);
+    }
+    return new Response(null, { status: 204 });
+  };
+}