groundmail 0.15.1 → 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-DYUh2ub4.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-N2LD34ND.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-DYUh2ub4.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-N2LD34ND.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/better-auth.ts
 function linkHtml(label, url) {

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

@@ -773,6 +773,19 @@ var MigrationsResource = class {
       body: JSON.stringify(params)
     });
   }
+  /** Recent imports (newest first), with totals. */
+  async list(params = {}) {
+    const query = params.limit ? `?limit=${encodeURIComponent(String(params.limit))}` : "";
+    return this.client.request(`/migrations${query}`, { method: "GET" });
+  }
+  /** The stored report of one import, every request merged. Webhook secrets are not kept. */
+  async get(id) {
+    return this.client.request(`/migrations/${encodeURIComponent(id)}`, { method: "GET" });
+  }
+  /** The report as CSV text: one row per domain, webhook and template, plus counts, skips and next steps. */
+  async reportCsv(id) {
+    return this.client.requestText(`/migrations/${encodeURIComponent(id)}/report`);
+  }
   /** The whole import: follows `next_cursor` until done and returns the combined report. */
   async run(params, options = {}) {
     const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -995,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"
@@ -1179,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 } : {}
       })
     });
   }
@@ -1431,6 +1448,18 @@ var Groundmail = class {
   get fetchImpl() {
     return this.options.fetch || fetch;
   }
+  /** GET a text body (CSV downloads). Errors are JSON, like every other route. */
+  async requestText(path) {
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${this.apiKey}` }
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({}));
+      throw GroundmailError.fromResponse(response.status, body);
+    }
+    return response.text();
+  }
   async request(path, init) {
     const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
       ...init,

package/dist/clerk.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail, S as SendEmailResult } from './client-DYUh2ub4.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-N2LD34ND.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/clerk.ts
 function resolveApiKey(options) {

package/dist/{client-DYUh2ub4.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). */
@@ -881,7 +912,31 @@ type CreateMigrationParams = {
     /** `next_cursor` from the previous response, to continue. */
     cursor?: string;
 };
+/**
+ * Running totals. Suppressions also count by kind: `bounce`, `complaint`,
+ * `unsubscribe`, `manual`, and `product_opt_out` (opt-outs that were never
+ * global at the old provider; they stop product email only).
+ */
 type MigrationTotals = Record<string, number>;
+/** One DNS change for a domain, compared with what it publishes today. */
+type MigrationDnsChange = {
+    /** `add` a record, `update` an existing one to `value` (SPF), `keep` yours (DMARC), or `done`. */
+    action: 'add' | 'update' | 'keep' | 'done';
+    type: string;
+    host: string;
+    value: string;
+    purpose: string;
+    /** What the name holds today, when relevant. */
+    current: string | null;
+    note: string | null;
+};
+type MigrationDnsPlan = {
+    /** False when DNS could not be read; every record is then listed as `add`. */
+    checked: boolean;
+    changes: MigrationDnsChange[];
+    /** Which old-provider records to keep while switching, and when to remove them. */
+    keep_old_records: string;
+};
 type MigrationDomainItem = {
     name: string;
     status: MigrationItemStatus;
@@ -893,6 +948,8 @@ type MigrationDomainItem = {
         value: string;
         purpose: string;
     }>;
+    /** Null in a preview, or when the import ran out of time to check. */
+    dns_plan: MigrationDnsPlan | null;
     dashboard_url: string | null;
     message: string | null;
 };
@@ -964,6 +1021,16 @@ type Migration = {
     }> | null;
     agent_prompt: string | null;
 };
+/** A stored import, as listed by `migrations.list()`. Previews are not stored. */
+type MigrationSummary = {
+    id: string;
+    provider: MigrationProvider;
+    status: Migration['status'];
+    resources: MigrationResource[];
+    started_at: string;
+    finished_at: string | null;
+    totals: Partial<Record<MigrationResource, MigrationTotals>>;
+};
 type RunMigrationOptions = {
     /** Called after each request with the report so far. */
     onProgress?: (migration: Migration) => void;
@@ -1079,6 +1146,18 @@ declare class MigrationsResource {
     create(params: CreateMigrationParams): Promise<{
         migration: Migration;
     }>;
+    /** Recent imports (newest first), with totals. */
+    list(params?: {
+        limit?: number;
+    }): Promise<{
+        data: MigrationSummary[];
+    }>;
+    /** The stored report of one import, every request merged. Webhook secrets are not kept. */
+    get(id: string): Promise<{
+        migration: Migration;
+    }>;
+    /** The report as CSV text: one row per domain, webhook and template, plus counts, skips and next steps. */
+    reportCsv(id: string): Promise<string>;
     /** The whole import: follows `next_cursor` until done and returns the combined report. */
     run(params: CreateMigrationParams, options?: RunMigrationOptions): Promise<Migration>;
 }
@@ -1210,7 +1289,9 @@ declare class Groundmail {
     validate(email: string): Promise<ValidateEmailResult>;
     get baseUrl(): string;
     get fetchImpl(): typeof fetch;
+    /** GET a text body (CSV downloads). Errors are JSON, like every other route. */
+    requestText(path: string): Promise<string>;
     request<T>(path: string, init: RequestInit): Promise<T>;
 }
 
-export { type EmailWebhookEventPayload as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateWebhookParams as H, DEFAULT_API_BASE_URL as I, type DailyRampLimitErrorDetails as J, type DeliverabilityBucket as K, type DeliverabilityDomainInsight as L, type DeliverabilityInsightsResult as M, type DeliverabilityMailServerRelay as N, type DeliverabilityWindow as O, type DnsProviderName as P, type Domain as Q, type DomainBimiAnalysis as R, type SendEmailResult as S, type DomainDetailResult as T, type DomainDmarcAnalysis as U, type DomainDnsAnalysis as V, type DomainStatus as W, type DomainTlsMode as X, type DomainTrackingDns as Y, type DomainTrackingStatus as Z, type EmailListItem as _, type ApiErrorCode as a, mergeMigrations as a$, type EmailWebhookEventType as a0, type EnrollmentSkip as a1, type EventRecord as a2, type GroundmailOptions as a3, type HeldBackErrorDetails as a4, type HeldBackReason as a5, type HeldBackRecipient as a6, type ListApiKeysParams as a7, type ListApiKeysResult as a8, type ListAutomationRunsParams as a9, type SendEmailParams as aA, type SuppressedErrorDetails as aB, type Suppression as aC, type Template as aD, type TemplateFormat as aE, type TemplateLintWarning as aF, type TemplateStarter as aG, type TemplateStatus as aH, type TemplateVersion as aI, type TestEmailWebhookParams as aJ, type TestEmailWebhookResult as aK, type TriggerEventParams as aL, type TriggerEventResult as aM, type TwilioIntegrationResponse as aN, type TwilioIntegrationStatus as aO, type UpdateAutomationParams as aP, type UpdateDomainParams as aQ, type UpdateEmailParams as aR, type UpdateTemplateParams as aS, type UpdateWebhookParams as aT, type ValidateEmailResult as aU, type ValidationReason as aV, type ValidationVerdict as aW, type VerifyDomainResult as aX, type WebhookEndpoint as aY, type WebhookEndpointWithSecret as aZ, type WebhookEventType as a_, type ListAutomationRunsResult as aa, type ListAutomationsResult as ab, type ListDomainsParams as ac, type ListDomainsResult as ad, type ListEmailsParams as ae, type ListEmailsResult as af, type ListReceivedEmailsParams as ag, type ListReceivedEmailsResult as ah, type ListSuppressionsParams as ai, type ListSuppressionsResult as aj, type ListTemplatesParams as ak, type ListTemplatesResult as al, type MailServerSigningStatus as am, type Migration as an, type MigrationDomainItem as ao, type MigrationItemStatus as ap, type MigrationProvider as aq, type MigrationResource as ar, type MigrationTemplateItem as as, type MigrationTotals as at, type MigrationWebhookItem as au, type ReceivedEmail as av, type ReceivedEmailAttachment as aw, type ReceivedEmailAttachmentMeta as ax, type RemoteApplyDnsCredentials as ay, type RunMigrationOptions as az, type ApiKey as b, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };
+export { type EmailWebhookEventPayload as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateWebhookParams as H, DEFAULT_API_BASE_URL as I, type DailyRampLimitErrorDetails as J, type DeliverabilityBucket as K, type DeliverabilityDomainInsight as L, type DeliverabilityInsightsResult as M, type DeliverabilityMailServerRelay as N, type DeliverabilityWindow as O, type DnsProviderName as P, type Domain as Q, type DomainBimiAnalysis as R, type SendEmailResult as S, type DomainDetailResult as T, type DomainDmarcAnalysis as U, type DomainDnsAnalysis as V, type DomainStatus as W, type DomainTlsMode as X, type DomainTrackingDns as Y, type DomainTrackingStatus as Z, type EmailListItem as _, type ApiErrorCode as a, type WebhookEndpoint as a$, type EmailWebhookEventType as a0, type EnrollmentSkip as a1, type EventRecord as a2, type GroundmailOptions as a3, type HeldBackErrorDetails as a4, type HeldBackReason as a5, type HeldBackRecipient as a6, type ListApiKeysParams as a7, type ListApiKeysResult as a8, type ListAutomationRunsParams as a9, type ReceivedEmailAttachmentMeta as aA, type RemoteApplyDnsCredentials as aB, type RunMigrationOptions as aC, type SendEmailParams as aD, type SuppressedErrorDetails as aE, type Suppression as aF, type Template as aG, type TemplateFormat as aH, type TemplateLintWarning as aI, type TemplateStarter as aJ, type TemplateStatus as aK, type TemplateVersion as aL, type TestEmailWebhookParams as aM, type TestEmailWebhookResult as aN, type TriggerEventParams as aO, type TriggerEventResult as aP, type TwilioIntegrationResponse as aQ, type TwilioIntegrationStatus as aR, type UpdateAutomationParams as aS, type UpdateDomainParams as aT, type UpdateEmailParams as aU, type UpdateTemplateParams as aV, type UpdateWebhookParams as aW, type ValidateEmailResult as aX, type ValidationReason as aY, type ValidationVerdict as aZ, type VerifyDomainResult as a_, type ListAutomationRunsResult as aa, type ListAutomationsResult as ab, type ListDomainsParams as ac, type ListDomainsResult as ad, type ListEmailsParams as ae, type ListEmailsResult as af, type ListReceivedEmailsParams as ag, type ListReceivedEmailsResult as ah, type ListSuppressionsParams as ai, type ListSuppressionsResult as aj, type ListTemplatesParams as ak, type ListTemplatesResult as al, type MailServerSigningStatus as am, type Migration as an, type MigrationDnsChange as ao, type MigrationDnsPlan as ap, type MigrationDomainItem as aq, type MigrationItemStatus as ar, type MigrationProvider as as, type MigrationResource as at, type MigrationSummary as au, type MigrationTemplateItem as av, type MigrationTotals as aw, type MigrationWebhookItem as ax, type ReceivedEmail as ay, type ReceivedEmailAttachment as az, type ApiKey as b, type WebhookEndpointWithSecret as b0, type WebhookEventType as b1, mergeMigrations as b2, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ApiErrorBody, D as DnsRecord } from './client-DYUh2ub4.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 MigrationDomainItem, ap as MigrationItemStatus, aq as MigrationProvider, ar as MigrationResource, as as MigrationTemplateItem, at as MigrationTotals, au as MigrationWebhookItem, av as ReceivedEmail, aw as ReceivedEmailAttachment, ax as ReceivedEmailAttachmentMeta, ay as RemoteApplyDnsCredentials, az as RunMigrationOptions, aA as SendEmailParams, S as SendEmailResult, aB as SuppressedErrorDetails, aC as Suppression, aD as Template, aE as TemplateFormat, aF as TemplateLintWarning, aG as TemplateStarter, aH as TemplateStatus, aI as TemplateVersion, aJ as TestEmailWebhookParams, aK as TestEmailWebhookResult, aL as TriggerEventParams, aM as TriggerEventResult, aN as TwilioIntegrationResponse, aO as TwilioIntegrationStatus, aP as UpdateAutomationParams, aQ as UpdateDomainParams, aR as UpdateEmailParams, aS as UpdateTemplateParams, aT as UpdateWebhookParams, aU as ValidateEmailResult, aV as ValidationReason, aW as ValidationVerdict, aX as VerifyDomainResult, aY as WebhookEndpoint, aZ as WebhookEndpointWithSecret, a_ as WebhookEventType, a$ as mergeMigrations } from './client-DYUh2ub4.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-N2LD34ND.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-DYUh2ub4.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-N2LD34ND.js";
+} from "./chunk-MJKAVFFN.js";
 
 // src/payload.ts
 function resolveApiKey(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail",
-  "version": "0.15.1",
+  "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.1"
+    "groundmail-nodemailer": "0.15.3"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1",