@pattern-js/mod-email-smtp 0.3.0-main.4a77893

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Makkr Studio
+
+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,37 @@
+# @pattern-js/mod-email-smtp
+
+The SMTP driver for
+[`@pattern-js/mod-email`](https://www.npmjs.com/package/@pattern-js/mod-email)
+on [Pattern](../../README.md), built on nodemailer — any relay, your own
+server, or a local catcher (Mailpit) in dev. Host/port/user are account
+options in admin → System → Email; the password comes from the vault or an
+env var.
+
+**Links:** [pattern-js.dev](https://pattern-js.dev) · [npm](https://www.npmjs.com/package/@pattern-js/mod-email-smtp)
+
+```bash
+npm install @pattern-js/mod-email @pattern-js/mod-email-smtp
+```
+
+## When to use / when not
+
+Reach for it when you already have SMTP credentials (SES, Postmark, Mailgun,
+a corporate relay) or want a local catcher in dev. Prefer
+[`mod-email-resend`](https://www.npmjs.com/package/@pattern-js/mod-email-resend)
+for the least-setup path to production email (one API key, no relay).
+
+## Config
+
+Nothing to configure in code — list it and manage accounts in the admin:
+
+```jsonc
+{ "mods": ["@pattern-js/mod-email", "@pattern-js/mod-email-smtp"] }
+```
+
+Account fields: `host` (required), `port` (587), `secure`
+(`"true"` = implicit TLS; default STARTTLS), `user`, and the `pass` secret
+(vault or env, e.g. `SMTP_PASSWORD`). For tests, the mod factory accepts a
+`transportFactory` seam: `smtpEmailMod({ transportFactory })`.
+
+Full documentation: the **Email · SMTP** chapter at `/docs`, or
+[the source](docs/index.md).

package/dist/driver.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @pattern-js/mod-email-smtp — the driver.
+ *
+ * nodemailer does the protocol work (STARTTLS vs implicit TLS, AUTH, MIME) —
+ * hand-rolling SMTP is a correctness-and-security tarpit this mod deliberately
+ * avoids. Transports pool connections, so they're cached per CONFIG: the key
+ * is a sha256 of {host,port,secure,user,pass}, which is functionally
+ * per-account and self-invalidates when credentials rotate (only the digest is
+ * ever retained). The `transportFactory` option is the test seam.
+ */
+import { type Transporter } from "nodemailer";
+import type { EmailDriverSpec } from "@pattern-js/mod-email";
+export interface SmtpTransportConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth?: {
+        user: string;
+        pass?: string;
+    };
+}
+export type TransportFactory = (config: SmtpTransportConfig) => Transporter;
+export declare function smtpDriver(factory?: TransportFactory): EmailDriverSpec;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxC;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,mBAAmB,KAAK,WAAW,CAAC;AAE5E,wBAAgB,UAAU,CAAC,OAAO,GAAE,gBAAiE,GAAG,eAAe,CAkDtH"}

package/dist/driver.js

@@ -0,0 +1,64 @@
+/**
+ * @pattern-js/mod-email-smtp — the driver.
+ *
+ * nodemailer does the protocol work (STARTTLS vs implicit TLS, AUTH, MIME) —
+ * hand-rolling SMTP is a correctness-and-security tarpit this mod deliberately
+ * avoids. Transports pool connections, so they're cached per CONFIG: the key
+ * is a sha256 of {host,port,secure,user,pass}, which is functionally
+ * per-account and self-invalidates when credentials rotate (only the digest is
+ * ever retained). The `transportFactory` option is the test seam.
+ */
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import nodemailer from "nodemailer";
+export function smtpDriver(factory = (config) => nodemailer.createTransport(config)) {
+    const cache = new Map();
+    function transportFor(creds, options) {
+        if (!options.host)
+            throw new Error('smtp: the account is missing its "host" option.');
+        const config = {
+            host: options.host,
+            port: Number(options.port || 587),
+            secure: options.secure === "true",
+            auth: options.user ? { user: options.user, pass: creds.pass } : undefined,
+        };
+        const key = createHash("sha256").update(JSON.stringify(config)).digest("hex");
+        let transport = cache.get(key);
+        if (!transport) {
+            transport = factory(config);
+            cache.set(key, transport);
+        }
+        return transport;
+    }
+    return {
+        id: "smtp",
+        label: "SMTP",
+        // Optional on purpose: unauthenticated relays (and local catchers) exist.
+        secrets: [{ field: "pass", label: "Password", required: false }],
+        options: [
+            { field: "host", label: "Host", required: true, placeholder: "smtp.example.com" },
+            { field: "port", label: "Port", required: false, placeholder: "587" },
+            { field: "secure", label: "Implicit TLS (true/false)", required: false, placeholder: "false = STARTTLS on 587" },
+            { field: "user", label: "Username", required: false, placeholder: "" },
+        ],
+        async send(message, creds, options) {
+            const info = await transportFor(creds, options).sendMail({
+                from: message.from,
+                to: message.to,
+                cc: message.cc,
+                bcc: message.bcc,
+                replyTo: message.replyTo,
+                subject: message.subject,
+                html: message.html,
+                text: message.text,
+                attachments: message.attachments?.map((a) => ({
+                    filename: a.filename,
+                    content: Buffer.from(a.content),
+                    contentType: a.mime,
+                })),
+            });
+            return { messageId: info?.messageId };
+        },
+    };
+}
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @pattern-js/mod-email-smtp — SMTP driver for mod-email.
+ *
+ * All the sending logic lives in driver.ts; this mod just registers it on
+ * mod-email's service in `ready` (after every setup ran — two-phase install,
+ * so listing order in pattern.config.json doesn't matter). Host/port/user are
+ * account options in admin → System → Email; the password comes from the
+ * vault or an env var.
+ */
+import { type PatternMod } from "@pattern-js/core";
+import { type TransportFactory } from "./driver.js";
+export { smtpDriver, type SmtpTransportConfig, type TransportFactory } from "./driver.js";
+export interface SmtpEmailModOptions {
+    /** Override how transports are built (the test seam; default nodemailer.createTransport). */
+    transportFactory?: TransportFactory;
+}
+export declare function smtpEmailMod(options?: SmtpEmailModOptions): PatternMod;
+/** Ready-to-use with defaults (for `loadMods`/`engine.use`). */
+declare const _default: PatternMod;
+export default _default;
+//# 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;;;;;;;;GAQG;AAKH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAAwC,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1F,OAAO,EAAE,UAAU,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE1F,MAAM,WAAW,mBAAmB;IAClC,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAYD,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAkB1E;AAED,gEAAgE;;AAChE,wBAA8B"}

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * @pattern-js/mod-email-smtp — SMTP driver for mod-email.
+ *
+ * All the sending logic lives in driver.ts; this mod just registers it on
+ * mod-email's service in `ready` (after every setup ran — two-phase install,
+ * so listing order in pattern.config.json doesn't matter). Host/port/user are
+ * account options in admin → System → Email; the password comes from the
+ * vault or an env var.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { localFs, provideFilesystem } from "@pattern-js/runtime-node";
+import { defineMod } from "@pattern-js/core";
+import { EMAIL_SERVICE } from "@pattern-js/mod-email";
+import { smtpDriver } from "./driver.js";
+export { smtpDriver } from "./driver.js";
+/** The packaged docs/ chapter (the `docs` contribution points at "email-smtp-docs"). */
+function packagedDocs(engine) {
+    try {
+        const dir = fileURLToPath(new URL("../docs", import.meta.url));
+        if (existsSync(dir))
+            provideFilesystem(engine, "email-smtp-docs", localFs(dir));
+    }
+    catch {
+        /* packaged without docs — the contribution is simply skipped */
+    }
+}
+export function smtpEmailMod(options = {}) {
+    return defineMod({
+        name: "@pattern-js/mod-email-smtp",
+        docs: { filesystem: "email-smtp-docs", title: "Email · SMTP", order: 45 },
+        // `ready`, not `setup`: mod-email provides its service in setup, and every
+        // setup runs before any ready — order in the config is free.
+        ready: (engine) => {
+            packagedDocs(engine);
+            const svc = engine.service(EMAIL_SERVICE);
+            if (!svc) {
+                console.error("[pattern] @pattern-js/mod-email-smtp: email service not found — add @pattern-js/mod-email to your mods.");
+                return;
+            }
+            svc.registerDriver(smtpDriver(options.transportFactory));
+        },
+    });
+}
+/** Ready-to-use with defaults (for `loadMods`/`engine.use`). */
+export default smtpEmailMod();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,SAAS,EAAgC,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAqB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAmD,MAAM,aAAa,CAAC;AAE1F,OAAO,EAAE,UAAU,EAAmD,MAAM,aAAa,CAAC;AAO1F,wFAAwF;AACxF,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/D,IAAI,UAAU,CAAC,GAAG,CAAC;YAAE,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,UAA+B,EAAE;IAC5D,OAAO,SAAS,CAAC;QACf,IAAI,EAAE,4BAA4B;QAClC,IAAI,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,EAAE;QACzE,2EAA2E;QAC3E,6DAA6D;QAC7D,KAAK,EAAE,CAAC,MAAc,EAAE,EAAE;YACxB,YAAY,CAAC,MAAM,CAAC,CAAC;YACrB,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAe,aAAa,CAAC,CAAC;YACxD,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,OAAO,CAAC,KAAK,CACX,yGAAyG,CAC1G,CAAC;gBACF,OAAO;YACT,CAAC;YACD,GAAG,CAAC,cAAc,CAAC,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAC3D,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,gEAAgE;AAChE,eAAe,YAAY,EAAE,CAAC"}

package/docs/index.md

@@ -0,0 +1,39 @@
+# Email · SMTP
+
+`@pattern-js/mod-email-smtp` is the SMTP driver for `@pattern-js/mod-email`,
+built on [nodemailer](https://nodemailer.com) — any relay (SES, Postmark,
+Mailgun, your provider's SMTP endpoint), your own server, or a local catcher
+like [Mailpit](https://mailpit.axllent.org) in dev.
+
+```jsonc
+{ "mods": ["@pattern-js/mod-email", "@pattern-js/mod-email-smtp"] }
+```
+
+## Fields
+
+Configured per account in admin → **System → Email**:
+
+- **Option `host`** (required) — the SMTP server.
+- **Option `port`** — default `587`.
+- **Option `secure`** — `"true"` for implicit TLS (usually port 465);
+  leave unset/`"false"` for STARTTLS on 587, the common case.
+- **Option `user`** — the username; leave empty for an unauthenticated relay.
+- **Secret `pass`** — the password, by reference (vault name or env-var name
+  such as `SMTP_PASSWORD`); only needed when `user` is set.
+
+Press **Test** after saving — a real email proves host, TLS mode, credentials
+and From acceptance in one go.
+
+## Dev tip: a local catcher
+
+Run Mailpit (`docker run -p 1025:1025 -p 8025:8025 axllent/mailpit`), create a
+`default` account with `host: localhost`, `port: 1025`, no user — and every
+sign-in link lands in the catcher's inbox at `http://localhost:8025`. Real
+delivery mechanics, zero real emails.
+
+## Under the hood
+
+nodemailer handles the protocol (STARTTLS vs implicit TLS, AUTH mechanisms,
+MIME); transports pool connections and are cached per account config, and the
+cache self-invalidates when credentials rotate. SMTP errors surface as the
+run's error verbatim (`454 TLS required`, `535 authentication failed`, …).

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pattern-js/mod-email-smtp",
+  "version": "0.3.0-main.4a77893",
+  "description": "SMTP driver for @pattern-js/mod-email, built on nodemailer — any relay, your own server, or a local catcher. Host/port/user are account options in admin → System → Email; the password comes from the vault or an env var.",
+  "keywords": [
+    "pattern",
+    "mod",
+    "email",
+    "smtp",
+    "nodemailer",
+    "driver"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "dependencies": {
+    "nodemailer": "^8.0.1",
+    "zod": "^4.0.0",
+    "@pattern-js/core": "0.3.0-main.4a77893",
+    "@pattern-js/mod-email": "0.3.0-main.4a77893",
+    "@pattern-js/runtime-node": "0.3.0-main.4a77893"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/nodemailer": "^8.0.1",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makkr-studio/pattern.git",
+    "directory": "packages/mod-email-smtp"
+  },
+  "homepage": "https://github.com/makkr-studio/pattern#readme",
+  "bugs": "https://github.com/makkr-studio/pattern/issues",
+  "author": "Makkr Studio (https://github.com/makkr-studio)",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}