groundmail 0.0.0-stage → 0.14.2

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+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;
+    /** 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;
+}
+
+declare function signWebhookPayload(secret: string, payload: string, timestamp: number): string;
+declare function buildSignatureHeader(secret: string, payload: string, timestamp?: number): string;
+/**
+ * Verify a Groundmail webhook signature header (`Groundmail-Signature`).
+ * Expects HMAC-SHA256 over `${timestamp}.${rawBody}` with the endpoint secret.
+ */
+declare function verifyWebhookSignature(secret: string, payload: string, header: string | null | undefined, toleranceSec?: number): boolean;
+
+/** Merge `include:host` into an existing SPF record (or create a minimal one). */
+declare function mergeSpfInclude(existing: string | null | undefined, includeHost: string): string;
+
+type DnsProviderName = 'cloudflare' | 'godaddy' | 'vercel';
+type ApplyDnsRecordResult = {
+    purpose: string;
+    host: string;
+    action: 'created' | 'updated' | 'unchanged' | 'merged';
+    detail?: string;
+};
+type ApplyDnsResult = {
+    provider: DnsProviderName;
+    domain: string;
+    results: ApplyDnsRecordResult[];
+};
+type ApplyDnsCredentials = {
+    cloudflareApiToken?: string;
+    cloudflareZoneId?: string;
+    godaddyApiKey?: string;
+    godaddyApiSecret?: string;
+    vercelApiToken?: string;
+    vercelTeamId?: string;
+};
+
+declare function applyDnsRecords(input: {
+    provider: DnsProviderName;
+    domain: string;
+    records: DnsRecord[];
+    credentials: ApplyDnsCredentials;
+    fetchImpl?: typeof fetch;
+}): Promise<ApplyDnsResult>;
+
+export { DnsRecord, GroundmailError, type GroundmailErrorOptions, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };

package/dist/index.js

@@ -0,0 +1,20 @@
+import {
+  DEFAULT_API_BASE_URL,
+  Groundmail,
+  GroundmailError,
+  applyDnsRecords,
+  buildSignatureHeader,
+  mergeSpfInclude,
+  signWebhookPayload,
+  verifyWebhookSignature
+} from "./chunk-2ZKYDDVV.js";
+export {
+  DEFAULT_API_BASE_URL,
+  Groundmail,
+  GroundmailError,
+  applyDnsRecords,
+  buildSignatureHeader,
+  mergeSpfInclude,
+  signWebhookPayload,
+  verifyWebhookSignature
+};

package/dist/nodemailer.d.ts

@@ -0,0 +1 @@
+export { GroundmailTransportOptions, HEADER_IDEMPOTENCY, HEADER_SCHEDULED_AT, HEADER_TAG, createGroundmailTransport, groundmailTransport, mailDataToSendParams } from 'groundmail-nodemailer';

package/dist/nodemailer.js

@@ -0,0 +1,17 @@
+// src/nodemailer.ts
+import {
+  createGroundmailTransport,
+  groundmailTransport,
+  mailDataToSendParams,
+  HEADER_IDEMPOTENCY,
+  HEADER_SCHEDULED_AT,
+  HEADER_TAG
+} from "groundmail-nodemailer";
+export {
+  HEADER_IDEMPOTENCY,
+  HEADER_SCHEDULED_AT,
+  HEADER_TAG,
+  createGroundmailTransport,
+  groundmailTransport,
+  mailDataToSendParams
+};

package/dist/payload.d.ts

