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

package/docs/guides/delivery.md

@@ -0,0 +1,57 @@
+# Wiring sign-in email delivery
+
+The zero-config path: install mod-email + a driver, create one account, done.
+
+## 1. Install the mods
+
+```jsonc
+// pattern.config.json — after the identity mods
+{ "mods": [
+  "@pattern-js/mod-identity",
+  "@pattern-js/mod-auth-magic-link",
+  "@pattern-js/mod-email",
+  "@pattern-js/mod-email-resend",   // or @pattern-js/mod-email-smtp
+  ...
+] }
+```
+
+(Order doesn't actually matter — drivers find the email service through the
+two-phase install.) `create-pattern` wires all of this when you pick Resend or
+SMTP at the "Sign-in link delivery?" question.
+
+## 2. Create the `default` account
+
+Admin → **System → Email** → new account named `default`:
+
+- **Resend**: the API key, from the vault (System → Secrets) or an env var
+  such as `RESEND_API_KEY`. The From address must be on a domain you verified
+  with Resend.
+- **SMTP**: host (+ port/TLS/username as options) and the password as the one
+  secret. A local catcher like Mailpit (`host: localhost`, `port: 1025`, no
+  auth) is great in dev.
+
+Press **Test** — it sends a real email to an address you type, which proves
+credentials, From address and inbox placement in one go.
+
+## 3. There is no step 3
+
+The packaged **`email.deliver-token`** workflow (visible in the admin catalog)
+is already subscribed to identity's `identity.deliverToken` hook. It probes
+for the `default` account on every delivery:
+
+- no account → the payload passes through untouched and the link prints to
+  the server console, exactly as before;
+- account exists → the link goes by email (subject "Your login link", a
+  button, a plain-text alternative) and the console stays silent;
+- the send throws (bad key, provider down) → identity logs a warning and the
+  console fallback still prints the link — you are never locked out.
+
+## Customizing the email
+
+Open `email.deliver-token` in the admin editor. The wording lives in two
+`core.string.template` nodes (`{{purpose}}`, `{{url}}`, `{{email}}` from the
+hook payload); the sender is the `email.account` node (point it at another
+account name if you keep `default` for something else). For a bigger rewrite,
+fork the workflow, subscribe your fork to the same hook (a `boundary.hook`
+trigger with `hook: "identity.deliverToken"`), and set a lower `priority` so
+it runs first — return `delivered: true` and the chain stops falling through.

package/docs/index.md

