@nxgt/mail-smtp 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,190 @@
+# @nxgt/mail-smtp
+
+An SMTP transport for [`@nxgt/mail`](https://github.com/softistx/nxgt-mail/tree/develop/packages/mail),
+on the [`nodemailer`](https://nodemailer.com) you install and configure. 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 real local SMTP server.
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport({
+		host: 'smtp.example.com',
+		port: 587,
+		auth: { user: 'acme', pass: process.env.SMTP_PASSWORD },
+	}),
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+
+const { messageId } = await mailer.send({
+	to: 'ada@example.com',
+	subject: 'Confirm your address',
+	html: '<p>…</p>',
+	text: '…',
+}); // '<…@acme.test>' — or it throws
+```
+
+> **0.x.** A minor version may still change the surface; the changelog says how.
+
+## Install
+
+```sh
+bun add @nxgt/mail-smtp @nxgt/mail nodemailer
+```
+
+Peers, all required:
+
+- `@nxgt/mail` — the port and the errors. One copy in your tree, so
+  `error instanceof MailFailure` holds.
+- `nodemailer` (`>=7 <11`; tested with 10). This package never imports it:
+  you create the transporter, with every SMTP option nodemailer has.
+- `typescript` (6). Bundler resolution (`"moduleResolution": "bundler"`) is
+  what is supported and tested; `nodenext` is out of contract.
+
+## Exports
+
+| Export | What it is |
+| --- | --- |
+| `createSmtpMailer(options)` | A `Mailer` that hands each message to your nodemailer transporter |
+| `SmtpMailerOptions` | `{ transporter, from? }` |
+| `SmtpTransporter` | The part of a nodemailer transporter it calls: `sendMail` |
+| `SmtpSentInfo` | What `sendMail` resolves with: the id, and the recipients refused while others were accepted |
+
+## Usage
+
+### Options
+
+| Option | Type | Default | |
+| --- | --- | --- | --- |
+| `transporter` | `SmtpTransporter` | required | What `nodemailer.createTransport(…)` answers, configured by you |
+| `from` | `Address` | none | The sender of a message that names none |
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+// An SMTP URL works as well as an options object.
+const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport(process.env.SMTP_URL ?? 'smtp://localhost:1025'),
+});
+
+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',
+	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 handed to nodemailer as `{ name, address }`: nodemailer quotes and
+  encodes it, so `Doe, John` names one recipient.
+- `messageId` is nodemailer's id (`<…@host>`), or `null` when it gives none.
+- The parts are strings: nodemailer is told never to read a file or a URL
+  (`disableFileAccess`, `disableUrlAccess`).
+
+### Errors — a refusal or a failure
+
+| When | Throws | `cause` |
+| --- | --- | --- |
+| The server cannot be reached, a timeout, a `4xx` (try later), credentials refused (`530`–`539`), the sender refused (`5xx` on `MAIL FROM`) | `MailFailure` — `send: the SMTP server could not take the message` | nodemailer's error, with its `code` and `responseCode` |
+| A permanent `5xx` on every recipient or on the content (`550`, `552` too large, `554`) | `MailRefused` — `send: the SMTP server refused the message` | nodemailer's error |
+| Some recipients refused, the others accepted — **they may have the message** | `MailRefused` — `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others` — or `MailFailure` — `send: the SMTP server could not take <n> of <total> recipients, …` when a refusal is not permanent, or nodemailer gives no reason | nodemailer's error for the first refused recipient |
+| No sender, on the message or as a default | `MailRefused` — `send: from is missing — give the message a from, or createSmtpMailer a default one` | — |
+| A bad option | `TypeError` from `createSmtpMailer` | — |
+
+```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: retry later, from a queue you can see
+	}
+	throw error;
+}
+```
+
+A message reports a shape, never a value: no address, no password, no
+server answer. What the server said is on `cause`. 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 against a real server, see [Testing](docs/guide/testing.md):
+a local `smtp-server`, `mailparser` to read back what arrived, and
+`describeMailer`.
+
+## Traps
+
+**Close a pooled transporter when the process stops.** With `pool: true`,
+nodemailer keeps connections open: call `transporter.close()` on shutdown.
+
+**nodemailer's timeouts are yours to set.** It waits up to two minutes for a
+connection by default; a send in a request handler should not. Set
+`connectionTimeout`, `greetingTimeout` and `socketTimeout` on the transporter.
+A timeout ends in `MailFailure`.
+
+**A `4xx` is a failure, a `5xx` a refusal** — except authentication (`530`–
+`539`) and a sender refused at `MAIL FROM`: the next message would be refused
+the same way, so it is a failure of the wiring, not of the message.
+
+**Some recipients refused still throws, after the others got it.** The
+server may accept one recipient and refuse another; the message then went out
+to the accepted one. Retrying it whole sends it to them twice — send to one
+recipient per `send` when every result must be all or nothing.
+
+**A custom header cannot set an address.** `headers: { Bcc: '…' }` would add
+an envelope recipient no check saw: `checkMessage` refuses `To`, `Cc`, `Bcc`,
+`From`, `Sender`, `Reply-To`, `Return-Path`, `Subject`, `MIME-Version` and
+`Content-*` in `headers`, in any case.
+
+**A string address is only an address.** `'Acme <noreply@acme.test>'` as
+`from` is a `TypeError` at wiring and a `MailRefused` on a message; write
+`{ name: 'Acme', address: 'noreply@acme.test' }`. A string holding whitespace,
+`,`, `;` or `:` is refused too, and nodemailer is handed every address as
+`{ name, address }`, so it never parses one.
+
+## Type safety, counted
+
+**6 plausible mistakes, 6 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-smtp/test/types/refusals.ts)
+that fails the typecheck the moment it stops holding:
+
+1. No `transporter`.
+2. nodemailer's options (`{ host, port }`) as the transporter, instead of what
+   `createTransport` answers.
+3. The SMTP options given to `createSmtpMailer` itself.
+4. A default `from` without its `address`.
+5. A `retries` option: the transport tries once.
+6. `messageId` read as a `string`: it is `string | null`.
+
+The same file holds the calls that must keep compiling — among them what
+`nodemailer.createTransport` answers, from options or a URL, with no cast.
+
+## Documentation
+
+- [The guides](docs/README.md) — setting up nodemailer, 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,64 @@
+/**
+ * `@nxgt/mail-smtp` — an SMTP transport for `@nxgt/mail`, on the `nodemailer`
+ * the application installs and configures.
+ *
+ * ```ts
+ * import nodemailer from 'nodemailer';
+ * import { createSmtpMailer } from '@nxgt/mail-smtp';
+ *
+ * const mailer = createSmtpMailer({
+ *   transporter: nodemailer.createTransport({ host, port: 587, auth }),
+ *   from: { name: 'Acme', address: 'noreply@acme.test' },
+ * });
+ * ```
+ *
+ * **A failure throws** the `MailFailure` or `MailRefused` of the `@nxgt/mail`
+ * peer, nodemailer's error as the `cause`. Nothing is retried.
+ */
+import { type Address, type Mailer } from '@nxgt/mail';
+/**
+ * An address as nodemailer takes it: always an object, so nodemailer never
+ * parses a string — it quotes and encodes the name itself.
+ */
+type NodemailerAddress = {
+    name: string;
+    address: string;
+};
+/**
+ * What nodemailer answers once the server took the message: its id, and the
+ * recipients it refused while accepting others — nodemailer resolves then.
+ */
+export interface SmtpSentInfo {
+    readonly messageId?: string;
+    readonly accepted?: readonly unknown[] | undefined;
+    readonly rejected?: readonly unknown[] | undefined;
+    /** One nodemailer error per refused recipient, with its `responseCode`. */
+    readonly rejectedErrors?: readonly unknown[] | undefined;
+}
+/**
+ * The part of a nodemailer transporter this transport calls — what
+ * `nodemailer.createTransport(…)` answers, from nodemailer 7 on.
+ */
+export interface SmtpTransporter {
+    sendMail(mail: {
+        from: NodemailerAddress;
+        to: NodemailerAddress[];
+        replyTo?: NodemailerAddress;
+        subject: string;
+        html: string;
+        text: string;
+        headers?: Record<string, string>;
+        disableFileAccess: boolean;
+        disableUrlAccess: boolean;
+    }): Promise<SmtpSentInfo>;
+}
+export interface SmtpMailerOptions {
+    /** `nodemailer.createTransport(…)`, configured by the application. */
+    readonly transporter: SmtpTransporter;
+    /** The sender of a message that names none. Without it, such a message is refused. */
+    readonly from?: Address;
+}
+/** Creates a {@link Mailer} that hands each message to `transporter`. */
+export declare function createSmtpMailer(options: SmtpMailerOptions): Mailer;
+export {};
+//# 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;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACN,KAAK,OAAO,EAEZ,KAAK,MAAM,EAKX,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,KAAK,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;IACnD,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,CAAC;CACzD;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,IAAI,EAAE;QACd,IAAI,EAAE,iBAAiB,CAAC;QACxB,EAAE,EAAE,iBAAiB,EAAE,CAAC;QACxB,OAAO,CAAC,EAAE,iBAAiB,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,iBAAiB,EAAE,OAAO,CAAC;QAC3B,gBAAgB,EAAE,OAAO,CAAC;KAC1B,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,sFAAsF;IACtF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACxB;AA+ED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CA4EnE"}

package/dist/index.js

@@ -0,0 +1,93 @@
+// src/index.ts
+import {
+  checkMessage,
+  MailFailure,
+  MailRefused
+} from "@nxgt/mail";
+var toNodemailer = (address) => typeof address === "string" ? { name: "", address } : { name: address.name, address: address.address };
+var fieldsOf = (error) => typeof error === "object" && error !== null ? error : {};
+function isPermanentRefusal(error) {
+  const { code, responseCode, command } = fieldsOf(error);
+  return (code === "EENVELOPE" || code === "EMESSAGE") && command !== "MAIL FROM" && typeof responseCode === "number" && responseCode >= 500 && responseCode < 600 && (responseCode < 530 || responseCode > 539);
+}
+function isRefusal(error) {
+  const { rejectedErrors } = fieldsOf(error);
+  if (Array.isArray(rejectedErrors) && rejectedErrors.length > 0) {
+    return rejectedErrors.every(isPermanentRefusal);
+  }
+  return isPermanentRefusal(error);
+}
+function throwOnPartialRejection(info) {
+  const errors = Array.isArray(info.rejectedErrors) ? info.rejectedErrors : [];
+  const rejected = Array.isArray(info.rejected) ? info.rejected : [];
+  const refusedCount = Math.max(errors.length, rejected.length);
+  if (refusedCount === 0)
+    return;
+  const accepted = Array.isArray(info.accepted) ? info.accepted.length : 0;
+  const counted = `${refusedCount} of ${refusedCount + accepted} recipients`;
+  const cause = errors[0] ?? Object.assign(new Error("the SMTP server refused some recipients"), {
+    rejected
+  });
+  if (errors.length > 0 && errors.every(isPermanentRefusal)) {
+    throw new MailRefused(`send: the SMTP server refused ${counted}, and may have delivered to the others`, { cause });
+  }
+  throw new MailFailure(`send: the SMTP server could not take ${counted}, and may have delivered to the others`, { cause });
+}
+function createSmtpMailer(options) {
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("createSmtpMailer: options must be an object, as { transporter }");
+  }
+  const { transporter, from } = options;
+  if (typeof transporter !== "object" || transporter === null || typeof transporter.sendMail !== "function") {
+    throw new TypeError("createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers");
+  }
+  if (from !== undefined) {
+    try {
+      checkMessage({ to: from, subject: "", html: "", text: "" });
+    } catch {
+      throw new TypeError("createSmtpMailer: from must be an e-mail address, as noreply@example.com or { name, address }");
+    }
+  }
+  return {
+    async send(message) {
+      checkMessage(message);
+      const sender = message.from ?? from;
+      if (sender === undefined) {
+        throw new MailRefused("send: from is missing — give the message a from, or createSmtpMailer a default one");
+      }
+      const to = Array.isArray(message.to) ? message.to : [message.to];
+      let info;
+      try {
+        info = await transporter.sendMail({
+          from: toNodemailer(sender),
+          to: to.map(toNodemailer),
+          ...message.replyTo === undefined ? {} : { replyTo: toNodemailer(message.replyTo) },
+          subject: message.subject,
+          html: message.html,
+          text: message.text,
+          ...message.headers === undefined ? {} : { headers: { ...message.headers } },
+          disableFileAccess: true,
+          disableUrlAccess: true
+        });
+      } catch (error) {
+        if (isRefusal(error)) {
+          throw new MailRefused("send: the SMTP server refused the message", {
+            cause: error
+          });
+        }
+        throw new MailFailure("send: the SMTP server could not take the message", {
+          cause: error
+        });
+      }
+      throwOnPartialRejection(info ?? {});
+      const messageId = typeof info?.messageId === "string" && info.messageId !== "" ? info.messageId : null;
+      return { messageId };
+    }
+  };
+}
+export {
+  createSmtpMailer
+};
+
+//# debugId=748DA33D57D71AF564756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * `@nxgt/mail-smtp` — an SMTP transport for `@nxgt/mail`, on the `nodemailer`\n * the application installs and configures.\n *\n * ```ts\n * import nodemailer from 'nodemailer';\n * import { createSmtpMailer } from '@nxgt/mail-smtp';\n *\n * const mailer = createSmtpMailer({\n *   transporter: nodemailer.createTransport({ host, port: 587, auth }),\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, nodemailer's error 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\n/**\n * An address as nodemailer takes it: always an object, so nodemailer never\n * parses a string — it quotes and encodes the name itself.\n */\ntype NodemailerAddress = { name: string; address: string };\n\n/**\n * What nodemailer answers once the server took the message: its id, and the\n * recipients it refused while accepting others — nodemailer resolves then.\n */\nexport interface SmtpSentInfo {\n\treadonly messageId?: string;\n\treadonly accepted?: readonly unknown[] | undefined;\n\treadonly rejected?: readonly unknown[] | undefined;\n\t/** One nodemailer error per refused recipient, with its `responseCode`. */\n\treadonly rejectedErrors?: readonly unknown[] | undefined;\n}\n\n/**\n * The part of a nodemailer transporter this transport calls — what\n * `nodemailer.createTransport(…)` answers, from nodemailer 7 on.\n */\nexport interface SmtpTransporter {\n\tsendMail(mail: {\n\t\tfrom: NodemailerAddress;\n\t\tto: NodemailerAddress[];\n\t\treplyTo?: NodemailerAddress;\n\t\tsubject: string;\n\t\thtml: string;\n\t\ttext: string;\n\t\theaders?: Record<string, string>;\n\t\tdisableFileAccess: boolean;\n\t\tdisableUrlAccess: boolean;\n\t}): Promise<SmtpSentInfo>;\n}\n\nexport interface SmtpMailerOptions {\n\t/** `nodemailer.createTransport(…)`, configured by the application. */\n\treadonly transporter: SmtpTransporter;\n\t/** The sender of a message that names none. Without it, such a message is refused. */\n\treadonly from?: Address;\n}\n\nconst toNodemailer = (address: Address): NodemailerAddress =>\n\ttypeof address === 'string'\n\t\t? { name: '', address }\n\t\t: { name: address.name, address: address.address };\n\ninterface SmtpError {\n\treadonly code?: unknown;\n\treadonly responseCode?: unknown;\n\treadonly command?: unknown;\n\treadonly message?: unknown;\n\treadonly rejectedErrors?: unknown;\n}\n\nconst fieldsOf = (error: unknown): SmtpError =>\n\ttypeof error === 'object' && error !== null ? (error as SmtpError) : {};\n\n/**\n * Whether one nodemailer error is the server refusing **this message** for\n * good — a permanent `5xx` on a recipient or on the content (`552` for a\n * message too large) — rather\n * than the server, the network or the wiring failing. Two `5xx` are\n * failures: authentication (`530`–`539`), and a sender refused at\n * `MAIL FROM` — the next message would be refused the same way.\n */\nfunction isPermanentRefusal(error: unknown): boolean {\n\tconst { code, responseCode, command } = fieldsOf(error);\n\treturn (\n\t\t(code === 'EENVELOPE' || code === 'EMESSAGE') &&\n\t\tcommand !== 'MAIL FROM' &&\n\t\ttypeof responseCode === 'number' &&\n\t\tresponseCode >= 500 &&\n\t\tresponseCode < 600 &&\n\t\t(responseCode < 530 || responseCode > 539)\n\t);\n}\n\n/**\n * Whether a rejected send is a refusal of the message. When every recipient\n * was refused, nodemailer's error carries the code of the **last** one only:\n * each refusal is read instead, and it is a refusal only if every one is.\n */\nfunction isRefusal(error: unknown): boolean {\n\tconst { rejectedErrors } = fieldsOf(error);\n\tif (Array.isArray(rejectedErrors) && rejectedErrors.length > 0) {\n\t\treturn rejectedErrors.every(isPermanentRefusal);\n\t}\n\treturn isPermanentRefusal(error);\n}\n\n/**\n * Throws when nodemailer resolved with some recipients refused: the server\n * took the message for the others, so it may already have reached them.\n */\nfunction throwOnPartialRejection(info: SmtpSentInfo): void {\n\tconst errors = Array.isArray(info.rejectedErrors) ? info.rejectedErrors : [];\n\tconst rejected = Array.isArray(info.rejected) ? info.rejected : [];\n\tconst refusedCount = Math.max(errors.length, rejected.length);\n\tif (refusedCount === 0) return;\n\tconst accepted = Array.isArray(info.accepted) ? info.accepted.length : 0;\n\tconst counted = `${refusedCount} of ${refusedCount + accepted} recipients`;\n\tconst cause =\n\t\terrors[0] ??\n\t\tObject.assign(new Error('the SMTP server refused some recipients'), {\n\t\t\trejected,\n\t\t});\n\tif (errors.length > 0 && errors.every(isPermanentRefusal)) {\n\t\tthrow new MailRefused(\n\t\t\t`send: the SMTP server refused ${counted}, and may have delivered to the others`,\n\t\t\t{ cause },\n\t\t);\n\t}\n\tthrow new MailFailure(\n\t\t`send: the SMTP server could not take ${counted}, and may have delivered to the others`,\n\t\t{ cause },\n\t);\n}\n\n/** Creates a {@link Mailer} that hands each message to `transporter`. */\nexport function createSmtpMailer(options: SmtpMailerOptions): Mailer {\n\tif (typeof options !== 'object' || options === null) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: options must be an object, as { transporter }',\n\t\t);\n\t}\n\tconst { transporter, from } = options;\n\tif (\n\t\ttypeof transporter !== 'object' ||\n\t\ttransporter === null ||\n\t\ttypeof transporter.sendMail !== 'function'\n\t) {\n\t\tthrow new TypeError(\n\t\t\t'createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers',\n\t\t);\n\t}\n\tif (from !== undefined) {\n\t\t// Checked once, as the message's own sender is: a wiring mistake.\n\t\ttry {\n\t\t\tcheckMessage({ to: from, subject: '', html: '', text: '' });\n\t\t} catch {\n\t\t\tthrow new TypeError(\n\t\t\t\t'createSmtpMailer: 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\treturn {\n\t\tasync send(message: MailMessage): Promise<SentMail> {\n\t\t\tcheckMessage(message);\n\t\t\tconst sender = message.from ?? 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 createSmtpMailer 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\tlet info: SmtpSentInfo;\n\t\t\ttry {\n\t\t\t\tinfo = await transporter.sendMail({\n\t\t\t\t\tfrom: toNodemailer(sender),\n\t\t\t\t\tto: to.map(toNodemailer),\n\t\t\t\t\t...(message.replyTo === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { replyTo: toNodemailer(message.replyTo) }),\n\t\t\t\t\tsubject: message.subject,\n\t\t\t\t\thtml: message.html,\n\t\t\t\t\ttext: message.text,\n\t\t\t\t\t...(message.headers === undefined\n\t\t\t\t\t\t? {}\n\t\t\t\t\t\t: { headers: { ...message.headers } }),\n\t\t\t\t\t// The parts are strings: nothing is ever read from a file or a URL.\n\t\t\t\t\tdisableFileAccess: true,\n\t\t\t\t\tdisableUrlAccess: true,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (isRefusal(error)) {\n\t\t\t\t\tthrow new MailRefused('send: the SMTP server refused the message', {\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tthrow new MailFailure(\n\t\t\t\t\t'send: the SMTP server could not take the message',\n\t\t\t\t\t{\n\t\t\t\t\t\tcause: error,\n\t\t\t\t\t},\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrowOnPartialRejection(info ?? {});\n\t\t\tconst messageId =\n\t\t\t\ttypeof info?.messageId === 'string' && info.messageId !== ''\n\t\t\t\t\t? info.messageId\n\t\t\t\t\t: null;\n\t\t\treturn { messageId };\n\t\t},\n\t};\n}\n"
+  ],
+  "mappings": ";AAkBA;AAAA;AAAA;AAAA;AAAA;AAqDA,IAAM,eAAe,CAAC,YACrB,OAAO,YAAY,WAChB,EAAE,MAAM,IAAI,QAAQ,IACpB,EAAE,MAAM,QAAQ,MAAM,SAAS,QAAQ,QAAQ;AAUnD,IAAM,WAAW,CAAC,UACjB,OAAO,UAAU,YAAY,UAAU,OAAQ,QAAsB,CAAC;AAUvE,SAAS,kBAAkB,CAAC,OAAyB;AAAA,EACpD,QAAQ,MAAM,cAAc,YAAY,SAAS,KAAK;AAAA,EACtD,QACE,SAAS,eAAe,SAAS,eAClC,YAAY,eACZ,OAAO,iBAAiB,YACxB,gBAAgB,OAChB,eAAe,QACd,eAAe,OAAO,eAAe;AAAA;AASxC,SAAS,SAAS,CAAC,OAAyB;AAAA,EAC3C,QAAQ,mBAAmB,SAAS,KAAK;AAAA,EACzC,IAAI,MAAM,QAAQ,cAAc,KAAK,eAAe,SAAS,GAAG;AAAA,IAC/D,OAAO,eAAe,MAAM,kBAAkB;AAAA,EAC/C;AAAA,EACA,OAAO,mBAAmB,KAAK;AAAA;AAOhC,SAAS,uBAAuB,CAAC,MAA0B;AAAA,EAC1D,MAAM,SAAS,MAAM,QAAQ,KAAK,cAAc,IAAI,KAAK,iBAAiB,CAAC;AAAA,EAC3E,MAAM,WAAW,MAAM,QAAQ,KAAK,QAAQ,IAAI,KAAK,WAAW,CAAC;AAAA,EACjE,MAAM,eAAe,KAAK,IAAI,OAAO,QAAQ,SAAS,MAAM;AAAA,EAC5D,IAAI,iBAAiB;AAAA,IAAG;AAAA,EACxB,MAAM,WAAW,MAAM,QAAQ,KAAK,QAAQ,IAAI,KAAK,SAAS,SAAS;AAAA,EACvE,MAAM,UAAU,GAAG,mBAAmB,eAAe;AAAA,EACrD,MAAM,QACL,OAAO,MACP,OAAO,OAAO,IAAI,MAAM,yCAAyC,GAAG;AAAA,IACnE;AAAA,EACD,CAAC;AAAA,EACF,IAAI,OAAO,SAAS,KAAK,OAAO,MAAM,kBAAkB,GAAG;AAAA,IAC1D,MAAM,IAAI,YACT,iCAAiC,iDACjC,EAAE,MAAM,CACT;AAAA,EACD;AAAA,EACA,MAAM,IAAI,YACT,wCAAwC,iDACxC,EAAE,MAAM,CACT;AAAA;AAIM,SAAS,gBAAgB,CAAC,SAAoC;AAAA,EACpE,IAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AAAA,IACpD,MAAM,IAAI,UACT,iEACD;AAAA,EACD;AAAA,EACA,QAAQ,aAAa,SAAS;AAAA,EAC9B,IACC,OAAO,gBAAgB,YACvB,gBAAgB,QAChB,OAAO,YAAY,aAAa,YAC/B;AAAA,IACD,MAAM,IAAI,UACT,kFACD;AAAA,EACD;AAAA,EACA,IAAI,SAAS,WAAW;AAAA,IAEvB,IAAI;AAAA,MACH,aAAa,EAAE,IAAI,MAAM,SAAS,IAAI,MAAM,IAAI,MAAM,GAAG,CAAC;AAAA,MACzD,MAAM;AAAA,MACP,MAAM,IAAI,UACT,+FACD;AAAA;AAAA,EAEF;AAAA,EAEA,OAAO;AAAA,SACA,KAAI,CAAC,SAAyC;AAAA,MACnD,aAAa,OAAO;AAAA,MACpB,MAAM,SAAS,QAAQ,QAAQ;AAAA,MAC/B,IAAI,WAAW,WAAW;AAAA,QACzB,MAAM,IAAI,YACT,oFACD;AAAA,MACD;AAAA,MACA,MAAM,KAAK,MAAM,QAAQ,QAAQ,EAAE,IAAI,QAAQ,KAAK,CAAC,QAAQ,EAAE;AAAA,MAC/D,IAAI;AAAA,MACJ,IAAI;AAAA,QACH,OAAO,MAAM,YAAY,SAAS;AAAA,UACjC,MAAM,aAAa,MAAM;AAAA,UACzB,IAAI,GAAG,IAAI,YAAY;AAAA,aACnB,QAAQ,YAAY,YACrB,CAAC,IACD,EAAE,SAAS,aAAa,QAAQ,OAAO,EAAE;AAAA,UAC5C,SAAS,QAAQ;AAAA,UACjB,MAAM,QAAQ;AAAA,UACd,MAAM,QAAQ;AAAA,aACV,QAAQ,YAAY,YACrB,CAAC,IACD,EAAE,SAAS,KAAK,QAAQ,QAAQ,EAAE;AAAA,UAErC,mBAAmB;AAAA,UACnB,kBAAkB;AAAA,QACnB,CAAC;AAAA,QACA,OAAO,OAAO;AAAA,QACf,IAAI,UAAU,KAAK,GAAG;AAAA,UACrB,MAAM,IAAI,YAAY,6CAA6C;AAAA,YAClE,OAAO;AAAA,UACR,CAAC;AAAA,QACF;AAAA,QACA,MAAM,IAAI,YACT,oDACA;AAAA,UACC,OAAO;AAAA,QACR,CACD;AAAA;AAAA,MAED,wBAAwB,QAAQ,CAAC,CAAC;AAAA,MAClC,MAAM,YACL,OAAO,MAAM,cAAc,YAAY,KAAK,cAAc,KACvD,KAAK,YACL;AAAA,MACJ,OAAO,EAAE,UAAU;AAAA;AAAA,EAErB;AAAA;",
+  "debugId": "748DA33D57D71AF564756E2164756E21",
+  "names": []
+}

package/docs/README.md

@@ -0,0 +1,14 @@
+# @nxgt/mail-smtp — 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 `createSmtpMailer` to a nodemailer transporter: host, port and TLS, credentials, a pool, timeouts, the default sender, and what a message becomes on the wire |
+| [Errors](guide/errors.md) | You are handling what `send` throws: which SMTP 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 real SMTP server — `smtp-server`, `mailparser`, `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,142 @@
+# Errors
+
+`send` resolves only once the SMTP server has accepted the message for every
+recipient. 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'`) — the message itself was
+  refused. Sending it again unchanged fails again.
+- **`MailFailure`** (`code: 'MAIL_FAILED'`) — the server could not take it:
+  unreachable, busy, or the credentials refused. Nothing is known to have
+  been sent — after a timeout or a dropped connection the server may have
+  taken it all the same — and a later attempt may work.
+
+One exception to "nothing sent" in either class: when the server refused
+some recipients and accepted the others, `send` throws, and the accepted
+recipients may already have the message. The message says so
+([below](#some-recipients-refused)); retrying it whole sends it to them again.
+
+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 SMTP answer is which
+
+nodemailer rejects with an error carrying a `code` (`ECONNECTION`, `ESOCKET`,
+`ETIMEDOUT`, `EAUTH`, `EENVELOPE`, `EMESSAGE`…) and, when the server answered,
+a `responseCode`. The transport reads both:
+
+| What happened | nodemailer's error | Throws |
+| --- | --- | --- |
+| The server cannot be reached, the connection drops, a timeout | `ECONNECTION`, `ESOCKET`, `ETIMEDOUT` | `MailFailure` |
+| The server closes the door (`421`), is busy or refuses for now (`4xx`) | any, with a `4xx` | `MailFailure` |
+| Credentials refused (`535`), authentication required (`530`) | `EAUTH`, or `EENVELOPE` with `530`–`539` | `MailFailure` |
+| The sender refused (`550`, `553` on `MAIL FROM`) | `EENVELOPE` with a `5xx` and `command: 'MAIL FROM'` | `MailFailure` |
+| A recipient refused for good (`550`, `553`) | `EENVELOPE` with a `5xx` | `MailRefused` |
+| Every recipient refused | `EENVELOPE`, one error per recipient on `rejectedErrors` | `MailRefused` if every one is a permanent `5xx` (not `530`–`539`), else `MailFailure` |
+| The content refused for good (`552` too large, `554` rejected) | `EMESSAGE` with a `5xx` | `MailRefused` |
+| Anything else | — | `MailFailure` |
+
+Two `5xx` are failures: authentication, and a sender refused at
+`MAIL FROM`. The next message would be refused the same way, whatever it
+holds: it is the wiring — the credentials, the sender, the host — that is
+wrong, not the message.
+
+When every recipient is refused, nodemailer's error carries the code of the
+last one only. The transport reads each of `rejectedErrors` instead: a `450`
+on one and a `550` on another is a `MailFailure`, whichever came last.
+
+## Some recipients refused
+
+nodemailer **resolves** when the server refuses some recipients and accepts
+the others: the message went out to the accepted ones. The transport throws
+all the same — a send that did not reach every recipient did not do what was
+asked — with a message that counts the refusals:
+
+| Every refusal a permanent `5xx` (not `530`–`539`) | Throws |
+| --- | --- |
+| yes | `MailRefused` — `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others` |
+| no, or nodemailer gives no reason | `MailFailure` — `send: the SMTP server could not take <n> of <total> recipients, and may have delivered to the others` |
+
+`cause` is nodemailer's error for the first refused recipient
+(`code: 'EENVELOPE'`, its `responseCode`, and `recipient`). Retrying the
+message as it was sends it again to the recipients who have it: send it to
+the refused ones only, or not at all.
+
+## What `cause` holds
+
+The error is nodemailer's, untouched: read `code`, `responseCode`, `command`
+and `response` from it to log what the server said.
+
+```ts
+import { MailError } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailError) {
+		const cause = error.cause as { code?: string; responseCode?: number };
+		logger.warn({ code: error.code, smtp: cause.code, reply: cause.responseCode }, error.message);
+	}
+	throw error;
+}
+```
+
+An error's `message` reports a shape, never a value: it never holds an
+address, a subject, a password or the server's reply. `cause` is nodemailer's
+error, and **its** message can quote the server, which can quote an address —
+log `cause.code` and `cause.responseCode` rather than the whole error when
+your logs must not hold one.
+
+## The messages
+
+| `message` | Class | When |
+| --- | --- | --- |
+| `send: the SMTP server could not take the message` | `MailFailure` | Every failure in the table above |
+| `send: the SMTP server refused the message` | `MailRefused` | A permanent `5xx` on every recipient or on the content |
+| `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others` | `MailRefused` | Some recipients refused for good, the others accepted |
+| `send: the SMTP server could not take <n> of <total> recipients, and may have delivered to the others` | `MailFailure` | Some recipients refused, one at least for now, the others accepted |
+| `send: from is missing — give the message a from, or createSmtpMailer a default one` | `MailRefused` | A message without `from`, on a mailer without a default. The transporter is not called |
+| `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 `createSmtpMailer` is called, never at the first send:
+
+| `message` | When |
+| --- | --- |
+| `createSmtpMailer: options must be an object, as { transporter }` | `createSmtpMailer()` or `createSmtpMailer(transporter)` |
+| `createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers` | No `transporter`, or one without `sendMail` — nodemailer's options passed instead of the transporter |
+| `createSmtpMailer: 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,209 @@
+# Setting up
+
+`createSmtpMailer` wraps a nodemailer transporter that **you** create: every
+SMTP option — host, port, TLS, credentials, a pool, DKIM, timeouts — is
+nodemailer's, and this package passes none of its own. What it adds is the
+`Mailer` contract of `@nxgt/mail`: the same refusals as every transport, the
+two errors, and no retry.
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+export const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport({
+		host: 'smtp.example.com',
+		port: 587, // STARTTLS; 465 with secure: true
+		auth: { user: 'acme', pass: process.env.SMTP_PASSWORD },
+	}),
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+```
+
+## The signature
+
+```ts
+function createSmtpMailer(options: SmtpMailerOptions): Mailer;
+
+interface SmtpMailerOptions {
+	readonly transporter: SmtpTransporter;
+	readonly from?: Address;
+}
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `transporter` | `SmtpTransporter` | required | Receives every message through `sendMail`. What `nodemailer.createTransport(…)` answers fits, with no cast |
+| `from` | `Address` | none | The sender of a message that has no `from`. Without it, such a message is refused with `MailRefused` |
+
+`SmtpTransporter` is the one method this package calls — so a test can pass a
+hand-written object, and nodemailer is never imported:
+
+```ts
+interface SmtpTransporter {
+	sendMail(mail: {
+		from: { name: string; address: string };
+		to: { name: string; address: string }[];
+		replyTo?: { name: string; address: string };
+		subject: string;
+		html: string;
+		text: string;
+		headers?: Record<string, string>;
+		disableFileAccess: boolean;
+		disableUrlAccess: boolean;
+	}): Promise<SmtpSentInfo>;
+}
+
+// What nodemailer resolves with. `rejected` and `rejectedErrors` are the
+// recipients the server refused while it accepted others: `send` throws then.
+interface SmtpSentInfo {
+	readonly messageId?: string;
+	readonly accepted?: readonly unknown[] | undefined;
+	readonly rejected?: readonly unknown[] | undefined;
+	readonly rejectedErrors?: readonly unknown[] | undefined;
+}
+```
+
+Options are checked when the mailer is created, and a mistake is a bare
+`TypeError` — see [Errors — wiring](errors.md#wiring--a-typeerror).
+
+## The transporter
+
+### From options, or from a URL
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+// Port 465: TLS from the first byte.
+const implicitTls = createSmtpMailer({
+	transporter: nodemailer.createTransport({
+		host: 'smtp.example.com',
+		port: 465,
+		secure: true,
+		auth: { user: 'acme', pass: process.env.SMTP_PASSWORD },
+	}),
+	from: 'noreply@acme.test',
+});
+
+// A URL, as a hosting provider often gives it.
+const fromUrl = createSmtpMailer({
+	transporter: nodemailer.createTransport(process.env.SMTP_URL ?? 'smtp://localhost:1025'),
+	from: 'noreply@acme.test',
+});
+```
+
+### Timeouts
+
+nodemailer waits up to two minutes for a connection and ten for a quiet
+socket. A send awaited in a request handler should give up sooner:
+
+```ts
+import nodemailer from 'nodemailer';
+
+const transporter = nodemailer.createTransport({
+	host: 'smtp.example.com',
+	port: 587,
+	auth: { user: 'acme', pass: process.env.SMTP_PASSWORD },
+	connectionTimeout: 10_000,
+	greetingTimeout: 10_000,
+	socketTimeout: 20_000,
+});
+```
+
+A timeout ends in `MailFailure`, nodemailer's `ETIMEDOUT` or `ESOCKET` error
+as its `cause`.
+
+### A pool
+
+With `pool: true`, nodemailer keeps connections open and sends several messages
+over each. Close it when the process stops, or the process waits for it:
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+const transporter = nodemailer.createTransport({
+	pool: true,
+	maxConnections: 5,
+	host: 'smtp.example.com',
+	port: 587,
+	auth: { user: 'acme', pass: process.env.SMTP_PASSWORD },
+});
+export const mailer = createSmtpMailer({ transporter, from: 'noreply@acme.test' });
+
+process.on('SIGTERM', () => transporter.close());
+```
+
+## 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 the transporter is
+called:
+
+```ts
+import { createSmtpMailer, type SmtpTransporter } from '@nxgt/mail-smtp';
+
+declare const transporter: SmtpTransporter;
+
+const mailer = createSmtpMailer({ transporter, 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: '…',
+});
+```
+
+A string is only an address: `'Acme <noreply@acme.test>'` is refused. Write
+`{ name: 'Acme', address: 'noreply@acme.test' }`.
+
+## What a message becomes
+
+| `MailMessage` | Handed to nodemailer as |
+| --- | --- |
+| `to` — one address or several | `to`, always a list |
+| a string address | `{ name: '', address }`: nodemailer never parses a string, so the address it sends to is the one `checkMessage` checked |
+| an `{ name, address }` | the same object: nodemailer quotes and encodes the name, so `Doe, John` or `Ada <mallory@example.test>` stays one recipient's name |
+| `from`, `replyTo` | `from`, `replyTo` |
+| `subject`, `html`, `text` | the same, as strings — the e-mail is `multipart/alternative` |
+| `headers` | `headers`, copied |
+| — | `disableFileAccess: true`, `disableUrlAccess: true`: a part is never read from a file or fetched from a URL |
+
+Before any of it, `checkMessage` from `@nxgt/mail` refuses what no transport
+hands over — no recipient, something that is not an address, a line break in
+the subject or a header, a custom header that would set an address, the
+subject or the MIME structure (`Bcc`, `To`, `Content-Type`…). 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 }`: nodemailer's `Message-ID` (`<…@acme.test>`), or
+`null` when the transporter answers none — an absence, not a failure.
+
+## With the renderer
+
+What `@nxgt/mail/renderer` answers spreads into the message:
+
+```ts
+import { createMailRenderer } from '@nxgt/mail/renderer';
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+const mails = createMailRenderer({ dir: 'dist' });
+const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport(process.env.SMTP_URL ?? 'smtp://localhost:1025'),
+	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 SMTP server, and the conformance suite.

package/docs/guide/testing.md

@@ -0,0 +1,178 @@
+# Testing
+
+Two different things to test, with two different tools:
+
+- **An application that sends e-mail.** Do not start an SMTP server: 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, against a real SMTP server.** A local
+  [`smtp-server`](https://nodemailer.com/extras/smtp-server/) receives, and
+  [`mailparser`](https://nodemailer.com/extras/mailparser/) reads back what
+  arrived. That is how this package passes `@nxgt/mail/conformance`, and the
+  rest of this page shows it.
+
+```sh
+bun add -d smtp-server mailparser @types/smtp-server @types/mailparser
+```
+
+## A local SMTP server
+
+It keeps what it receives, and fails on demand **the way an SMTP server
+fails** — a `421` for an outage, a `554` for a refusal — so the suite proves
+the transport's reading of nodemailer's errors, not a wrapper's:
+
+```ts
+// smtp-server.ts
+import type { AddressInfo } from 'node:net';
+import type { DeliveredMail } from '@nxgt/mail/conformance';
+import { simpleParser } from 'mailparser';
+import { SMTPServer } from 'smtp-server';
+
+type Fault = 'outage' | 'refusal';
+
+export async function startSmtpServer() {
+	const delivered: DeliveredMail[] = [];
+	const faults: Fault[] = [];
+	let attempts = 0;
+	const reply = (message: string, responseCode: number) => Object.assign(new Error(message), { responseCode });
+
+	const server = new SMTPServer({
+		authOptional: true,
+		disabledCommands: ['STARTTLS'],
+		logger: false,
+		onMailFrom(_address, _session, callback) {
+			attempts += 1; // one hand-over
+			if (faults[0] === 'outage') {
+				faults.shift();
+				return callback(reply('Service not available', 421));
+			}
+			callback();
+		},
+		onData(stream, session, callback) {
+			const refuse = faults[0] === 'refusal';
+			if (refuse) faults.shift();
+			simpleParser(stream).then(
+				(parsed) => {
+					if (refuse) return callback(reply('Message rejected', 554));
+					delivered.push({
+						to: session.envelope.rcptTo.map((rcpt) => rcpt.address), // what the envelope named
+						subject: parsed.subject ?? '',
+						html: typeof parsed.html === 'string' ? parsed.html : '',
+						text: parsed.text ?? '',
+					});
+					callback();
+				},
+				(error: Error) => callback(error),
+			);
+		},
+	});
+	await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+	const { port } = server.server.address() as AddressInfo;
+	return {
+		port,
+		delivered,
+		faults,
+		attempts: () => attempts,
+		close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+	};
+}
+```
+
+`to` is read from the **envelope** (`RCPT TO`), not from the `To:` header: it
+is who the server was asked to deliver to, and what proves a name did not
+smuggle a second recipient in.
+
+## The conformance suite
+
+One fresh server and transporter per case, closed after it:
+
+```ts
+import { describe, it } from 'bun:test';
+import { describeMailer } from '@nxgt/mail/conformance';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+import nodemailer from 'nodemailer';
+import { startSmtpServer } from './smtp-server';
+
+describeMailer({
+	name: 'createSmtpMailer',
+	runner: { describe, it }, // bun test puts neither on globalThis
+	harness: {
+		async open() {
+			const server = await startSmtpServer();
+			const transporter = nodemailer.createTransport({ host: '127.0.0.1', port: server.port, secure: false, ignoreTLS: true });
+			return {
+				mailer: createSmtpMailer({ transporter }),
+				delivered: async () => [...server.delivered],
+				faults: {
+					failNext: async (kind) => {
+						server.faults.push(kind);
+					},
+					attempts: async () => server.attempts(),
+				},
+				async close() {
+					transporter.close();
+					await server.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-smtp/src/index.spec.ts))
+add what the suite does not ask of every transport:
+
+- a server that is not listening ends in `MailFailure`, `ESOCKET` on `cause`;
+- a recipient refused for good (`550`) is a `MailRefused`, one refused for now
+  (`450`) a `MailFailure`;
+- one recipient refused while another is accepted still throws — the
+  accepted one has the message — and every recipient refused is a
+  `MailRefused` only when every refusal is permanent, whatever their order;
+- credentials refused (`535`, `EAUTH`), authentication required (`530`) and
+  a sender refused at `MAIL FROM` (`550`) are a `MailFailure`;
+- a string address is handed to nodemailer as `{ name: '', address }`, so it
+  never parses one;
+- no error message holds the password or a recipient's address;
+- the default `from`, `replyTo` and `headers` reach the server, and the id is
+  nodemailer's;
+- nodemailer is told never to read a file or a URL.
+
+A transporter can also be a plain object, when a test only needs to see what
+was handed over:
+
+```ts
+import { expect, test } from 'bun:test';
+import { sampleMessage } from '@nxgt/mail/conformance';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+test('hands the parts over as strings', async () => {
+	const handed: unknown[] = [];
+	const mailer = createSmtpMailer({
+		transporter: {
+			async sendMail(mail) {
+				handed.push(mail);
+				return { messageId: '<1@test>' };
+			},
+		},
+	});
+	expect(await mailer.send(sampleMessage)).toEqual({ messageId: '<1@test>' });
+	expect(handed[0]).toMatchObject({ subject: sampleMessage.subject, disableUrlAccess: true });
+});
+```
+
+## 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,50 @@
+# Roadmap
+
+Where `@nxgt/mail-smtp` 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
+
+Nothing planned yet. Say what you need in an issue.
+
+## Not planned
+
+- **SMTP options of our own** — host, port, TLS, pooling, DKIM and timeouts
+  are nodemailer's; wrapping them would lag behind it. You create the
+  transporter.
+- **Silent retries** — 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.
+- **Attachments and files read by nodemailer** — a message is three strings;
+  `disableFileAccess` and `disableUrlAccess` stay on.
+- **Bundling nodemailer** — it is a peer: one copy, the version you choose.
+
+## Shipped
+
+The last ten, newest first, each with the version it came in. Everything
+before is in the [CHANGELOG](../CHANGELOG.md).
+
+- **An SMTP transport on your nodemailer, v0.1.0** — `createSmtpMailer({ transporter,
+  from })`: every SMTP option is nodemailer's, set where you create the
+  transporter. Each message is checked as every transport checks it, a name is
+  quoted by nodemailer so it names one recipient, and nothing is read from a
+  file or a URL.
+- **Errors you can act on, v0.1.0** — a permanent `5xx` on the recipients or the
+  content (`552` for a message too large) is a `MailRefused`; an
+  unreachable server, a timeout, a `4xx`, refused credentials or a refused
+  sender is a `MailFailure`, nodemailer's error on `cause`. Some recipients
+  refused while others were accepted throws too, and says the others may
+  have the message. The classes are `@nxgt/mail`'s, so `instanceof` holds.
+- **Proven against a real server, v0.1.0** — the `@nxgt/mail/conformance` suite
+  passes against a local `smtp-server`, what arrived read back with
+  `mailparser`.

package/docs/troubleshooting.md

@@ -0,0 +1,223 @@
+# Troubleshooting `@nxgt/mail-smtp`
+
+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.** No address, no
+  subject, no password, no server reply: what the server said is on the
+  error's `cause`, nodemailer's error untouched.
+- **Every message starts with the call you wrote**: `send: …` or
+  `createSmtpMailer: …`.
+- **A `TypeError` is a wiring mistake**, thrown by `createSmtpMailer` 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: the SMTP server could not take the message`](#send-the-smtp-server-could-not-take-the-message)
+- [`send: the SMTP server refused the message`](#send-the-smtp-server-refused-the-message)
+- [`send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others`](#send-the-smtp-server-refused-n-of-total-recipients-and-may-have-delivered-to-the-others)
+- [`send: the SMTP server could not take <n> of <total> recipients, and may have delivered to the others`](#send-the-smtp-server-could-not-take-n-of-total-recipients-and-may-have-delivered-to-the-others)
+- [`send: from is missing — give the message a from, or createSmtpMailer a default one`](#send-from-is-missing--give-the-message-a-from-or-createsmtpmailer-a-default-one)
+
+**Wiring**
+- [`createSmtpMailer: options must be an object, as { transporter }`](#createsmtpmailer-options-must-be-an-object-as--transporter-)
+- [`createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers`](#createsmtpmailer-transporter-must-be-what-nodemailercreatetransport-answers)
+- [`createSmtpMailer: from must be an e-mail address, as noreply@example.com or { name, address }`](#createsmtpmailer-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 | null' is not assignable to type 'string'.`](#ts2322-type-string--null-is-not-assignable-to-type-string)
+
+## Sending
+
+### `send: the SMTP server could not take the message`
+
+A `MailFailure`, code `MAIL_FAILED`. **Nothing is known to have been sent**:
+after a timeout or a connection dropped once the message was on its way, the
+server may have taken it all the same.
+
+**When:** nodemailer could not hand the message over — the server cannot be
+reached, the connection dropped or timed out, the server answered a `4xx`
+(busy, try later, `421` closing), refused the credentials (`535`, `530`) or
+the sender (`550` on `MAIL FROM`: `cause.command` is `'MAIL FROM'`), or
+refused every recipient with at least one refusal for now (`450`).
+
+**Why:** none of these is about the message: the same message may go through
+later, or once the credentials or the sender are fixed.
+
+**Fix:** read `cause` — nodemailer's error:
+
+```ts
+import { MailFailure } from '@nxgt/mail';
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailFailure) {
+		const { code, responseCode } = error.cause as { code?: string; responseCode?: number };
+		// ECONNECTION / ESOCKET: host or port wrong, or the server is down
+		// ETIMEDOUT: the server is slow, or a firewall drops the connection
+		// EAUTH, 535: user or password wrong; 530: the server wants credentials
+		// 5xx with command 'MAIL FROM': the server refuses this sender — check from
+		// 4xx: the server is busy or rate-limiting — try later
+		console.warn(code, responseCode);
+	}
+	throw error;
+}
+```
+
+A retry is yours to decide — from a queue, with a delay. The transport never
+retries in secret.
+
+### `send: the SMTP server refused the message`
+
+A `MailRefused`, code `MAIL_REFUSED`.
+
+**When:** the server answered a permanent `5xx` to every recipient (`550` no
+such mailbox, `553` address not allowed) or to the content (`552` too large,
+`554` rejected — as spam, for example).
+
+**Why:** the server will refuse the same message again; retrying it
+unchanged is pointless.
+
+**Fix:** read `cause.responseCode` and `cause.response` to see which — with
+every recipient refused, `cause.rejectedErrors` holds one error per
+recipient; correct the address or the content. A recipient that does not
+exist is usually worth telling the user about.
+
+### `send: the SMTP server refused <n> of <total> recipients, and may have delivered to the others`
+
+A `MailRefused`, code `MAIL_REFUSED`. **The accepted recipients may already
+have the message.**
+
+**When:** a message to several recipients: the server refused `<n>` of them
+for good (`550`, `553`) and accepted the others. nodemailer resolves then;
+the transport throws, since the send did not reach everyone it named.
+
+**Why:** a refused recipient is refused again; the accepted ones were handed
+the message.
+
+**Fix:** do not retry the message whole — it would reach the accepted
+recipients twice. `cause` is nodemailer's error for the first refused
+recipient: its `responseCode`, and `recipient`.
+
+```ts
+import { MailRefused } from '@nxgt/mail';
+
+declare function markUndeliverable(recipient: string | undefined, responseCode: number | undefined): Promise<void>;
+
+try {
+	await mailer.send(message);
+} catch (error) {
+	if (error instanceof MailRefused && error.message.includes('may have delivered to the others')) {
+		const { recipient, responseCode } = error.cause as { recipient?: string; responseCode?: number };
+		// Mark `recipient` as undeliverable, and do not send again to the others.
+		await markUndeliverable(recipient, responseCode);
+	}
+	throw error;
+}
+```
+
+Sending to one recipient per `send` makes every result all or nothing.
+
+### `send: the SMTP server could not take <n> of <total> recipients, and may have delivered to the others`
+
+A `MailFailure`, code `MAIL_FAILED`. **The accepted recipients may already
+have the message.**
+
+**When:** a message to several recipients: the server accepted some, and
+refused `<n>` with one refusal at least for now (a `4xx`, `450` mailbox
+busy) or for a reason that is not the message (`530`–`539`), or nodemailer
+reported the refusals without a reason.
+
+**Why:** the refused recipients may be reachable later; the accepted ones
+were handed the message.
+
+**Fix:** retry for the refused recipients only, later — never the message
+whole. `cause` is nodemailer's error for the first refused recipient.
+Sending to one recipient per `send` makes every result all or nothing.
+
+### `send: from is missing — give the message a from, or createSmtpMailer a default one`
+
+A `MailRefused`, thrown before the transporter is called.
+
+**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 nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+const mailer = createSmtpMailer({
+	transporter: nodemailer.createTransport(process.env.SMTP_URL ?? 'smtp://localhost:1025'),
+	from: { name: 'Acme', address: 'noreply@acme.test' },
+});
+```
+
+## Wiring
+
+### `createSmtpMailer: options must be an object, as { transporter }`
+
+A `TypeError`. `createSmtpMailer` was called with nothing, or with the
+transporter itself.
+
+```ts
+createSmtpMailer(transporter); // ✗
+createSmtpMailer({ transporter }); // ✓
+```
+
+### `createSmtpMailer: transporter must be what nodemailer.createTransport(…) answers`
+
+A `TypeError`. `transporter` is missing, or has no `sendMail` — nodemailer's
+options were passed where its transporter belongs.
+
+```ts
+import nodemailer from 'nodemailer';
+import { createSmtpMailer } from '@nxgt/mail-smtp';
+
+// ✗ createSmtpMailer({ transporter: { host: 'smtp.example.com', port: 587 } })
+createSmtpMailer({ transporter: nodemailer.createTransport({ host: 'smtp.example.com', port: 587 }) }); // ✓
+```
+
+### `createSmtpMailer: 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
+createSmtpMailer({ transporter, from: 'Acme <noreply@acme.test>' }); // ✗
+createSmtpMailer({ transporter, from: { name: 'Acme', address: 'noreply@acme.test' } }); // ✓
+```
+
+A string is only an address: the transport never parses one, so a name can
+never smuggle a second address into a header.
+
+## 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 | null' is not assignable to type 'string'.`
+
+`messageId` is `string | null`: nodemailer may give 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,61 @@
+{
+	"name": "@nxgt/mail-smtp",
+	"version": "0.1.0",
+	"description": "An SMTP transport for @nxgt/mail, on the nodemailer you install: 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",
+		"smtp",
+		"nodemailer",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-mail.git",
+		"directory": "packages/mail-smtp"
+	},
+	"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",
+		"@types/mailparser": "^3.4.6",
+		"@types/nodemailer": "^8.0.2",
+		"@types/smtp-server": "^3.5.13",
+		"mailparser": "^3.9.28",
+		"nodemailer": "^10.0.10",
+		"smtp-server": "^3.19.13"
+	},
+	"peerDependencies": {
+		"@nxgt/mail": "^0.1.0",
+		"nodemailer": ">=7.0.0 <11",
+		"typescript": "^6.0.3"
+	}
+}