@@ -0,0 +1,87 @@
+import { G as Groundmail } from './client-B8xoWTgr.js';
+
+/**
+ * Minimal Payload `SendEmailOptions` / address shapes used by this adapter.
+ * Compatible with Payload 3 without requiring `payload` at build time.
+ */
+type PayloadEmailAddress = string | {
+    name?: string;
+    address: string;
+} | Array<string | {
+    name?: string;
+    address: string;
+}>;
+type PayloadSendEmailOptions = {
+    from?: PayloadEmailAddress;
+    to?: PayloadEmailAddress;
+    cc?: PayloadEmailAddress;
+    bcc?: PayloadEmailAddress;
+    replyTo?: PayloadEmailAddress;
+    subject?: string;
+    html?: string | {
+        toString(): string;
+    };
+    text?: string | {
+        toString(): string;
+    };
+    headers?: Array<{
+        key: string;
+        value: string;
+    }> | Record<string, string | string[] | {
+        prepared: boolean;
+        value: string;
+    }>;
+    attachments?: Array<{
+        filename?: string | false;
+        content?: string | Buffer;
+        path?: string | {
+            href: string;
+        };
+    }>;
+};
+/** Payload `EmailAdapter` factory return shape (sync outer factory). */
+type PayloadEmailAdapterInstance = {
+    name: string;
+    defaultFromAddress: string;
+    defaultFromName: string;
+    sendEmail: (message: PayloadSendEmailOptions) => Promise<{
+        id: string;
+    }>;
+};
+type PayloadEmailAdapter = () => PayloadEmailAdapterInstance;
+type GroundmailPayloadAdapterArgs = {
+    /** Verified default From address (required by Payload). */
+    defaultFromAddress: string;
+    /** Display name for the default From. */
+    defaultFromName: string;
+    /** Groundmail API key (`gm_…`). Falls back to `GROUNDMAIL_API_KEY`. */
+    apiKey?: string;
+    /** Override API base URL (tests / self-hosted). */
+    baseUrl?: string;
+    /** Injected client (tests). */
+    client?: Groundmail;
+    /** Force all mail to this address (local/dev). */
+    overrideRecipientAddress?: string;
+};
+/**
+ * Payload CMS email adapter for Groundmail (HTTP API).
+ *
+ * Drop-in for Payload 3 `email:` config — same shape as official REST adapters.
+ *
+ * @example
+ * ```ts
+ * import { buildConfig } from 'payload'
+ * import { groundmailAdapter } from 'groundmail-payload'
+ *
+ * export default buildConfig({
+ *   email: groundmailAdapter({
+ *     defaultFromAddress: 'noreply@yourdomain.com',
+ *     defaultFromName: 'Acme',
+ *     // apiKey: process.env.GROUNDMAIL_API_KEY,
+ *   }),
+ * })
+ * ```
+ */
+declare function groundmailAdapter(args: GroundmailPayloadAdapterArgs): PayloadEmailAdapter;
+
+export { type GroundmailPayloadAdapterArgs, type PayloadEmailAdapter, type PayloadEmailAdapterInstance, type PayloadEmailAddress, type PayloadSendEmailOptions, groundmailAdapter };

package/dist/payload.js

