@agdirlabs/nodemailer-transport 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog — @agdirlabs/nodemailer-transport
+
+All notable changes to this package are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses [Semantic Versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-10-30
+
+### Added
+
+- `agdirTransport()` / `AgdirTransport`: a Nodemailer transport that sends through the Agdir Email API with `@agdirlabs/email`.
+- Accepts every Nodemailer address form (strings, `{ name, address }`, arrays, groups) and `html`/`text` as strings, Buffers, streams, files or URLs.
+- Custom headers (object or array form), `inReplyTo`, `references`, `list` and `priority`.
+- Tags, scheduled sending and idempotency keys via message options (`tags`, `scheduledAt`, `idempotencyKey`) or `X-Agdir-*` headers.
+- `sendMail` info with the Agdir email id as `messageId`; API failures reported as `AgdirEmailError` (`code`, `status`, `responseCode`).
+- Clear errors for features the API does not support yet (attachments, `raw`, `alternatives`, `icalEvent`, custom `envelope`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agdir AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# @agdirlabs/nodemailer-transport
 
-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.
+[![npm](https://img.shields.io/npm/v/@agdirlabs/nodemailer-transport.svg)](https://www.npmjs.com/package/@agdirlabs/nodemailer-transport)
+[![CI](https://github.com/AgdirAS/agdirlabs-sdks/actions/workflows/node.yml/badge.svg)](https://github.com/AgdirAS/agdirlabs-sdks/actions/workflows/node.yml)
+
+A [Nodemailer](https://nodemailer.com) transport for [Agdir Email](https://agdir.email) — programmatic SMTP for developers, hosted in the EU. Keep your existing `transporter.sendMail()` code and send over the Agdir Email API instead of SMTP. Built by [Agdir Labs](https://agdirlabs.com) at [Agdir](https://agdir.no) on top of the official SDK, [`@agdirlabs/email`](https://www.npmjs.com/package/@agdirlabs/email).
+
+- Drop-in: any Nodemailer address form, Buffers and streams for `html`/`text`, custom headers
+- Tags, scheduled sending and idempotency keys
+- Safe automatic retries (rate limits, server and network errors) from the SDK
+- Fully typed, ESM and CommonJS, Nodemailer 6 and newer, Node.js 20+
+
+## Install
+
+```bash
+npm install @agdirlabs/nodemailer-transport nodemailer
+```
+
+## Quick start
+
+Create an API key at [app.agdir.email](https://app.agdir.email) and verify a sending domain, then:
+
+```ts
+import nodemailer from 'nodemailer';
+import { agdirTransport } from '@agdirlabs/nodemailer-transport';
+
+const transporter = nodemailer.createTransport(agdirTransport({ apiKey: process.env.AGDIR_EMAIL_API_KEY }));
+
+const info = await transporter.sendMail({
+  from: 'Acme <hello@acme.com>',
+  to: 'user@example.com',
+  subject: 'Welcome to Acme',
+  html: '<p>Thanks for signing up!</p>'
+});
+
+info.messageId; // the Agdir Email id, e.g. for agdir.emails.get(info.messageId)
+```
+
+`agdirTransport()` with no arguments reads `AGDIR_EMAIL_API_KEY` (and `AGDIR_EMAIL_BASE_URL`) from the environment.
+
+CommonJS works the same way:
+
+```js
+const nodemailer = require('nodemailer');
+const { agdirTransport } = require('@agdirlabs/nodemailer-transport');
+```
+
+## Options
+
+```ts
+agdirTransport({
+  apiKey: 're_…', // default: AGDIR_EMAIL_API_KEY
+  baseUrl: 'https://api.agdir.email', // default: AGDIR_EMAIL_BASE_URL, else this
+  maxRetries: 2, // retries for rate limits, server errors and network failures; 0 disables
+  timeoutMs: 30_000, // per attempt
+  fetch: customFetch // e.g. for a proxy
+});
+
+// Or reuse a client you already have
+import { AgdirEmail } from '@agdirlabs/email';
+const agdir = new AgdirEmail();
+const transporter = nodemailer.createTransport(agdirTransport({ client: agdir }));
+```
+
+## Messages
+
+All standard address fields work — `from`, `to`, `cc`, `bcc`, `replyTo` — as strings (`'Ana <ana@example.com>, ben@example.com'`), `{ name, address }` objects, or arrays of either. `html` and `text` can be strings, Buffers, streams, or `{ path }` / `{ href }` (resolved by Nodemailer, subject to its `disableFileAccess` / `disableUrlAccess` settings). At least one of `html` and `text` is required.
+
+Custom `headers` (object or `[{ key, value }]` form) are sent with the email; `inReplyTo`, `references`, `list` and `priority` become their usual headers.
+
+### Tags, scheduling and idempotency
+
+Agdir-specific options can be given as message fields or, if you'd rather not touch your message objects (or their TypeScript types), as `X-Agdir-*` headers. The transport reads these headers and does **not** send them.
+
+| | Message field | Header |
+|---|---|---|
+| Tags (echoed back in webhook events) | `tags: [{ name, value }]` or `tags: { name: value }` | `X-Agdir-Tags: category=welcome, plan=pro` |
+| Deliver later | `scheduledAt: Date \| ISO 8601 string` | `X-Agdir-Scheduled-At: 2026-11-01T09:00:00Z` |
+| Idempotency key | `idempotencyKey: 'welcome/42'` | `X-Agdir-Idempotency-Key: welcome/42` |
+
+Tag names and values may contain ASCII letters, digits, `_` and `-`. Tags from both places are combined; for the other two the message field wins.
+
+```ts
+// Headers: works with any typing
+await transporter.sendMail({
+  from, to, subject, html,
+  headers: {
+    'X-Agdir-Tags': 'category=welcome',
+    'X-Agdir-Scheduled-At': new Date(Date.now() + 3600_000).toISOString(),
+    'X-Agdir-Idempotency-Key': `welcome/${user.id}`
+  }
+});
+
+// Message fields: build the message as a variable (Nodemailer's types don't declare these fields,
+// so an inline object literal would fail TypeScript's excess-property check)
+import type { AgdirMailOptions } from '@agdirlabs/nodemailer-transport';
+import type { SendMailOptions } from 'nodemailer';
+
+const message: SendMailOptions & AgdirMailOptions = {
+  from, to, subject, html,
+  tags: { category: 'welcome' },
+  scheduledAt: new Date(Date.now() + 3600_000),
+  idempotencyKey: `welcome/${user.id}`
+};
+await transporter.sendMail(message);
+```
+
+Scheduled emails can be cancelled with the SDK: `await agdir.emails.cancel(info.messageId)`.
+
+### Result
+
+`sendMail` resolves (or calls back) with:
+
+```ts
+{
+  messageId: '4ef9a3c2-…', // Agdir Email id
+  envelope: { from: 'hello@acme.com', to: ['user@example.com'] },
+  accepted: ['user@example.com'], // every envelope recipient: the API accepts the email as a whole
+  rejected: [],
+  pending: [],
+  response: 'Accepted 4ef9a3c2-…'
+}
+```
+
+Delivery happens asynchronously; follow it with `agdir.emails.get(id)` or [webhooks](https://www.npmjs.com/package/@agdirlabs/email#webhooks).
+
+### Not supported (yet)
+
+The Agdir Email API does not take attachments yet, so a message with `attachments` (or `raw`, `alternatives`, `icalEvent`) fails with an `AgdirEmailError` whose `code` is `unsupported` — link to files from the body instead. A custom SMTP `envelope` is rejected the same way, because the email always goes to its `to`, `cc` and `bcc` recipients. `amp` and `watchHtml` are ignored, as is `verify()` (there is no connection to check).
+
+## Errors
+
+Failures are reported as an `AgdirEmailError` (re-exported from this package):
+
+```ts
+import { AgdirEmailError } from '@agdirlabs/nodemailer-transport';
+
+try {
+  await transporter.sendMail(message);
+} catch (err) {
+  if (err instanceof AgdirEmailError) {
+    err.code; // 'validation_error' | 'daily_quota_exceeded' | 'rate_limit_exceeded' | 'network_error' | 'unsupported' | …
+    err.status; // HTTP status, 0 if no response (or the message was rejected before sending)
+  }
+}
+```
+
+Like Nodemailer's SMTP transports, the error also carries `responseCode` (the HTTP status) when the API answered.
+
+## Retries and idempotency
+
+Rate limits (`429 rate_limit_exceeded`), server errors and network failures are retried by the SDK up to `maxRetries` times, honouring `retry-after`. Each send gets a generated idempotency key, so a retry can never deliver an email twice; pass your own (`idempotencyKey` / `X-Agdir-Idempotency-Key`) to make sends safe across process restarts too. Quota errors are not retried.
+
+## Releasing
+
+Push a tag `nodemailer-transport@<version>` matching `package.json` — `.github/workflows/release.yml` publishes it to npm with Trusted Publishing. One-time setup: on npmjs.com, add `AgdirAS/agdirlabs-sdks` with workflow `release.yml` as a trusted publisher for `@agdirlabs/nodemailer-transport` (for a brand-new package, the first version may have to be published by hand before the trusted publisher can be configured).
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](../../CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md). The opt-in live test runs against a real API:
+
+```bash
+AGDIR_EMAIL_LIVE_BASE_URL=… AGDIR_EMAIL_LIVE_API_KEY=re_… AGDIR_EMAIL_LIVE_FROM=hi@your-domain.com pnpm test
+```
+
+## License
+
+[MIT](LICENSE) © [Agdir AS](https://agdir.no)

package/dist/index.cjs

@@ -0,0 +1,228 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgdirEmail: () => import_email2.AgdirEmail,
+  AgdirEmailError: () => import_email2.AgdirEmailError,
+  AgdirTransport: () => AgdirTransport,
+  IDEMPOTENCY_KEY_HEADER: () => IDEMPOTENCY_KEY_HEADER,
+  SCHEDULED_AT_HEADER: () => SCHEDULED_AT_HEADER,
+  TAGS_HEADER: () => TAGS_HEADER,
+  VERSION: () => VERSION,
+  agdirTransport: () => agdirTransport
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/transport.ts
+var import_email = require("@agdirlabs/email");
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/transport.ts
+var TAGS_HEADER = "x-agdir-tags";
+var SCHEDULED_AT_HEADER = "x-agdir-scheduled-at";
+var IDEMPOTENCY_KEY_HEADER = "x-agdir-idempotency-key";
+var CONTROL_HEADERS = /* @__PURE__ */ new Set([TAGS_HEADER, SCHEDULED_AT_HEADER, IDEMPOTENCY_KEY_HEADER]);
+var AgdirTransport = class {
+  name = "AgdirEmail";
+  version = VERSION;
+  client;
+  constructor(options = {}) {
+    this.client = options.client ?? new import_email.AgdirEmail(options);
+  }
+  send(mail, callback) {
+    this.sendAsync(mail).then(
+      (info) => callback(null, info),
+      (err) => callback(toNodemailerError(err))
+    );
+  }
+  async sendAsync(mail) {
+    rejectUnsupported(mail.data);
+    const envelope = mail.message.getEnvelope();
+    const data = await new Promise(
+      (resolve, reject) => mail.normalize((err, normalized) => err ? reject(err) : resolve(normalized))
+    );
+    const { input, idempotencyKey } = toSendInput(data);
+    const { id } = await this.client.emails.send(input, idempotencyKey ? { idempotencyKey } : {});
+    return {
+      messageId: id,
+      envelope,
+      accepted: [...envelope.to],
+      rejected: [],
+      pending: [],
+      response: `Accepted ${id}`
+    };
+  }
+};
+function agdirTransport(options = {}) {
+  return new AgdirTransport(options);
+}
+function unsupported(message) {
+  return new import_email.AgdirEmailError(message, "unsupported", 0);
+}
+function invalid(message) {
+  return new import_email.AgdirEmailError(message, "validation_error", 0);
+}
+function rejectUnsupported(data) {
+  if (Array.isArray(data.attachments) ? data.attachments.length > 0 : data.attachments) {
+    throw unsupported("Attachments are not supported by the Agdir Email API yet. Link to the file from the email body instead.");
+  }
+  if (data.raw) throw unsupported("Raw MIME messages (`raw`) are not supported by the Agdir Email API.");
+  if (Array.isArray(data.alternatives) ? data.alternatives.length > 0 : data.alternatives) {
+    throw unsupported("`alternatives` are not supported by the Agdir Email API; use `html` and `text`.");
+  }
+  if (data.icalEvent) throw unsupported("Calendar events (`icalEvent`) are not supported by the Agdir Email API yet.");
+  if (data.envelope) {
+    throw unsupported("A custom SMTP `envelope` is not supported: the email is sent to its to, cc and bcc recipients.");
+  }
+}
+function toSendInput(data) {
+  const headers = {};
+  const control = {};
+  for (const [key, value] of headerEntries(data.headers)) {
+    const lower = key.toLowerCase();
+    if (CONTROL_HEADERS.has(lower)) control[lower] = value;
+    else headers[key] = key in headers ? `${headers[key]}, ${value}` : value;
+  }
+  for (const [key, value] of Object.entries(data.normalizedHeaders ?? {})) {
+    if ((key === "in-reply-to" || key === "references" || key.startsWith("list-")) && typeof value === "string" && value) {
+      const existing = Object.keys(headers).find((k) => k.toLowerCase() === key);
+      headers[existing ?? canonicalHeaderName(key)] = value;
+    }
+  }
+  Object.assign(headers, priorityHeaders(data.priority));
+  const tags = [...toTags(data.tags), ...control[TAGS_HEADER] ? parseTagsHeader(control[TAGS_HEADER]) : []];
+  const scheduledAt = data.scheduledAt ?? control[SCHEDULED_AT_HEADER];
+  const idempotencyKey = data.idempotencyKey ?? control[IDEMPOTENCY_KEY_HEADER];
+  const input = {
+    from: formatAddresses(data.from)[0],
+    to: formatAddresses(data.to),
+    subject: data.subject
+  };
+  const html = content(data.html);
+  const text = content(data.text);
+  if (html !== void 0) input.html = html;
+  if (text !== void 0) input.text = text;
+  const cc = formatAddresses(data.cc);
+  const bcc = formatAddresses(data.bcc);
+  const replyTo = formatAddresses(data.replyTo);
+  if (cc.length) input.cc = cc;
+  if (bcc.length) input.bcc = bcc;
+  if (replyTo.length) input.replyTo = replyTo;
+  if (Object.keys(headers).length) input.headers = headers;
+  if (tags.length) input.tags = tags;
+  if (scheduledAt !== void 0 && scheduledAt !== "") input.scheduledAt = scheduledAt;
+  return { input, idempotencyKey: idempotencyKey || void 0 };
+}
+function headerEntries(headers) {
+  const entries = [];
+  if (Array.isArray(headers)) {
+    for (const h of headers) if (h && typeof h.key === "string") entries.push([h.key, h.value]);
+  } else if (headers && typeof headers === "object") {
+    for (const [key, value] of Object.entries(headers)) {
+      for (const v of Array.isArray(value) ? value : [value]) entries.push([key, v]);
+    }
+  }
+  const out = [];
+  for (const [key, raw] of entries) {
+    const value = raw && typeof raw === "object" && "value" in raw ? raw.value : raw;
+    if (value === void 0 || value === null || value === false || value === "") continue;
+    out.push([key, String(value)]);
+  }
+  return out;
+}
+function canonicalHeaderName(key) {
+  if (key === "in-reply-to") return "In-Reply-To";
+  return key.replace(/(^|-)([a-z])/g, (_, dash, c) => dash + c.toUpperCase());
+}
+function priorityHeaders(priority) {
+  switch (String(priority ?? "").toLowerCase()) {
+    case "high":
+      return { "X-Priority": "1 (Highest)", "X-MSMail-Priority": "High", Importance: "High" };
+    case "low":
+      return { "X-Priority": "5 (Lowest)", "X-MSMail-Priority": "Low", Importance: "Low" };
+    default:
+      return {};
+  }
+}
+function toTags(tags) {
+  if (!tags) return [];
+  if (Array.isArray(tags)) return tags.map((t) => ({ name: String(t.name), value: String(t.value) }));
+  if (typeof tags === "object") return Object.entries(tags).map(([name, value]) => ({ name, value: String(value) }));
+  throw invalid("`tags` must be an array of { name, value } or an object of name \u2192 value.");
+}
+function parseTagsHeader(value) {
+  return value.split(/[,;]/).map((part) => part.trim()).filter(Boolean).map((part) => {
+    const eq = part.indexOf("=");
+    if (eq <= 0) throw invalid(`Invalid X-Agdir-Tags entry "${part}": expected name=value.`);
+    return { name: part.slice(0, eq).trim(), value: part.slice(eq + 1).trim() };
+  });
+}
+function content(value) {
+  if (value === void 0 || value === null || value === false) return void 0;
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value)) return value.toString();
+  if (typeof value === "object" && "content" in value) return content(value.content);
+  return String(value);
+}
+function formatAddresses(value) {
+  if (!value) return [];
+  const out = [];
+  for (const entry of Array.isArray(value) ? value : [value]) {
+    if (!entry) continue;
+    if (typeof entry === "string") {
+      out.push(entry);
+      continue;
+    }
+    const parsed = entry;
+    if (parsed.group) {
+      out.push(...formatAddresses(parsed.group));
+    } else if (parsed.address) {
+      out.push(parsed.name ? `${quoteName(parsed.name)} <${parsed.address}>` : parsed.address);
+    }
+  }
+  return out;
+}
+function quoteName(name) {
+  return /^[\w !#$%&'*+\-/=?^`{|}~]*$/.test(name) ? name : `"${name.replace(/["\\]/g, (c) => `\\${c}`)}"`;
+}
+function toNodemailerError(err) {
+  if (err instanceof import_email.AgdirEmailError) {
+    if (err.status) Object.assign(err, { responseCode: err.status });
+    return err;
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+// src/index.ts
+var import_email2 = require("@agdirlabs/email");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgdirEmail,
+  AgdirEmailError,
+  AgdirTransport,
+  IDEMPOTENCY_KEY_HEADER,
+  SCHEDULED_AT_HEADER,
+  TAGS_HEADER,
+  VERSION,
+  agdirTransport
+});

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+import { SendEmailInput, Tag, AgdirEmailOptions } from '@agdirlabs/email';
+export { AgdirEmail, AgdirEmailError } from '@agdirlabs/email';
+
+/** The part of `AgdirEmail` the transport uses (handy for tests and wrappers). */
+interface AgdirEmailSender {
+    emails: {
+        send(input: SendEmailInput, options?: {
+            idempotencyKey?: string;
+        }): Promise<{
+            id: string;
+        }>;
+    };
+}
+type AgdirTransportOptions = (AgdirEmailOptions & {
+    client?: undefined;
+}) | {
+    /** An existing client; `apiKey`, `baseUrl` etc. are then ignored. */
+    client: AgdirEmailSender;
+};
+/** Extra message fields understood by the transport (alongside the standard Nodemailer ones). */
+interface AgdirMailOptions {
+    /** Tags echoed back in webhook events: `[{ name, value }]` or `{ name: value }`. ASCII letters, digits, `_`, `-`. */
+    tags?: Tag[] | Record<string, string>;
+    /** Deliver later: a `Date` or an ISO 8601 string with offset. */
+    scheduledAt?: Date | string;
+    /** Makes the send safe to repeat: the same key and message return the original email id. */
+    idempotencyKey?: string;
+}
+/** Passed to the `sendMail` callback / resolved by its promise. */
+interface AgdirSentMessageInfo {
+    /** The Agdir Email id; use it with `agdir.emails.get()` / `cancel()`. */
+    messageId: string;
+    envelope: {
+        from: string | false;
+        to: string[];
+    };
+    accepted: string[];
+    rejected: string[];
+    pending: string[];
+    response: string;
+}
+/** Control headers: read by the transport and never sent with the email. */
+declare const TAGS_HEADER = "x-agdir-tags";
+declare const SCHEDULED_AT_HEADER = "x-agdir-scheduled-at";
+declare const IDEMPOTENCY_KEY_HEADER = "x-agdir-idempotency-key";
+interface MailMessageLike {
+    data: Record<string, any>;
+    message: {
+        getEnvelope(): {
+            from: string | false;
+            to: string[];
+        };
+    };
+    normalize(callback: (err: Error | null | undefined, data?: Record<string, any>) => void): void;
+}
+/** A Nodemailer transport; pass it to `nodemailer.createTransport()`. */
+declare class AgdirTransport {
+    readonly name = "AgdirEmail";
+    readonly version = "0.1.0";
+    readonly client: AgdirEmailSender;
+    constructor(options?: AgdirTransportOptions);
+    send(mail: MailMessageLike, callback: (err: Error | null, info?: AgdirSentMessageInfo) => void): void;
+    private sendAsync;
+}
+/**
+ * Creates a Nodemailer transport that sends through the Agdir Email API.
+ *
+ * ```ts
+ * const transporter = nodemailer.createTransport(agdirTransport({ apiKey: 're_…' }));
+ * ```
+ */
+declare function agdirTransport(options?: AgdirTransportOptions): AgdirTransport;
+
+declare const VERSION = "0.1.0";
+
+export { type AgdirEmailSender, type AgdirMailOptions, type AgdirSentMessageInfo, AgdirTransport, type AgdirTransportOptions, IDEMPOTENCY_KEY_HEADER, SCHEDULED_AT_HEADER, TAGS_HEADER, VERSION, agdirTransport };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+import { SendEmailInput, Tag, AgdirEmailOptions } from '@agdirlabs/email';
+export { AgdirEmail, AgdirEmailError } from '@agdirlabs/email';
+
+/** The part of `AgdirEmail` the transport uses (handy for tests and wrappers). */
+interface AgdirEmailSender {
+    emails: {
+        send(input: SendEmailInput, options?: {
+            idempotencyKey?: string;
+        }): Promise<{
+            id: string;
+        }>;
+    };
+}
+type AgdirTransportOptions = (AgdirEmailOptions & {
+    client?: undefined;
+}) | {
+    /** An existing client; `apiKey`, `baseUrl` etc. are then ignored. */
+    client: AgdirEmailSender;
+};
+/** Extra message fields understood by the transport (alongside the standard Nodemailer ones). */
+interface AgdirMailOptions {
+    /** Tags echoed back in webhook events: `[{ name, value }]` or `{ name: value }`. ASCII letters, digits, `_`, `-`. */
+    tags?: Tag[] | Record<string, string>;
+    /** Deliver later: a `Date` or an ISO 8601 string with offset. */
+    scheduledAt?: Date | string;
+    /** Makes the send safe to repeat: the same key and message return the original email id. */
+    idempotencyKey?: string;
+}
+/** Passed to the `sendMail` callback / resolved by its promise. */
+interface AgdirSentMessageInfo {
+    /** The Agdir Email id; use it with `agdir.emails.get()` / `cancel()`. */
+    messageId: string;
+    envelope: {
+        from: string | false;
+        to: string[];
+    };
+    accepted: string[];
+    rejected: string[];
+    pending: string[];
+    response: string;
+}
+/** Control headers: read by the transport and never sent with the email. */
+declare const TAGS_HEADER = "x-agdir-tags";
+declare const SCHEDULED_AT_HEADER = "x-agdir-scheduled-at";
+declare const IDEMPOTENCY_KEY_HEADER = "x-agdir-idempotency-key";
+interface MailMessageLike {
+    data: Record<string, any>;
+    message: {
+        getEnvelope(): {
+            from: string | false;
+            to: string[];
+        };
+    };
+    normalize(callback: (err: Error | null | undefined, data?: Record<string, any>) => void): void;
+}
+/** A Nodemailer transport; pass it to `nodemailer.createTransport()`. */
+declare class AgdirTransport {
+    readonly name = "AgdirEmail";
+    readonly version = "0.1.0";
+    readonly client: AgdirEmailSender;
+    constructor(options?: AgdirTransportOptions);
+    send(mail: MailMessageLike, callback: (err: Error | null, info?: AgdirSentMessageInfo) => void): void;
+    private sendAsync;
+}
+/**
+ * Creates a Nodemailer transport that sends through the Agdir Email API.
+ *
+ * ```ts
+ * const transporter = nodemailer.createTransport(agdirTransport({ apiKey: 're_…' }));
+ * ```
+ */
+declare function agdirTransport(options?: AgdirTransportOptions): AgdirTransport;
+
+declare const VERSION = "0.1.0";
+
+export { type AgdirEmailSender, type AgdirMailOptions, type AgdirSentMessageInfo, AgdirTransport, type AgdirTransportOptions, IDEMPOTENCY_KEY_HEADER, SCHEDULED_AT_HEADER, TAGS_HEADER, VERSION, agdirTransport };

package/dist/index.js

@@ -0,0 +1,194 @@
+// src/transport.ts
+import { AgdirEmail, AgdirEmailError } from "@agdirlabs/email";
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/transport.ts
+var TAGS_HEADER = "x-agdir-tags";
+var SCHEDULED_AT_HEADER = "x-agdir-scheduled-at";
+var IDEMPOTENCY_KEY_HEADER = "x-agdir-idempotency-key";
+var CONTROL_HEADERS = /* @__PURE__ */ new Set([TAGS_HEADER, SCHEDULED_AT_HEADER, IDEMPOTENCY_KEY_HEADER]);
+var AgdirTransport = class {
+  name = "AgdirEmail";
+  version = VERSION;
+  client;
+  constructor(options = {}) {
+    this.client = options.client ?? new AgdirEmail(options);
+  }
+  send(mail, callback) {
+    this.sendAsync(mail).then(
+      (info) => callback(null, info),
+      (err) => callback(toNodemailerError(err))
+    );
+  }
+  async sendAsync(mail) {
+    rejectUnsupported(mail.data);
+    const envelope = mail.message.getEnvelope();
+    const data = await new Promise(
+      (resolve, reject) => mail.normalize((err, normalized) => err ? reject(err) : resolve(normalized))
+    );
+    const { input, idempotencyKey } = toSendInput(data);
+    const { id } = await this.client.emails.send(input, idempotencyKey ? { idempotencyKey } : {});
+    return {
+      messageId: id,
+      envelope,
+      accepted: [...envelope.to],
+      rejected: [],
+      pending: [],
+      response: `Accepted ${id}`
+    };
+  }
+};
+function agdirTransport(options = {}) {
+  return new AgdirTransport(options);
+}
+function unsupported(message) {
+  return new AgdirEmailError(message, "unsupported", 0);
+}
+function invalid(message) {
+  return new AgdirEmailError(message, "validation_error", 0);
+}
+function rejectUnsupported(data) {
+  if (Array.isArray(data.attachments) ? data.attachments.length > 0 : data.attachments) {
+    throw unsupported("Attachments are not supported by the Agdir Email API yet. Link to the file from the email body instead.");
+  }
+  if (data.raw) throw unsupported("Raw MIME messages (`raw`) are not supported by the Agdir Email API.");
+  if (Array.isArray(data.alternatives) ? data.alternatives.length > 0 : data.alternatives) {
+    throw unsupported("`alternatives` are not supported by the Agdir Email API; use `html` and `text`.");
+  }
+  if (data.icalEvent) throw unsupported("Calendar events (`icalEvent`) are not supported by the Agdir Email API yet.");
+  if (data.envelope) {
+    throw unsupported("A custom SMTP `envelope` is not supported: the email is sent to its to, cc and bcc recipients.");
+  }
+}
+function toSendInput(data) {
+  const headers = {};
+  const control = {};
+  for (const [key, value] of headerEntries(data.headers)) {
+    const lower = key.toLowerCase();
+    if (CONTROL_HEADERS.has(lower)) control[lower] = value;
+    else headers[key] = key in headers ? `${headers[key]}, ${value}` : value;
+  }
+  for (const [key, value] of Object.entries(data.normalizedHeaders ?? {})) {
+    if ((key === "in-reply-to" || key === "references" || key.startsWith("list-")) && typeof value === "string" && value) {
+      const existing = Object.keys(headers).find((k) => k.toLowerCase() === key);
+      headers[existing ?? canonicalHeaderName(key)] = value;
+    }
+  }
+  Object.assign(headers, priorityHeaders(data.priority));
+  const tags = [...toTags(data.tags), ...control[TAGS_HEADER] ? parseTagsHeader(control[TAGS_HEADER]) : []];
+  const scheduledAt = data.scheduledAt ?? control[SCHEDULED_AT_HEADER];
+  const idempotencyKey = data.idempotencyKey ?? control[IDEMPOTENCY_KEY_HEADER];
+  const input = {
+    from: formatAddresses(data.from)[0],
+    to: formatAddresses(data.to),
+    subject: data.subject
+  };
+  const html = content(data.html);
+  const text = content(data.text);
+  if (html !== void 0) input.html = html;
+  if (text !== void 0) input.text = text;
+  const cc = formatAddresses(data.cc);
+  const bcc = formatAddresses(data.bcc);
+  const replyTo = formatAddresses(data.replyTo);
+  if (cc.length) input.cc = cc;
+  if (bcc.length) input.bcc = bcc;
+  if (replyTo.length) input.replyTo = replyTo;
+  if (Object.keys(headers).length) input.headers = headers;
+  if (tags.length) input.tags = tags;
+  if (scheduledAt !== void 0 && scheduledAt !== "") input.scheduledAt = scheduledAt;
+  return { input, idempotencyKey: idempotencyKey || void 0 };
+}
+function headerEntries(headers) {
+  const entries = [];
+  if (Array.isArray(headers)) {
+    for (const h of headers) if (h && typeof h.key === "string") entries.push([h.key, h.value]);
+  } else if (headers && typeof headers === "object") {
+    for (const [key, value] of Object.entries(headers)) {
+      for (const v of Array.isArray(value) ? value : [value]) entries.push([key, v]);
+    }
+  }
+  const out = [];
+  for (const [key, raw] of entries) {
+    const value = raw && typeof raw === "object" && "value" in raw ? raw.value : raw;
+    if (value === void 0 || value === null || value === false || value === "") continue;
+    out.push([key, String(value)]);
+  }
+  return out;
+}
+function canonicalHeaderName(key) {
+  if (key === "in-reply-to") return "In-Reply-To";
+  return key.replace(/(^|-)([a-z])/g, (_, dash, c) => dash + c.toUpperCase());
+}
+function priorityHeaders(priority) {
+  switch (String(priority ?? "").toLowerCase()) {
+    case "high":
+      return { "X-Priority": "1 (Highest)", "X-MSMail-Priority": "High", Importance: "High" };
+    case "low":
+      return { "X-Priority": "5 (Lowest)", "X-MSMail-Priority": "Low", Importance: "Low" };
+    default:
+      return {};
+  }
+}
+function toTags(tags) {
+  if (!tags) return [];
+  if (Array.isArray(tags)) return tags.map((t) => ({ name: String(t.name), value: String(t.value) }));
+  if (typeof tags === "object") return Object.entries(tags).map(([name, value]) => ({ name, value: String(value) }));
+  throw invalid("`tags` must be an array of { name, value } or an object of name \u2192 value.");
+}
+function parseTagsHeader(value) {
+  return value.split(/[,;]/).map((part) => part.trim()).filter(Boolean).map((part) => {
+    const eq = part.indexOf("=");
+    if (eq <= 0) throw invalid(`Invalid X-Agdir-Tags entry "${part}": expected name=value.`);
+    return { name: part.slice(0, eq).trim(), value: part.slice(eq + 1).trim() };
+  });
+}
+function content(value) {
+  if (value === void 0 || value === null || value === false) return void 0;
+  if (typeof value === "string") return value;
+  if (Buffer.isBuffer(value)) return value.toString();
+  if (typeof value === "object" && "content" in value) return content(value.content);
+  return String(value);
+}
+function formatAddresses(value) {
+  if (!value) return [];
+  const out = [];
+  for (const entry of Array.isArray(value) ? value : [value]) {
+    if (!entry) continue;
+    if (typeof entry === "string") {
+      out.push(entry);
+      continue;
+    }
+    const parsed = entry;
+    if (parsed.group) {
+      out.push(...formatAddresses(parsed.group));
+    } else if (parsed.address) {
+      out.push(parsed.name ? `${quoteName(parsed.name)} <${parsed.address}>` : parsed.address);
+    }
+  }
+  return out;
+}
+function quoteName(name) {
+  return /^[\w !#$%&'*+\-/=?^`{|}~]*$/.test(name) ? name : `"${name.replace(/["\\]/g, (c) => `\\${c}`)}"`;
+}
+function toNodemailerError(err) {
+  if (err instanceof AgdirEmailError) {
+    if (err.status) Object.assign(err, { responseCode: err.status });
+    return err;
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+// src/index.ts
+import { AgdirEmail as AgdirEmail2, AgdirEmailError as AgdirEmailError2 } from "@agdirlabs/email";
+export {
+  AgdirEmail2 as AgdirEmail,
+  AgdirEmailError2 as AgdirEmailError,
+  AgdirTransport,
+  IDEMPOTENCY_KEY_HEADER,
+  SCHEDULED_AT_HEADER,
+  TAGS_HEADER,
+  VERSION,
+  agdirTransport
+};

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@agdirlabs/nodemailer-transport",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Nodemailer transport for Agdir Email — send with Nodemailer through the Agdir Email API.",
+  "license": "MIT",
+  "author": "Agdir AS",
+  "homepage": "https://agdir.email",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgdirAS/agdirlabs-sdks.git",
+    "directory": "packages/nodemailer-transport"
+  },
+  "keywords": [
+    "email",
+    "smtp",
+    "transactional-email",
+    "email-api",
+    "nodemailer",
+    "nodemailer-transport",
+    "agdir"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --target es2022",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@agdirlabs/email": "^0.1.1"
+  },
+  "peerDependencies": {
+    "nodemailer": ">=6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/nodemailer": "^8.0.2",
+    "nodemailer": "^10.3.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  },
+  "bugs": {
+    "url": "https://github.com/AgdirAS/agdirlabs-sdks/issues"
+  }
+}