@vellumai/assistant 0.6.4 → 0.6.5

package/src/cli/commands/email.ts

@@ -1,4 +1,9 @@
-import { createWriteStream, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  createWriteStream,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { basename, join } from "node:path";
 import type { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -233,12 +238,15 @@ current usage and quota information from the platform.
 
 Examples:
   $ assistant email status
-  Address: mybot@${domain}
-  Status:  active
-  Sent:    12 / 100 (daily)
+  Address:  hi@mybot.${domain}
+  Status:   active
+  Since:    2026-04-15
+  Sent:     12 / 100 (daily)
+  Received: 5 (today)
+  Monthly:  42 sent, 18 received
 
   $ assistant email status --json
-  {"address":"mybot@${domain}","status":"active","usage":{"sent_today":12,"daily_limit":100}}`,
+  {"address":"hi@mybot.${domain}","status":"active","created_at":"2026-04-15T...","usage":{...}}`,
     )
     .action(async (_opts: unknown, cmd: Command) => {
       try {
@@ -294,23 +302,30 @@ Examples:
         const statusData = (await statusResponse.json()) as {
           address: string;
           status: string;
+          created_at: string;
           usage: {
             sent_today: number;
             daily_limit: number;
             received_today: number;
+            sent_this_month: number;
+            received_this_month: number;
           };
         };
 
         if (shouldOutputJson(cmd)) {
           writeOutput(cmd, statusData);
         } else {
-          log.info(`Address: ${statusData.address}`);
-          log.info(`Status:  ${statusData.status}`);
+          log.info(`Address:  ${statusData.address}`);
+          log.info(`Status:   ${statusData.status}`);
+          log.info(`Since:    ${statusData.created_at.split("T")[0]}`);
           if (statusData.usage) {
             log.info(
-              `Sent:    ${statusData.usage.sent_today} / ${statusData.usage.daily_limit} (daily)`,
+              `Sent:     ${statusData.usage.sent_today} / ${statusData.usage.daily_limit} (daily)`,
+            );
+            log.info(`Received: ${statusData.usage.received_today} (today)`);
+            log.info(
+              `Monthly:  ${statusData.usage.sent_this_month} sent, ${statusData.usage.received_this_month} received`,
             );
-            log.info(`Received today: ${statusData.usage.received_today}`);
           }
         }
       } catch (err) {
@@ -569,12 +584,24 @@ Examples:
     );
 
   email
-    .command("send <to>")
+    .command("send <to...>")
     .description("Send an email from this assistant")
     .option("-s, --subject <text>", "Subject line")
     .option("-b, --body <text>", "Email body (plain text)")
     .option("-f, --file <path>", "Read body from file")
     .option("--html <path>", "HTML body file (optional)")
+    .option(
+      "--cc <address>",
+      "CC recipient (repeatable)",
+      (val: string, prev: string[]) => [...prev, val],
+      [] as string[],
+    )
+    .option(
+      "--bcc <address>",
+      "BCC recipient (repeatable)",
+      (val: string, prev: string[]) => [...prev, val],
+      [] as string[],
+    )
     .option(
       "--reply-to <email_id>",
       "Reply to an email by its ID (auto-resolves threading headers and subject)",
@@ -583,7 +610,7 @@ Examples:
       "after",
       `
 Arguments:
-  to   Recipient email address
+  to   Recipient email address(es) — one or more
 
 Sends an email from the assistant's registered email address via the
 Vellum runtime proxy. The "from" address is automatically resolved
@@ -599,10 +626,13 @@ Examples:
   $ assistant email send user@example.com -s "Hello" -b "Hi there"
   ✓ Sent to user@example.com (delivery_id: abc123)
 
-  $ assistant email send user@example.com -b "Thanks!" --reply-to 019d96e4-e5d2-7201-890e-04a21e8f95bb
+  $ assistant email send a@example.com b@example.com --cc c@example.com -s "Team" -b "Hi all"
+  ✓ Sent to a@example.com, b@example.com (delivery_id: abc123)
+
+  $ assistant email send user@example.com --bcc boss@example.com -s "FYI" -b "See below"
   ✓ Sent to user@example.com (delivery_id: def456)
 
-  $ echo "Body text" | assistant email send user@example.com -s "Hello"
+  $ assistant email send user@example.com -b "Thanks!" --reply-to 019d96e4-e5d2-7201-890e-04a21e8f95bb
   ✓ Sent to user@example.com (delivery_id: ghi789)
 
   $ assistant email send user@example.com -s "Hello" -b "Hi" --json
@@ -610,12 +640,14 @@ Examples:
     )
     .action(
       async (
-        to: string,
+        to: string[],
         opts: {
           subject?: string;
           body?: string;
           file?: string;
           html?: string;
+          cc?: string[];
+          bcc?: string[];
           replyTo?: string;
         },
         cmd: Command,
@@ -681,13 +713,15 @@ Examples:
           }
 
           // 4. Build payload
-          const payload: Record<string, string> = {
+          const payload: Record<string, unknown> = {
             to,
             from_address: fromAddress,
             text,
           };
           if (opts.subject) payload.subject = opts.subject;
           if (html) payload.html = html;
+          if (opts.cc && opts.cc.length > 0) payload.cc = opts.cc;
+          if (opts.bcc && opts.bcc.length > 0) payload.bcc = opts.bcc;
           if (opts.replyTo) payload.reply_to = opts.replyTo;
 
           // 5. Send via runtime proxy
@@ -702,6 +736,11 @@ Examples:
               string,
               unknown
             >;
+            if (response.status === 402) {
+              throw new Error(
+                "Insufficient balance to send email. Add credits at https://platform.vellum.ai/billing",
+              );
+            }
             const detail = body.detail ?? `HTTP ${response.status}`;
             throw new Error(String(detail));
           }
@@ -714,7 +753,9 @@ Examples:
           if (shouldOutputJson(cmd)) {
             writeOutput(cmd, data);
           } else {
-            log.info(`✓ Sent to ${to} (delivery_id: ${data.delivery_id})`);
+            log.info(
+              `✓ Sent to ${to.join(", ")} (delivery_id: ${data.delivery_id})`,
+            );
           }
         } catch (err) {
           const message = err instanceof Error ? err.message : String(err);
@@ -728,19 +769,19 @@ Examples:
       },
     );
 
-email
-  .command("attachment <message-id> [attachment-id]")
-  .description("Download email attachments")
-  .option("--all", "Download all attachments for the message")
-  .option(
-    "-o, --output <dir>",
-    "Output directory (default: current directory)",
-    ".",
-  )
-  .option("--list", "List attachments without downloading")
-  .addHelpText(
-    "after",
-    `
+  email
+    .command("attachment <message-id> [attachment-id]")
+    .description("Download email attachments")
+    .option("--all", "Download all attachments for the message")
+    .option(
+      "-o, --output <dir>",
+      "Output directory (default: current directory)",
+      ".",
+    )
+    .option("--list", "List attachments without downloading")
+    .addHelpText(
+      "after",
+      `
 Arguments:
 message-id      Email message ID (from \`assistant email list --json\`)
 attachment-id   Attachment ID (optional — required unless --all or --list)
@@ -755,206 +796,205 @@ $ assistant email attachment msg_abc1 att_xyz1 -o ./downloads/
 $ assistant email attachment msg_abc1 --all
 $ assistant email attachment msg_abc1 --all -o ./attachments/
 $ assistant email attachment msg_abc1 --list --json`,
-  )
-  .action(
-    async (
-      messageId: string,
-      attachmentId: string | undefined,
-      opts: {
-        all?: boolean;
-        output?: string;
-        list?: boolean;
-      },
-      cmd: Command,
-    ) => {
-      try {
-        const client = await VellumPlatformClient.create();
-        if (!client) {
-          throw new Error(
-            "Platform credentials not configured. Run: assistant platform connect",
-          );
-        }
-        if (!client.platformAssistantId) {
-          throw new Error(
-            "Assistant ID not configured. Set PLATFORM_ASSISTANT_ID or run: assistant platform connect",
-          );
-        }
+    )
+    .action(
+      async (
+        messageId: string,
+        attachmentId: string | undefined,
+        opts: {
+          all?: boolean;
+          output?: string;
+          list?: boolean;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          const client = await VellumPlatformClient.create();
+          if (!client) {
+            throw new Error(
+              "Platform credentials not configured. Run: assistant platform connect",
+            );
+          }
+          if (!client.platformAssistantId) {
+            throw new Error(
+              "Assistant ID not configured. Set PLATFORM_ASSISTANT_ID or run: assistant platform connect",
+            );
+          }
 
-        const assistantId = client.platformAssistantId;
-        const basePath = `/v1/assistants/${assistantId}/emails/${messageId}/attachments`;
+          const assistantId = client.platformAssistantId;
+          const basePath = `/v1/assistants/${assistantId}/emails/${messageId}/attachments`;
 
-        if (opts.list) {
-          // List mode — show attachment metadata without downloading
-          const response = await client.fetch(`${basePath}/`);
-          if (!response.ok) {
-            const body = (await response
-              .json()
-              .catch(() => ({}))) as Record<string, unknown>;
-            const detail = body.detail ?? `HTTP ${response.status}`;
-            throw new Error(String(detail));
-          }
+          if (opts.list) {
+            // List mode — show attachment metadata without downloading
+            const response = await client.fetch(`${basePath}/`);
+            if (!response.ok) {
+              const body = (await response.json().catch(() => ({}))) as Record<
+                string,
+                unknown
+              >;
+              const detail = body.detail ?? `HTTP ${response.status}`;
+              throw new Error(String(detail));
+            }
 
-          const data = (await response.json()) as {
-            results: AttachmentMeta[];
-          };
+            const data = (await response.json()) as {
+              results: AttachmentMeta[];
+            };
 
-          if (shouldOutputJson(cmd)) {
-            writeOutput(cmd, data);
-          } else {
-            const attachments = data.results ?? [];
-            if (attachments.length === 0) {
-              log.info("No attachments for this message.");
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, data);
             } else {
-              for (const att of attachments) {
-                log.info(
-                  `  ${att.id}  ${att.filename}  (${att.content_type}, ${formatBytes(att.size_bytes)})`,
-                );
+              const attachments = data.results ?? [];
+              if (attachments.length === 0) {
+                log.info("No attachments for this message.");
+              } else {
+                for (const att of attachments) {
+                  log.info(
+                    `  ${att.id}  ${att.filename}  (${att.content_type}, ${formatBytes(att.size_bytes)})`,
+                  );
+                }
+                log.info(`\n${attachments.length} attachment(s)`);
               }
-              log.info(`\n${attachments.length} attachment(s)`);
             }
+            return;
           }
-          return;
-        }
 
-        if (!opts.all && !attachmentId) {
-          throw new Error(
-            "Specify an attachment ID, or use --all to download all attachments. Use --list to see available attachments.",
-          );
-        }
+          if (!opts.all && !attachmentId) {
+            throw new Error(
+              "Specify an attachment ID, or use --all to download all attachments. Use --list to see available attachments.",
+            );
+          }
 
-        // Ensure output directory exists
-        const outDir = opts.output ?? ".";
-        mkdirSync(outDir, { recursive: true });
+          // Ensure output directory exists
+          const outDir = opts.output ?? ".";
+          mkdirSync(outDir, { recursive: true });
 
-        if (opts.all) {
-          // Download all attachments
-          const listResponse = await client.fetch(`${basePath}/`);
-          if (!listResponse.ok) {
-            const body = (await listResponse
-              .json()
-              .catch(() => ({}))) as Record<string, unknown>;
-            const detail = body.detail ?? `HTTP ${listResponse.status}`;
-            throw new Error(String(detail));
-          }
+          if (opts.all) {
+            // Download all attachments
+            const listResponse = await client.fetch(`${basePath}/`);
+            if (!listResponse.ok) {
+              const body = (await listResponse
+                .json()
+                .catch(() => ({}))) as Record<string, unknown>;
+              const detail = body.detail ?? `HTTP ${listResponse.status}`;
+              throw new Error(String(detail));
+            }
 
-          const listData = (await listResponse.json()) as {
-            results: AttachmentMeta[];
-          };
+            const listData = (await listResponse.json()) as {
+              results: AttachmentMeta[];
+            };
 
-          const attachments = listData.results ?? [];
-          if (attachments.length === 0) {
-            throw new Error("No attachments for this message.");
-          }
+            const attachments = listData.results ?? [];
+            if (attachments.length === 0) {
+              throw new Error("No attachments for this message.");
+            }
 
-          const downloaded: { filename: string; size_bytes: number }[] = [];
-          for (const att of attachments) {
-            const dest = join(outDir, safeFilename(att.filename));
-            await downloadAttachment(client, basePath, att.id, dest);
-            downloaded.push({
-              filename: att.filename,
-              size_bytes: att.size_bytes,
-            });
-          }
+            const downloaded: { filename: string; size_bytes: number }[] = [];
+            for (const att of attachments) {
+              const dest = join(outDir, safeFilename(att.filename));
+              await downloadAttachment(client, basePath, att.id, dest);
+              downloaded.push({
+                filename: att.filename,
+                size_bytes: att.size_bytes,
+              });
+            }
 
-          if (shouldOutputJson(cmd)) {
-            writeOutput(cmd, {
-              downloaded: downloaded.length,
-              directory: outDir,
-              files: downloaded,
-            });
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, {
+                downloaded: downloaded.length,
+                directory: outDir,
+                files: downloaded,
+              });
+            } else {
+              log.info(
+                `✓ Downloaded ${downloaded.length} attachment(s) to ${outDir}`,
+              );
+              for (const f of downloaded) {
+                log.info(`  - ${f.filename} (${formatBytes(f.size_bytes)})`);
+              }
+            }
           } else {
-            log.info(
-              `✓ Downloaded ${downloaded.length} attachment(s) to ${outDir}`,
+            // Download single attachment — first get metadata for the filename
+            const metaResponse = await client.fetch(
+              `${basePath}/${attachmentId}/`,
             );
-            for (const f of downloaded) {
-              log.info(`  - ${f.filename} (${formatBytes(f.size_bytes)})`);
+            if (!metaResponse.ok) {
+              const body = (await metaResponse
+                .json()
+                .catch(() => ({}))) as Record<string, unknown>;
+              const detail = body.detail ?? `HTTP ${metaResponse.status}`;
+              throw new Error(String(detail));
             }
-          }
-        } else {
-          // Download single attachment — first get metadata for the filename
-          const metaResponse = await client.fetch(
-            `${basePath}/${attachmentId}/`,
-          );
-          if (!metaResponse.ok) {
-            const body = (await metaResponse
-              .json()
-              .catch(() => ({}))) as Record<string, unknown>;
-            const detail = body.detail ?? `HTTP ${metaResponse.status}`;
-            throw new Error(String(detail));
-          }
 
-          const meta = (await metaResponse.json()) as AttachmentMeta;
-          const dest = join(outDir, safeFilename(meta.filename));
-          await downloadAttachment(client, basePath, meta.id, dest);
+            const meta = (await metaResponse.json()) as AttachmentMeta;
+            const dest = join(outDir, safeFilename(meta.filename));
+            await downloadAttachment(client, basePath, meta.id, dest);
 
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, {
+                filename: meta.filename,
+                size_bytes: meta.size_bytes,
+                saved: dest,
+              });
+            } else {
+              log.info(
+                `✓ Downloaded ${meta.filename} (${formatBytes(meta.size_bytes)})`,
+              );
+            }
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
           if (shouldOutputJson(cmd)) {
-            writeOutput(cmd, {
-              filename: meta.filename,
-              size_bytes: meta.size_bytes,
-              saved: dest,
-            });
+            writeOutput(cmd, { error: message });
           } else {
-            log.info(
-              `✓ Downloaded ${meta.filename} (${formatBytes(meta.size_bytes)})`,
-            );
+            log.error(`Error: ${message}`);
           }
+          process.exitCode = 1;
         }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        if (shouldOutputJson(cmd)) {
-          writeOutput(cmd, { error: message });
-        } else {
-          log.error(`Error: ${message}`);
-        }
-        process.exitCode = 1;
-      }
-    },
-  );
+      },
+    );
 }
 
 interface AttachmentMeta {
-id: string;
-filename: string;
-content_type: string;
-size_bytes: number;
-content_id: string;
-created_at: string;
+  id: string;
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+  content_id: string;
+  created_at: string;
 }
 
 function formatBytes(bytes: number): string {
-if (bytes < 1024) return `${bytes} B`;
-if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 
 function safeFilename(name: string): string {
-// Strip path separators and null bytes — keep the basename only
-return basename(name).replace(/[\x00/\\]/g, "_") || "attachment";
+  // Strip path separators and null bytes — keep the basename only
+  return basename(name).replace(/[\x00/\\]/g, "_") || "attachment";
 }
 
 async function downloadAttachment(
-client: VellumPlatformClient,
-basePath: string,
-attachmentId: string,
-dest: string,
+  client: VellumPlatformClient,
+  basePath: string,
+  attachmentId: string,
+  dest: string,
 ): Promise<void> {
-const response = await client.fetch(
-  `${basePath}/${attachmentId}/download/`,
-);
-
-if (!response.ok) {
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >;
-  const detail = body.detail ?? `HTTP ${response.status}`;
-  throw new Error(`Failed to download attachment: ${detail}`);
-}
-
-if (!response.body) {
-  throw new Error("Empty response body from download endpoint.");
-}
-
-const fileStream = createWriteStream(dest);
-await pipeline(response.body as unknown as Readable, fileStream);
+  const response = await client.fetch(`${basePath}/${attachmentId}/download/`);
+
+  if (!response.ok) {
+    const body = (await response.json().catch(() => ({}))) as Record<
+      string,
+      unknown
+    >;
+    const detail = body.detail ?? `HTTP ${response.status}`;
+    throw new Error(`Failed to download attachment: ${detail}`);
+  }
+
+  if (!response.body) {
+    throw new Error("Empty response body from download endpoint.");
+  }
+
+  const fileStream = createWriteStream(dest);
+  await pipeline(response.body as unknown as Readable, fileStream);
 }