carlyemail 0.6.2 → 0.6.4

package/README.md

@@ -86,7 +86,7 @@ npm install -g carlyemail
 | `inboxes` | List inboxes |
 | `create --username <u>` | Create an inbox |
 | `delete <inbox> --yes` | Delete an inbox and its mail |
-| `send --from <i> --to <a> --subject <s> --text <t>` | Send an email |
+| `send --from <i> --to <a> --subject <s> --text <t>` | Send an email (also `--cc`, `--bcc`, `--reply-to`, `--attach <file>`) |
 | `messages <inbox>` | List messages |
 | `read <inbox> <id>` | Read one message in full |
 | `search <inbox> <text>` | Search messages |

package/carlyemail.js

@@ -14,11 +14,11 @@
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 
-export const VERSION = "0.6.2";
+export const VERSION = "0.6.4";
 
 const DEFAULT_API = "https://api.carlyemail.com";
 const CONFIG_DIR = join(homedir(), ".carlyemail");
@@ -171,6 +171,11 @@ export async function request(
 export function parseArgs(argv) {
   const flags = {};
   const positional = [];
+  // A flag given twice keeps both values, as an array. Last-one-wins would
+  // silently drop the first `--attach`.
+  const set = (name, value) => {
+    flags[name] = Object.hasOwn(flags, name) ? [].concat(flags[name], value) : value;
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (!arg.startsWith("--")) {
@@ -179,11 +184,11 @@ export function parseArgs(argv) {
     }
     const equals = arg.indexOf("=");
     if (equals !== -1) {
-      flags[arg.slice(2, equals)] = arg.slice(equals + 1);
+      set(arg.slice(2, equals), arg.slice(equals + 1));
     } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
-      flags[arg.slice(2)] = argv[++i];
+      set(arg.slice(2), argv[++i]);
     } else {
-      flags[arg.slice(2)] = true;
+      set(arg.slice(2), true);
     }
   }
   return { flags, positional };
@@ -197,6 +202,106 @@ function required(flags, name) {
   return value;
 }
 
+/**
+ * An address flag. Commas and repeats both work, so `--cc a@x.com,b@y.com` and
+ * `--cc a@x.com --cc b@y.com` send the same message.
+ */
+function addresses(flags, name, { require = false } = {}) {
+  const value = flags[name];
+  if (value === undefined) {
+    if (require) throw new UsageError(`--${name} is required`);
+    return undefined;
+  }
+  const given = [].concat(value);
+  if (given.some((v) => typeof v !== "string")) throw new UsageError(`--${name} needs an address`);
+  const list = given.flatMap((v) => v.split(",")).map((s) => s.trim()).filter(Boolean);
+  if (!list.length) throw new UsageError(`--${name} needs an address`);
+  return list;
+}
+
+/**
+ * Enough types that a PDF or a photo arrives as one. Anything not listed goes
+ * without a type and the API sends it as application/octet-stream.
+ */
+const CONTENT_TYPES = {
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".csv": "text/csv",
+  ".html": "text/html",
+  ".json": "application/json",
+  ".ics": "text/calendar",
+  ".zip": "application/zip",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+};
+
+/** Every `--attach <file>`, read and base64-encoded the way the API takes it. */
+function attachments(flags) {
+  if (flags.attach === undefined) return undefined;
+  return [].concat(flags.attach).map((path) => {
+    if (typeof path !== "string" || !path) throw new UsageError("--attach needs a file");
+    let content;
+    try {
+      content = readFileSync(path);
+    } catch (error) {
+      throw new UsageError(`cannot read ${path} (${error.code ?? error.message})`);
+    }
+    return {
+      filename: basename(path),
+      content_type: CONTENT_TYPES[extname(path).toLowerCase()],
+      content: content.toString("base64"),
+    };
+  });
+}
+
+/**
+ * The flags each command reads, beyond the global --json, --help and --version.
+ *
+ * Anything else is refused before a request is made. `send` used to accept
+ * `--cc` and `--attach` and ignore them, so the message went out without its
+ * copy or its file and the command still printed "sent". A test checks this
+ * table against the flags each command's code actually reads.
+ */
+const FLAGS = {
+  signup: ["human-email", "username", "display-name"],
+  signin: ["human-email"],
+  verify: ["code"],
+  create: ["username", "domain", "display-name"],
+  delete: ["yes", "force"],
+  send: ["from", "to", "cc", "bcc", "reply-to", "subject", "text", "html", "attach"],
+  search: ["query"],
+  reply: ["last", "text", "html", "all"],
+  draft: ["to", "subject", "text"],
+  webhook: ["events"],
+  domain: ["zone", "check", "subdomains"],
+  upgrade: ["plan"],
+};
+const GLOBAL_FLAGS = ["json", "help", "version"];
+const REPEATABLE = new Set(["to", "cc", "bcc", "reply-to", "attach"]);
+
+/** Why these flags cannot be run with this command, or null when they can. */
+export function refusedFlag(commandName, flags) {
+  const own = FLAGS[commandName] ?? [];
+  for (const [name, value] of Object.entries(flags)) {
+    if (!GLOBAL_FLAGS.includes(name) && !own.includes(name)) {
+      const takes = own.length ? own.map((f) => `--${f}`).join(", ") : "no options";
+      return `${commandName} has no --${name} option (it takes ${takes})`;
+    }
+    if (Array.isArray(value) && !REPEATABLE.has(name)) {
+      return `--${name} was given more than once`;
+    }
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------- commands
 
 const commands = {};
@@ -419,7 +524,7 @@ define(
   }
 );
 
-define("delete", "Delete an inbox and its mail", "carlyemail delete support@carlyemail.com", async (ctx) => {
+define("delete", "Delete an inbox and its mail", "carlyemail delete support@carlyemail.com --yes", async (ctx) => {
   const inbox = ctx.positional[0];
   if (!inbox) throw new UsageError("which inbox? carlyemail delete <inbox>");
   if (!ctx.flags.yes) {
@@ -427,21 +532,37 @@ define("delete", "Delete an inbox and its mail", "carlyemail delete support@carl
       `this deletes ${inbox} and every message in it. Re-run with --yes to confirm.`
     );
   }
-  await request(ctx.config, "DELETE", `/v0/inboxes/${encodeURIComponent(inbox)}`);
+  // An inbox that sent mail or whose key was used in the last 30 days is
+  // refused with `inbox_in_use`, and the API's fix names its own parameter.
+  // Here the answer is a flag, so say that instead.
+  const force = ctx.flags.force === true;
+  const path = `/v0/inboxes/${encodeURIComponent(inbox)}${force ? "?force=true" : ""}`;
+  try {
+    await request(ctx.config, "DELETE", path);
+  } catch (error) {
+    if (error instanceof ApiError && error.code === "inbox_in_use") {
+      error.fix = "Check nothing still sends from it. To delete it anyway, re-run with --force.";
+    }
+    throw error;
+  }
   ctx.print(ok(`deleted ${inbox}`));
 });
 
 define(
   "send",
   "Send an email",
-  'carlyemail send --from me@carlyemail.com --to you@example.com --subject Hi --text "Hello"',
+  'carlyemail send --from me@carlyemail.com --to you@example.com --subject Hi --text "Hello" [--cc a,b] [--bcc a] [--attach file]',
   async (ctx) => {
     const from = required(ctx.flags, "from");
     const body = {
-      to: required(ctx.flags, "to").split(",").map((s) => s.trim()),
+      to: addresses(ctx.flags, "to", { require: true }),
+      cc: addresses(ctx.flags, "cc"),
+      bcc: addresses(ctx.flags, "bcc"),
+      reply_to: addresses(ctx.flags, "reply-to"),
       subject: typeof ctx.flags.subject === "string" ? ctx.flags.subject : undefined,
       text: typeof ctx.flags.text === "string" ? ctx.flags.text : undefined,
       html: typeof ctx.flags.html === "string" ? ctx.flags.html : undefined,
+      attachments: attachments(ctx.flags),
     };
     const sent = await request(
       ctx.config,
@@ -613,7 +734,7 @@ define(
     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()),
+      to: addresses(ctx.flags, "to", { require: true }),
       subject: typeof ctx.flags.subject === "string" ? ctx.flags.subject : undefined,
       text: typeof ctx.flags.text === "string" ? ctx.flags.text : undefined,
     };
@@ -922,6 +1043,14 @@ export async function main(
     return 1;
   }
 
+  // Before the config is read, and so before anything can be sent.
+  const refused = refusedFlag(name, flags);
+  if (refused) {
+    print(`${paint(31, "✗")} ${refused}`);
+    print(dim(`  ${command.usage}`));
+    return 1;
+  }
+
   const config = loadConfig(env, configFile);
   try {
     await command.run({ config, flags, positional, print, ask, configFile, configDir });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carlyemail",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",

package/sdk.d.ts

@@ -576,6 +576,7 @@ export interface UpdateInboxRequest {
 
 export interface UpdateInboxWebhookRequest {
   event_types?: Array<string> | null;
+  enabled?: boolean | null;
 }
 
 export interface UpdateMessageRequest {
@@ -605,6 +606,7 @@ export interface UpdateWebhookHeadersRequest {
 
 export interface UpdateWebhookRequest {
   event_types?: Array<string> | null;
+  enabled?: boolean | null;
   add_inbox_ids?: Array<string> | null;
   remove_inbox_ids?: Array<string> | null;
   add_pod_ids?: Array<string> | null;
@@ -652,6 +654,9 @@ export interface WebhookOut {
   inbox_ids?: Array<string>;
   secret?: string | null;
   enabled?: boolean;
+  disabled_reason?: string | null;
+  disabled_at?: string | null;
+  failing_since?: string | null;
   client_id?: string | null;
   updated_at: string;
   created_at: string;
@@ -697,7 +702,7 @@ export declare class Inboxes {
   create(body: CreateInboxRequest): Promise<InboxOut>;
   get(inboxId: string): Promise<InboxOut>;
   update(inboxId: string, body: UpdateInboxRequest): Promise<InboxOut>;
-  delete(inboxId: string): Promise<void>;
+  delete(inboxId: string, query?: { force?: boolean }): Promise<void>;
 }
 
 export declare class Messages {
@@ -794,7 +799,7 @@ export declare class Pods {
   createInbox(podId: string, body: CreateInboxRequest): Promise<InboxOut>;
   getInbox(inboxId: string, podId: string): Promise<InboxOut>;
   updateInbox(inboxId: string, podId: string, body: UpdateInboxRequest): Promise<InboxOut>;
-  deleteInbox(inboxId: string, podId: string): Promise<void>;
+  deleteInbox(inboxId: string, podId: string, query?: { force?: boolean }): Promise<void>;
   listThreads(podId: string, query?: { limit?: number | null; pageToken?: string | null; labels?: Array<string> | null; before?: string | null; after?: string | null; ascending?: boolean; includeSpam?: boolean; includeBlocked?: boolean; includeUnauthenticated?: boolean; includeTrash?: boolean; senders?: Array<string> | null; recipients?: Array<string> | null; subject?: string | null }): Promise<ListThreadsResponse>;
   searchThreads(podId: string, query?: { q?: string; limit?: number | null; pageToken?: string | null; before?: string | null; after?: string | null }): Promise<ListThreadsResponse>;
   getThread(threadId: string, podId: string): Promise<ThreadOut>;

package/sdk.js

@@ -163,8 +163,8 @@ class Inboxes {
   }
 
   /** Delete Inbox */
-  delete(inboxId) {
-    return this.$.request("DELETE", `/v0/inboxes/${encode(inboxId)}`);
+  delete(inboxId, query = {}) {
+    return this.$.request("DELETE", `/v0/inboxes/${encode(inboxId)}`, { query: { "force": query.force } });
   }
 }
 
@@ -567,8 +567,8 @@ class Pods {
   }
 
   /** Delete Inbox */
-  deleteInbox(inboxId, podId) {
-    return this.$.request("DELETE", `/v0/pods/${encode(podId)}/inboxes/${encode(inboxId)}`);
+  deleteInbox(inboxId, podId, query = {}) {
+    return this.$.request("DELETE", `/v0/pods/${encode(podId)}/inboxes/${encode(inboxId)}`, { query: { "force": query.force } });
   }
 
   /** List Threads */