groundmail-nodemailer 0.0.0-stage → 0.14.2

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# groundmail-nodemailer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**[Nodemailer](https://nodemailer.com) transport for [Groundmail](https://groundmail.dev)** — keep `transporter.sendMail(...)` and deliver over the Groundmail HTTP API (not SMTP).
+
+This repository is the **source of truth** for the transport implementation. Issues and PRs belong here. The HTTP client lives in [`groundmail`](https://www.npmjs.com/package/groundmail).
+
+Works anywhere Nodemailer is accepted: Express apps, Payload, Auth.js email, Strapi, Ghost, workers, and custom stacks.
+
+## Install
+
+```bash
+npm install groundmail-nodemailer groundmail nodemailer
+```
+
+```bash
+GROUNDMAIL_API_KEY=gm_your_key_here
+```
+
+## Usage
+
+```ts
+import nodemailer from 'nodemailer'
+import { createGroundmailTransport } from 'groundmail-nodemailer'
+
+const transporter = nodemailer.createTransport(
+  createGroundmailTransport({
+    apiKey: process.env.GROUNDMAIL_API_KEY!,
+  }),
+)
+
+await transporter.sendMail({
+  from: 'ops@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Your receipt',
+  html: '<p>Thanks for your purchase.</p>',
+  headers: {
+    'X-Groundmail-Tag': 'campaign=welcome',
+    'X-Groundmail-Idempotency-Key': 'receipt-123',
+  },
+})
+```
+
+The same transport is also available as `groundmail/nodemailer` (re-export).
+
+## Docs
+
+https://docs.groundmail.dev/frameworks/node
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { Transport, TransportOptions } from 'nodemailer';
+import MailMessage from 'nodemailer/lib/mailer/mail-message.js';
+import { Groundmail, SendEmailParams } from 'groundmail';
+
+declare const HEADER_IDEMPOTENCY = "X-Groundmail-Idempotency-Key";
+declare const HEADER_SCHEDULED_AT = "X-Groundmail-Scheduled-At";
+declare const HEADER_TAG = "X-Groundmail-Tag";
+type GroundmailTransportOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    /** Prebuilt client (tests / advanced wiring). */
+    client?: Groundmail;
+};
+declare function mailDataToSendParams(data: MailMessage['data']): Promise<SendEmailParams>;
+/** Nodemailer transport that delivers via Groundmail HTTP API. */
+declare function createGroundmailTransport(options: GroundmailTransportOptions): Transport & TransportOptions;
+/** Alias matching common `createTransport(transport(...))` naming. */
+declare const groundmailTransport: typeof createGroundmailTransport;
+
+export { type GroundmailTransportOptions, HEADER_IDEMPOTENCY, HEADER_SCHEDULED_AT, HEADER_TAG, createGroundmailTransport, groundmailTransport, mailDataToSendParams };

package/dist/index.js

