carlyemail 0.6.0 → 0.6.3

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.0";
+export const VERSION = "0.6.3";
 
 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"],
+  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 = {};
@@ -244,8 +349,8 @@ async function startSignin(ctx, human_email, { known = false } = {}) {
   ctx.print(
     arrow(
       known
-        ? `a sign-in code is on its way to ${human_email} (good for 10 minutes), then:`
-        : `if ${human_email} has an account, a code is on its way (good for 10 minutes), then:`
+        ? `a sign-in code is on its way to ${human_email} (good for 30 minutes), then:`
+        : `if ${human_email} has an account, a code is on its way (good for 30 minutes), then:`
     )
   );
   ctx.print(`    carlyemail verify <code>`);
@@ -434,14 +539,18 @@ define("delete", "Delete an inbox and its mail", "carlyemail delete support@carl
 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 +722,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 +1031,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.0",
+  "version": "0.6.3",
   "description": "Real email inboxes your agent can send, receive and reply from. SDK and CLI.",
   "keywords": [
     "email",
@@ -13,11 +13,16 @@
   ],
   "homepage": "https://docs.carlyemail.com",
   "bugs": "https://docs.carlyemail.com/support",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shirschfield/carlyemail.git",
+    "directory": "cli"
+  },
   "license": "MIT",
   "author": "SWH Labs LLC",
   "type": "module",
   "bin": {
-    "carlyemail": "./carlyemail.js"
+    "carlyemail": "carlyemail.js"
   },
   "types": "./sdk.d.ts",
   "exports": {

package/sdk.d.ts

@@ -16,6 +16,8 @@ export interface AgentSigninVerifyRequest {
 export interface AgentSigninVerifyResponse {
   organization_id: string;
   api_key: string;
+  inbox_domain?: string | null;
+  inboxes_on_signup_domain?: Array<string>;
 }
 
 export interface AgentSignupRequest {
@@ -39,6 +41,8 @@ export interface AgentVerifyRequest {
 export interface AgentVerifyResponse {
   organization_id: string;
   verified: boolean;
+  inbox_domain?: string | null;
+  inboxes_on_signup_domain?: Array<string>;
 }
 
 export interface ApiKeyOut {
@@ -50,6 +54,7 @@ export interface ApiKeyOut {
   used_at?: string | null;
   permissions?: Record<string, boolean> | null;
   created_at: string;
+  expires_at?: string | null;
 }
 
 export interface AttachmentOut {
@@ -97,6 +102,7 @@ export interface BatchUpdateMessagesResponse {
 export interface CreateApiKeyRequest {
   name?: string | null;
   permissions?: Record<string, boolean> | null;
+  expires_at?: string | null;
 }
 
 export interface CreateApiKeyResponse {
@@ -108,6 +114,7 @@ export interface CreateApiKeyResponse {
   inbox_id?: string | null;
   permissions?: Record<string, boolean> | null;
   created_at: string;
+  expires_at?: string | null;
 }
 
 export interface CreateDomainRequest {
@@ -204,6 +211,26 @@ export interface DraftOut {
   created_at: string;
 }
 
+export interface EventOut {
+  event_id: string;
+  event_type: string;
+  organization_id: string;
+  pod_id?: string | null;
+  inbox_id?: string | null;
+  message_id?: string | null;
+  thread_id?: string | null;
+  payload?: Record<string, unknown>;
+  created_at: string;
+}
+
+export interface FeedbackRequest {
+  message: string;
+}
+
+export interface FeedbackResponse {
+  received: boolean;
+}
+
 export interface ForwardMessageRequest {
   to?: Array<string> | string | null;
   cc?: Array<string> | string | null;
@@ -286,6 +313,13 @@ export interface ListEntryOut {
   created_at: string;
 }
 
+export interface ListEventsResponse {
+  count: number;
+  limit?: number | null;
+  next_page_token?: string | null;
+  events: Array<EventOut>;
+}
+
 export interface ListInboxEventsResponse {
   count: number;
   limit?: number | null;
@@ -328,6 +362,11 @@ export interface ListThreadsResponse {
   threads: Array<ThreadItem>;
 }
 
+export interface ListWebhookAttemptsResponse {
+  count: number;
+  attempts: Array<WebhookAttemptOut>;
+}
+
 export interface ListWebhooksResponse {
   count: number;
   limit?: number | null;
@@ -378,6 +417,7 @@ export interface MessageOut {
   in_reply_to?: string | null;
   references?: Array<string>;
   headers?: Record<string, unknown>;
+  authentication?: Record<string, string>;
 }
 
 export interface OrganizationOut {
@@ -587,6 +627,19 @@ export interface VerificationRecord {
   priority?: number | null;
 }
 
+export interface WebhookAttemptOut {
+  attempt_id: string;
+  webhook_id: string;
+  event_id: string;
+  event_type: string;
+  url: string;
+  status_code?: number | null;
+  ok: boolean;
+  detail?: string | null;
+  duration_ms: number;
+  created_at: string;
+}
+
 export interface WebhookHeadersResponse {
   header_names: Array<string>;
 }
@@ -635,6 +688,10 @@ export declare class Billing {
   current(): Promise<Record<string, unknown>>;
 }
 
+export declare class Feedback {
+  send(body: FeedbackRequest): Promise<FeedbackResponse>;
+}
+
 export declare class Inboxes {
   list(query?: { limit?: number | null; pageToken?: string | null; ascending?: boolean }): Promise<ListInboxesResponse>;
   create(body: CreateInboxRequest): Promise<InboxOut>;
@@ -717,6 +774,10 @@ export declare class ApiKeys {
   deleteInbox(inboxId: string, apiKeyId: string): Promise<void>;
 }
 
+export declare class Events {
+  list(query?: { eventTypes?: Array<string> | null; inboxId?: string | null; start?: string | null; end?: string | null; limit?: number | null; pageToken?: string | null }): Promise<ListEventsResponse>;
+}
+
 export declare class Metrics {
   orgEvents(query?: { eventTypes?: Array<string> | null; start?: string | null; end?: string | null; period?: number | null; limit?: number | null; descending?: boolean }): Promise<Record<string, unknown>>;
   orgUsage(query?: { usageTypes?: Array<string> | null; start?: string | null; end?: string | null; period?: number | null; limit?: number | null; descending?: boolean }): Promise<Record<string, unknown>>;
@@ -779,6 +840,8 @@ export declare class InboxEvents {
 export declare class Webhooks {
   list(query?: { limit?: number | null; pageToken?: string | null; ascending?: boolean }): Promise<ListWebhooksResponse>;
   create(body: CreateWebhookRequest): Promise<WebhookOut>;
+  listAllAttempts(query?: { limit?: number }): Promise<ListWebhookAttemptsResponse>;
+  listAttempts(webhookId: string, query?: { limit?: number }): Promise<ListWebhookAttemptsResponse>;
   get(webhookId: string): Promise<WebhookOut>;
   update(webhookId: string, body: UpdateWebhookRequest): Promise<WebhookOut>;
   delete(webhookId: string): Promise<void>;
@@ -798,6 +861,7 @@ export declare class CarlyEmail {
   agent: Agent;
   auth: Auth;
   billing: Billing;
+  feedback: Feedback;
   inboxes: Inboxes;
   messages: Messages;
   threads: Threads;
@@ -805,6 +869,7 @@ export declare class CarlyEmail {
   lists: Lists;
   domains: Domains;
   apiKeys: ApiKeys;
+  events: Events;
   metrics: Metrics;
   pods: Pods;
   organizations: Organizations;

package/sdk.js

@@ -126,6 +126,17 @@ class Billing {
   }
 }
 
+class Feedback {
+  constructor(transport) {
+    this.$ = transport;
+  }
+
+  /** Send Feedback */
+  send(body) {
+    return this.$.request("POST", `/v0/feedback`, { body });
+  }
+}
+
 class Inboxes {
   constructor(transport) {
     this.$ = transport;
@@ -473,6 +484,17 @@ class ApiKeys {
   }
 }
 
+class Events {
+  constructor(transport) {
+    this.$ = transport;
+  }
+
+  /** List Events */
+  list(query = {}) {
+    return this.$.request("GET", `/v0/events`, { query: { "event_types": query.eventTypes, "inbox_id": query.inboxId, "start": query.start, "end": query.end, "limit": query.limit, "page_token": query.pageToken } });
+  }
+}
+
 class Metrics {
   constructor(transport) {
     this.$ = transport;
@@ -747,6 +769,16 @@ class Webhooks {
     return this.$.request("POST", `/v0/webhooks`, { body });
   }
 
+  /** List All Attempts */
+  listAllAttempts(query = {}) {
+    return this.$.request("GET", `/v0/webhooks/attempts`, { query: { "limit": query.limit } });
+  }
+
+  /** List Attempts */
+  listAttempts(webhookId, query = {}) {
+    return this.$.request("GET", `/v0/webhooks/${encode(webhookId)}/attempts`, { query: { "limit": query.limit } });
+  }
+
   /** Get Webhook */
   get(webhookId) {
     return this.$.request("GET", `/v0/webhooks/${encode(webhookId)}`);
@@ -814,6 +846,7 @@ export class CarlyEmail {
     this.agent = new Agent(transport);
     this.auth = new Auth(transport);
     this.billing = new Billing(transport);
+    this.feedback = new Feedback(transport);
     this.inboxes = new Inboxes(transport);
     this.messages = new Messages(transport);
     this.threads = new Threads(transport);
@@ -821,6 +854,7 @@ export class CarlyEmail {
     this.lists = new Lists(transport);
     this.domains = new Domains(transport);
     this.apiKeys = new ApiKeys(transport);
+    this.events = new Events(transport);
     this.metrics = new Metrics(transport);
     this.pods = new Pods(transport);
     this.organizations = new Organizations(transport);