@owlmeans/mailer-smtp 0.1.18-rc.0

package/README.md

@@ -0,0 +1,74 @@
+# @owlmeans/mailer-smtp
+
+SMTP transport for the OwlMeans `MailerService` contract, built on [nodemailer](https://nodemailer.com).
+
+## Overview
+
+- `makeSmtpMailerService(alias?)` — `MailerService` implementation reading `cfg.smtp`
+- `SmtpSettings` / `SmtpConfig` — the config block; numbers and booleans also accept their string form, because config values mounted from files always arrive as text
+- `verify()` — open a session and authenticate without sending, for health checks and tests
+- `toTransportOptions()` / `toMailOptions()` — the pure translations into nodemailer's shapes
+- Works with any SMTP relay; Mailgun, SES and Postmark all expose one
+
+## Installation
+
+```bash
+bun add @owlmeans/mailer-smtp
+```
+
+## Usage
+
+```typescript
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeSmtpMailerService } from '@owlmeans/mailer-smtp'
+
+cfg.smtp = {
+  host: 'smtp.eu.mailgun.org',
+  port: 465,           // implicit TLS; use 587 / 2525 with `secure: false` for STARTTLS
+  secure: true,
+  user: 'no-reply@example.com',
+  pass: process.env.SMTP_PASSWORD,
+  from: 'Example <no-reply@example.com>',
+}
+
+// Register under MAILER_SERVICE so consumers — the email-OTP auth plugin above all —
+// resolve the mailer without knowing which transport backs it.
+context.registerService(makeSmtpMailerService(MAILER_SERVICE))
+```
+
+In a server context, point the settings at mounted files instead of literals — the
+`fileConfigReader` middleware replaces any value starting with `/` by the file's contents:
+
+```typescript
+cfg.smtp = {
+  host: '/etc/app-config/smtp-host',
+  user: '/etc/app-config/smtp-user',
+  from: '/etc/app-config/smtp-from',
+  pass: '/etc/master-secret/smtp-secret',
+}
+```
+
+## Tests
+
+`tests/message.spec.ts` needs nothing. `tests/send.spec.ts` is env-gated and **delivers real
+mail** when open — see the SMTP block in the monorepo's `.env.example`.
+
+```bash
+bun run build && bun test ./tests
+```
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/mailer-smtp",
+  "version": "0.1.18-rc.0",
+  "generatedAt": "2026-08-16T22:20:50.500Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "mailer-smtp",
+      "category": "package-specific",
+      "file": "skills/mailer-smtp/SKILL.md",
+      "canonicalPath": ".agents/skills/mailer-smtp/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/mailer-smtp/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: mailer-smtp
+description: "How to use @owlmeans/mailer-smtp — SMTP transport (nodemailer) for the MailerService contract. Use when configuring real outbound email, an SMTP relay such as Mailgun, or the email-OTP mailer. Applies to files matching **/context.ts, **/config.ts, **/setup.ts."
+metadata:
+  applyTo: "**/context.ts, **/config.ts, **/setup.ts"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# Using `@owlmeans/mailer-smtp`
+
+SMTP transport implementing `@owlmeans/mailer`'s `MailerService`, built on `nodemailer` (the
+zero-dependency de-facto standard for Node SMTP). Reads `ctx.cfg.smtp`. Works against any relay —
+Mailgun, SES, Postmark all expose SMTP.
+
+## Public API surface
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `makeSmtpMailerService(alias?)` | fn | Service factory; default alias `SMTP_MAILER` |
+| `SmtpMailerService` | interface | `MailerService` + `verify()` + `close()` |
+| `SmtpSettings` / `SmtpConfig` | interface | `cfg.smtp` block |
+| `SMTP_MAILER` | const | `'smtp-mailer'` |
+| `SMTP_DEFAULT_PORT` | const | `465` |
+| `toTransportOptions` / `toMailOptions` | fn | Pure translations into nodemailer's shapes; test these, not the socket |
+
+## Config shape
+
+```ts
+cfg.smtp = {
+  host: 'smtp.eu.mailgun.org',
+  port: 465,          // default
+  secure: true,       // default — implicit TLS
+  user: 'no-reply@example.com',
+  pass: process.env.SMTP_PASSWORD,
+  from: 'Example <no-reply@example.com>',
+  // optional: replyTo, headers, rejectUnauthorized, timeout
+}
+```
+
+Every numeric/boolean field also accepts its **string** form. That is not sloppiness: in a server
+context the values usually come from mounted files, and `fileConfigReader` yields text.
+
+```ts
+cfg.smtp = {
+  host: '/etc/app-config/smtp-host',
+  user: '/etc/app-config/smtp-user',
+  from: '/etc/app-config/smtp-from',
+  pass: '/etc/master-secret/smtp-secret',   // secret volume, never a ConfigMap
+}
+```
+
+## Registration
+
+```ts
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeSmtpMailerService } from '@owlmeans/mailer-smtp'
+
+context.registerService(makeSmtpMailerService(MAILER_SERVICE))
+```
+
+Register under `MAILER_SERVICE` so platform code — `OtpService` above all — resolves the mailer
+without knowing the transport. Select between transports on config, not on a build flag:
+
+```ts
+context.registerService(
+  cfg.smtp?.host != null && cfg.smtp.host !== ''
+    ? makeSmtpMailerService(MAILER_SERVICE)
+    : makeConsoleMailerService(MAILER_SERVICE)
+)
+```
+
+## Ports and TLS
+
+| Port | Mode | `secure` |
+|---|---|---|
+| 465 | implicit TLS from the first byte | `true` (default) |
+| 587, 2525 | STARTTLS upgrade | `false` |
+| 25 | plain / STARTTLS, often blocked | `false` |
+
+## Rules
+
+- **The relay's SMTP credential is not the account login.** Mailgun issues a per-sending-domain
+  user (`postmaster@domain` or a custom one) under the domain's SMTP settings.
+- The `From` domain must be verified with the relay; the local part is free-form.
+- Deliberately **unpooled** — a pooled transport holds its socket and keeps a short-lived process
+  alive. Add pooling only with a matching lifecycle.
+- Errors are rethrown prefixed with the service alias and the server's own reply
+  (`code`/`responseCode`/`response`). The password never reaches a message or a log.
+- `verify()` authenticates without submitting a message — right for health checks; not proof that
+  the relay accepts *a message* from your sender.
+- Never register this in unit tests — use `makeConsoleMailerService`. `toMailOptions` plus
+  nodemailer's own `jsonTransport` cover envelope assertions without a socket.
+- **Never authenticate with a deliberately wrong password against a live relay.** Repeated failed
+  logins trip the provider's brute-force protection and lock the shared credential for every
+  environment using it — Mailgun then answers `535 Authentication failed` to the correct password
+  too, and the credential has to be reset in its dashboard. Provoke transport errors with an
+  unreachable socket (`host: '127.0.0.1', port: '1'`) instead.
+- The live spec (`tests/send.spec.ts`) is gated on the SMTP block in `/.env.example` and **delivers
+  real mail** when the gate is open. Empty variables = skip, never a failure.
+- Rollup-bundling for a container image works with the default `preferBuiltins: true` node-resolve
+  setup; nodemailer's dynamic requires do not need to be externalized.
+
+## External references
+
+- [nodemailer](https://www.npmjs.com/package/nodemailer) — v9.x, MIT-0, **zero dependencies**, the
+  de-facto standard (~10.8k dependents). Ships no types; `@types/nodemailer` (v8.x) supplies them.
+  CJS — import the default (`import nodemailer from 'nodemailer'`), not named members, so both Bun
+  and Rollup's commonjs interop resolve it. Verified working under Bun and inside a Rollup CJS
+  bundle (2026-08).
+- [Mailgun — Send via SMTP](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-smtp)
+  — hosts `smtp.mailgun.org` / `smtp.eu.mailgun.org`; port 465 requires TLS, ports 25/587/2525 start
+  plain and upgrade via STARTTLS. Credentials are **per sending domain**, managed under that domain's
+  SMTP settings — not the account login. `X-Mailgun-Drop-Message: yes` submits in test mode (accepted,
+  never delivered); other `X-Mailgun-*` headers cover tagging, DKIM, tracking and required TLS.

package/build/consts.d.ts

@@ -0,0 +1,4 @@
+export declare const SMTP_MAILER = "smtp-mailer";
+/** Implicit TLS from the first byte. Ports 25 / 587 / 2525 are STARTTLS instead. */
+export declare const SMTP_DEFAULT_PORT = 465;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,gBAAgB,CAAA;AAExC,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,MAAM,CAAA"}

package/build/consts.js

@@ -0,0 +1,4 @@
+export const SMTP_MAILER = 'smtp-mailer';
+/** Implicit TLS from the first byte. Ports 25 / 587 / 2525 are STARTTLS instead. */
+export const SMTP_DEFAULT_PORT = 465;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAA;AAExC,oFAAoF;AACpF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './service.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -0,0 +1,3 @@
+export * from './consts.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/service.d.ts

@@ -0,0 +1,23 @@
+import type { MailMessage } from '@owlmeans/mailer';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport/index.js';
+import type Mail from 'nodemailer/lib/mailer/index.js';
+import type { SmtpMailerService, SmtpSettings } from './types.js';
+/**
+ * Translate the settings block into nodemailer's transport options.
+ *
+ * Deliberately unpooled: a pooled transport holds its socket open and would keep a
+ * short-lived process alive, and the traffic this serves — login codes — is far below
+ * the volume that makes pooling worth that.
+ */
+export declare const toTransportOptions: (smtp: SmtpSettings) => SMTPTransport.Options;
+/** Translate a provider-agnostic message into nodemailer's envelope, applying the config defaults. */
+export declare const toMailOptions: (smtp: SmtpSettings, message: MailMessage) => Mail.Options;
+/**
+ * SMTP transport for the `MailerService` contract. Reads `cfg.smtp` and keeps one
+ * nodemailer transporter per service instance.
+ *
+ * Register it under `MAILER_SERVICE` so callers — the email-OTP plugin above all —
+ * resolve it without knowing which transport is in play.
+ */
+export declare const makeSmtpMailerService: (alias?: string) => SmtpMailerService;
+//# sourceMappingURL=service.d.ts.map

package/build/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAInD,OAAO,KAAK,aAAa,MAAM,wCAAwC,CAAA;AACvE,OAAO,KAAK,IAAI,MAAM,gCAAgC,CAAA;AAEtD,OAAO,KAAK,EAAc,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAgB7E;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,SAAU,YAAY,KAAG,aAAa,CAAC,OASpE,CAAA;AAEF,sGAAsG;AACtG,eAAO,MAAM,aAAa,SAAU,YAAY,WAAW,WAAW,KAAG,IAAI,CAAC,OAa7E,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,sBAA0B,iBAsD3D,CAAA"}

package/build/service.js

@@ -0,0 +1,99 @@
+import { createService } from '@owlmeans/context';
+import nodemailer from 'nodemailer';
+import { SMTP_DEFAULT_PORT, SMTP_MAILER } from './consts.js';
+const toNumber = (value, def) => {
+    if (value == null || value === '')
+        return def;
+    const num = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(num) ? num : def;
+};
+const toBoolean = (value, def) => {
+    if (value == null || value === '')
+        return def;
+    if (typeof value === 'boolean')
+        return value;
+    return ['1', 'on', 'true', 'yes'].includes(value.trim().toLowerCase());
+};
+/**
+ * Translate the settings block into nodemailer's transport options.
+ *
+ * Deliberately unpooled: a pooled transport holds its socket open and would keep a
+ * short-lived process alive, and the traffic this serves — login codes — is far below
+ * the volume that makes pooling worth that.
+ */
+export const toTransportOptions = (smtp) => ({
+    host: smtp.host,
+    port: toNumber(smtp.port, SMTP_DEFAULT_PORT),
+    secure: toBoolean(smtp.secure, true),
+    tls: { rejectUnauthorized: toBoolean(smtp.rejectUnauthorized, true) },
+    ...(smtp.timeout != null ? { connectionTimeout: toNumber(smtp.timeout, 0) } : {}),
+    ...(smtp.user != null && smtp.user !== ''
+        ? { auth: { user: smtp.user, pass: smtp.pass ?? '' } }
+        : {}),
+});
+/** Translate a provider-agnostic message into nodemailer's envelope, applying the config defaults. */
+export const toMailOptions = (smtp, message) => {
+    const headers = { ...smtp.headers, ...message.headers };
+    const replyTo = message.replyTo ?? smtp.replyTo;
+    return {
+        from: message.from ?? smtp.from,
+        to: message.to,
+        subject: message.subject,
+        ...(message.text != null ? { text: message.text } : {}),
+        ...(message.html != null ? { html: message.html } : {}),
+        ...(replyTo != null ? { replyTo } : {}),
+        ...(Object.keys(headers).length > 0 ? { headers } : {}),
+    };
+};
+/**
+ * SMTP transport for the `MailerService` contract. Reads `cfg.smtp` and keeps one
+ * nodemailer transporter per service instance.
+ *
+ * Register it under `MAILER_SERVICE` so callers — the email-OTP plugin above all —
+ * resolve it without knowing which transport is in play.
+ */
+export const makeSmtpMailerService = (alias = SMTP_MAILER) => {
+    let transport = null;
+    const settings = () => {
+        const ctx = service.assertCtx(alias);
+        const smtp = ctx.cfg.smtp;
+        if (smtp?.host == null || smtp.host === '') {
+            throw new SyntaxError(`${alias}: cfg.smtp.host is not configured`);
+        }
+        return smtp;
+    };
+    const transporter = () => transport ??= nodemailer.createTransport(toTransportOptions(settings()));
+    // Credentials never reach the message: nodemailer reports the server's own reply only.
+    const fail = (action, error) => {
+        const err = error;
+        const detail = [err.code, err.responseCode, err.response ?? err.message]
+            .filter(part => part != null && part !== '').join(' ');
+        throw new Error(`${alias}: ${action}${detail !== '' ? ` — ${detail}` : ''}`);
+    };
+    const service = createService(alias, {
+        send: async (message) => {
+            const options = toMailOptions(settings(), message);
+            try {
+                await transporter().sendMail(options);
+            }
+            catch (error) {
+                fail(`failed to send to ${message.to}`, error);
+            }
+        },
+        verify: async () => {
+            try {
+                await transporter().verify();
+            }
+            catch (error) {
+                fail('failed to verify the SMTP connection', error);
+            }
+            return true;
+        },
+        close: async () => {
+            transport?.close();
+            transport = null;
+        },
+    });
+    return service;
+};
+//# sourceMappingURL=service.js.map

package/build/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,39 @@
+import type { MailerService } from '@owlmeans/mailer';
+import type { ServerConfig } from '@owlmeans/server-context';
+/**
+ * SMTP transport settings, read from `cfg.smtp` at send time.
+ *
+ * Numbers and booleans accept a string form on purpose: server contexts resolve
+ * config leafs that look like paths through `fileConfigReader`, so a value mounted
+ * from a Kubernetes ConfigMap always arrives as text. The service coerces them.
+ */
+export interface SmtpSettings {
+    /** SMTP server, e.g. `smtp.eu.mailgun.org`. */
+    host: string;
+    /** Defaults to 465. */
+    port?: number | string;
+    /** `true` (default) = implicit TLS, for port 465. Use `false` with the STARTTLS ports. */
+    secure?: boolean | string;
+    user?: string;
+    pass?: string;
+    /** Default `From` header — `'OwlMeans <no-reply@example.com>'`. A message may override it. */
+    from: string;
+    /** Default `Reply-To` header. */
+    replyTo?: string;
+    /** Verify the server certificate. Defaults to `true`; only disable knowingly. */
+    rejectUnauthorized?: boolean | string;
+    /** Headers added to every message. Per-message headers win on conflict. */
+    headers?: Record<string, string>;
+    /** Connection timeout in milliseconds. */
+    timeout?: number | string;
+}
+export interface SmtpConfig extends ServerConfig {
+    smtp: SmtpSettings;
+}
+export interface SmtpMailerService extends MailerService {
+    /** Open a session and authenticate without submitting a message. Throws when the server rejects. */
+    verify: () => Promise<true>;
+    /** Release a pooled connection. A no-op for the default, non-pooled transport. */
+    close: () => Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;IACZ,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IACrC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,UAAW,SAAQ,YAAY;IAC9C,IAAI,EAAE,YAAY,CAAA;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,oGAAoG;IACpG,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B,kFAAkF;IAClF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3B"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@owlmeans/mailer-smtp",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 4 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/context": "^0.1.18-rc.0",
+    "@owlmeans/mailer": "^0.1.18-rc.0",
+    "@owlmeans/server-context": "^0.1.18-rc.0",
+    "nodemailer": "^9.0.5"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test": "^0.1.18-rc.0",
+    "@owlmeans/test-integration": "^0.1.18-rc.0",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "@types/nodemailer": "^8.0.1",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,4 @@
+export const SMTP_MAILER = 'smtp-mailer'
+
+/** Implicit TLS from the first byte. Ports 25 / 587 / 2525 are STARTTLS instead. */
+export const SMTP_DEFAULT_PORT = 465

package/src/index.ts

@@ -0,0 +1,3 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './service.js'

package/src/service.ts

@@ -0,0 +1,120 @@
+import { createService } from '@owlmeans/context'
+import type { MailMessage } from '@owlmeans/mailer'
+import type { ServerContext } from '@owlmeans/server-context'
+import nodemailer from 'nodemailer'
+import type { Transporter } from 'nodemailer'
+import type SMTPTransport from 'nodemailer/lib/smtp-transport/index.js'
+import type Mail from 'nodemailer/lib/mailer/index.js'
+import { SMTP_DEFAULT_PORT, SMTP_MAILER } from './consts.js'
+import type { SmtpConfig, SmtpMailerService, SmtpSettings } from './types.js'
+
+const toNumber = (value: number | string | undefined, def: number): number => {
+  if (value == null || value === '') return def
+  const num = typeof value === 'number' ? value : Number(value)
+
+  return Number.isFinite(num) ? num : def
+}
+
+const toBoolean = (value: boolean | string | undefined, def: boolean): boolean => {
+  if (value == null || value === '') return def
+  if (typeof value === 'boolean') return value
+
+  return ['1', 'on', 'true', 'yes'].includes(value.trim().toLowerCase())
+}
+
+/**
+ * Translate the settings block into nodemailer's transport options.
+ *
+ * Deliberately unpooled: a pooled transport holds its socket open and would keep a
+ * short-lived process alive, and the traffic this serves — login codes — is far below
+ * the volume that makes pooling worth that.
+ */
+export const toTransportOptions = (smtp: SmtpSettings): SMTPTransport.Options => ({
+  host: smtp.host,
+  port: toNumber(smtp.port, SMTP_DEFAULT_PORT),
+  secure: toBoolean(smtp.secure, true),
+  tls: { rejectUnauthorized: toBoolean(smtp.rejectUnauthorized, true) },
+  ...(smtp.timeout != null ? { connectionTimeout: toNumber(smtp.timeout, 0) } : {}),
+  ...(smtp.user != null && smtp.user !== ''
+    ? { auth: { user: smtp.user, pass: smtp.pass ?? '' } }
+    : {}),
+})
+
+/** Translate a provider-agnostic message into nodemailer's envelope, applying the config defaults. */
+export const toMailOptions = (smtp: SmtpSettings, message: MailMessage): Mail.Options => {
+  const headers = { ...smtp.headers, ...message.headers }
+  const replyTo = message.replyTo ?? smtp.replyTo
+
+  return {
+    from: message.from ?? smtp.from,
+    to: message.to,
+    subject: message.subject,
+    ...(message.text != null ? { text: message.text } : {}),
+    ...(message.html != null ? { html: message.html } : {}),
+    ...(replyTo != null ? { replyTo } : {}),
+    ...(Object.keys(headers).length > 0 ? { headers } : {}),
+  }
+}
+
+/**
+ * SMTP transport for the `MailerService` contract. Reads `cfg.smtp` and keeps one
+ * nodemailer transporter per service instance.
+ *
+ * Register it under `MAILER_SERVICE` so callers — the email-OTP plugin above all —
+ * resolve it without knowing which transport is in play.
+ */
+export const makeSmtpMailerService = (alias = SMTP_MAILER): SmtpMailerService => {
+  let transport: Transporter<SMTPTransport.SentMessageInfo> | null = null
+
+  const settings = (): SmtpSettings => {
+    const ctx = service.assertCtx<SmtpConfig, ServerContext<SmtpConfig>>(alias)
+    const smtp = ctx.cfg.smtp
+
+    if (smtp?.host == null || smtp.host === '') {
+      throw new SyntaxError(`${alias}: cfg.smtp.host is not configured`)
+    }
+
+    return smtp
+  }
+
+  const transporter = (): Transporter<SMTPTransport.SentMessageInfo> =>
+    transport ??= nodemailer.createTransport(toTransportOptions(settings()))
+
+  // Credentials never reach the message: nodemailer reports the server's own reply only.
+  const fail = (action: string, error: unknown): never => {
+    const err = error as { code?: string, responseCode?: number, response?: string, message?: string }
+    const detail = [err.code, err.responseCode, err.response ?? err.message]
+      .filter(part => part != null && part !== '').join(' ')
+
+    throw new Error(`${alias}: ${action}${detail !== '' ? ` — ${detail}` : ''}`)
+  }
+
+  const service = createService<SmtpMailerService>(alias, {
+    send: async (message: MailMessage): Promise<void> => {
+      const options = toMailOptions(settings(), message)
+
+      try {
+        await transporter().sendMail(options)
+      } catch (error) {
+        fail(`failed to send to ${message.to}`, error)
+      }
+    },
+
+    verify: async (): Promise<true> => {
+      try {
+        await transporter().verify()
+      } catch (error) {
+        fail('failed to verify the SMTP connection', error)
+      }
+
+      return true
+    },
+
+    close: async (): Promise<void> => {
+      transport?.close()
+      transport = null
+    },
+  })
+
+  return service
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+import type { MailerService } from '@owlmeans/mailer'
+import type { ServerConfig } from '@owlmeans/server-context'
+
+/**
+ * SMTP transport settings, read from `cfg.smtp` at send time.
+ *
+ * Numbers and booleans accept a string form on purpose: server contexts resolve
+ * config leafs that look like paths through `fileConfigReader`, so a value mounted
+ * from a Kubernetes ConfigMap always arrives as text. The service coerces them.
+ */
+export interface SmtpSettings {
+  /** SMTP server, e.g. `smtp.eu.mailgun.org`. */
+  host: string
+  /** Defaults to 465. */
+  port?: number | string
+  /** `true` (default) = implicit TLS, for port 465. Use `false` with the STARTTLS ports. */
+  secure?: boolean | string
+  user?: string
+  pass?: string
+  /** Default `From` header — `'OwlMeans <no-reply@example.com>'`. A message may override it. */
+  from: string
+  /** Default `Reply-To` header. */
+  replyTo?: string
+  /** Verify the server certificate. Defaults to `true`; only disable knowingly. */
+  rejectUnauthorized?: boolean | string
+  /** Headers added to every message. Per-message headers win on conflict. */
+  headers?: Record<string, string>
+  /** Connection timeout in milliseconds. */
+  timeout?: number | string
+}
+
+export interface SmtpConfig extends ServerConfig {
+  smtp: SmtpSettings
+}
+
+export interface SmtpMailerService extends MailerService {
+  /** Open a session and authenticate without submitting a message. Throws when the server rejects. */
+  verify: () => Promise<true>
+  /** Release a pooled connection. A no-op for the default, non-pooled transport. */
+  close: () => Promise<void>
+}

package/tests/context.ts

@@ -0,0 +1,45 @@
+import { smtpGate } from '@owlmeans/test-integration'
+import type { IntegrationGate, SmtpEnv } from '@owlmeans/test-integration'
+import { config, makeServerContext } from '@owlmeans/server-context'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import { MAILER_SERVICE } from '@owlmeans/mailer'
+import { makeSmtpMailerService } from '@owlmeans/mailer-smtp'
+import type { SmtpConfig, SmtpMailerService, SmtpSettings } from '@owlmeans/mailer-smtp'
+
+/**
+ * Live relay gate. Every variable empty means the delivery specs self-skip with a
+ * printed reason — never a failure. When it is open these specs send REAL mail, so
+ * `SMTP_TEST_TO` is required rather than optional.
+ */
+export const gate: IntegrationGate<SmtpEnv> = smtpGate()
+
+/** Never logged, never asserted on — only handed to the transport. */
+export const settings = (): SmtpSettings => ({
+  host: gate.env.SMTP_HOST as string,
+  port: gate.env.SMTP_PORT ?? '465',
+  secure: gate.env.SMTP_SECURE ?? 'true',
+  user: gate.env.SMTP_USER as string,
+  pass: gate.env.SMTP_PASSWORD as string,
+  from: gate.env.SMTP_FROM as string,
+})
+
+export const recipient = (): string => gate.env.SMTP_TEST_TO as string
+
+export interface Booted {
+  context: ServerContext<ServerConfig>
+  mailer: SmtpMailerService
+}
+
+/** Real context, real service registration — the same path a server app takes. */
+export const boot = async (overrides: Partial<SmtpSettings> = {}): Promise<Booted> => {
+  const cfg = config('smtp-test') as SmtpConfig
+  cfg.smtp = { ...settings(), ...overrides }
+
+  const context = makeServerContext(cfg) as unknown as ServerContext<ServerConfig>
+  context.registerService(makeSmtpMailerService(MAILER_SERVICE) as never)
+
+  context.configure()
+  await context.init()
+
+  return { context, mailer: context.service<SmtpMailerService>(MAILER_SERVICE) }
+}

package/tests/message.spec.ts

@@ -0,0 +1,94 @@
+import { describe, expect, test } from 'bun:test'
+import nodemailer from 'nodemailer'
+import { SMTP_DEFAULT_PORT, toMailOptions, toTransportOptions } from '@owlmeans/mailer-smtp'
+import type { SmtpSettings } from '@owlmeans/mailer-smtp'
+
+const base: SmtpSettings = {
+  host: 'smtp.example.org',
+  user: 'no-reply@example.org',
+  pass: 'secret',
+  from: 'Example <no-reply@example.org>',
+}
+
+/**
+ * No gate and no network: these assert the translation into nodemailer's own shapes,
+ * and let nodemailer itself build the envelope through its bundled `jsonTransport`.
+ */
+describe('@owlmeans/mailer-smtp — transport options', () => {
+  test('defaults to implicit TLS on 465 with certificate verification', () => {
+    const options = toTransportOptions(base)
+
+    expect(options.port).toBe(SMTP_DEFAULT_PORT)
+    expect(options.secure).toBe(true)
+    expect(options.tls).toEqual({ rejectUnauthorized: true })
+    expect(options.auth).toEqual({ user: base.user, pass: base.pass })
+  })
+
+  test('coerces the string forms a ConfigMap file delivers', () => {
+    const options = toTransportOptions({
+      ...base, port: '2525', secure: 'false', rejectUnauthorized: '0', timeout: '5000',
+    })
+
+    expect(options.port).toBe(2525)
+    expect(options.secure).toBe(false)
+    expect(options.tls).toEqual({ rejectUnauthorized: false })
+    expect(options.connectionTimeout).toBe(5000)
+  })
+
+  test('falls back to the default port when the value is unusable', () => {
+    expect(toTransportOptions({ ...base, port: '' }).port).toBe(SMTP_DEFAULT_PORT)
+    expect(toTransportOptions({ ...base, port: 'nonsense' }).port).toBe(SMTP_DEFAULT_PORT)
+  })
+
+  test('omits auth for an unauthenticated relay', () => {
+    expect(toTransportOptions({ ...base, user: '' }).auth).toBeUndefined()
+  })
+})
+
+describe('@owlmeans/mailer-smtp — message mapping', () => {
+  const message = { to: 'user@example.com', subject: 'Your login code', text: '106341' }
+
+  test('applies the configured sender and reply-to', () => {
+    const options = toMailOptions({ ...base, replyTo: 'support@example.org' }, message)
+
+    expect(options.from).toBe(base.from)
+    expect(options.replyTo).toBe('support@example.org')
+    expect(options.headers).toBeUndefined()
+  })
+
+  test('lets a message override the sender and reply-to', () => {
+    const options = toMailOptions(
+      { ...base, replyTo: 'support@example.org' },
+      { ...message, from: 'Other <other@example.org>', replyTo: 'nobody@example.org' }
+    )
+
+    expect(options.from).toBe('Other <other@example.org>')
+    expect(options.replyTo).toBe('nobody@example.org')
+  })
+
+  test('merges headers with the message winning', () => {
+    const options = toMailOptions(
+      { ...base, headers: { 'X-Origin': 'config', 'X-Kept': 'yes' } },
+      { ...message, headers: { 'X-Origin': 'message' } }
+    )
+
+    expect(options.headers).toEqual({ 'X-Origin': 'message', 'X-Kept': 'yes' })
+  })
+
+  test('nodemailer builds the envelope we described', async () => {
+    const transport = nodemailer.createTransport({ jsonTransport: true })
+    const info = await transport.sendMail(toMailOptions(
+      { ...base, headers: { 'X-OwlMeans-Test': 'mapping' } },
+      { ...message, html: '<p>106341</p>' }
+    ))
+
+    const built = JSON.parse(info.message as unknown as string)
+
+    expect(built.from.address).toBe('no-reply@example.org')
+    expect(built.to[0].address).toBe('user@example.com')
+    expect(built.subject).toBe('Your login code')
+    expect(built.text).toBe('106341')
+    expect(built.html).toBe('<p>106341</p>')
+    expect(built.headers['X-OwlMeans-Test']).toBe('mapping')
+  })
+})

package/tests/send.spec.ts

@@ -0,0 +1,59 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { randomNamespace } from '@owlmeans/test-integration'
+import { boot, gate, recipient } from './context.js'
+import type { SmtpMailerService } from '@owlmeans/mailer-smtp'
+
+/**
+ * Live delivery against the configured relay (Mailgun EU in our deployments).
+ *
+ * These send real mail on every run — that is the point: the only thing that proves
+ * the relay accepts our sender, credentials and TLS mode is the relay accepting it.
+ */
+describe('@owlmeans/mailer-smtp — live delivery', () => {
+  if (gate.skip) {
+    test.skip(gate.reason ?? 'smtp gate closed', () => { })
+    return
+  }
+
+  const opened: SmtpMailerService[] = []
+
+  afterAll(async () => {
+    while (opened.length > 0) {
+      await opened.pop()?.close().catch(() => undefined)
+    }
+  })
+
+  test('authenticates against the relay', async () => {
+    const { mailer } = await boot()
+    opened.push(mailer)
+
+    expect(await mailer.verify()).toBe(true)
+  })
+
+  test('delivers a message', async () => {
+    const { mailer } = await boot()
+    opened.push(mailer)
+    const stamp = randomNamespace('omt-smtp')
+
+    await mailer.send({
+      to: recipient(),
+      subject: `OwlMeans SMTP integration ${stamp}`,
+      text: `Delivery check ${stamp}. Sent by @owlmeans/mailer-smtp.`,
+      html: `<p>Delivery check <strong>${stamp}</strong>.</p>`,
+      headers: { 'X-OwlMeans-Test': stamp },
+    })
+  })
+
+  /**
+   * Failure is provoked with an unreachable socket, never with a wrong password: repeated bad
+   * logins trip the relay's brute-force protection and lock the shared credential for everyone.
+   * Never authenticate incorrectly on purpose against a live relay.
+   */
+  test('reports a transport failure instead of swallowing it', async () => {
+    const { mailer } = await boot({ host: '127.0.0.1', port: '1', secure: 'false', timeout: '1000' })
+    opened.push(mailer)
+
+    // The alias prefixes the message so a failure in a server log names the transport.
+    expect(mailer.verify()).rejects.toThrow(/mailer-service/)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}