groundmail-cli 0.26.3 → 0.27.0

package/README.md

@@ -63,6 +63,21 @@ SENDGRID_API_KEY=… groundmail migrate sendgrid --dry-run   # import from SendG
 
 Run `groundmail --help` or `groundmail <command> --help` for flags.
 
+## Email testing
+
+Your team has a test domain (`<team>.test.groundmail.dev`). Mail sent there from any provider is
+caught and never delivered. Get a fresh address, have your app send to it, then wait for it:
+
+```bash
+TO=$(groundmail test-inbox address --prefix signup)   # signup-k3m9x2pq@acme.test.groundmail.dev
+# …trigger your app's signup with $TO…
+groundmail test-inbox wait --to "$TO" --timeout 30    # prints the subject, code and links
+groundmail test-inbox wait --to "$TO" --json | jq -r .email.code
+groundmail test-inbox list --to "$TO"
+```
+
+`wait` exits 2 when nothing arrives in time. Docs: https://docs.groundmail.dev/email-testing
+
 ## Tenants
 
 If you send email for your own customers, give each one a tenant: its own domains,

package/dist/cli.js

@@ -1452,7 +1452,7 @@ function trimUrl(value) {
 }
 
 // package.json
-var version = "0.26.3";
+var version = "0.27.0";
 
 // src/user-agent.ts
 function buildUserAgent(own) {
@@ -3745,6 +3745,80 @@ Updated the DMARC record with ${result2.applied.provider}.`);
   }
 }
 
+// src/commands/test-inbox/test-inbox.ts
+function readFlag24(args, flag) {
+  const index = args.indexOf(flag);
+  if (index === -1) return void 0;
+  return args[index + 1];
+}
+async function createTestInboxClient(apiKey, baseUrl) {
+  const { Groundmail } = await import("groundmail");
+  return new Groundmail(apiKey, baseUrl ? { baseUrl } : void 0);
+}
+function formatTestEmail(email) {
+  const lines = [
+    `Subject: ${email.subject}`,
+    `From:    ${email.from}`,
+    `To:      ${email.to.join(", ")}`,
+    `Code:    ${email.code ?? "(none found)"}`
+  ];
+  if (email.links.length) {
+    lines.push("Links:");
+    for (const link of email.links) lines.push(`  ${link}`);
+  } else {
+    lines.push("Links:   (none)");
+  }
+  lines.push(`Id:      ${email.id}`);
+  return lines.join("\n");
+}
+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 = readFlag24(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, readFlag24(args, "--base-url"));
+    if (subcommand === "address") {
+      console.log(await client2.testInbox.address({ prefix: readFlag24(args, "--prefix") }));
+      return { exitCode: 0 };
+    }
+    if (subcommand === "list") {
+      const result = await client2.testInbox.list({
+        to: readFlag24(args, "--to"),
+        since: readFlag24(args, "--since"),
+        limit: readFlag24(args, "--limit") ? Number(readFlag24(args, "--limit")) : void 0
+      });
+      if (json) console.log(JSON.stringify(result));
+      else if (!result.emails.length) console.log("No test emails yet.");
+      else {
+        for (const email of result.emails) {
+          console.log(`${email.received_at}  ${email.id}  ${email.to.join(", ")}  ${email.subject}${email.code ? `  code ${email.code}` : ""}`);
+        }
+      }
+      return { exitCode: 0 };
+    }
+    const to = readFlag24(args, "--to");
+    if (!to) return { exitCode: 1, error: "Missing --to. Usage: groundmail test-inbox wait --to signup-k3m9x2pq@acme.test.groundmail.dev" };
+    const timeoutRaw = readFlag24(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: readFlag24(args, "--since") });
+      console.log(json ? JSON.stringify({ email }) : formatTestEmail(email));
+      return { exitCode: 0 };
+    } catch (error) {
+      const status = error?.status;
+      if (status === 408) {
+        return { exitCode: 2, error: `No email to ${to} arrived within ${seconds} seconds.` };
+      }
+      throw error;
+    }
+  } catch (error) {
+    return { exitCode: 1, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 // src/help.ts
 var USAGE_LINES = [
   "  groundmail login [--scope <scopes>] [--workspace <name>]   sign in through the browser (OAuth; no key to copy)",
@@ -3768,6 +3842,9 @@ var USAGE_LINES = [
   "  groundmail dmarc disable example.com",
   "  groundmail received-emails list [--domain inbound.example.com]",
   "  groundmail received-emails get inb_...",
+  "  groundmail test-inbox address [--prefix signup]   a fresh address on your team's test domain (mail there is caught, never delivered)",
+  "  groundmail test-inbox wait --to <address> [--timeout 30] [--since <iso>] [--json]   wait for an email; prints its code and links (exit 2 on timeout)",
+  "  groundmail test-inbox list [--to <address>] [--since <iso>] [--json]",
   '  groundmail emails send --from you@domain.com --to user@example.com --subject "Hello" --html "<p>Hi</p>" [--category transactional|product|newsletter] [--unsubscribe] [--tenant <tenant>]',
   "  groundmail emails batch --file ./emails.json [--tenant <tenant>]",
   "  groundmail emails list [--limit 25] [--cursor \u2026] [--test | --live] [--tenant <tenant>] [--stream transactional|product|newsletter]",
@@ -3923,6 +4000,7 @@ async function main() {
   if (command === "migrate") await finish(await runMigrateCommand(subcommand, rest));
   if (command === "validate") await finish(await runValidateCommand([...subcommand ? [subcommand] : [], ...rest]));
   if (command === "dmarc") await finish(await runDmarcCommand(subcommand, rest));
+  if (command === "test-inbox") await finish(await runTestInboxCommand(subcommand, rest));
   if (command === "domains") {
     if (subcommand === "add" || subcommand === "create") {
       const result = await runAddCommand(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail-cli",
-  "version": "0.26.3",
+  "version": "0.27.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.25.1"
+    "groundmail": "0.26.0"
   },
   "devDependencies": {
     "tsup": "^8.5.0",