groundmail 0.14.1 → 0.14.2

package/dist/authjs.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DdrSVDkA.js';
+import { G as Groundmail } from './client-B8xoWTgr.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-B8xoWTgr.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-B8xoWTgr.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-B8xoWTgr.d.ts}

@@ -719,13 +719,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 {

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-B8xoWTgr.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-B8xoWTgr.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-B8xoWTgr.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.2",
   "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.2"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1",