groundmail 0.14.1 → 0.14.3

package/dist/authjs.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DdrSVDkA.js';
+import { G as Groundmail } from './client-xZ_HIfb9.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-IZYE7HGT.js";
+} from "./chunk-2ZKYDDVV.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-DdrSVDkA.js';
+import { S as SendEmailResult, G as Groundmail } from './client-xZ_HIfb9.js';
 
 type BetterAuthEmailUser = {
     email: string;

package/dist/better-auth.js

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

package/dist/{chunk-IZYE7HGT.js → chunk-2ZKYDDVV.js}

@@ -7,14 +7,44 @@ var GroundmailError = class _GroundmailError extends Error {
     this.details = details;
     this.code = options?.code;
     this.upgradeUrl = options?.upgradeUrl;
+    this.hint = options?.hint;
+    this.docsUrl = options?.docsUrl;
+    this.requiredScope = options?.requiredScope;
+  }
+  /** Same fields as the API's error body, snake_case, for logging. */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      ...this.code ? { code: this.code } : {},
+      ...this.hint ? { hint: this.hint } : {},
+      ...this.docsUrl ? { docs_url: this.docsUrl } : {},
+      ...this.requiredScope ? { required_scope: this.requiredScope } : {},
+      ...this.upgradeUrl ? { upgrade_url: this.upgradeUrl } : {},
+      ...this.details !== void 0 ? { details: this.details } : {}
+    };
   }
+  /**
+   * Reads both error shapes the API returns: `{ error: { message, code, hint,
+   * docs_url, … } }`, and the older `{ error: "<message>", code, hint, docs_url }`.
+   */
   static fromResponse(status, body) {
-    const err = body.error;
-    const message = typeof err === "string" ? err : err?.message || `Request failed with status ${status}`;
-    const details = typeof err === "object" && err ? err.details : void 0;
-    const code = typeof err === "object" && err && "code" in err ? String(err.code) : void 0;
-    const upgradeUrl = typeof err === "object" && err && "upgrade_url" in err ? String(err.upgrade_url) : void 0;
-    return new _GroundmailError(message, status, details, { code, upgradeUrl });
+    const err = body?.error;
+    const nested = typeof err === "object" && err ? err : void 0;
+    const top = body ?? {};
+    const pick = (key) => {
+      const value = nested?.[key] ?? top[key];
+      return typeof value === "string" && value ? value : void 0;
+    };
+    const message = typeof err === "string" && err || nested?.message || pick("message") || `Request failed with status ${status}`;
+    return new _GroundmailError(message, status, nested ? nested.details : top.details, {
+      code: pick("code"),
+      upgradeUrl: pick("upgrade_url"),
+      hint: pick("hint"),
+      docsUrl: pick("docs_url"),
+      requiredScope: pick("required_scope")
+    });
   }
 };
 

package/dist/clerk.d.ts

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

package/dist/{client-DdrSVDkA.d.ts → client-xZ_HIfb9.d.ts}

@@ -582,6 +582,7 @@ type DomainDnsAnalysis = {
     dmarc: DomainDmarcAnalysis;
     bimi: DomainBimiAnalysis;
 };