@@ -0,0 +1,114 @@
+import {
+  DEFAULT_API_BASE_URL,
+  Groundmail
+} from "./chunk-2ZKYDDVV.js";
+
+// src/payload.ts
+function resolveApiKey(args) {
+  return args.apiKey || (typeof process !== "undefined" ? process.env.GROUNDMAIL_API_KEY : void 0);
+}
+function formatAddress(address) {
+  if (typeof address === "string") return address;
+  return address.name ? `${address.name} <${address.address}>` : address.address;
+}
+function mapFrom(address, defaultFromName, defaultFromAddress) {
+  if (!address) return `${defaultFromName} <${defaultFromAddress}>`;
+  if (Array.isArray(address)) {
+    const first = address[0];
+    if (!first) return `${defaultFromName} <${defaultFromAddress}>`;
+    return formatAddress(first);
+  }
+  return formatAddress(address);
+}
+function mapAddresses(addresses) {
+  if (!addresses) return void 0;
+  if (typeof addresses === "string") return addresses;
+  if (Array.isArray(addresses)) {
+    return addresses.map((a) => typeof a === "string" ? a : a.address);
+  }
+  return addresses.address;
+}
+function mapHeaders(headers) {
+  if (!headers) return void 0;
+  if (Array.isArray(headers)) {
+    return headers.reduce((acc, { key, value }) => {
+      acc[key] = value;
+      return acc;
+    }, {});
+  }
+  return Object.entries(headers).reduce((acc, [key, value]) => {
+    if (typeof value === "string") acc[key] = value;
+    else if (Array.isArray(value)) acc[key] = value.join(", ");
+    else acc[key] = value.value;
+    return acc;
+  }, {});
+}
+function mapAttachments(attachments) {
+  if (!attachments?.length) return void 0;
+  return attachments.map((attachment) => {
+    if (attachment.filename == null || attachment.filename === false) {
+      throw new Error("Groundmail Payload adapter: attachment is missing filename");
+    }
+    if (attachment.path && !attachment.content) {
+      throw new Error(
+        "Groundmail Payload adapter: path-only attachments are not supported \u2014 pass content (base64 or string)"
+      );
+    }
+    if (typeof attachment.content === "string") {
+      return { filename: attachment.filename, content: attachment.content };
+    }
+    if (attachment.content instanceof Buffer) {
+      return { filename: attachment.filename, content: attachment.content.toString("base64") };
+    }
+    throw new Error("Groundmail Payload adapter: attachment content must be a string or Buffer");
+  });
+}
+function groundmailAdapter(args) {
+  const { defaultFromAddress, defaultFromName } = args;
+  if (!defaultFromAddress?.trim()) {
+    throw new Error("groundmailAdapter requires defaultFromAddress");
+  }
+  if (!defaultFromName?.trim()) {
+    throw new Error("groundmailAdapter requires defaultFromName");
+  }
+  const adapter = () => ({
+    name: "groundmail",
+    defaultFromAddress,
+    defaultFromName,
+    sendEmail: async (message) => {
+      const client = args.client ?? (() => {
+        const key = resolveApiKey(args);
+        if (!key) {
+          throw new Error(
+            "Groundmail Payload adapter requires `apiKey` or GROUNDMAIL_API_KEY"
+          );
+        }
+        return new Groundmail(key, {
+          baseUrl: args.baseUrl ?? DEFAULT_API_BASE_URL
+        });
+      })();
+      const to = args.overrideRecipientAddress ? args.overrideRecipientAddress : mapAddresses(message.to);
+      if (!to || Array.isArray(to) && to.length === 0) {
+        throw new Error("Groundmail Payload adapter: message.to is required");
+      }
+      const result = await client.emails.send({
+        from: mapFrom(message.from, defaultFromName, defaultFromAddress),
+        to,
+        cc: mapAddresses(message.cc),
+        bcc: mapAddresses(message.bcc),
+        replyTo: mapAddresses(message.replyTo),
+        subject: message.subject ?? "",
+        html: message.html?.toString(),
+        text: message.text?.toString(),
+        headers: mapHeaders(message.headers),
+        attachments: mapAttachments(message.attachments),
+        tags: [{ name: "product", value: "payload" }]
+      });
+      return { id: result.id };
+    }
+  });
+  return adapter;
+}
+export {
+  groundmailAdapter
+};

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "groundmail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.2",
+  "description": "Groundmail transactional email API client",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./nodemailer": {
+      "types": "./dist/nodemailer.d.ts",
+      "import": "./dist/nodemailer.js"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth.d.ts",
+      "import": "./dist/better-auth.js"
+    },
+    "./authjs": {
+      "types": "./dist/authjs.d.ts",
+      "import": "./dist/authjs.js"
+    },
+    "./clerk": {
+      "types": "./dist/clerk.d.ts",
+      "import": "./dist/clerk.js"
+    },
+    "./payload": {
+      "types": "./dist/payload.d.ts",
+      "import": "./dist/payload.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Groundmail/groundmail-sdks.git"
+  },
+  "homepage": "https://docs.groundmail.dev/quickstart",
+  "bugs": {
+    "url": "https://github.com/Groundmail/groundmail-sdks/issues"
+  },
+  "keywords": [
+    "email",
+    "transactional",
+    "groundmail",
+    "smtp",
+    "nodemailer",
+    "better-auth",
+    "auth.js",
+    "next-auth",
+    "nextauth",
+    "clerk",
+    "payload",
+    "payloadcms",
+    "react-email"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@react-email/render": ">=0.0.16",
+    "nodemailer": ">=6.0.0",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-email/render": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/better-auth.ts src/authjs.ts src/clerk.ts src/payload.ts --format esm --dts --clean",
+    "build:nodemailer-bridge": "tsup src/nodemailer.ts --format esm --dts --external groundmail-nodemailer",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run build:nodemailer-bridge"
+  },
+  "dependencies": {
+    "groundmail-nodemailer": "0.14.2"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^8.0.1",
+    "nodemailer": "^9.0.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  }
+}