@@ -0,0 +1,95 @@
+# Email
+
+`@pattern-js/mod-email` is the **email contract**: it owns the accounts, the
+`email.send` / `email.account` ops, the admin page, and a packaged workflow
+that delivers identity sign-in links. It sends nothing by itself — a **driver
+mod** does the wire work: `@pattern-js/mod-email-resend` (the Resend API) or
+`@pattern-js/mod-email-smtp` (any SMTP relay, via nodemailer). Several drivers
+can live in one runtime side by side.
+
+```jsonc
+{ "mods": ["@pattern-js/mod-email", "@pattern-js/mod-email-resend"] }
+```
+
+## Accounts
+
+The one persisted concept is the **account** — a memorable name bound to a
+driver, a From address, sourced secrets and driver options. Two accounts of
+the same driver with different credentials are just two records (prod + a
+staging relay, a marketing sender + an alerts sender). Manage them in admin →
+**System → Email**; the form generates itself from whatever fields the
+registered drivers declare, and the **Test** button sends a real email so you
+verify end-to-end delivery, not a wiring check.
+
+The `"default"` account is the convention everything falls back to: an
+`email.send` node with nothing wired uses it, and the sign-in delivery
+workflow probes for it.
+
+Credentials never sit in workflow values or in the accounts file — an account
+stores *references* (`{ source: "vault" | "env", key }`), resolved at send
+time. The value flowing on edges is an `EmailAccountRef` (the account NAME),
+so re-pointing an account in admin instantly re-targets every workflow using
+it — the same move as mod-ai's model aliases.
+
+## Sending from a workflow
+
+`email.send` takes `to` + `subject` + a body. Write the body once in
+**`markdown`** — it renders to inline-styled HTML plus a plain-text
+alternative, and a paragraph that is exactly one link becomes a button — or
+pass explicit `html`/`text`, which win per part. Attachments accept in-memory
+media (`{ bytes, mime }`, what `ai.image.generate` outputs), blob references
+(`{ blobId }`, what `store.blob.put` returns), or literal files
+(`{ filename, content }`). Pick a non-default sender by wiring an
+`email.account` node into its `account` input.
+
+## Sign-in links, delivered
+
+mod-identity delivers login/invite links through its `identity.deliverToken`
+hook, with a console fallback. This mod ships a visible workflow —
+**`email.deliver-token`** — subscribed to that hook: while no `default`
+account exists it passes the payload through untouched (links keep printing to
+the console, nothing to configure), and the moment you create the account,
+sign-in links go by email. A broken account never locks you out: the send
+fails, identity logs a warning, and the console fallback prints the link
+anyway. Open the workflow in the admin editor to reword the email (two
+`core.string.template` nodes) or fork it entirely — see the
+[delivery guide](guides/delivery.md).
+
+## Writing a driver
+
+A driver mod registers an `EmailDriverSpec` on the email service in `ready()`:
+
+```ts
+import { EMAIL_SERVICE, type EmailService } from "@pattern-js/mod-email";
+
+export default defineMod({
+  name: "my-email-driver",
+  ready: (engine) => {
+    engine.service<EmailService>(EMAIL_SERVICE)?.registerDriver({
+      id: "acme",
+      label: "Acme Mail",
+      secrets: [{ field: "apiKey", label: "API key", required: true }],
+      options: [{ field: "region", label: "Region", placeholder: "us-east-1" }],
+      send: async (message, creds, options) => {
+        // message is fully normalized: from/to[]/subject/html/text/attachments (bytes)
+        return { messageId: "..." };
+      },
+    });
+  },
+});
+```
+
+The declared `secrets`/`options` fields drive the account form in admin — a
+driver mod ships zero UI. `mod-email-resend` is the worked example to copy
+(one fetch, ~60 lines).
+
+## Config
+
+Defaults work from the bare config entry. The accounts file lives at
+`.pattern-data/email-config.json`; to move it, export a local wrapper mod:
+
+```js
+// mods/email.mjs
+import { emailMod } from "@pattern-js/mod-email";
+export default emailMod({ configPath: "./.pattern-data/email-config.json" });
+```

package/docs/ops/email.account.md

@@ -0,0 +1 @@
+Resolve an account name (configured in admin → System → Email) to an account reference for `email.send` — the ref carries the NAME, never the credentials, so re-pointing the account in admin instantly re-targets every workflow using it. Defaults to `"default"`. Two modes: `required: true` (the default) throws with an admin hint when the account is missing — the right failure for a workflow that must send; `required: false` probes instead, outputting `account: null` + `configured: false` so a `core.flow.branch` can take a fallback path — exactly how the packaged `email.deliver-token` workflow decides between emailing a sign-in link and leaving the console fallback alone.

package/docs/ops/email.send.md

@@ -0,0 +1 @@
+Send one email through a configured account. Write the body once in `markdown` — it renders to inline-styled HTML plus a plain-text alternative, and a paragraph that is exactly one link becomes a button (the "click to sign in" line costs nothing to author) — or pass explicit `html`/`text`, which win per part. Attachments accept in-memory media (`{bytes,mime}`, what the AI generation ops output), blob references (`{blobId}`, what `store.blob.put` returns — mod-store resolves the bytes), or literal files (`{filename,content}`). With nothing wired to `account` it uses the `"default"` account; wire an `email.account` node (or a bare name string) to pick another. `from` defaults to the account's From and can be overridden per message. Credentials resolve at send time from the vault or env — they never ride the graph.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@pattern-js/mod-email",
+  "version": "0.3.0-main.4a77893",
+  "description": "Transactional email for Pattern — the contract mod. Admin-configured accounts (provider + sourced secrets + from), driver mods plug in (Resend, SMTP, …), one email.send op, and a packaged workflow that delivers identity sign-in links the moment a default account exists.",
+  "keywords": [
+    "pattern",
+    "mod",
+    "email",
+    "transactional-email",
+    "smtp",
+    "resend"
+  ],
+  "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": {
+    "zod": "^4.0.0",
+    "@pattern-js/core": "0.3.0-main.4a77893",
+    "@pattern-js/runtime-node": "0.3.0-main.4a77893"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "@pattern-js/mod-identity": "0.3.0-main.4a77893",
+    "@pattern-js/mod-auth-magic-link": "0.3.0-main.4a77893"
+  },
+  "engines": {
+    "node": ">=22.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makkr-studio/pattern.git",
+    "directory": "packages/mod-email"
+  },
+  "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"
+  }
+}