groundmail 0.16.0 → 0.17.0

package/README.md

@@ -25,6 +25,27 @@ const email = await tx.emails.send({
 console.log(email.id, email.status)
 ```
 
+## Testing
+
+Use a test key (`gm_test_…`, create one with `tx.apiKeys.create({ test: true })` or in the
+dashboard) to run sends through validation, templates and webhooks without delivering anything.
+Simulator addresses produce a specific outcome with any key and never leave Groundmail:
+
+```ts
+import { simulatorAddress } from 'groundmail'
+
+await tx.emails.send({
+  from: 'ops@yourdomain.com',
+  to: simulatorAddress('bounce', 'signup-42'), // bounce+signup-42@simulator.groundmail.dev
+  subject: 'Bounce handling test',
+  html: '<p>Simulated.</p>',
+})
+// status `bounced`, then an `email.bounced` webhook with `data.test: true`
+```
+
+Outcomes: `delivered`, `bounce`, `block`, `complaint`, `suppressed`, `delayed`. Details:
+https://docs.groundmail.dev/testing
+
 ## Adapters
 
 Optional entry points (install peer deps as needed):
@@ -41,6 +62,7 @@ Optional entry points (install peer deps as needed):
 
 - Quickstart: https://docs.groundmail.dev/quickstart
 - Node / Nodemailer: https://docs.groundmail.dev/frameworks/node
+- Testing (test keys, simulator): https://docs.groundmail.dev/testing
 - API reference: https://docs.groundmail.dev/api/emails
 - Product: https://groundmail.dev
 

package/dist/authjs.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DXYsWgOT.js';
+import { G as Groundmail } from './client-DLz4rpD9.js';
 
 /** Subset of Auth.js theme used for the default magic-link email. */
 type AuthjsTheme = {

package/dist/authjs.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/authjs.ts
 function escapeHtml(value) {

package/dist/better-auth.d.ts

@@ -1,4 +1,4 @@
-import { S as SendEmailResult, G as Groundmail } from './client-DXYsWgOT.js';
+import { S as SendEmailResult, G as Groundmail } from './client-DLz4rpD9.js';
 
 type BetterAuthEmailUser = {
     email: string;

package/dist/better-auth.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/better-auth.ts
 function linkHtml(label, url) {

package/dist/{chunk-JYLRUBEJ.js → chunk-MJKAVFFN.js}

@@ -1008,6 +1008,7 @@ var EmailsResource = class {
     const search = new URLSearchParams();
     if (params.limit != null) search.set("limit", String(params.limit));
     if (params.cursor) search.set("cursor", params.cursor);
+    if (params.test != null) search.set("test", String(params.test));
     const query = search.toString();
     return this.client.request(`/emails${query ? `?${query}` : ""}`, {
       method: "GET"
@@ -1192,7 +1193,10 @@ var KeysResource = class {
       method: "POST",
       body: JSON.stringify({
         ...params.name ? { name: params.name } : {},
-        ...params.scope ? { scope: params.scope } : {}
+        ...params.scope && !params.scopes?.length ? { scope: params.scope } : {},
+        ...params.scopes?.length ? { scopes: params.scopes } : {},
+        ...params.allowedDomains?.length ? { allowed_domains: params.allowedDomains } : {},
+        ...params.test ? { test: true } : {}
       })
     });
   }

package/dist/clerk.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail, S as SendEmailResult } from './client-DXYsWgOT.js';
+import { G as Groundmail, S as SendEmailResult } from './client-DLz4rpD9.js';
 
 /**
  * Subset of Clerk `email.created` webhook `data` used for delivery.

package/dist/clerk.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/clerk.ts
 function resolveApiKey(options) {

package/dist/{client-DXYsWgOT.d.ts → client-DLz4rpD9.d.ts}

@@ -78,6 +78,8 @@ type SendEmailResult = {
     status: string;
     /** Present when some recipients were held back and the email went to the rest. */
     held_back?: HeldBackRecipient[];
+    /** `true` on a test send (a `gm_test_…` key or only simulator addresses): nothing was delivered. */
+    test?: true;
 };
 /** `details` on `POST /emails` 422 when Groundmail validation held back every `to` recipient. */
 type HeldBackErrorDetails = {
@@ -111,6 +113,7 @@ type BatchSendEmailResult = {
         id?: string;
         status?: string;
         held_back?: HeldBackRecipient[];
+        test?: true;
         error?: {
             message: string;
             code?: string;
@@ -148,6 +151,11 @@ type EmailListItem = {
     bounce_type: BounceType | null;
     /** Recipients Groundmail validation held back before sending, with why. Empty when none were. */
     held_back: HeldBackRecipient[];
+    /**
+     * `true` when the email never reached the mail server: sent with a test key or only to
+     * simulator addresses. Its status and events are simulated.
+     */
+    test: boolean;
     tags: unknown;
     scheduled_at: string | null;
     cancelled_at: string | null;
@@ -207,6 +215,8 @@ type ListReceivedEmailsResult = {
 type ListEmailsParams = {
     limit?: number;
     cursor?: string;
+    /** `true`: only test emails; `false`: only live ones. Omit for both. */
+    test?: boolean;
 };
 type ListEmailsResult = {
     emails: EmailListItem[];
@@ -261,6 +271,12 @@ type ApiKey = {
     id: string;
     name: string;
     scope: ApiKeyScope;
+    /** Fine-grained scopes (`emails:send`, `domains:read`, …). */
+    scopes?: string[];
+    /** Domains the key may send from; empty means any verified domain. */
+    allowed_domains?: string[];
+    /** A test key (`gm_test_…`): its sends are simulated and never delivered. */
+    test?: boolean;
     prefix: string;
     created_at: string;
     last_used_at: string | null;
@@ -277,11 +293,24 @@ type ListApiKeysResult = {
 type CreateApiKeyParams = {
     name?: string;
     scope?: ApiKeyScope;
+    /** Fine-grained scopes, e.g. `['emails:send']`. Takes precedence over `scope`. */
+    scopes?: string[];
+    /** Verified domains the key may send from (needs `emails:send`, not `full`). */
+    allowedDomains?: string[];
+    /**
+     * Create a test key (`gm_test_…`): same scopes and checks as a live key, but sends are
+     * never delivered. They get simulated events and webhooks and count toward nothing.
+     */
+    test?: boolean;
 };
 type CreateApiKeyResult = {
     id: string;
     name: string;
     scope: ApiKeyScope;
+    scopes?: string[];
+    allowed_domains?: string[];
+    /** A test key (`gm_test_…`). */
+    test?: boolean;
     prefix: string;
     token: string;
     created_at: string;
@@ -326,6 +355,8 @@ type EmailWebhookEventPayload = {
         bounce_reason?: string | null;
         /** Set on `email.bounced` and `email.failed` when the email bounced: `hard` or `block`. */
         bounce_type?: BounceType | null;
+        /** `true` on simulated events (test keys, simulator addresses, `POST /emails/test`). Absent on real mail. */
+        test?: true;
     };
 };
 /** `contact.unsubscribed` webhook payload (`scope` distinguishes global vs category opt-out). */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ApiErrorBody, D as DnsRecord } from './client-DXYsWgOT.js';
-export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateWebhookParams, I as DEFAULT_API_BASE_URL, J as DailyRampLimitErrorDetails, K as DeliverabilityBucket, L as DeliverabilityDomainInsight, M as DeliverabilityInsightsResult, N as DeliverabilityMailServerRelay, O as DeliverabilityWindow, P as DnsProviderName, Q as Domain, R as DomainBimiAnalysis, T as DomainDetailResult, U as DomainDmarcAnalysis, V as DomainDnsAnalysis, W as DomainStatus, X as DomainTlsMode, Y as DomainTrackingDns, Z as DomainTrackingStatus, _ as EmailListItem, $ as EmailWebhookEventPayload, a0 as EmailWebhookEventType, a1 as EnrollmentSkip, a2 as EventRecord, G as Groundmail, a3 as GroundmailOptions, a4 as HeldBackErrorDetails, a5 as HeldBackReason, a6 as HeldBackRecipient, a7 as ListApiKeysParams, a8 as ListApiKeysResult, a9 as ListAutomationRunsParams, aa as ListAutomationRunsResult, ab as ListAutomationsResult, ac as ListDomainsParams, ad as ListDomainsResult, ae as ListEmailsParams, af as ListEmailsResult, ag as ListReceivedEmailsParams, ah as ListReceivedEmailsResult, ai as ListSuppressionsParams, aj as ListSuppressionsResult, ak as ListTemplatesParams, al as ListTemplatesResult, am as MailServerSigningStatus, an as Migration, ao as MigrationDnsChange, ap as MigrationDnsPlan, aq as MigrationDomainItem, ar as MigrationItemStatus, as as MigrationProvider, at as MigrationResource, au as MigrationSummary, av as MigrationTemplateItem, aw as MigrationTotals, ax as MigrationWebhookItem, ay as ReceivedEmail, az as ReceivedEmailAttachment, aA as ReceivedEmailAttachmentMeta, aB as RemoteApplyDnsCredentials, aC as RunMigrationOptions, aD as SendEmailParams, S as SendEmailResult, aE as SuppressedErrorDetails, aF as Suppression, aG as Template, aH as TemplateFormat, aI as TemplateLintWarning, aJ as TemplateStarter, aK as TemplateStatus, aL as TemplateVersion, aM as TestEmailWebhookParams, aN as TestEmailWebhookResult, aO as TriggerEventParams, aP as TriggerEventResult, aQ as TwilioIntegrationResponse, aR as TwilioIntegrationStatus, aS as UpdateAutomationParams, aT as UpdateDomainParams, aU as UpdateEmailParams, aV as UpdateTemplateParams, aW as UpdateWebhookParams, aX as ValidateEmailResult, aY as ValidationReason, aZ as ValidationVerdict, a_ as VerifyDomainResult, a$ as WebhookEndpoint, b0 as WebhookEndpointWithSecret, b1 as WebhookEventType, b2 as mergeMigrations } from './client-DXYsWgOT.js';
+import { A as ApiErrorBody, D as DnsRecord } from './client-DLz4rpD9.js';
+export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateWebhookParams, I as DEFAULT_API_BASE_URL, J as DailyRampLimitErrorDetails, K as DeliverabilityBucket, L as DeliverabilityDomainInsight, M as DeliverabilityInsightsResult, N as DeliverabilityMailServerRelay, O as DeliverabilityWindow, P as DnsProviderName, Q as Domain, R as DomainBimiAnalysis, T as DomainDetailResult, U as DomainDmarcAnalysis, V as DomainDnsAnalysis, W as DomainStatus, X as DomainTlsMode, Y as DomainTrackingDns, Z as DomainTrackingStatus, _ as EmailListItem, $ as EmailWebhookEventPayload, a0 as EmailWebhookEventType, a1 as EnrollmentSkip, a2 as EventRecord, G as Groundmail, a3 as GroundmailOptions, a4 as HeldBackErrorDetails, a5 as HeldBackReason, a6 as HeldBackRecipient, a7 as ListApiKeysParams, a8 as ListApiKeysResult, a9 as ListAutomationRunsParams, aa as ListAutomationRunsResult, ab as ListAutomationsResult, ac as ListDomainsParams, ad as ListDomainsResult, ae as ListEmailsParams, af as ListEmailsResult, ag as ListReceivedEmailsParams, ah as ListReceivedEmailsResult, ai as ListSuppressionsParams, aj as ListSuppressionsResult, ak as ListTemplatesParams, al as ListTemplatesResult, am as MailServerSigningStatus, an as Migration, ao as MigrationDnsChange, ap as MigrationDnsPlan, aq as MigrationDomainItem, ar as MigrationItemStatus, as as MigrationProvider, at as MigrationResource, au as MigrationSummary, av as MigrationTemplateItem, aw as MigrationTotals, ax as MigrationWebhookItem, ay as ReceivedEmail, az as ReceivedEmailAttachment, aA as ReceivedEmailAttachmentMeta, aB as RemoteApplyDnsCredentials, aC as RunMigrationOptions, aD as SendEmailParams, S as SendEmailResult, aE as SuppressedErrorDetails, aF as Suppression, aG as Template, aH as TemplateFormat, aI as TemplateLintWarning, aJ as TemplateStarter, aK as TemplateStatus, aL as TemplateVersion, aM as TestEmailWebhookParams, aN as TestEmailWebhookResult, aO as TriggerEventParams, aP as TriggerEventResult, aQ as TwilioIntegrationResponse, aR as TwilioIntegrationStatus, aS as UpdateAutomationParams, aT as UpdateDomainParams, aU as UpdateEmailParams, aV as UpdateTemplateParams, aW as UpdateWebhookParams, aX as ValidateEmailResult, aY as ValidationReason, aZ as ValidationVerdict, a_ as VerifyDomainResult, a$ as WebhookEndpoint, b0 as WebhookEndpointWithSecret, b1 as WebhookEventType, b2 as mergeMigrations } from './client-DLz4rpD9.js';
 
 type GroundmailErrorOptions = {
     code?: string;
@@ -43,6 +43,40 @@ declare function buildSignatureHeader(secret: string, payload: string, timestamp
  */
 declare function verifyWebhookSignature(secret: string, payload: string, header: string | null | undefined, toleranceSec?: number): boolean;
 
+/**
+ * Test mode helpers.
+ *
+ * Simulator addresses at `simulator.groundmail.dev` produce one outcome each, with
+ * the same status and webhooks as real mail, and never leave Groundmail. They work
+ * with live and test keys. Plus addressing tells sends apart:
+ *
+ * ```ts
+ * import { simulatorAddress } from 'groundmail'
+ * await groundmail.emails.send({ from, to: simulatorAddress('bounce', 'signup-42'), subject, html })
+ * // → bounce+signup-42@simulator.groundmail.dev: status `bounced`, `email.bounced` webhook
+ * ```
+ *
+ * Docs: https://docs.groundmail.dev/testing
+ */
+declare const SIMULATOR_DOMAIN = "simulator.groundmail.dev";
+declare const SIMULATOR_OUTCOMES: readonly ["delivered", "bounce", "block", "complaint", "suppressed", "delayed"];
+/**
+ * - `delivered`: `email.delivered`
+ * - `bounce`: hard bounce, `email.bounced` with `bounce_type: "hard"`
+ * - `block`: block bounce, `email.bounced` with `bounce_type: "block"`
+ * - `complaint`: `email.delivered`, then `email.complained`
+ * - `suppressed`: refused like a suppressed recipient (422), `email.suppressed`
+ * - `delayed`: `email.delivery_delayed`
+ */
+type SimulatorOutcome = (typeof SIMULATOR_OUTCOMES)[number];
+/** `simulatorAddress('bounce')` → `bounce@simulator.groundmail.dev`; a tag adds `+tag`. */
+declare function simulatorAddress(outcome: SimulatorOutcome, tag?: string): string;
+/** True for any address at the simulator domain. */
+declare function isSimulatorAddress(address: string): boolean;
+/** Test keys start with `gm_test_`. */
+declare const TEST_API_KEY_PREFIX = "gm_test_";
+declare function isTestApiKey(key: string | null | undefined): boolean;
+
 /** Merge `include:host` into an existing SPF record (or create a minimal one). */
 declare function mergeSpfInclude(existing: string | null | undefined, includeHost: string): string;
 
@@ -75,4 +109,4 @@ declare function applyDnsRecords(input: {
     fetchImpl?: typeof fetch;
 }): Promise<ApplyDnsResult>;
 
-export { DnsRecord, GroundmailError, type GroundmailErrorOptions, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };
+export { DnsRecord, GroundmailError, type GroundmailErrorOptions, SIMULATOR_DOMAIN, SIMULATOR_OUTCOMES, type SimulatorOutcome, TEST_API_KEY_PREFIX, applyDnsRecords, buildSignatureHeader, isSimulatorAddress, isTestApiKey, mergeSpfInclude, signWebhookPayload, simulatorAddress, verifyWebhookSignature };

package/dist/index.js

@@ -8,15 +8,41 @@ import {
   mergeSpfInclude,
   signWebhookPayload,
   verifyWebhookSignature
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-MJKAVFFN.js";
+
+// src/simulator.ts
+var SIMULATOR_DOMAIN = "simulator.groundmail.dev";
+var SIMULATOR_OUTCOMES = ["delivered", "bounce", "block", "complaint", "suppressed", "delayed"];
+function simulatorAddress(outcome, tag) {
+  if (!SIMULATOR_OUTCOMES.includes(outcome)) {
+    throw new Error(`Unknown simulator outcome: ${outcome}`);
+  }
+  const cleanTag = tag?.trim().replace(/[^A-Za-z0-9._-]+/g, "-");
+  return `${outcome}${cleanTag ? `+${cleanTag}` : ""}@${SIMULATOR_DOMAIN}`;
+}
+function isSimulatorAddress(address) {
+  const match = address.match(/<([^>]+)>/);
+  const bare = (match ? match[1] : address).trim().toLowerCase();
+  return bare.endsWith(`@${SIMULATOR_DOMAIN}`);
+}
+var TEST_API_KEY_PREFIX = "gm_test_";
+function isTestApiKey(key) {
+  return Boolean(key?.startsWith(TEST_API_KEY_PREFIX));
+}
 export {
   DEFAULT_API_BASE_URL,
   Groundmail,
   GroundmailError,
+  SIMULATOR_DOMAIN,
+  SIMULATOR_OUTCOMES,
+  TEST_API_KEY_PREFIX,
   applyDnsRecords,
   buildSignatureHeader,
+  isSimulatorAddress,
+  isTestApiKey,
   mergeMigrations,
   mergeSpfInclude,
   signWebhookPayload,
+  simulatorAddress,
   verifyWebhookSignature
 };

package/dist/payload.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DXYsWgOT.js';
+import { G as Groundmail } from './client-DLz4rpD9.js';
 
 /**
  * Minimal Payload `SendEmailOptions` / address shapes used by this adapter.

package/dist/payload.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/payload.ts
 function resolveApiKey(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Groundmail transactional email API client",
   "license": "MIT",
   "type": "module",
@@ -89,7 +89,7 @@
     "prepublishOnly": "npm run build && npm run build:nodemailer-bridge"
   },
   "dependencies": {
-    "groundmail-nodemailer": "0.15.2"
+    "groundmail-nodemailer": "0.15.3"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1",