groundmail-cli 0.35.1 → 0.37.0

package/README.md

@@ -74,7 +74,11 @@ groundmail workspaces use <name>
 groundmail domains list
 groundmail domains verify example.com
 groundmail webhooks list
+groundmail webhooks deliveries list --webhook <webhook-id> --status failed
+groundmail webhooks deliveries resend --webhook <webhook-id> --id <delivery-id>
 groundmail emails list
+groundmail batches get batch_…                           # status counts for an emails batch
+groundmail batches cancel batch_…                        # cancel the batch's emails that are still scheduled
 groundmail brand set --logo-url https://cdn.acme.com/logo.png --color '#2f6feb' --company "Acme Inc"   # logo, color and footer every template follows
 groundmail senders list                                  # saved senders; send with --sender billing instead of --from
 SENDGRID_API_KEY=… groundmail migrate sendgrid --dry-run   # import from SendGrid, Postmark, Mailgun, Resend or Amazon SES (beta)

package/dist/cli.js

@@ -2001,6 +2001,57 @@ function parseEnabledFlag(value) {
   return { error: "--enabled must be true or false" };
 }
 
+// src/commands/webhooks/deliveries.ts
+var VALUE_FILTERS = {
+  "--status": "status",
+  "--event": "event",
+  "--email-id": "email_id",
+  "--q": "q",
+  "--cursor": "cursor"
+};
+function listParams(args) {
+  const params = {};
+  for (const [flag, key] of Object.entries(VALUE_FILTERS)) {
+    const value = readFlag13(args, flag);
+    if (value) params[key] = value;
+  }
+  const limit = readFlag13(args, "--limit");
+  if (limit) {
+    const parsed = Number(limit);
+    if (!Number.isInteger(parsed) || parsed < 1) return { error: "--limit must be a positive whole number." };
+    params.limit = parsed;
+  }
+  const test = readFlag13(args, "--test");
+  if (test) {
+    if (test !== "true" && test !== "false") return { error: "--test must be true or false." };
+    params.test = test === "true";
+  }
+  return params;
+}
+async function runDeliveriesCommand(args, env = process.env) {
+  const [action, ...rest] = args;
+  if (action !== "list" && action !== "get" && action !== "resend") {
+    return { exitCode: 1, error: "Usage: groundmail webhooks deliveries list|get|resend --webhook <webhook-id> [--id <delivery-id>]" };
+  }
+  const options = parseWebhooksCommonArgs(rest);
+  const apiKey = resolveApiKey6(options, env);
+  if (!apiKey) return { exitCode: 1, error: "Missing API key. Set GROUNDMAIL_API_KEY or pass --api-key." };
+  const webhookId = readFlag13(rest, "--webhook");
+  if (!webhookId) return { exitCode: 1, error: "Missing webhook id. Pass --webhook <webhook-id>." };
+  const deliveryId = readFlag13(rest, "--id");
+  if (action !== "list" && !deliveryId) return { exitCode: 1, error: "Missing delivery id. Pass --id <delivery-id>." };
+  const params = action === "list" ? listParams(rest) : null;
+  if (params && "error" in params) return { exitCode: 1, error: params.error };
+  try {
+    const { webhooks } = await createWebhooksClient(apiKey, options.baseUrl);
+    const result = action === "list" ? await webhooks.deliveries.list(webhookId, params ?? {}) : action === "get" ? await webhooks.deliveries.get(webhookId, deliveryId) : await webhooks.deliveries.resend(webhookId, deliveryId);
+    console.log(JSON.stringify(result));
+    return { exitCode: 0 };
+  } catch (error) {
+    return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 // src/commands/keys/list.ts
 function readFlag16(args, flag) {
   const index = args.indexOf(flag);
@@ -2055,7 +2106,7 @@ function trimUrl(value) {
 }
 
 // package.json
-var version = "0.35.1";
+var version = "0.37.0";
 
 // src/user-agent.ts
 function buildUserAgent(own) {
@@ -4159,6 +4210,51 @@ async function runSetCommand(args, env = process.env) {
   });
 }
 
+// src/commands/batches/commands.ts
+var VALUE_FLAGS3 = ["--api-key", "--base-url", "--id"];
+var MISSING_KEY3 = "Missing API key. Set GROUNDMAIL_API_KEY or pass --api-key.";
+function readFlag23(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return void 0;
+  return args[index + 1];
+}
+function batchRef(args) {
+  const id = readFlag23(args, "--id");
+  if (id) return id;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      if (VALUE_FLAGS3.includes(arg)) i += 1;
+      continue;
+    }
+    return arg;
+  }
+  return void 0;
+}
+async function createBatchesClient(apiKey, baseUrl) {
+  const { Groundmail } = await import("groundmail");
+  return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
+}
+async function withBatch(args, env, usage, run) {
+  const batchId = batchRef(args);
+  if (!batchId) return { exitCode: 1, error: `Missing batch id (batch_\u2026). Usage: ${usage}` };
+  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  if (!apiKey) return { exitCode: 1, error: MISSING_KEY3 };
+  try {
+    const client2 = await createBatchesClient(apiKey, readFlag23(args, "--base-url"));
+    console.log(JSON.stringify(await run(client2, batchId)));
+    return { exitCode: 0 };
+  } catch (error) {
+    return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function runGetCommand10(args, env = process.env) {
+  return withBatch(args, env, "groundmail batches get <batch_id>", (client2, id) => client2.batches.get(id));
+}
+async function runCancelCommand2(args, env = process.env) {
+  return withBatch(args, env, "groundmail batches cancel <batch_id>", (client2, id) => client2.batches.cancel(id));
+}
+
 // src/commands/auth.ts
 async function runAuthCommand(subcommand, argv, deps = {}) {
   const env = deps.env ?? process.env;
@@ -4322,7 +4418,7 @@ function sesParams(args, env) {
       "Use a key with the read-only import policy (https://docs.groundmail.dev/migrations#amazon-ses-iam-policy). It is used for this import only and never stored."
     ].join("\n");
   }
-  const region = readFlag23(args, "--region") || env.AWS_REGION || env.AWS_DEFAULT_REGION;
+  const region = readFlag24(args, "--region") || env.AWS_REGION || env.AWS_DEFAULT_REGION;
   if (!region) return "Set the SES region with --region (for example --region us-east-1) or AWS_REGION. One region per import.";
   if (!AWS_REGION.test(region)) return `--region must be an AWS region such as us-east-1, not ${region}`;
   return {
@@ -4333,8 +4429,8 @@ function sesParams(args, env) {
     aws_region: region
   };
 }
-var VALUE_FLAGS3 = /* @__PURE__ */ new Set(["--api-key", "--base-url"]);
-function readFlag23(args, flag) {
+var VALUE_FLAGS4 = /* @__PURE__ */ new Set(["--api-key", "--base-url"]);
+function readFlag24(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
@@ -4409,10 +4505,10 @@ function formatMigrationSummary(m) {
   return lines.join("\n");
 }
 async function client(args, env) {
-  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag24(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return null;
   const { Groundmail } = await import("groundmail");
-  const baseUrl = readFlag23(args, "--base-url");
+  const baseUrl = readFlag24(args, "--base-url");
   return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
 }
 async function runStoredCommand(sub, args, env) {
@@ -4426,7 +4522,7 @@ async function runStoredCommand(sub, args, env) {
       if (!data.length) console.error("No imports yet. Previews are not stored.");
       return { exitCode: 0 };
     }
-    const id = args.find((arg, i) => !arg.startsWith("--") && !VALUE_FLAGS3.has(args[i - 1] ?? ""));
+    const id = args.find((arg, i) => !arg.startsWith("--") && !VALUE_FLAGS4.has(args[i - 1] ?? ""));
     if (!id) return { exitCode: 1, error: "Usage: groundmail migrate report <import id> [--csv]" };
     if (args.includes("--csv")) {
       process.stdout.write(await gm.migrations.reportCsv(id));
@@ -4449,7 +4545,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
     };
   }
   const id = provider;
-  const apiKey = readFlag23(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag24(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) {
     return { exitCode: 1, error: "Not signed in. Run `groundmail login`, or set GROUNDMAIL_API_KEY." };
   }
@@ -4459,7 +4555,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
     if (typeof ses === "string") return { exitCode: 1, error: ses };
     params = ses;
   } else {
-    const providerKey = readFlag23(args, "--key") || env[KEY_ENV[id]];
+    const providerKey = readFlag24(args, "--key") || env[KEY_ENV[id]];
     if (!providerKey) {
       const resend = id === "resend" ? " Use a key with Full access (Resend \u2192 API Keys); a Sending access key cannot read your account." : "";
       return {
@@ -4469,15 +4565,15 @@ async function runMigrateCommand(provider, args, env = process.env) {
     }
     params = { provider: id, api_key: providerKey };
     if (id === "postmark") {
-      const accountToken = readFlag23(args, "--account-token") || env.POSTMARK_ACCOUNT_TOKEN;
+      const accountToken = readFlag24(args, "--account-token") || env.POSTMARK_ACCOUNT_TOKEN;
       if (accountToken) params.account_api_key = accountToken;
     } else if (id === "sendgrid" || id === "mailgun") {
-      const region = readFlag23(args, "--region");
+      const region = readFlag24(args, "--region");
       if (region === "us" || region === "eu") params.region = region;
       else if (region) return { exitCode: 1, error: "--region must be us or eu" };
     }
   }
-  const only = readFlag23(args, "--only");
+  const only = readFlag24(args, "--only");
   if (only) {
     const list = only.split(",").map((s) => s.trim()).filter(Boolean);
     const bad = list.filter((r) => !RESOURCES.includes(r));
@@ -4489,7 +4585,7 @@ async function runMigrateCommand(provider, args, env = process.env) {
   if (args.includes("--dry-run")) params.dry_run = true;
   try {
     const { Groundmail } = await import("groundmail");
-    const baseUrl = readFlag23(args, "--base-url");
+    const baseUrl = readFlag24(args, "--base-url");
     const client2 = new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
     console.error(`${params.dry_run ? "Previewing" : "Importing"} from ${LABELS[id]}${params.provider === "ses" ? ` (${params.aws_region})` : ""} (Beta)\u2026`);
     const report = await client2.migrations.run(params, {
@@ -4533,17 +4629,17 @@ async function runValidateCommand(args, env = process.env) {
 
 // src/commands/dmarc/dmarc.ts
 var DMARC_APPLY_PROVIDERS = ["cloudflare", "vercel", "godaddy", "netlify", "digitalocean", "dnsimple"];
-function readFlag24(args, flag) {
+function readFlag25(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
 }
-var VALUE_FLAGS4 = ["--api-key", "--base-url", "--domain", "--apply"];
+var VALUE_FLAGS5 = ["--api-key", "--base-url", "--domain", "--apply"];
 function readFirstPositional15(args) {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
     if (arg.startsWith("--")) {
-      if (VALUE_FLAGS4.includes(arg)) i += 1;
+      if (VALUE_FLAGS5.includes(arg)) i += 1;
       continue;
     }
     return arg;
@@ -4590,23 +4686,23 @@ function formatDmarcStatus(dmarc) {
   return lines.join("\n");
 }
 async function runDmarcCommand(subcommand, args, env = process.env) {
-  const apiKey = readFlag24(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag25(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return { exitCode: 1, error: "Missing API key. Run groundmail login, set GROUNDMAIL_API_KEY or pass --api-key." };
-  const domain = readFlag24(args, "--domain") || readFirstPositional15(args);
+  const domain = readFlag25(args, "--domain") || readFirstPositional15(args);
   if (!subcommand || !["status", "enable", "disable", "digest"].includes(subcommand)) {
     return { exitCode: 1, error: "Usage: groundmail dmarc status|enable|disable|digest <domain>" };
   }
   if (!domain) return { exitCode: 1, error: `Missing domain. Usage: groundmail dmarc ${subcommand} example.com` };
   const json = args.includes("--json");
   try {
-    const client2 = await createDmarcClient(apiKey, readFlag24(args, "--base-url"));
+    const client2 = await createDmarcClient(apiKey, readFlag25(args, "--base-url"));
     if (subcommand === "status") {
       const result2 = await client2.dmarc.get(domain);
       console.log(json ? JSON.stringify(result2) : formatDmarcStatus(result2.dmarc));
       return { exitCode: 0 };
     }
     if (subcommand === "enable") {
-      const apply = readFlag24(args, "--apply");
+      const apply = readFlag25(args, "--apply");
       if (apply && !DMARC_APPLY_PROVIDERS.includes(apply)) {
         return { exitCode: 1, error: `--apply must be one of: ${DMARC_APPLY_PROVIDERS.join(", ")}` };
       }
@@ -4636,7 +4732,7 @@ Updated the DMARC record with ${result2.applied.provider}.`);
 }
 
 // src/commands/test-inbox/test-inbox.ts
-function readFlag25(args, flag) {
+function readFlag26(args, flag) {
   const index = args.indexOf(flag);
   if (index === -1) return void 0;
   return args[index + 1];
@@ -4664,20 +4760,20 @@ function formatTestEmail(email) {
 var USAGE = "Usage: groundmail test-inbox address [--prefix signup] | wait --to <address> [--timeout 30] [--since <iso>] [--json] | list [--to <address>] [--json]";
 async function runTestInboxCommand(subcommand, args, env = process.env) {
   if (!subcommand || !["address", "wait", "list"].includes(subcommand)) return { exitCode: 1, error: USAGE };
-  const apiKey = readFlag25(args, "--api-key") || env.GROUNDMAIL_API_KEY;
+  const apiKey = readFlag26(args, "--api-key") || env.GROUNDMAIL_API_KEY;
   if (!apiKey) return { exitCode: 1, error: "Missing API key. Run groundmail login, set GROUNDMAIL_API_KEY or pass --api-key." };
   const json = args.includes("--json");
   try {
-    const client2 = await createTestInboxClient(apiKey, readFlag25(args, "--base-url"));
+    const client2 = await createTestInboxClient(apiKey, readFlag26(args, "--base-url"));
     if (subcommand === "address") {
-      console.log(await client2.testInbox.address({ prefix: readFlag25(args, "--prefix") }));
+      console.log(await client2.testInbox.address({ prefix: readFlag26(args, "--prefix") }));
       return { exitCode: 0 };
     }
     if (subcommand === "list") {
       const result = await client2.testInbox.list({
-        to: readFlag25(args, "--to"),
-        since: readFlag25(args, "--since"),
-        limit: readFlag25(args, "--limit") ? Number(readFlag25(args, "--limit")) : void 0
+        to: readFlag26(args, "--to"),
+        since: readFlag26(args, "--since"),
+        limit: readFlag26(args, "--limit") ? Number(readFlag26(args, "--limit")) : void 0
       });
       if (json) console.log(JSON.stringify(result));
       else if (!result.emails.length) console.log("No test emails yet.");
@@ -4688,13 +4784,13 @@ async function runTestInboxCommand(subcommand, args, env = process.env) {
       }
       return { exitCode: 0 };
     }
-    const to = readFlag25(args, "--to");
+    const to = readFlag26(args, "--to");
     if (!to) return { exitCode: 1, error: "Missing --to. Usage: groundmail test-inbox wait --to signup-k3m9x2pq@acme.test.groundmail.dev" };
-    const timeoutRaw = readFlag25(args, "--timeout");
+    const timeoutRaw = readFlag26(args, "--timeout");
     const seconds = timeoutRaw === void 0 ? 30 : Number(timeoutRaw);
     if (!Number.isFinite(seconds) || seconds < 0) return { exitCode: 1, error: "--timeout must be a number of seconds" };
     try {
-      const email = await client2.testInbox.waitFor({ to, timeout: seconds * 1e3, since: readFlag25(args, "--since") });
+      const email = await client2.testInbox.waitFor({ to, timeout: seconds * 1e3, since: readFlag26(args, "--since") });
       console.log(json ? JSON.stringify({ email }) : formatTestEmail(email));
       return { exitCode: 0 };
     } catch (error) {
@@ -4742,6 +4838,8 @@ var USAGE_LINES = [
   "  groundmail emails insights [--window 7d|30d]",
   "  groundmail emails get --id msg_\u2026 [--watch [--timeout 60] [--json]]   --watch: follow an email you already sent until it lands",
   "  groundmail emails cancel --id msg_\u2026",
+  "  groundmail batches get <batch_id>   an emails batch's status counts (the batch_id `emails batch` returned)",
+  "  groundmail batches cancel <batch_id>   cancel the batch's emails that are still scheduled; safe to repeat",
   "  groundmail emails resend --id msg_\u2026",
   `  groundmail events send --name user.created --email user@example.com --data '{"name":"Ada"}'`,
   "  groundmail automations list",
@@ -4759,6 +4857,9 @@ var USAGE_LINES = [
   "  groundmail webhooks get --id wh_\u2026",
   "  groundmail webhooks update --id wh_\u2026 [--url \u2026] [--event email.sent] [--enabled true|false] [--tenants a,b|all]",
   "  groundmail webhooks delete --id <webhook-id>",
+  "  groundmail webhooks deliveries list --webhook <webhook-id> [--status failed] [--event email.delivered] [--email-id msg_\u2026] [--q \u2026] [--test true|false] [--limit 25] [--cursor \u2026]",
+  "  groundmail webhooks deliveries get --webhook <webhook-id> --id <delivery-id>",
+  "  groundmail webhooks deliveries resend --webhook <webhook-id> --id <delivery-id>",
   "  groundmail validate user@example.com   Groundmail validation: verdict, reasons, typo suggestion (exit 2 when invalid)",
   "  groundmail suppressions list [--tenant <tenant>]",
   "  groundmail suppressions add --email user@example.com [--reason \u2026] [--tenant <tenant>]",
@@ -5036,6 +5137,11 @@ async function main() {
     }
   }
   if (command === "webhooks") {
+    if (subcommand === "deliveries") {
+      const result = await runDeliveriesCommand(rest);
+      if (result.error) console.error(result.error);
+      process.exit(result.exitCode);
+    }
     if (subcommand === "list") {
       const result = await runListCommand5(rest);
       if (result.error) console.error(result.error);
@@ -5182,6 +5288,10 @@ async function main() {
     if (subcommand === "get") await finish(await runGetCommand9(rest));
     if (subcommand === "set" || subcommand === "update") await finish(await runSetCommand(rest));
   }
+  if (command === "batches") {
+    if (subcommand === "get") await finish(await runGetCommand10(rest));
+    if (subcommand === "cancel") await finish(await runCancelCommand2(rest));
+  }
   if (command === "senders") {
     if (subcommand === "list") await finish(await runListCommand9(rest));
     if (subcommand === "create" || subcommand === "add") await finish(await runCreateCommand5(rest));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-cli",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "description": "Groundmail CLI — send transactional email from the terminal",
   "license": "MIT",
   "type": "module",
@@ -38,7 +38,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "groundmail": "0.37.0"
+    "groundmail": "0.39.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",