+type DomainTrackingStatus = 'disabled' | 'pending' | 'active' | 'error';
 type DomainTrackingDns = {
     required: boolean;
     host: string | null;
@@ -596,6 +597,14 @@ type Domain = {
     verified_at: string | null;
     open_tracking: boolean;
     click_tracking: boolean;
+    /**
+     * Whether open/click tracking is actually being applied to outgoing mail:
+     * `pending` until the tracking CNAME is accepted and a certificate is issued for the
+     * tracking hostname (a few minutes after the CNAME is added), `active` once both are done.
+     */
+    tracking_status?: DomainTrackingStatus | string;
+    /** Why tracking is not active yet, when `tracking_status` is `pending` or `error`. */
+    tracking_error?: string | null;
     tls_mode: DomainTlsMode | string;
     inbound_enabled: boolean;
     inbound_status: 'disabled' | 'pending' | 'active' | 'error' | string;
@@ -719,13 +728,24 @@ type ApplyDnsResult = {
     domain: string;
     results: ApplyDnsRecordResult[];
 };
+/** Fields the API puts on an error, nested under `error` or (older routes) beside it. */
+type ApiErrorFields = {
+    message?: string;
+    details?: unknown;
+    /** Stable machine-readable code, e.g. `insufficient_scope`. */
+    code?: string;
+    /** How to fix it. */
+    hint?: string;
+    /** https://docs.groundmail.dev/errors#<code> */
+    docs_url?: string;
+    /** With `insufficient_scope`: the scope(s) the endpoint needs, space-separated. */
+    required_scope?: string;
+    upgrade_url?: string;
+};
 type ApiErrorBody = {
-    error?: string | {
-        message?: string;
-        details?: unknown;
-        code?: string;
-        upgrade_url?: string;
-    };
+    error?: string | ApiErrorFields;
+} & Omit<ApiErrorFields, 'message'> & {
+    message?: string;
 };
 
 declare class AutomationsResource {
@@ -947,4 +967,4 @@ declare class Groundmail {
     request<T>(path: string, init: RequestInit): Promise<T>;
 }
 
-export { type ListAutomationRunsParams as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, DEFAULT_API_BASE_URL as E, type DeliverabilityBucket as F, Groundmail as G, type DeliverabilityDomainInsight as H, type DeliverabilityInsightsResult as I, type DeliverabilityMailServerRelay as J, type DeliverabilityWindow as K, type DnsProviderName as L, type Domain as M, type DomainBimiAnalysis as N, type DomainDetailResult as O, type DomainDmarcAnalysis as P, type DomainDnsAnalysis as Q, type DomainStatus as R, type SendEmailResult as S, type DomainTlsMode as T, type DomainTrackingDns as U, type EmailListItem as V, type EmailWebhookEventType as W, type EventRecord as X, type GroundmailOptions as Y, type ListApiKeysParams as Z, type ListApiKeysResult as _, type ApiErrorCode as a, type ListAutomationRunsResult as a0, type ListAutomationsResult as a1, type ListDomainsParams as a2, type ListDomainsResult as a3, type ListEmailsParams as a4, type ListEmailsResult as a5, type ListReceivedEmailsParams as a6, type ListReceivedEmailsResult as a7, type ListSuppressionsParams as a8, type ListSuppressionsResult as a9, type UpdateWebhookParams as aA, type VerifyDomainResult as aB, type WebhookEndpoint as aC, type WebhookEndpointWithSecret as aD, type WebhookEventType as aE, type ListTemplatesParams as aa, type ListTemplatesResult as ab, type MailServerSigningStatus as ac, type ReceivedEmail as ad, type ReceivedEmailAttachment as ae, type ReceivedEmailAttachmentMeta as af, type RemoteApplyDnsCredentials as ag, type SendEmailParams as ah, type SuppressedErrorDetails as ai, type Suppression as aj, type Template as ak, type TemplateFormat as al, type TemplateLintWarning as am, type TemplateStarter as an, type TemplateStatus as ao, type TemplateVersion as ap, type TestEmailWebhookParams as aq, type TestEmailWebhookResult as ar, type TriggerEventParams as as, type TriggerEventResult as at, type TwilioIntegrationResponse as au, type TwilioIntegrationStatus as av, type UpdateAutomationParams as aw, type UpdateDomainParams as ax, type UpdateEmailParams as ay, type UpdateTemplateParams 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 AutomationRun as i, type AutomationRunResponse as j, type AutomationRunStatus as k, type AutomationRunStep as l, type AutomationRunStepStatus as m, type AutomationStatus as n, type AutomationStep as o, type AutomationTrigger as p, type ConnectTwilioParams as q, type ContactWebhookEventPayload as r, type CreateApiKeyParams as s, type CreateApiKeyResult as t, type CreateAutomationParams as u, type CreateDomainParams as v, type CreateDomainResult as w, type CreateSuppressionParams as x, type CreateTemplateParams as y, type CreateWebhookParams as z };
+export { type ListApiKeysResult as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, DEFAULT_API_BASE_URL as E, type DeliverabilityBucket as F, Groundmail as G, type DeliverabilityDomainInsight as H, type DeliverabilityInsightsResult as I, type DeliverabilityMailServerRelay as J, type DeliverabilityWindow as K, type DnsProviderName as L, type Domain as M, type DomainBimiAnalysis as N, type DomainDetailResult as O, type DomainDmarcAnalysis as P, type DomainDnsAnalysis as Q, type DomainStatus as R, type SendEmailResult as S, type DomainTlsMode as T, type DomainTrackingDns as U, type DomainTrackingStatus as V, type EmailListItem as W, type EmailWebhookEventType as X, type EventRecord as Y, type GroundmailOptions as Z, type ListApiKeysParams as _, type ApiErrorCode as a, type ListAutomationRunsParams as a0, type ListAutomationRunsResult as a1, type ListAutomationsResult as a2, type ListDomainsParams as a3, type ListDomainsResult as a4, type ListEmailsParams as a5, type ListEmailsResult as a6, type ListReceivedEmailsParams as a7, type ListReceivedEmailsResult as a8, type ListSuppressionsParams as a9, type UpdateTemplateParams as aA, type UpdateWebhookParams as aB, type VerifyDomainResult as aC, type WebhookEndpoint as aD, type WebhookEndpointWithSecret as aE, type WebhookEventType as aF, type ListSuppressionsResult as aa, type ListTemplatesParams as ab, type ListTemplatesResult as ac, type MailServerSigningStatus as ad, type ReceivedEmail as ae, type ReceivedEmailAttachment as af, type ReceivedEmailAttachmentMeta as ag, type RemoteApplyDnsCredentials as ah, type SendEmailParams as ai, type SuppressedErrorDetails as aj, type Suppression as ak, type Template as al, type TemplateFormat as am, type TemplateLintWarning as an, type TemplateStarter as ao, type TemplateStatus as ap, type TemplateVersion as aq, type TestEmailWebhookParams as ar, type TestEmailWebhookResult as as, type TriggerEventParams as at, type TriggerEventResult as au, type TwilioIntegrationResponse as av, type TwilioIntegrationStatus as aw, type UpdateAutomationParams as ax, type UpdateDomainParams as ay, type UpdateEmailParams 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 AutomationRun as i, type AutomationRunResponse as j, type AutomationRunStatus as k, type AutomationRunStep as l, type AutomationRunStepStatus as m, type AutomationStatus as n, type AutomationStep as o, type AutomationTrigger as p, type ConnectTwilioParams as q, type ContactWebhookEventPayload as r, type CreateApiKeyParams as s, type CreateApiKeyResult as t, type CreateAutomationParams as u, type CreateDomainParams as v, type CreateDomainResult as w, type CreateSuppressionParams as x, type CreateTemplateParams as y, type CreateWebhookParams as z };

package/dist/index.d.ts

@@ -1,15 +1,37 @@
-import { A as ApiErrorBody, D as DnsRecord } from './client-DdrSVDkA.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 AutomationRun, j as AutomationRunResponse, k as AutomationRunStatus, l as AutomationRunStep, m as AutomationRunStepStatus, n as AutomationStatus, o as AutomationStep, p as AutomationTrigger, B as BatchSendEmailResult, C as CategoryUnsubscribedErrorDetails, q as ConnectTwilioParams, r as ContactWebhookEventPayload, s as CreateApiKeyParams, t as CreateApiKeyResult, u as CreateAutomationParams, v as CreateDomainParams, w as CreateDomainResult, x as CreateSuppressionParams, y as CreateTemplateParams, z as CreateWebhookParams, E as DEFAULT_API_BASE_URL, F as DeliverabilityBucket, H as DeliverabilityDomainInsight, I as DeliverabilityInsightsResult, J as DeliverabilityMailServerRelay, K as DeliverabilityWindow, L as DnsProviderName, M as Domain, N as DomainBimiAnalysis, O as DomainDetailResult, P as DomainDmarcAnalysis, Q as DomainDnsAnalysis, R as DomainStatus, T as DomainTlsMode, U as DomainTrackingDns, V as EmailListItem, W as EmailWebhookEventType, X as EventRecord, G as Groundmail, Y as GroundmailOptions, Z as ListApiKeysParams, _ as ListApiKeysResult, $ as ListAutomationRunsParams, a0 as ListAutomationRunsResult, a1 as ListAutomationsResult, a2 as ListDomainsParams, a3 as ListDomainsResult, a4 as ListEmailsParams, a5 as ListEmailsResult, a6 as ListReceivedEmailsParams, a7 as ListReceivedEmailsResult, a8 as ListSuppressionsParams, a9 as ListSuppressionsResult, aa as ListTemplatesParams, ab as ListTemplatesResult, ac as MailServerSigningStatus, ad as ReceivedEmail, ae as ReceivedEmailAttachment, af as ReceivedEmailAttachmentMeta, ag as RemoteApplyDnsCredentials, ah as SendEmailParams, S as SendEmailResult, ai as SuppressedErrorDetails, aj as Suppression, ak as Template, al as TemplateFormat, am as TemplateLintWarning, an as TemplateStarter, ao as TemplateStatus, ap as TemplateVersion, aq as TestEmailWebhookParams, ar as TestEmailWebhookResult, as as TriggerEventParams, at as TriggerEventResult, au as TwilioIntegrationResponse, av as TwilioIntegrationStatus, aw as UpdateAutomationParams, ax as UpdateDomainParams, ay as UpdateEmailParams, az as UpdateTemplateParams, aA as UpdateWebhookParams, aB as VerifyDomainResult, aC as WebhookEndpoint, aD as WebhookEndpointWithSecret, aE as WebhookEventType } from './client-DdrSVDkA.js';
+import { A as ApiErrorBody, D as DnsRecord } from './client-xZ_HIfb9.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 AutomationRun, j as AutomationRunResponse, k as AutomationRunStatus, l as AutomationRunStep, m as AutomationRunStepStatus, n as AutomationStatus, o as AutomationStep, p as AutomationTrigger, B as BatchSendEmailResult, C as CategoryUnsubscribedErrorDetails, q as ConnectTwilioParams, r as ContactWebhookEventPayload, s as CreateApiKeyParams, t as CreateApiKeyResult, u as CreateAutomationParams, v as CreateDomainParams, w as CreateDomainResult, x as CreateSuppressionParams, y as CreateTemplateParams, z as CreateWebhookParams, E as DEFAULT_API_BASE_URL, F as DeliverabilityBucket, H as DeliverabilityDomainInsight, I as DeliverabilityInsightsResult, J as DeliverabilityMailServerRelay, K as DeliverabilityWindow, L as DnsProviderName, M as Domain, N as DomainBimiAnalysis, O as DomainDetailResult, P as DomainDmarcAnalysis, Q as DomainDnsAnalysis, R as DomainStatus, T as DomainTlsMode, U as DomainTrackingDns, V as DomainTrackingStatus, W as EmailListItem, X as EmailWebhookEventType, Y as EventRecord, G as Groundmail, Z as GroundmailOptions, _ as ListApiKeysParams, $ as ListApiKeysResult, a0 as ListAutomationRunsParams, a1 as ListAutomationRunsResult, a2 as ListAutomationsResult, a3 as ListDomainsParams, a4 as ListDomainsResult, a5 as ListEmailsParams, a6 as ListEmailsResult, a7 as ListReceivedEmailsParams, a8 as ListReceivedEmailsResult, a9 as ListSuppressionsParams, aa as ListSuppressionsResult, ab as ListTemplatesParams, ac as ListTemplatesResult, ad as MailServerSigningStatus, ae as ReceivedEmail, af as ReceivedEmailAttachment, ag as ReceivedEmailAttachmentMeta, ah as RemoteApplyDnsCredentials, ai as SendEmailParams, S as SendEmailResult, aj as SuppressedErrorDetails, ak as Suppression, al as Template, am as TemplateFormat, an as TemplateLintWarning, ao as TemplateStarter, ap as TemplateStatus, aq as TemplateVersion, ar as TestEmailWebhookParams, as as TestEmailWebhookResult, at as TriggerEventParams, au as TriggerEventResult, av as TwilioIntegrationResponse, aw as TwilioIntegrationStatus, ax as UpdateAutomationParams, ay as UpdateDomainParams, az as UpdateEmailParams, aA as UpdateTemplateParams, aB as UpdateWebhookParams, aC as VerifyDomainResult, aD as WebhookEndpoint, aE as WebhookEndpointWithSecret, aF as WebhookEventType } from './client-xZ_HIfb9.js';
 
+type GroundmailErrorOptions = {
+    code?: string;
+    upgradeUrl?: string;
+    hint?: string;
+    docsUrl?: string;
+    requiredScope?: string;
+};
+/**
+ * An API error. Besides `message` and `status`, the API says how to recover:
+ * `code` (stable, e.g. `insufficient_scope`), `hint` (what to do next),
+ * `docsUrl` (the errors page entry for the code), `requiredScope` (with
+ * `insufficient_scope`) and `upgradeUrl` (with plan limits).
+ */
 declare class GroundmailError extends Error {
     readonly status: number;
     readonly details?: unknown;
     readonly code?: string;
     readonly upgradeUrl?: string;
-    constructor(message: string, status: number, details?: unknown, options?: {
-        code?: string;
-        upgradeUrl?: string;
-    });
+    /** How to fix it, from the API. */
+    readonly hint?: string;
+    /** Docs for this error code, e.g. https://docs.groundmail.dev/errors#insufficient_scope */
+    readonly docsUrl?: string;
+    /** With `insufficient_scope`: the scope(s) the endpoint needs, space-separated. */
+    readonly requiredScope?: string;
+    constructor(message: string, status: number, details?: unknown, options?: GroundmailErrorOptions);
+    /** Same fields as the API's error body, snake_case, for logging. */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Reads both error shapes the API returns: `{ error: { message, code, hint,
+     * docs_url, … } }`, and the older `{ error: "<message>", code, hint, docs_url }`.
+     */
     static fromResponse(status: number, body: ApiErrorBody): GroundmailError;
 }
 
@@ -53,4 +75,4 @@ declare function applyDnsRecords(input: {
     fetchImpl?: typeof fetch;
 }): Promise<ApplyDnsResult>;
 
-export { DnsRecord, GroundmailError, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };
+export { DnsRecord, GroundmailError, type GroundmailErrorOptions, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   mergeSpfInclude,
   signWebhookPayload,
   verifyWebhookSignature
-} from "./chunk-IZYE7HGT.js";
+} from "./chunk-2ZKYDDVV.js";
 export {
   DEFAULT_API_BASE_URL,
   Groundmail,

package/dist/payload.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DdrSVDkA.js';
+import { G as Groundmail } from './client-xZ_HIfb9.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-IZYE7HGT.js";
+} from "./chunk-2ZKYDDVV.js";
 
 // src/payload.ts
 function resolveApiKey(args) {

package/package.json

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