groundmail-cli 0.35.0 → 0.36.0

package/README.md

@@ -75,6 +75,8 @@ groundmail domains list
 groundmail domains verify example.com
 groundmail webhooks list
 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

@@ -2055,7 +2055,7 @@ function trimUrl(value) {
 }
 
 // package.json
-var version = "0.35.0";
+var version = "0.36.0";
 
 // src/user-agent.ts
 function buildUserAgent(own) {
@@ -2082,6 +2082,12 @@ function fetchWithUserAgent(userAgent) {
 
 // src/client-info.ts
 var CLI_PACKAGE = { name: "groundmail-cli", version };
+function sdkOptions(baseUrl) {
+  return {
+    ...baseUrl ? { baseUrl } : {},
+    fetch: fetchWithUserAgent(buildUserAgent(CLI_PACKAGE))
+  };
+}
 
 // src/session/http.ts
 var CliRequestError = class extends Error {
@@ -3133,7 +3139,7 @@ function resolveApiKey8(options, env) {
 }
 async function createTemplatesClient(apiKey, baseUrl) {
   const { Groundmail } = await import("groundmail");
-  return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
+  return new Groundmail(apiKey, sdkOptions(baseUrl));
 }
 
 // src/commands/templates/delete.ts
@@ -4153,6 +4159,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;
@@ -4316,7 +4367,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 {
@@ -4327,8 +4378,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];
@@ -4403,10 +4454,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) {
@@ -4420,7 +4471,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));
@@ -4443,7 +4494,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." };
   }
@@ -4453,7 +4504,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 {
@@ -4463,15 +4514,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));
@@ -4483,7 +4534,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, {
@@ -4527,17 +4578,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;
@@ -4584,23 +4635,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(", ")}` };
       }
@@ -4630,7 +4681,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];
@@ -4658,20 +4709,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.");
@@ -4682,13 +4733,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) {
@@ -4736,6 +4787,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",
@@ -5176,6 +5229,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.0",
+  "version": "0.36.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.38.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",