@nxgt/mail-resend 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Tsala
+
+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

@@ -0,0 +1,174 @@
+# @nxgt/mail-resend
+
+A [Resend](https://resend.com) transport for
+[`@nxgt/mail`](https://github.com/softistx/nxgt-mail/tree/develop/packages/mail),
+over `fetch`, with no SDK and no dependency. It throws the `MailFailure` and
+`MailRefused` of its `@nxgt/mail` peer, so `instanceof` holds whichever
+transport is wired, and it passes the `@nxgt/mail/conformance` suite against a
+local server answering as Resend's API does.
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+
+const { messageId } = await mailer.send({
+	to: 'ada@example.com',
+	subject: 'Confirm your address',
+	html: '<p>…</p>',
+	text: '…',
+}); // Resend's id — or it throws
+```
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/mail-resend @nxgt/mail
+```
+
+Peers, all required:
+
+- `@nxgt/mail` — the port and the errors. One copy in your tree, so
+  `error instanceof MailFailure` holds.
+- `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
+  what is supported and tested; `nodenext` is out of contract.
+
+It runs wherever `fetch` does — Node, Bun, Deno, an edge runtime — and imports
+no Node built-in.
+
+## Exports
+
+| Export | What it is |
+| --- | --- |
+| `createResendMailer(options)` | A `Mailer` that sends each message with `POST /emails` |
+| `ResendMailerOptions` | `{ apiKey, from?, baseUrl?, fetch?, timeoutMs? }` |
+| `formatAddress(address)` | An `Address` as Resend reads it: bare, or `"name" <address>` with the name quoted |
+
+## Usage
+
+### Options
+
+| Option | Type | Default | |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | required | The Resend API key, `re_…` |
+| `from` | `Address` | none | The sender of a message that names none |
+| `baseUrl` | `string` | `https://api.resend.com` | Where `POST /emails` goes: a proxy, or a test server |
+| `fetch` | `(url, init) => Promise<Response>` | the global `fetch` | For a proxy agent, or a test |
+| `timeoutMs` | `number` | `30000` | A send taking longer fails with `MailFailure`, whatever `fetch` does with the signal. At most `2147483647` |
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '', timeoutMs: 10_000 });
+
+await mailer.send({
+	to: [{ name: 'Doe, John', address: 'john@example.com' }],
+	from: 'billing@acme.test', // required here: this mailer has no default
+	replyTo: 'support@acme.test', // sent as reply_to
+	headers: { 'List-Unsubscribe': '<https://acme.test/unsubscribe>' },
+	subject: 'Your invoice',
+	html: '<p>…</p>',
+	text: '…',
+});
+```
+
+- Every message is checked by `checkMessage` from `@nxgt/mail` first: the
+  same refusals, with the same messages, as every transport.
+- A message's own `from` wins over the default.
+- A name is sent as a quoted string — `"Doe, John" <john@example.com>` — so a
+  comma or an angle bracket in it never names another recipient.
+- `messageId` is Resend's `id`, or `null` when the answer carries none.
+
+### Errors — a refusal or a failure
+
+| When | Throws | `cause` |
+| --- | --- | --- |
+| `400`, `422` — Resend refuses the message | `MailRefused` — `send: Resend refused the message` | an `Error` with `status`, `errorName` and Resend's `detail` |
+| `401`, `403`, `429`, `5xx`, any other status | `MailFailure` — `send: Resend could not take the message` | the same |
+| A network error | `MailFailure` — `send: Resend could not be reached` | the `fetch` error |
+| No answer within `timeoutMs` | `MailFailure` — `send: Resend did not answer within <timeoutMs> ms` | the `TimeoutError` |
+| No sender, on the message or as a default | `MailRefused` — `send: from is missing — give the message a from, or createResendMailer a default one` | — |
+| A bad option | `TypeError` from `createResendMailer` | — |
+
+```ts
+import { MailFailure, MailRefused } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailRefused) {
+		// sending it again unchanged fails again: fix the address or the content
+	} else if (error instanceof MailFailure) {
+		// nothing is known to have been sent: a bad key, a rate limit, an outage — retry later, from a queue
+	}
+	throw error;
+}
+```
+
+A message reports a shape, never a value: never the key, an address or what
+Resend said — that is on `cause.detail`. Nothing is retried. Every case is in
+[Errors](docs/guide/errors.md).
+
+### Testing
+
+In an application's tests, use `createMemoryMailer()` from `@nxgt/mail`. To
+test this transport, see [Testing](docs/guide/testing.md): a local Bun server
+answering as Resend does, `baseUrl` pointed at it, and `describeMailer`.
+
+## Traps
+
+**Read the key where the process starts, and decide its absence there.**
+`apiKey: process.env.RESEND_API_KEY` does not compile (`string | undefined`);
+`?? ''` makes an unset variable a `TypeError` at start-up, not a failure at
+the first send.
+
+**A key read from a file keeps its line break.** A key holding whitespace is
+refused at wiring; trim it.
+
+**A `403` is a failure, not a refusal.** An invalid key or an unverified
+sending domain refuses every message alike: it is the wiring that is wrong.
+
+**A `429` is a failure.** Resend rate-limits per second; slow down or queue.
+The transport does not wait and retry for you.
+
+**A timeout does not mean nothing was sent.** After `timeoutMs`, or a
+connection dropped mid-request, Resend may have accepted the e-mail: a retry
+can send it twice. Weigh that before retrying.
+
+## Type safety, counted
+
+**7 plausible mistakes, 7 refused** at compile time, each measured by a
+`@ts-expect-error` in
+[`test/types/refusals.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-resend/test/types/refusals.ts)
+that fails the typecheck the moment it stops holding:
+
+1. No `apiKey`.
+2. An `apiKey` that may be `undefined` — `process.env.RESEND_API_KEY` as is.
+3. `timeoutMs` written as a duration (`'30s'`).
+4. A default `from` without its `address`.
+5. Resend's wire format in the options (`reply_to`): a message carries its
+   `replyTo`.
+6. A `retries` option: the transport tries once.
+7. `messageId` read as a `string`: it is `string | null`.
+
+The same file holds the calls that must keep compiling — among them a `fetch`
+written as a plain function.
+
+## Documentation
+
+- [The guides](docs/README.md) — the options, the errors, testing.
+- [Troubleshooting](docs/troubleshooting.md) — an error message, its cause and
+  its fix.
+- [Roadmap](docs/roadmap.md) — what is next, and what is deliberately not
+  planned.
+- [Vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md)
+  — the words these pages use, defined once.
+
+## Licence
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `@nxgt/mail-resend` — a Resend transport for `@nxgt/mail`, over `fetch`,
+ * with no SDK.
+ *
+ * ```ts
+ * import { createResendMailer } from '@nxgt/mail-resend';
+ *
+ * const mailer = createResendMailer({
+ *   apiKey: process.env.RESEND_API_KEY ?? '',
+ *   from: { name: 'Acme', address: 'noreply@acme.test' },
+ * });
+ * ```
+ *
+ * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`
+ * peer, what Resend answered as the `cause`. Nothing is retried.
+ */
+import { type Address, type Mailer } from '@nxgt/mail';
+export interface ResendMailerOptions {
+    /** The API key, `re_…`. */
+    readonly apiKey: string;
+    /** The sender of a message that names none. Without it, such a message is refused. */
+    readonly from?: Address;
+    /** Default `https://api.resend.com`. */
+    readonly baseUrl?: string;
+    /** Default the global `fetch`. For a proxy, or a test. */
+    readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    /** How long a send may take before it fails. Default `30000`. */
+    readonly timeoutMs?: number;
+}
+/**
+ * An address as Resend reads it: bare, or `"name" <address>` — the name a
+ * quoted string, so a comma or an angle bracket in it names no one else.
+ */
+export declare function formatAddress(address: Address): string;
+/** Creates a {@link Mailer} that sends each message through Resend's API. */
+export declare function createResendMailer(options: ResendMailerOptions): Mailer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,mBAAmB;IACnC,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,wCAAwC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvE,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAItD;AA4HD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CA8EvE"}