@@ -0,0 +1,187 @@
+// src/transport.ts
+import {
+  Groundmail,
+  DEFAULT_API_BASE_URL,
+  GroundmailError
+} from "groundmail";
+var HEADER_IDEMPOTENCY = "X-Groundmail-Idempotency-Key";
+var HEADER_SCHEDULED_AT = "X-Groundmail-Scheduled-At";
+var HEADER_TAG = "X-Groundmail-Tag";
+var RESERVED_HEADERS = /* @__PURE__ */ new Set([
+  "from",
+  "to",
+  "cc",
+  "bcc",
+  "reply-to",
+  "subject",
+  "content-type",
+  "mime-version",
+  "date",
+  "message-id",
+  "x-groundmail-idempotency-key",
+  "x-groundmail-scheduled-at",
+  "x-groundmail-tag",
+  "idempotency-key"
+]);
+function formatOne(addr) {
+  if (typeof addr === "string") return addr.trim();
+  const email = addr.address?.trim();
+  if (!email) return "";
+  const name = addr.name?.trim();
+  return name ? `${name} <${email}>` : email;
+}
+function formatAddresses(value) {
+  if (value == null) return [];
+  const list = Array.isArray(value) ? value : [value];
+  return list.map(formatOne).filter(Boolean);
+}
+function headerMap(headers) {
+  const out = {};
+  if (!headers) return out;
+  if (Array.isArray(headers)) {
+    for (const entry of headers) {
+      if (!entry || typeof entry !== "object") continue;
+      const key = String(entry.key || "").toLowerCase();
+      const value = String(entry.value ?? "");
+      if (!key) continue;
+      (out[key] ??= []).push(value);
+    }
+    return out;
+  }
+  for (const [key, raw] of Object.entries(headers)) {
+    const k = key.toLowerCase();
+    if (Array.isArray(raw)) {
+      out[k] = raw.map(String);
+    } else if (raw != null) {
+      out[k] = [String(raw)];
+    }
+  }
+  return out;
+}
+async function attachmentContentToBase64(content) {
+  if (content == null) {
+    throw new Error("Attachment is missing content");
+  }
+  if (typeof content === "string") {
+    return Buffer.from(content).toString("base64");
+  }
+  if (Buffer.isBuffer(content)) {
+    return content.toString("base64");
+  }
+  if (content instanceof Uint8Array) {
+    return Buffer.from(content).toString("base64");
+  }
+  throw new Error("Unsupported attachment content type");
+}
+async function mailDataToSendParams(data) {
+  const fromList = formatAddresses(data.from);
+  if (!fromList.length) throw new Error("Email is missing a From address.");
+  const to = formatAddresses(data.to);
+  if (!to.length) throw new Error("Email is missing a To recipient.");
+  const html = typeof data.html === "string" ? data.html : void 0;
+  const text = typeof data.text === "string" ? data.text : void 0;
+  if (!html && !text) {
+    throw new Error("Email must include html or text content.");
+  }
+  const headers = headerMap(data.headers);
+  const params = {
+    from: fromList[0],
+    to: to.length === 1 ? to[0] : to
+  };
+  if (typeof data.subject === "string" && data.subject) params.subject = data.subject;
+  if (html) params.html = html;
+  if (text) params.text = text;
+  const reply = formatAddresses(data.replyTo);
+  if (reply.length) params.replyTo = reply.length === 1 ? reply[0] : reply;
+  const cc = formatAddresses(data.cc);
+  if (cc.length) params.cc = cc;
+  const bcc = formatAddresses(data.bcc);
+  if (bcc.length) params.bcc = bcc;
+  if (data.attachments?.length) {
+    params.attachments = await Promise.all(
+      data.attachments.map(async (att) => {
+        const filename = att.filename || att.cid || "attachment";
+        const contentType = att.contentType || "application/octet-stream";
+        if (att.path || typeof att.raw === "string") {
+          throw new Error(
+            `Attachment "${filename}" must include inline content (Buffer/string). path/raw are not supported.`
+          );
+        }
+        return {
+          filename: String(filename),
+          contentType,
+          content: await attachmentContentToBase64(att.content),
+          ...att.cid ? { contentId: String(att.cid) } : {}
+        };
+      })
+    );
+  }
+  const tagValues = headers["x-groundmail-tag"] ?? [];
+  if (tagValues.length) {
+    params.tags = tagValues.flatMap((raw) => {
+      const trimmed = raw.trim();
+      if (!trimmed) return [];
+      if (trimmed.includes("=")) {
+        const [name, value] = trimmed.split("=", 2);
+        if (name.trim() && value.trim()) return [{ name: name.trim(), value: value.trim() }];
+        return [];
+      }
+      return [{ name: "tag", value: trimmed }];
+    });
+  }
+  const forward = {};
+  for (const [key, values] of Object.entries(headers)) {
+    if (RESERVED_HEADERS.has(key)) continue;
+    if (key.startsWith("content-")) continue;
+    const value = values[values.length - 1]?.trim();
+    if (value) forward[key] = value;
+  }
+  if (Object.keys(forward).length) params.headers = forward;
+  const idem = headers["x-groundmail-idempotency-key"]?.[0]?.trim() || headers["idempotency-key"]?.[0]?.trim();
+  if (idem) params.idempotencyKey = idem;
+  const scheduled = headers["x-groundmail-scheduled-at"]?.[0]?.trim();
+  if (scheduled) params.scheduledAt = scheduled;
+  return params;
+}
+function createGroundmailTransport(options) {
+  const client = options.client ?? new Groundmail(options.apiKey, {
+    baseUrl: options.baseUrl ?? DEFAULT_API_BASE_URL
+  });
+  return {
+    name: "Groundmail",
+    version: "0.14.0",
+    send(mail, callback) {
+      ;
+      (async () => {
+        const params = await mailDataToSendParams(mail.data);
+        const result = await client.emails.send(params);
+        const envelope = mail.message.getEnvelope();
+        return {
+          envelope,
+          messageId: result.id,
+          accepted: envelope.to,
+          rejected: [],
+          pending: [],
+          response: `${result.status} ${result.id}`
+        };
+      })().then(
+        (info) => {
+          callback(null, info);
+        },
+        (err) => {
+          const error = err instanceof GroundmailError ? err : err instanceof Error ? err : new Error(String(err));
+          callback(error, void 0);
+        }
+      );
+    }
+  };
+}
+var groundmailTransport = createGroundmailTransport;
+export {
+  HEADER_IDEMPOTENCY,
+  HEADER_SCHEDULED_AT,
+  HEADER_TAG,
+  createGroundmailTransport,
+  groundmailTransport,
+  mailDataToSendParams
+};

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "groundmail-nodemailer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.14.2",
+  "description": "Nodemailer transport for Groundmail transactional email (HTTP API, not SMTP)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Groundmail/groundmail-nodemailer.git"
+  },
+  "homepage": "https://docs.groundmail.dev/frameworks/node",
+  "bugs": {
+    "url": "https://github.com/Groundmail/groundmail-nodemailer/issues"
+  },
+  "keywords": [
+    "nodemailer",
+    "nodemailer-transport",
+    "email",
+    "transactional",
+    "transport",
+    "groundmail",
+    "smtp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "nodemailer": ">=6.0.0",
+    "groundmail": ">=0.13.0"
+  },
+  "dependencies": {
+    "groundmail": "0.14.2"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^8.0.1",
+    "nodemailer": "^9.0.3",
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --external groundmail --external nodemailer --clean",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Nodemailer transport for Groundmail.
+ *
+ * Source of truth for the transport lives in this package (public GitHub repo
+ * Groundmail/groundmail-nodemailer). The core `groundmail` SDK re-exports
+ * these symbols as `groundmail/nodemailer` for backward compatibility.
+ */
+export {
+  createGroundmailTransport,
+  groundmailTransport,
+  mailDataToSendParams,
+  HEADER_IDEMPOTENCY,
+  HEADER_SCHEDULED_AT,
+  HEADER_TAG,
+  type GroundmailTransportOptions,
+} from './transport'

package/src/transport.ts

@@ -0,0 +1,228 @@
+import type { Transport, TransportOptions } from 'nodemailer'
+import type MailMessage from 'nodemailer/lib/mailer/mail-message.js'
+import type { Address as NodemailerAddress } from 'nodemailer/lib/mailer/index.js'
+import {
+  Groundmail,
+  DEFAULT_API_BASE_URL,
+  GroundmailError,
+  type SendEmailParams,
+} from 'groundmail'
+
+export const HEADER_IDEMPOTENCY = 'X-Groundmail-Idempotency-Key'
+export const HEADER_SCHEDULED_AT = 'X-Groundmail-Scheduled-At'
+export const HEADER_TAG = 'X-Groundmail-Tag'
+
+const RESERVED_HEADERS = new Set([
+  'from',
+  'to',
+  'cc',
+  'bcc',
+  'reply-to',
+  'subject',
+  'content-type',
+  'mime-version',
+  'date',
+  'message-id',
+  'x-groundmail-idempotency-key',
+  'x-groundmail-scheduled-at',
+  'x-groundmail-tag',
+  'idempotency-key',
+])
+
+export type GroundmailTransportOptions = {
+  apiKey: string
+  baseUrl?: string
+  /** Prebuilt client (tests / advanced wiring). */
+  client?: Groundmail
+}
+
+type AddressLike = string | NodemailerAddress | Array<string | NodemailerAddress> | undefined
+
+function formatOne(addr: string | NodemailerAddress): string {
+  if (typeof addr === 'string') return addr.trim()
+  const email = addr.address?.trim()
+  if (!email) return ''
+  const name = addr.name?.trim()
+  return name ? `${name} <${email}>` : email
+}
+
+function formatAddresses(value: AddressLike): string[] {
+  if (value == null) return []
+  const list = Array.isArray(value) ? value : [value]
+  return list.map(formatOne).filter(Boolean)
+}
+
+function headerMap(headers: MailMessage['data']['headers']): Record<string, string[]> {
+  const out: Record<string, string[]> = {}
+  if (!headers) return out
+
+  if (Array.isArray(headers)) {
+    for (const entry of headers) {
+      if (!entry || typeof entry !== 'object') continue
+      const key = String((entry as { key?: string }).key || '').toLowerCase()
+      const value = String((entry as { value?: string }).value ?? '')
+      if (!key) continue
+      ;(out[key] ??= []).push(value)
+    }
+    return out
+  }
+
+  for (const [key, raw] of Object.entries(headers)) {
+    const k = key.toLowerCase()
+    if (Array.isArray(raw)) {
+      out[k] = raw.map(String)
+    } else if (raw != null) {
+      out[k] = [String(raw)]
+    }
+  }
+  return out
+}
+
+async function attachmentContentToBase64(content: unknown): Promise<string> {
+  if (content == null) {
+    throw new Error('Attachment is missing content')
+  }
+  if (typeof content === 'string') {
+    return Buffer.from(content).toString('base64')
+  }
+  if (Buffer.isBuffer(content)) {
+    return content.toString('base64')
+  }
+  if (content instanceof Uint8Array) {
+    return Buffer.from(content).toString('base64')
+  }
+  throw new Error('Unsupported attachment content type')
+}
+
+export async function mailDataToSendParams(data: MailMessage['data']): Promise<SendEmailParams> {
+  const fromList = formatAddresses(data.from as AddressLike)
+  if (!fromList.length) throw new Error('Email is missing a From address.')
+  const to = formatAddresses(data.to as AddressLike)
+  if (!to.length) throw new Error('Email is missing a To recipient.')
+
+  const html = typeof data.html === 'string' ? data.html : undefined
+  const text = typeof data.text === 'string' ? data.text : undefined
+  if (!html && !text) {
+    throw new Error('Email must include html or text content.')
+  }
+
+  const headers = headerMap(data.headers)
+  const params: SendEmailParams = {
+    from: fromList[0],
+    to: to.length === 1 ? to[0] : to,
+  }
+
+  if (typeof data.subject === 'string' && data.subject) params.subject = data.subject
+  if (html) params.html = html
+  if (text) params.text = text
+
+  const reply = formatAddresses(data.replyTo as AddressLike)
+  if (reply.length) params.replyTo = reply.length === 1 ? reply[0] : reply
+
+  const cc = formatAddresses(data.cc as AddressLike)
+  if (cc.length) params.cc = cc
+  const bcc = formatAddresses(data.bcc as AddressLike)
+  if (bcc.length) params.bcc = bcc
+
+  if (data.attachments?.length) {
+    params.attachments = await Promise.all(
+      data.attachments.map(async (att) => {
+        const filename = att.filename || att.cid || 'attachment'
+        const contentType = att.contentType || 'application/octet-stream'
+        if (att.path || typeof att.raw === 'string') {
+          throw new Error(
+            `Attachment "${filename}" must include inline content (Buffer/string). path/raw are not supported.`,
+          )
+        }
+        return {
+          filename: String(filename),
+          contentType,
+          content: await attachmentContentToBase64(att.content),
+          ...(att.cid ? { contentId: String(att.cid) } : {}),
+        }
+      }),
+    )
+  }
+
+  const tagValues = headers['x-groundmail-tag'] ?? []
+  if (tagValues.length) {
+    params.tags = tagValues.flatMap((raw) => {
+      const trimmed = raw.trim()
+      if (!trimmed) return []
+      if (trimmed.includes('=')) {
+        const [name, value] = trimmed.split('=', 2)
+        if (name.trim() && value.trim()) return [{ name: name.trim(), value: value.trim() }]
+        return []
+      }
+      return [{ name: 'tag', value: trimmed }]
+    })
+  }
+
+  const forward: Record<string, string> = {}
+  for (const [key, values] of Object.entries(headers)) {
+    if (RESERVED_HEADERS.has(key)) continue
+    if (key.startsWith('content-')) continue
+    const value = values[values.length - 1]?.trim()
+    if (value) forward[key] = value
+  }
+  if (Object.keys(forward).length) params.headers = forward
+
+  const idem =
+    headers['x-groundmail-idempotency-key']?.[0]?.trim() ||
+    headers['idempotency-key']?.[0]?.trim()
+  if (idem) params.idempotencyKey = idem
+
+  const scheduled = headers['x-groundmail-scheduled-at']?.[0]?.trim()
+  if (scheduled) params.scheduledAt = scheduled
+
+  return params
+}
+
+/** Nodemailer transport that delivers via Groundmail HTTP API. */
+export function createGroundmailTransport(
+  options: GroundmailTransportOptions,
+): Transport & TransportOptions {
+  const client =
+    options.client ??
+    new Groundmail(options.apiKey, {
+      baseUrl: options.baseUrl ?? DEFAULT_API_BASE_URL,
+    })
+
+  return {
+    name: 'Groundmail',
+    version: '0.14.0',
+    send(mail, callback) {
+      // Settle via .then so every rejection reaches the Nodemailer callback
+      // (avoids a floating promise from void async IIFE).
+      ;(async () => {
+        const params = await mailDataToSendParams(mail.data)
+        const result = await client.emails.send(params)
+        const envelope = mail.message.getEnvelope()
+        return {
+          envelope,
+          messageId: result.id,
+          accepted: envelope.to,
+          rejected: [] as string[],
+          pending: [] as string[],
+          response: `${result.status} ${result.id}`,
+        }
+      })().then(
+        (info) => {
+          callback(null, info)
+        },
+        (err: unknown) => {
+          const error =
+            err instanceof GroundmailError
+              ? err
+              : err instanceof Error
+                ? err
+                : new Error(String(err))
+          callback(error, undefined as never)
+        },
+      )
+    },
+  }
+}
+
+/** Alias matching common `createTransport(transport(...))` naming. */
+export const groundmailTransport = createGroundmailTransport