package/dist/index.js

@@ -0,0 +1,130 @@
+// src/index.ts
+import {
+  checkMessage,
+  MailFailure,
+  MailRefused
+} from "@nxgt/mail";
+function formatAddress(address) {
+  if (typeof address === "string")
+    return address;
+  const name = address.name.replace(/[\\"]/g, (char) => `\\${char}`);
+  return `"${name}" <${address.address}>`;
+}
+function resendAnswer(status, errorName, detail) {
+  return Object.assign(new Error(`Resend answered ${status}${errorName === null ? "" : ` ${errorName}`}`), { status, errorName, detail });
+}
+function beforeAbort(work, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    if (signal.aborted)
+      return abort();
+    signal.addEventListener("abort", abort, { once: true });
+    work.then((value) => {
+      signal.removeEventListener("abort", abort);
+      resolve(value);
+    }, (error) => {
+      signal.removeEventListener("abort", abort);
+      reject(error);
+    });
+  });
+}
+async function readAnswer(response, signal) {
+  const body = await beforeAbort(response.json(), signal).then((value) => value, () => null);
+  return typeof body === "object" && body !== null ? body : {};
+}
+var MAX_TIMEOUT_MS = 2147483647;
+var text = (value) => typeof value === "string" && value !== "" ? value : null;
+function checkOptions(options) {
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("createResendMailer: options must be an object, as { apiKey }");
+  }
+  if (typeof options.apiKey !== "string" || options.apiKey.trim() === "") {
+    throw new TypeError("createResendMailer: apiKey must be a Resend API key — is the environment variable set?");
+  }
+  if (/\s/.test(options.apiKey)) {
+    throw new TypeError("createResendMailer: apiKey holds whitespace — trim the value it was read from");
+  }
+  if (options.baseUrl !== undefined && (typeof options.baseUrl !== "string" || !/^https?:\/\/[^/]/.test(options.baseUrl))) {
+    throw new TypeError("createResendMailer: baseUrl must be an http: or https: URL");
+  }
+  if (options.fetch !== undefined && typeof options.fetch !== "function") {
+    throw new TypeError("createResendMailer: fetch must be a function");
+  }
+  if (options.timeoutMs !== undefined && !(Number.isInteger(options.timeoutMs) && options.timeoutMs > 0)) {
+    throw new TypeError("createResendMailer: timeoutMs must be a positive integer");
+  }
+  if (options.timeoutMs !== undefined && options.timeoutMs > MAX_TIMEOUT_MS) {
+    throw new TypeError(`createResendMailer: timeoutMs must be at most ${MAX_TIMEOUT_MS} — a longer timer fires at once`);
+  }
+  if (options.from !== undefined) {
+    try {
+      checkMessage({ to: options.from, subject: "", html: "", text: "" });
+    } catch {
+      throw new TypeError("createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }");
+    }
+  }
+}
+function createResendMailer(options) {
+  checkOptions(options);
+  const endpoint = `${(options.baseUrl ?? "https://api.resend.com").replace(/\/+$/, "")}/emails`;
+  const post = options.fetch ?? ((url, init) => globalThis.fetch(url, init));
+  const timeoutMs = options.timeoutMs ?? 30000;
+  return {
+    async send(message) {
+      checkMessage(message);
+      const sender = message.from ?? options.from;
+      if (sender === undefined) {
+        throw new MailRefused("send: from is missing — give the message a from, or createResendMailer a default one");
+      }
+      const to = Array.isArray(message.to) ? message.to : [message.to];
+      const body = {
+        from: formatAddress(sender),
+        to: to.map(formatAddress),
+        subject: message.subject,
+        html: message.html,
+        text: message.text,
+        ...message.replyTo === undefined ? {} : {
+          reply_to: formatAddress(message.replyTo)
+        },
+        ...message.headers === undefined ? {} : { headers: message.headers }
+      };
+      const signal = AbortSignal.timeout(timeoutMs);
+      let response;
+      try {
+        response = await beforeAbort(post(endpoint, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${options.apiKey}`,
+            "content-type": "application/json"
+          },
+          body: JSON.stringify(body),
+          signal
+        }), signal);
+      } catch (error) {
+        if (error instanceof DOMException && error.name === "TimeoutError") {
+          throw new MailFailure(`send: Resend did not answer within ${timeoutMs} ms`, { cause: error });
+        }
+        throw new MailFailure("send: Resend could not be reached", {
+          cause: error
+        });
+      }
+      const answer = await readAnswer(response, signal);
+      if (response.ok)
+        return { messageId: text(answer.id) };
+      const cause = resendAnswer(response.status, text(answer.name), text(answer.message));
+      if (response.status === 400 || response.status === 422) {
+        throw new MailRefused("send: Resend refused the message", { cause });
+      }
+      throw new MailFailure("send: Resend could not take the message", {
+        cause
+      });
+    }
+  };
+}
+export {
+  createResendMailer,
+  formatAddress
+};
+
+//# debugId=900CD1C929776F6D64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@nxgt/mail-resend` — a Resend transport for `@nxgt/mail`, over `fetch`,\n * with no SDK.\n *\n * ```ts\n * import { createResendMailer } from '@nxgt/mail-resend';\n *\n * const mailer = createResendMailer({\n *   apiKey: process.env.RESEND_API_KEY ?? '',\n *   from: { name: 'Acme', address: 'noreply@acme.test' },\n * });\n * ```\n *\n * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`\n * peer, what Resend answered as the `cause`. Nothing is retried.\n */\n\nimport {\n\ttype Address,\n\tcheckMessage,\n\ttype Mailer,\n\tMailFailure,\n\ttype MailMessage,\n\tMailRefused,\n\ttype SentMail,\n} from '@nxgt/mail';\n\nexport interface ResendMailerOptions {\n\t/** The API key, `re_…`. */\n\treadonly apiKey: string;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n\t/** Default `https://api.resend.com`. */\n\treadonly baseUrl?: string;\n\t/** Default the global `fetch`. For a proxy, or a test. */\n\treadonly fetch?: (url: string, init: RequestInit) => Promise<Response>;\n\t/** How long a send may take before it fails. Default `30000`. */\n\treadonly timeoutMs?: number;\n}\n\n/**\n * An address as Resend reads it: bare, or `\"name\" <address>` — the name a\n * quoted string, so a comma or an angle bracket in it names no one else.\n */\nexport function formatAddress(address: Address): string {\n\tif (typeof address === 'string') return address;\n\tconst name = address.name.replace(/[\\\\\"]/g, (char) => `\\\\${char}`);\n\treturn `\"${name}\" <${address.address}>`;\n}\n\n/**\n * What Resend answered, kept as the `cause`: a plain `Error` — a transport\n * defines no error class of its own — with the status, Resend's error name\n * (`validation_error`, `rate_limit_exceeded`…) and its message as `detail`.\n * Its own message holds the status and the name only: Resend's message can\n * quote an address, and a message reports a shape, never a value.\n */\nfunction resendAnswer(\n\tstatus: number,\n\terrorName: string | null,\n\tdetail: string | null,\n): Error & {\n\treadonly status: number;\n\treadonly errorName: string | null;\n\treadonly detail: string | null;\n} {\n\treturn Object.assign(\n\t\tnew Error(\n\t\t\t`Resend answered ${status}${errorName === null ? '' : ` ${errorName}`}`,\n\t\t),\n\t\t{ status, errorName, detail },\n\t);\n}\n\n/**\n * Settles with `work`, or rejects with the signal's reason once it aborts —\n * so the timeout holds even with an injected `fetch` that ignores the signal.\n */\nfunction beforeAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {\n\treturn new Promise<T>((resolve, reject) => {\n\t\tconst abort = () => reject(signal.reason);\n\t\tif (signal.aborted) return abort();\n\t\tsignal.addEventListener('abort', abort, { once: true });\n\t\twork.then(\n\t\t\t(value) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\tresolve(value);\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsignal.removeEventListener('abort', abort);\n\t\t\t\treject(error);\n\t\t\t},\n\t\t);\n\t});\n}\n\n/** The JSON body of an answer, or `{}` when it is not JSON or never ends. */\nasync function readAnswer(\n\tresponse: Response,\n\tsignal: AbortSignal,\n): Promise<Record<string, unknown>> {\n\tconst body: unknown = await beforeAbort(response.json(), signal).then(\n\t\t(value: unknown) => value,\n\t\t() => null,\n\t);\n\treturn typeof body === 'object' && body !== null\n\t\t? (body as Record<string, unknown>)\n\t\t: {};\n}\n\n/** The largest delay a timer takes, 2³¹ − 1 ms — about 24.8 days. */\nconst MAX_TIMEOUT_MS = 2_147_483_647;\n\nconst text = (value: unknown) =>\n\ttypeof value === 'string' && value !== '' ? value : null;\n\nfunction checkOptions(options: ResendMailerOptions): void {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: options must be an object, as { apiKey }',\n\t\t);\n\t}\n\tif (typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey must be a Resend API key — is the environment variable set?',\n\t\t);\n\t}\n\tif (/\\s/.test(options.apiKey)) {\n\t\t// A key read from a file often keeps its final line break; `fetch`\n\t\t// would then refuse the header at every send, as an outage.\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: apiKey holds whitespace — trim the value it was read from',\n\t\t);\n\t}\n\tif (\n\t\toptions.baseUrl !== undefined &&\n\t\t(typeof options.baseUrl !== 'string' ||\n\t\t\t!/^https?:\\/\\/[^/]/.test(options.baseUrl))\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: baseUrl must be an http: or https: URL',\n\t\t);\n\t}\n\tif (options.fetch !== undefined && typeof options.fetch !== 'function') {\n\t\tthrow new TypeError('createResendMailer: fetch must be a function');\n\t}\n\tif (\n\t\toptions.timeoutMs !== undefined &&\n\t\t!(Number.isInteger(options.timeoutMs) && options.timeoutMs > 0)\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createResendMailer: timeoutMs must be a positive integer',\n\t\t);\n\t}\n\tif (options.timeoutMs !== undefined && options.timeoutMs > MAX_TIMEOUT_MS) {\n\t\t// A timer's delay is a signed 32-bit integer: above it, the runtime\n\t\t// fires at once, and every send would time out.\n\t\tthrow new TypeError(\n\t\t\t`createResendMailer: timeoutMs must be at most ${MAX_TIMEOUT_MS} — a longer timer fires at once`,\n\t\t);\n\t}\n\tif (options.from !== undefined) {\n\t\ttry {\n\t\t\tcheckMessage({ to: options.from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }',\n\t\t\t);\n\t\t}\n\t}\n}\n\n/** Creates a {@link Mailer} that sends each message through Resend's API. */\nexport function createResendMailer(options: ResendMailerOptions): Mailer {\n\tcheckOptions(options);\n\tconst endpoint = `${(options.baseUrl ?? 'https://api.resend.com').replace(/\\/+$/, '')}/emails`;\n\tconst post =\n\t\toptions.fetch ??\n\t\t((url: string, init: RequestInit) => globalThis.fetch(url, init));\n\tconst timeoutMs = options.timeoutMs ?? 30_000;\n\n\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? options.from;\n\t\t\tif (sender === undefined) {\n\t\t\t\tthrow new MailRefused(\n\t\t\t\t\t'send: from is missing — give the message a from, or createResendMailer a default one',\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst to = Array.isArray(message.to) ? message.to : [message.to];\n\t\t\tconst body = {\n\t\t\t\tfrom: formatAddress(sender),\n\t\t\t\tto: to.map(formatAddress),\n\t\t\t\tsubject: message.subject,\n\t\t\t\thtml: message.html,\n\t\t\t\ttext: message.text,\n\t\t\t\t...(message.replyTo === undefined\n\t\t\t\t\t? {}\n\t\t\t\t\t: {\n\t\t\t\t\t\t\t// biome-ignore lint/style/useNamingConvention: Resend's wire format names the field, not us.\n\t\t\t\t\t\t\treply_to: formatAddress(message.replyTo),\n\t\t\t\t\t\t}),\n\t\t\t\t...(message.headers === undefined ? {} : { headers: message.headers }),\n\t\t\t};\n\n\t\t\tconst signal = AbortSignal.timeout(timeoutMs);\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await beforeAbort(\n\t\t\t\t\tpost(endpoint, {\n\t\t\t\t\t\tmethod: 'POST',\n\t\t\t\t\t\theaders: {\n\t\t\t\t\t\t\tauthorization: `Bearer ${options.apiKey}`,\n\t\t\t\t\t\t\t'content-type': 'application/json',\n\t\t\t\t\t\t},\n\t\t\t\t\t\tbody: JSON.stringify(body),\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t}),\n\t\t\t\t\tsignal,\n\t\t\t\t);\n\t\t\t} catch (error) {\n\t\t\t\tif (error instanceof DOMException && error.name === 'TimeoutError') {\n\t\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t\t`send: Resend did not answer within ${timeoutMs} ms`,\n\t\t\t\t\t\t{ cause: error },\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure('send: Resend could not be reached', {\n\t\t\t\t\tcause: error,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tconst answer = await readAnswer(response, signal);\n\t\t\tif (response.ok) return { messageId: text(answer.id) };\n\n\t\t\tconst cause = resendAnswer(\n\t\t\t\tresponse.status,\n\t\t\t\ttext(answer.name),\n\t\t\t\ttext(answer.message),\n\t\t\t);\n\t\t\t// 400 and 422 are Resend refusing the message; anything else — a key\n\t\t\t// refused, a rate limit, an outage — is Resend failing to take it.\n\t\t\tif (response.status === 400 || response.status === 422) {\n\t\t\t\tthrow new MailRefused('send: Resend refused the message', { cause });\n\t\t\t}\n\t\t\tthrow new MailFailure('send: Resend could not take the message', {\n\t\t\t\tcause,\n\t\t\t});\n\t\t},\n\t};\n}\n"
+  ],
+  "mappings": ";AAiBA;AAAA;AAAA;AAAA;AAAA;AA2BO,SAAS,aAAa,CAAC,SAA0B;AAAA,EACvD,IAAI,OAAO,YAAY;AAAA,IAAU,OAAO;AAAA,EACxC,MAAM,OAAO,QAAQ,KAAK,QAAQ,UAAU,CAAC,SAAS,KAAK,MAAM;AAAA,EACjE,OAAO,IAAI,UAAU,QAAQ;AAAA;AAU9B,SAAS,YAAY,CACpB,QACA,WACA,QAKC;AAAA,EACD,OAAO,OAAO,OACb,IAAI,MACH,mBAAmB,SAAS,cAAc,OAAO,KAAK,IAAI,aAC3D,GACA,EAAE,QAAQ,WAAW,OAAO,CAC7B;AAAA;AAOD,SAAS,WAAc,CAAC,MAAkB,QAAiC;AAAA,EAC1E,OAAO,IAAI,QAAW,CAAC,SAAS,WAAW;AAAA,IAC1C,MAAM,QAAQ,MAAM,OAAO,OAAO,MAAM;AAAA,IACxC,IAAI,OAAO;AAAA,MAAS,OAAO,MAAM;AAAA,IACjC,OAAO,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;AAAA,IACtD,KAAK,KACJ,CAAC,UAAU;AAAA,MACV,OAAO,oBAAoB,SAAS,KAAK;AAAA,MACzC,QAAQ,KAAK;AAAA,OAEd,CAAC,UAAmB;AAAA,MACnB,OAAO,oBAAoB,SAAS,KAAK;AAAA,MACzC,OAAO,KAAK;AAAA,KAEd;AAAA,GACA;AAAA;AAIF,eAAe,UAAU,CACxB,UACA,QACmC;AAAA,EACnC,MAAM,OAAgB,MAAM,YAAY,SAAS,KAAK,GAAG,MAAM,EAAE,KAChE,CAAC,UAAmB,OACpB,MAAM,IACP;AAAA,EACA,OAAO,OAAO,SAAS,YAAY,SAAS,OACxC,OACD,CAAC;AAAA;AAIL,IAAM,iBAAiB;AAEvB,IAAM,OAAO,CAAC,UACb,OAAO,UAAU,YAAY,UAAU,KAAK,QAAQ;AAErD,SAAS,YAAY,CAAC,SAAoC;AAAA,EACzD,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AAAA,IACpD,MAAM,IAAI,UACT,8DACD;AAAA,EACD;AAAA,EACA,IAAI,OAAO,QAAQ,WAAW,YAAY,QAAQ,OAAO,KAAK,MAAM,IAAI;AAAA,IACvE,MAAM,IAAI,UACT,wFACD;AAAA,EACD;AAAA,EACA,IAAI,KAAK,KAAK,QAAQ,MAAM,GAAG;AAAA,IAG9B,MAAM,IAAI,UACT,+EACD;AAAA,EACD;AAAA,EACA,IACC,QAAQ,YAAY,cACnB,OAAO,QAAQ,YAAY,YAC3B,CAAC,mBAAmB,KAAK,QAAQ,OAAO,IACxC;AAAA,IACD,MAAM,IAAI,UACT,4DACD;AAAA,EACD;AAAA,EACA,IAAI,QAAQ,UAAU,aAAa,OAAO,QAAQ,UAAU,YAAY;AAAA,IACvE,MAAM,IAAI,UAAU,8CAA8C;AAAA,EACnE;AAAA,EACA,IACC,QAAQ,cAAc,aACtB,EAAE,OAAO,UAAU,QAAQ,SAAS,KAAK,QAAQ,YAAY,IAC5D;AAAA,IACD,MAAM,IAAI,UACT,0DACD;AAAA,EACD;AAAA,EACA,IAAI,QAAQ,cAAc,aAAa,QAAQ,YAAY,gBAAgB;AAAA,IAG1E,MAAM,IAAI,UACT,iDAAiD,+CAClD;AAAA,EACD;AAAA,EACA,IAAI,QAAQ,SAAS,WAAW;AAAA,IAC/B,IAAI;AAAA,MACH,aAAa,EAAE,IAAI,QAAQ,MAAM,SAAS,IAAI,MAAM,IAAI,MAAM,GAAG,CAAC;AAAA,MACjE,MAAM;AAAA,MACP,MAAM,IAAI,UACT,iGACD;AAAA;AAAA,EAEF;AAAA;AAIM,SAAS,kBAAkB,CAAC,SAAsC;AAAA,EACxE,aAAa,OAAO;AAAA,EACpB,MAAM,WAAW,IAAI,QAAQ,WAAW,0BAA0B,QAAQ,QAAQ,EAAE;AAAA,EACpF,MAAM,OACL,QAAQ,UACP,CAAC,KAAa,SAAsB,WAAW,MAAM,KAAK,IAAI;AAAA,EAChE,MAAM,YAAY,QAAQ,aAAa;AAAA,EAEvC,OAAO;AAAA,SACA,KAAI,CAAC,SAAyC;AAAA,MACnD,aAAa,OAAO;AAAA,MACpB,MAAM,SAAS,QAAQ,QAAQ,QAAQ;AAAA,MACvC,IAAI,WAAW,WAAW;AAAA,QACzB,MAAM,IAAI,YACT,sFACD;AAAA,MACD;AAAA,MACA,MAAM,KAAK,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE;AAAA,MAC/D,MAAM,OAAO;AAAA,QACZ,MAAM,cAAc,MAAM;AAAA,QAC1B,IAAI,GAAG,IAAI,aAAa;AAAA,QACxB,SAAS,QAAQ;AAAA,QACjB,MAAM,QAAQ;AAAA,QACd,MAAM,QAAQ;AAAA,WACV,QAAQ,YAAY,YACrB,CAAC,IACD;AAAA,UAEA,UAAU,cAAc,QAAQ,OAAO;AAAA,QACxC;AAAA,WACE,QAAQ,YAAY,YAAY,CAAC,IAAI,EAAE,SAAS,QAAQ,QAAQ;AAAA,MACrE;AAAA,MAEA,MAAM,SAAS,YAAY,QAAQ,SAAS;AAAA,MAC5C,IAAI;AAAA,MACJ,IAAI;AAAA,QACH,WAAW,MAAM,YAChB,KAAK,UAAU;AAAA,UACd,QAAQ;AAAA,UACR,SAAS;AAAA,YACR,eAAe,UAAU,QAAQ;AAAA,YACjC,gBAAgB;AAAA,UACjB;AAAA,UACA,MAAM,KAAK,UAAU,IAAI;AAAA,UACzB;AAAA,QACD,CAAC,GACD,MACD;AAAA,QACC,OAAO,OAAO;AAAA,QACf,IAAI,iBAAiB,gBAAgB,MAAM,SAAS,gBAAgB;AAAA,UACnE,MAAM,IAAI,YACT,sCAAsC,gBACtC,EAAE,OAAO,MAAM,CAChB;AAAA,QACD;AAAA,QACA,MAAM,IAAI,YAAY,qCAAqC;AAAA,UAC1D,OAAO;AAAA,QACR,CAAC;AAAA;AAAA,MAGF,MAAM,SAAS,MAAM,WAAW,UAAU,MAAM;AAAA,MAChD,IAAI,SAAS;AAAA,QAAI,OAAO,EAAE,WAAW,KAAK,OAAO,EAAE,EAAE;AAAA,MAErD,MAAM,QAAQ,aACb,SAAS,QACT,KAAK,OAAO,IAAI,GAChB,KAAK,OAAO,OAAO,CACpB;AAAA,MAGA,IAAI,SAAS,WAAW,OAAO,SAAS,WAAW,KAAK;AAAA,QACvD,MAAM,IAAI,YAAY,oCAAoC,EAAE,MAAM,CAAC;AAAA,MACpE;AAAA,MACA,MAAM,IAAI,YAAY,2CAA2C;AAAA,QAChE;AAAA,MACD,CAAC;AAAA;AAAA,EAEH;AAAA;",
+  "debugId": "900CD1C929776F6D64756E2164756E21",
+  "names": []
+}

package/docs/README.md

@@ -0,0 +1,14 @@
+# @nxgt/mail-resend — documentation
+
+The [README](../README.md) shows that it works; these pages show how, one area
+at a time, with an example for every option. The words they use — e-mail,
+mailer, transport, hand-over, refusal, failure — are defined once, in the
+[vocabulary](https://github.com/softistx/nxgt-mail/blob/develop/docs/vocabulary.md).
+
+| Page | Read it when |
+| --- | --- |
+| [Setting up](guide/setup.md) | You are wiring `createResendMailer`: the key, the default sender, a proxy or another `baseUrl`, your own `fetch`, the timeout, and the request each message becomes |
+| [Errors](guide/errors.md) | You are handling what `send` throws: which Resend answers are a `MailRefused`, which a `MailFailure`, what is on `cause`, and every `TypeError` at wiring |
+| [Testing](guide/testing.md) | You are testing the transport against a local server answering as Resend does, with `describeMailer` — or an application that uses it |
+| [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
+| [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/errors.md

@@ -0,0 +1,127 @@
+# Errors
+
+`send` resolves only once Resend has answered `2xx`. Otherwise it rejects with
+one of the two classes of its `@nxgt/mail` peer — this package defines no
+error class, so `error instanceof MailFailure` holds whichever transport the
+application wires:
+
+- **`MailRefused`** (`code: 'MAIL_REFUSED'`) — Resend refused the message
+  itself. Sending it again unchanged fails again.
+- **`MailFailure`** (`code: 'MAIL_FAILED'`) — Resend could not take it:
+  unreachable, too slow, rate-limited, or the key refused. Nothing is known
+  to have been sent: after a timeout or a dropped connection, Resend may have
+  accepted it all the same.
+
+Nothing is retried. Whether and when to retry is yours to decide, where you
+can see it.
+
+```ts
+import { MailError, type MailErrorCode, type Mailer, type MailMessage } from '@nxgt/mail';
+
+function statusOf(code: MailErrorCode): number {
+	switch (code) {
+		case 'MAIL_FAILED':
+			return 503;
+		case 'MAIL_REFUSED':
+			return 422;
+	}
+}
+
+export async function sendOrRespond(mailer: Mailer, message: MailMessage): Promise<Response> {
+	try {
+		await mailer.send(message);
+		return new Response(null, { status: 202 });
+	} catch (error) {
+		if (!(error instanceof MailError)) throw error;
+		return Response.json({ code: error.code }, { status: statusOf(error.code) });
+	}
+}
+```
+
+## Which answer is which
+
+Resend answers an error as `{ statusCode, name, message }`:
+
+| Resend answers | Typical `name` | Throws |
+| --- | --- | --- |
+| `400` | `validation_error` | `MailRefused` |
+| `422` | `validation_error`, `missing_required_field` | `MailRefused` |
+| `401`, `403` | `missing_api_key`, `invalid_api_key`, an unverified domain | `MailFailure` |
+| `429` | `rate_limit_exceeded`, `daily_quota_exceeded` | `MailFailure` |
+| `5xx` | `internal_server_error` | `MailFailure` |
+| any other status | — | `MailFailure` |
+| no answer: DNS, a refused connection, TLS | — | `MailFailure` — `send: Resend could not be reached` |
+| no answer within `timeoutMs` | — | `MailFailure` — `send: Resend did not answer within <timeoutMs> ms` |
+
+A `401` or `403` is a failure although it is a `4xx`: a bad key or an
+unverified domain refuses every message alike. It is the wiring that is
+wrong, not the message.
+
+## What `cause` holds
+
+For an answer, `cause` is a plain `Error` — the transport defines no class —
+carrying what Resend said:
+
+| Property | Type | Example |
+| --- | --- | --- |
+| `message` | `string` | `Resend answered 422 validation_error` |
+| `status` | `number` | `422` |
+| `errorName` | `string \| null` | `'validation_error'`, or `null` when the body had none |
+| `detail` | `string \| null` | Resend's own `message`, or `null` |
+
+For no answer, `cause` is the `fetch` error — a `TypeError` from the runtime,
+or the `TimeoutError` of the timeout.
+
+```ts
+import { MailError } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailError) {
+		const cause = error.cause as { status?: number; errorName?: string | null };
+		logger.warn({ code: error.code, status: cause.status, resend: cause.errorName }, error.message);
+	}
+	throw error;
+}
+```
+
+Neither message holds a value: never the key, an address, a subject, or what
+Resend said. Resend's own message can quote an address, so it is kept on
+`detail` and never put in a `message` — log `detail` only where your logs may
+hold one.
+
+## The messages
+
+| `message` | Class | When |
+| --- | --- | --- |
+| `send: Resend refused the message` | `MailRefused` | A `400` or `422` |
+| `send: Resend could not take the message` | `MailFailure` | Any other answer that is not `2xx` |
+| `send: Resend could not be reached` | `MailFailure` | `fetch` threw |
+| `send: Resend did not answer within <timeoutMs> ms` | `MailFailure` | The timeout aborted the request |
+| `send: from is missing — give the message a from, or createResendMailer a default one` | `MailRefused` | A message without `from`, on a mailer without a default. No request is made |
+| `send: …` from `checkMessage` | `MailRefused` | A message no transport hands over — see [`@nxgt/mail`'s troubleshooting](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/troubleshooting.md#sending) |
+
+## Wiring — a `TypeError`
+
+A bad option is a mistake in how the application was put together, thrown
+when `createResendMailer` is called, never at the first send. No message
+prints the value:
+
+| `message` | When |
+| --- | --- |
+| `createResendMailer: options must be an object, as { apiKey }` | `createResendMailer()`, or the key passed on its own |
+| `createResendMailer: apiKey must be a Resend API key — is the environment variable set?` | No `apiKey`, an empty or a blank one |
+| `createResendMailer: apiKey holds whitespace — trim the value it was read from` | A key with a space or a line break in it |
+| `createResendMailer: baseUrl must be an http: or https: URL` | `baseUrl` without its scheme, or not a string |
+| `createResendMailer: fetch must be a function` | `fetch` that is not a function |
+| `createResendMailer: timeoutMs must be a positive integer` | `0`, a negative number, a fraction |
+| `createResendMailer: timeoutMs must be at most 2147483647 — a longer timer fires at once` | A `timeoutMs` above 2³¹ − 1 ms, about 24.8 days |
+| `createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }` | A default `from` that is not an address — `'Acme <noreply@acme.test>'` included |
+
+## See also
+
+- [Troubleshooting](../troubleshooting.md) — each message, its cause and its
+  fix.
+- [`@nxgt/mail` — sending](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/sending.md)
+  — the errors, from the caller's side.

package/docs/guide/setup.md

@@ -0,0 +1,214 @@
+# Setting up
+
+`createResendMailer` sends each message with one `POST /emails` to Resend's
+API, over `fetch`: no SDK, no dependency, no Node built-in. It adds the
+`Mailer` contract of `@nxgt/mail` — the same refusals as every transport, the
+two errors, no retry.
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+export const mailer = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+```
+
+## The signature
+
+```ts
+function createResendMailer(options: ResendMailerOptions): Mailer;
+
+interface ResendMailerOptions {
+	readonly apiKey: string;
+	readonly from?: Address;
+	readonly baseUrl?: string;
+	readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+	readonly timeoutMs?: number;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | required | Sent as `Authorization: Bearer …`. Empty, blank or holding whitespace is a `TypeError` |
+| `from` | `Address` | none | The sender of a message that has no `from`. Without it, such a message is refused with `MailRefused` |
+| `baseUrl` | `string` | `https://api.resend.com` | An `http:` or `https:` URL; `/emails` is appended, a trailing `/` dropped |
+| `fetch` | `(url, init) => Promise<Response>` | the global `fetch` | Every request goes through it |
+| `timeoutMs` | `number` | `30000` | A positive integer, at most `2147483647`. A send that has no answer by then is aborted and fails with `MailFailure` |
+
+Options are checked when the mailer is created, and a mistake is a bare
+`TypeError` — see [Errors — wiring](errors.md#wiring--a-typeerror).
+
+## The key
+
+Read it where the process starts, and decide there what an unset variable
+means. `process.env.RESEND_API_KEY` is `string | undefined`, which does not
+compile as `apiKey`:
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+// An unset variable: a TypeError now, at start-up — never a failure at the first send.
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '' });
+```
+
+A key read from a file keeps its final line break, and `fetch` would refuse
+the header at every send. A key holding whitespace is refused at wiring
+instead:
+
+```ts
+import { readFileSync } from 'node:fs';
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const apiKey = readFileSync('/run/secrets/resend', 'utf8').trim();
+const mailer = createResendMailer({ apiKey });
+```
+
+The key is never written in an error message.
+
+## The sender
+
+A message's own `from` wins; the default is used when it has none; with
+neither, the send is refused with `MailRefused` before any request:
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+
+await mailer.send({ to: 'ada@example.com', subject: 'Hi', html: '<p>Hi</p>', text: 'Hi' }); // from Acme
+await mailer.send({
+	to: 'ada@example.com',
+	from: 'billing@acme.test', // this one wins
+	subject: 'Your invoice',
+	html: '<p>…</p>',
+	text: '…',
+});
+```
+
+The sending domain must be verified in Resend; one that is not is answered
+`403`, a `MailFailure`.
+
+## A proxy, a region, a test server — `baseUrl` and `fetch`
+
+`baseUrl` moves every request; `fetch` replaces the function that makes it:
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+// Through a gateway of your own.
+const viaGateway = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	baseUrl: 'https://mail-gateway.internal.example',
+});
+
+// With a fetch that logs each request's timing.
+const timed = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	fetch: async (url, init) => {
+		const started = performance.now();
+		try {
+			return await fetch(url, init);
+		} finally {
+			console.info('resend', Math.round(performance.now() - started), 'ms');
+		}
+	},
+});
+```
+
+A `fetch` you pass receives the `AbortSignal` of the timeout in `init.signal`:
+pass `init` on, and the request is aborted when it fires. The timeout holds
+either way — the send stops waiting for a `fetch` that ignores the signal and
+fails with `MailFailure` — but only a `fetch` that passes the signal on
+stops the request itself.
+
+## The timeout
+
+`timeoutMs` (30 seconds by default) bounds the request: past it, the request
+is aborted and the send fails with `MailFailure` —
+`send: Resend did not answer within 30000 ms`. Resend may still have accepted
+the message; the id is simply unknown. The bound covers the answer's body
+too: a `2xx` whose body never ends answers `{ messageId: null }` once the
+timeout passes. It is a timer, so at most `2147483647` ms — a longer one
+would fire at once, and is refused at wiring. A send awaited in a request handler
+usually wants less:
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '', timeoutMs: 10_000 });
+```
+
+## What a message becomes
+
+```ts
+await mailer.send({
+	to: ['ada@example.com', { name: 'Doe, "John"', address: 'john@example.com' }],
+	replyTo: 'support@acme.test',
+	headers: { 'List-Unsubscribe': '<https://acme.test/u>' },
+	subject: 'Hi',
+	html: '<p>Hi</p>',
+	text: 'Hi',
+});
+```
+
+```http
+POST /emails HTTP/1.1
+Host: api.resend.com
+Authorization: Bearer re_…
+Content-Type: application/json
+
+{
+  "from": "\"Acme\" <noreply@acme.test>",
+  "to": ["ada@example.com", "\"Doe, \\\"John\\\"\" <john@example.com>"],
+  "subject": "Hi",
+  "html": "<p>Hi</p>",
+  "text": "Hi",
+  "reply_to": "support@acme.test",
+  "headers": { "List-Unsubscribe": "<https://acme.test/u>" }
+}
+```
+
+- Every address goes through `formatAddress`: a bare address as is, a name as
+  a quoted string with `"` and `\` escaped — so a comma or an angle bracket in
+  a name never names another recipient. It is exported, for code that builds
+  Resend requests of its own:
+
+  ```ts
+  import { formatAddress } from '@nxgt/mail-resend';
+
+  formatAddress({ name: 'Doe, John', address: 'john@example.com' }); // '"Doe, John" <john@example.com>'
+  ```
+
+- `replyTo` is sent as `reply_to`, Resend's name for it; `reply_to` and
+  `headers` are left out when the message has none.
+- Before any of it, `checkMessage` from `@nxgt/mail` refuses what no transport
+  hands over. Its messages are listed in
+  [`@nxgt/mail`'s troubleshooting](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/troubleshooting.md#sending).
+
+`send` answers `{ messageId }`: Resend's `id`, or `null` when a `2xx` answer
+carries none, or is not JSON — the message was accepted, the id is absent.
+
+## With the renderer
+
+```ts
+import { createMailRenderer } from '@nxgt/mail/renderer';
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mails = createMailRenderer({ dir: 'dist' });
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '', from: 'noreply@acme.test' });
+
+await mailer.send({
+	to: 'ada@example.com',
+	...mails.render('verify-email', { name: 'Ada', link: 'https://app.example.com/verify?token=abc' }, { locale: 'fr' }),
+});
+```
+
+## See also
+
+- [Errors](errors.md) — what `send` throws, and when.
+- [Testing](testing.md) — a local server answering as Resend does, and the
+  conformance suite.

package/docs/guide/testing.md

@@ -0,0 +1,160 @@
+# Testing
+
+Two different things to test, with two different tools:
+
+- **An application that sends e-mail.** Do not call Resend, nor fake it: wire
+  `createMemoryMailer()` from `@nxgt/mail` in the tests, read its outbox, and
+  make a send fail with `failNext()`. See
+  [`@nxgt/mail` — testing](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/testing.md).
+- **This transport.** A local server answering as Resend's API does, and
+  `baseUrl` pointed at it: the transport's real `fetch`, real HTTP, real JSON.
+  That is how this package passes `@nxgt/mail/conformance`, and the rest of
+  this page shows it.
+
+## A local Resend
+
+It checks the key, keeps what it accepted, and fails on demand **the way
+Resend fails** — a `503` for an outage, a `422 validation_error` for a
+refusal — so the suite proves the transport's reading of Resend's answers,
+not a wrapper's:
+
+```ts
+// local-resend.ts
+import type { DeliveredMail } from '@nxgt/mail/conformance';
+
+export const API_KEY = 're_test';
+
+/** The bare addresses of `"name" <address>` or `address`: a quoted name names no one. */
+const addressOf = (entry: string) => entry.match(/<([^<>]+)>$/)?.[1] ?? entry;
+
+export function startResend() {
+	const delivered: DeliveredMail[] = [];
+	const faults: ('outage' | 'refusal')[] = [];
+	let attempts = 0;
+	const answer = (statusCode: number, name: string, message: string) =>
+		Response.json({ statusCode, name, message }, { status: statusCode });
+
+	const server = Bun.serve({
+		port: 0,
+		hostname: '127.0.0.1',
+		async fetch(request) {
+			if (request.method !== 'POST' || new URL(request.url).pathname !== '/emails') {
+				return answer(404, 'not_found', 'The requested endpoint does not exist.');
+			}
+			if (request.headers.get('authorization') !== `Bearer ${API_KEY}`) {
+				return answer(401, 'missing_api_key', 'Missing API key in the authorization header.');
+			}
+			attempts += 1; // one hand-over
+			const fault = faults.shift();
+			if (fault === 'outage') return answer(503, 'internal_server_error', 'Service unavailable.');
+			if (fault === 'refusal') return answer(422, 'validation_error', 'Invalid `to` field.');
+
+			const body = (await request.json()) as { to: string[]; subject: string; html: string; text: string };
+			delivered.push({ to: body.to.map(addressOf), subject: body.subject, html: body.html, text: body.text });
+			return Response.json({ id: `resend-${delivered.length}` });
+		},
+	});
+	return {
+		baseUrl: `http://127.0.0.1:${server.port}`,
+		delivered,
+		faults,
+		attempts: () => attempts,
+		close: () => server.stop(true),
+	};
+}
+```
+
+`addressOf` above takes the address after the last `<`, which is enough for
+the transport's own output. The package's spec reads each `to` entry as an
+RFC 5322 address list instead — quoted strings, escapes, commas — as Resend
+does, so a transport that forgot to quote a name would deliver to two
+addresses there, and fail `send.hostileName`.
+
+## The conformance suite
+
+One fresh server per case, stopped after it:
+
+```ts
+import { describe, it } from 'bun:test';
+import { describeMailer } from '@nxgt/mail/conformance';
+import { createResendMailer } from '@nxgt/mail-resend';
+import { API_KEY, startResend } from './local-resend';
+
+describeMailer({
+	name: 'createResendMailer',
+	runner: { describe, it }, // bun test puts neither on globalThis
+	harness: {
+		async open() {
+			const resend = startResend();
+			return {
+				mailer: createResendMailer({ apiKey: API_KEY, baseUrl: resend.baseUrl }),
+				delivered: async () => [...resend.delivered],
+				faults: {
+					failNext: async (kind) => {
+						resend.faults.push(kind);
+					},
+					attempts: async () => resend.attempts(),
+				},
+				close: () => resend.close(),
+			};
+		},
+	},
+});
+```
+
+All eleven cases pass: a send answers `SentMail`, the message arrives byte for
+byte (accents, an emoji, `&amp;` in a link), every recipient is delivered to,
+a hostile name reaches only its own address, the refusals — a `Bcc` among the
+custom headers included — and the three
+failure cases — an outage is a `MailFailure` with its `cause` and one attempt,
+a refusal a `MailRefused`, and the next send goes through.
+
+## Beyond the suite
+
+The package's own specs
+([`src/index.spec.ts`](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail-resend/src/index.spec.ts))
+add what the suite does not ask of every transport:
+
+- a `400` is a `MailRefused`; a `403`, a `429` and a `503` are a `MailFailure`
+  with the status on `cause`, each tried once;
+- a server that is not listening ends in `MailFailure` —
+  `send: Resend could not be reached` — with the `fetch` error as `cause`;
+- a server that does not answer within `timeoutMs` ends in `MailFailure`, a
+  `TimeoutError` as `cause` — and so does a `fetch` that ignores the signal
+  and never settles; an answer whose body never ends answers
+  `{ messageId: null }` once the timeout passes;
+- no message — the error's nor its cause's — holds the key, a recipient's
+  address or what Resend said;
+- the request: `POST /emails`, the bearer key, JSON, a quoted name,
+  `reply_to` and `headers`;
+- a `2xx` with no id, or with a body that is not JSON, answers
+  `{ messageId: null }`;
+- every `TypeError` at wiring, a `timeoutMs` above `2147483647` included.
+
+A `fetch` of your own needs no server at all, when a test only needs to see
+the request:
+
+```ts
+import { expect, test } from 'bun:test';
+import { sampleMessage } from '@nxgt/mail/conformance';
+import { createResendMailer } from '@nxgt/mail-resend';
+
+test('posts the message to /emails', async () => {
+	const requests: { url: string; body: unknown }[] = [];
+	const mailer = createResendMailer({
+		apiKey: 're_test',
+		fetch: async (url, init) => {
+			requests.push({ url, body: JSON.parse(String(init.body)) });
+			return Response.json({ id: 'email-1' });
+		},
+	});
+	expect(await mailer.send(sampleMessage)).toEqual({ messageId: 'email-1' });
+	expect(requests[0]?.url).toBe('https://api.resend.com/emails');
+});
+```
+
+## See also
+
+- [`@nxgt/mail` — writing a transport](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/transports.md)
+  — the contract, the harness and every case.
+- [Errors](errors.md) — the mapping these tests pin down.

package/docs/roadmap.md

@@ -0,0 +1,46 @@
+# Roadmap
+
+Where `@nxgt/mail-resend` is heading. A direction, not a commitment: there are
+no dates here, and the version something shipped in is the only number.
+
+## Now
+
+Nothing between releases.
+
+## Next
+
+Nothing yet.
+
+## Later
+
+- **An idempotency key per send** — Resend's `Idempotency-Key` header, so a
+  retry the caller decides cannot send the same e-mail twice.
+- **Tags** — Resend's `tags`, to group sends in its dashboard.
+
+## Not planned
+
+- **The Resend SDK** — one request does not need it, and without it the
+  transport has no dependency.
+- **Silent retries**, including on a `429` — the transport tries once. A
+  retry is the caller's decision, made where it can be seen; a hidden one can
+  send the same e-mail twice.
+- **A transport's own error class** — it throws `@nxgt/mail`'s `MailFailure`
+  and `MailRefused`, so `instanceof` holds whichever transport you wire.
+- **Scheduling, batch sending and attachments** — a message is three strings
+  sent now; the port has no room for more.
+
+## Shipped
+
+The last ten, newest first, each with the version it came in. Everything
+before is in the [CHANGELOG](../CHANGELOG.md).
+
+- **A Resend transport over `fetch`, v0.1.0** — `createResendMailer({ apiKey, from })`:
+  one `POST /emails` per message, no SDK, no dependency, no Node built-in, so
+  it runs on an edge runtime too. Each message is checked as every transport
+  checks it, and a name is sent quoted so it names one recipient.
+- **Errors you can act on, v0.1.0** — a `400` or `422` is a `MailRefused`; a bad key,
+  a rate limit, an outage, a network error or a timeout is a `MailFailure`,
+  what Resend answered on `cause`. The classes are `@nxgt/mail`'s, so
+  `instanceof` holds.
+- **Proven against Resend's API shape, v0.1.0** — the `@nxgt/mail/conformance` suite
+  passes against a local server answering as Resend does.

package/docs/troubleshooting.md

@@ -0,0 +1,252 @@
+# Troubleshooting `@nxgt/mail-resend`
+
+Each entry is headed by the message you see. Search this page for the words of
+your message.
+
+How the messages are shaped:
+
+- **A message names where the problem is, never the value.** Never the key,
+  an address, a subject or what Resend said: Resend's answer is on the
+  error's `cause` — `status`, `errorName`, and its own message as `detail`.
+- **Every message starts with the call you wrote**: `send: …` or
+  `createResendMailer: …`.
+- **A `TypeError` is a wiring mistake**, thrown by `createResendMailer` when
+  the application starts. Fix the code; no handler should answer one.
+- **A `MailError` is a refusal at call time**: a `MailFailure`
+  (`MAIL_FAILED`) or a `MailRefused` (`MAIL_REFUSED`), the classes of the
+  `@nxgt/mail` peer.
+
+A `send: …` message not on this page comes from `checkMessage` in
+`@nxgt/mail` — a message no transport hands over. See
+[its troubleshooting](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/troubleshooting.md#sending).
+
+## Index
+
+**Sending**
+- [`send: Resend refused the message`](#send-resend-refused-the-message)
+- [`send: Resend could not take the message`](#send-resend-could-not-take-the-message)
+- [`send: Resend could not be reached`](#send-resend-could-not-be-reached)
+- [`send: Resend did not answer within <timeoutMs> ms`](#send-resend-did-not-answer-within-timeoutms-ms)
+- [`send: from is missing — give the message a from, or createResendMailer a default one`](#send-from-is-missing--give-the-message-a-from-or-createresendmailer-a-default-one)
+- [`Resend answered <status> <name>`](#resend-answered-status-name)
+
+**Wiring**
+- [`createResendMailer: options must be an object, as { apiKey }`](#createresendmailer-options-must-be-an-object-as--apikey-)
+- [`createResendMailer: apiKey must be a Resend API key — is the environment variable set?`](#createresendmailer-apikey-must-be-a-resend-api-key--is-the-environment-variable-set)
+- [`createResendMailer: apiKey holds whitespace — trim the value it was read from`](#createresendmailer-apikey-holds-whitespace--trim-the-value-it-was-read-from)
+- [`createResendMailer: baseUrl must be an http: or https: URL`](#createresendmailer-baseurl-must-be-an-http-or-https-url)
+- [`createResendMailer: fetch must be a function`](#createresendmailer-fetch-must-be-a-function)
+- [`createResendMailer: timeoutMs must be a positive integer`](#createresendmailer-timeoutms-must-be-a-positive-integer)
+- [`createResendMailer: timeoutMs must be at most 2147483647 — a longer timer fires at once`](#createresendmailer-timeoutms-must-be-at-most-2147483647--a-longer-timer-fires-at-once)
+- [`createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }`](#createresendmailer-from-must-be-an-e-mail-address-as-noreplyexamplecom-or--name-address-)
+
+**Install and types**
+- [`error instanceof MailFailure` is `false`](#error-instanceof-mailfailure-is-false)
+- [`TS2322: Type 'string | undefined' is not assignable to type 'string'.`](#ts2322-type-string--undefined-is-not-assignable-to-type-string)
+- [`TS2322: Type 'string | null' is not assignable to type 'string'.`](#ts2322-type-string--null-is-not-assignable-to-type-string)
+
+## Sending
+
+### `send: Resend refused the message`
+
+A `MailRefused`, code `MAIL_REFUSED`.
+
+**When:** Resend answered `400` or `422`: a field it does not accept — an
+address in a form it refuses, a header it does not allow, a subject too long.
+
+**Why:** Resend will refuse the same message again; retrying it unchanged is
+pointless.
+
+**Fix:** read `cause.errorName` and `cause.detail` — Resend's own words:
+
+```ts
+import { MailRefused } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailRefused && error.cause instanceof Error) {
+		const { status, errorName, detail } = error.cause as Error & {
+			status?: number;
+			errorName?: string | null;
+			detail?: string | null;
+		};
+		console.warn(status, errorName, detail); // 422 validation_error Invalid `to` field. …
+	}
+	throw error;
+}
+```
+
+`detail` may quote an address: keep it out of logs that must not hold one.
+
+### `send: Resend could not take the message`
+
+A `MailFailure`, code `MAIL_FAILED`. **Nothing is known to have been sent**:
+Resend answered that it did not take the message, but a `5xx` can come from
+a server that accepted it before failing.
+
+**When:** Resend answered with a status that is neither `2xx` nor a refusal:
+
+| `cause.status` | Usually | Fix |
+| --- | --- | --- |
+| `401` | No key reached Resend | Check the key the process was started with |
+| `403` | An invalid or revoked key; a sending domain not verified; a test key sending to someone else than the account's owner | Check the key, and verify the `from` domain in Resend |
+| `429` | The rate limit or the daily quota | Send less often, or from a queue that spaces the sends |
+| `5xx` | Resend is failing | Retry later |
+
+The transport does not retry: a retry is yours to decide, where you can see
+it.
+
+### `send: Resend could not be reached`
+
+A `MailFailure`. **Nothing is known to have been sent**: a connection that
+dropped after the request left may have delivered it to Resend.
+
+**When:** `fetch` threw before any answer: DNS, a refused connection, TLS, a
+proxy in the way, or a `baseUrl` pointing nowhere. `cause` is the `fetch`
+error.
+
+**Fix:** check the network from the process's host
+(`curl -I https://api.resend.com`), and `baseUrl` if you set one.
+
+### `send: Resend did not answer within <timeoutMs> ms`
+
+A `MailFailure`. `cause` is the `TimeoutError` that aborted the request.
+
+**When:** no answer within `timeoutMs` (30 seconds by default) — whatever
+`fetch` is used: one that ignores the signal is no longer waited for.
+
+**Why:** the request was aborted: Resend may still have accepted the e-mail,
+but the transport cannot know, and does not say it was sent.
+
+**Fix:** a slow network or a slow proxy — raise `timeoutMs`, or retry later.
+Before retrying, weigh that the first send may have gone through.
+
+### `send: from is missing — give the message a from, or createResendMailer a default one`
+
+A `MailRefused`, thrown before any request.
+
+**When:** the message has no `from`, and the mailer was created without one.
+
+**Fix:** give the mailer a default sender, or the message its own:
+
+```ts
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({
+	apiKey: process.env.RESEND_API_KEY ?? '',
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+```
+
+### `Resend answered <status> <name>`
+
+The message of the `cause` of a `MailRefused` or a `MailFailure` — for
+example `Resend answered 422 validation_error`, or `Resend answered 503` when
+the body named no error. See the entry of the error it is the cause of,
+above; `cause.detail` holds Resend's own message.
+
+## Wiring
+
+### `createResendMailer: options must be an object, as { apiKey }`
+
+A `TypeError`. `createResendMailer` was called with nothing, or with the key
+itself:
+
+```ts
+createResendMailer(process.env.RESEND_API_KEY ?? ''); // ✗
+createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '' }); // ✓
+```
+
+### `createResendMailer: apiKey must be a Resend API key — is the environment variable set?`
+
+A `TypeError`. `apiKey` is missing, empty or blank — most often an environment
+variable that is not set where the process runs. The value is never printed.
+
+**Fix:** set `RESEND_API_KEY` for that process (a deployment's secrets, a
+`.env` the process actually loads).
+
+### `createResendMailer: apiKey holds whitespace — trim the value it was read from`
+
+A `TypeError`. The key holds a space or a line break — a key read from a file
+or a secret mount keeps its final line break. Sent as is, every request would
+fail.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { createResendMailer } from '@nxgt/mail-resend';
+
+const mailer = createResendMailer({ apiKey: readFileSync('/run/secrets/resend', 'utf8').trim() });
+```
+
+### `createResendMailer: baseUrl must be an http: or https: URL`
+
+A `TypeError`. `baseUrl` is not a string, or has no scheme:
+
+```ts
+createResendMailer({ apiKey, baseUrl: 'api.resend.com' }); // ✗
+createResendMailer({ apiKey, baseUrl: 'https://api.resend.com' }); // ✓ — the default
+```
+
+### `createResendMailer: fetch must be a function`
+
+A `TypeError`. `fetch` was given something that is not a function — a URL, or
+an agent meant for another option. Pass a function `(url, init) =>
+Promise<Response>`, or leave it out for the global `fetch`.
+
+### `createResendMailer: timeoutMs must be a positive integer`
+
+A `TypeError`. `timeoutMs` is `0`, negative, a fraction or not a number. It is
+milliseconds: `10_000` for ten seconds.
+
+### `createResendMailer: timeoutMs must be at most 2147483647 — a longer timer fires at once`
+
+A `TypeError`. `timeoutMs` is above 2³¹ − 1 milliseconds, about 24.8 days —
+often a value in microseconds, or a duration meant as "never". A timer that
+long fires at once, and every send would time out.
+
+**Fix:** a timeout in milliseconds, far below the bound; leave it out for the
+default, 30 seconds:
+
+```ts
+createResendMailer({ apiKey, timeoutMs: Number.MAX_SAFE_INTEGER }); // ✗
+createResendMailer({ apiKey, timeoutMs: 60_000 }); // ✓ — one minute
+```
+
+### `createResendMailer: from must be an e-mail address, as noreply@example.com or { name, address }`
+
+A `TypeError`. The default `from` is not an address. Most often, a name
+written inside the string:
+
+```ts
+createResendMailer({ apiKey, from: 'Acme <noreply@acme.test>' }); // ✗
+createResendMailer({ apiKey, from: { name: 'Acme', address: 'noreply@acme.test' } }); // ✓
+```
+
+## Install and types
+
+### `error instanceof MailFailure` is `false`
+
+Two copies of `@nxgt/mail` are installed, and the transport throws the other
+one's class. `@nxgt/mail` is a **peer** of this package: list it in your own
+`package.json`, in a range this package accepts, and install again. `bun pm ls
+@nxgt/mail` (or `npm ls @nxgt/mail`) should show one version.
+
+### `TS2322: Type 'string | undefined' is not assignable to type 'string'.`
+
+On `apiKey: process.env.RESEND_API_KEY`. Decide what an unset variable means
+where you read it; `?? ''` makes it a `TypeError` at start-up:
+
+```ts
+const mailer = createResendMailer({ apiKey: process.env.RESEND_API_KEY ?? '' });
+```
+
+### `TS2322: Type 'string | null' is not assignable to type 'string'.`
+
+`messageId` is `string | null`: an answer may carry no id, and an absence is
+`null`. Decide what an absent id means where you read it:
+
+```ts
+const { messageId } = await mailer.send(message);
+const reference = messageId ?? 'none';
+```

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@nxgt/mail-resend",
+	"version": "0.1.0",
+	"description": "A Resend transport for @nxgt/mail over fetch, with no SDK: it throws the MailFailure and MailRefused of its @nxgt/mail peer, and passes the conformance suite.",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json",
+		"LICENSE"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"keywords": [
+		"email",
+		"transactional",
+		"mailer",
+		"resend",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-mail.git",
+		"directory": "packages/mail-resend"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"test": "bun test src",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@nxgt/mail": "0.1.0",
+		"@types/bun": "^1.4.2"
+	},
+	"peerDependencies": {
+		"@nxgt/mail": "^0.1.0",
+		"typescript": "^6.0.3"
+	}
+}