@ultimat3/mail 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+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,120 @@
+# @ultimat3/mail ✉️
+
+Transactional email as data. One template renders **both** an HTML part and a plain-text part,
+every string is an i18n key, every colour is a design token, and delivery is a job.
+
+```ts
+import { defineMail, send, blocks, t } from '@ultimat3/mail';
+
+export const receiptMail = defineMail({
+  id: 'receipt',
+  subject: 'mail.receipt.subject',            // an i18n key, never a literal
+  input: t.object({ name: t.string, url: t.url }),
+  template: ({ data }) => [
+    blocks.heading('mail.receipt.heading', { name: data.name }),
+    blocks.paragraph('mail.receipt.body'),
+    blocks.button('mail.receipt.cta', data.url),
+  ],
+});
+
+await send(receiptMail, { name: user.name, url }, { to: user.email, locale: ctx.locale });
+```
+
+`send` validates `data` through the mail's schema, renders, then enqueues `mail.send`. It
+delivers inline only when `{ sync: true }` is passed or no job driver is configured.
+
+## Rules
+
+| Rule | Why |
+|---|---|
+| `locale` is required by the **type** | a mail is read hours later; there is no ambient request locale to fall back to. `X_MAIL_LOCALE_MISSING` is the backstop for JS callers |
+| Text part is mandatory | HTML-only mail scores as spam and is unreadable to screen readers. Empty text ⇒ `X_MAIL_TEXT_MISSING` |
+| Text is derived from blocks | never scraped out of the HTML, so the two parts cannot drift |
+| Every string is a key | `mail.<id>.<slot>`; English lives in `src/catalog.ts` and app catalogs override it |
+| Every colour is a token | `MAIL_TOKENS` in `layout.ts` holds light + dark hexes; templates never see a hex |
+| Every date takes an IANA zone | `options.tz`, else `ctx.tz`, else `UTC` |
+| Sending is a job | `retry: { attempts: 5, backoff: 'exponential' }`, idempotency key derived from `(mailId, recipients, hash(rendered))` |
+
+## Drivers
+
+`setMailDriver(driver)` once at boot. Asking for one that was never set is
+`X_MAIL_DRIVER_UNAVAILABLE`.
+
+| Driver | Use | Behaviour |
+|---|---|---|
+| `createMemoryDriver()` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel |
+| `createLogDriver()` | workers without credentials | one structured line per message through core's `logger`; bodies never logged |
+| `createSmtpDriver({ url, from })` | prod | real ESMTP over `Bun.connect`: STARTTLS, `AUTH PLAIN`/`LOGIN`, quoted-printable MIME |
+| `createResendDriver({ apiKey, from })` | prod | one `POST /emails`, `Idempotency-Key` on every request |
+
+### Which one a boot installs
+
+`selectMailDriver(env)` is the one answer, and `x dev` calls it — an unset variable means the
+embedded default, the same law the database, event bus and storage bindings follow. Nothing about
+the app changes between environments; the credential does.
+
+| env | driver |
+|---|---|
+| *(nothing set)* | `createMemoryDriver()` — caught, never sent |
+| `SMTP_URL` + `MAIL_FROM` | `createSmtpDriver(...)`, `MAIL_POOL_SIZE` optional |
+| `RESEND_API_KEY` + `MAIL_FROM` | `createResendDriver(...)` |
+
+Both credentials at once is `X_CONFIG_INVALID` rather than a winner picked for you, and a
+transport with no `MAIL_FROM` is refused at boot instead of on the first send. A host that is not
+`x dev` calls `selectMailDriver` itself, or constructs a driver directly — `setMailDriver` is the
+only seam either way.
+
+### SMTP
+
+`smtps://user:pass@host:465` is implicit TLS; `smtp://host:587` starts in the clear and upgrades
+with STARTTLS. Credentials are percent-decoded, so a password with `@` or `/` works.
+
+| Rule | Why |
+|---|---|
+| A server offering no STARTTLS is refused | the message *and* the password would cross in the clear. `allowInsecure: true` is the explicit opt-out |
+| Capabilities are re-read after STARTTLS | most servers only advertise `AUTH` once encrypted, and a cleartext EHLO can be stripped in flight |
+| Any rejected recipient fails the send | delivering to three of four addresses and reporting success is the one outcome a caller cannot detect |
+| `poolSize` (default 4) caps concurrent connections | a burst of sends queues instead of opening one socket each |
+| `Bcc` never reaches a header | it travels in `RCPT TO` only |
+| The reported `id` is the `Message-ID` | an SMTP `250` carries nothing a caller could correlate. It is not derived from the idempotency key, which holds the recipient list |
+
+### Resend
+
+`RESEND_API_KEY` and a verified sending domain. Every request carries `Idempotency-Key:
+mailIdempotencyKey(message)` — a job retry after a timeout hands Resend the identical message, and
+that header is what makes it one email. 408/409/425/429 and 5xx are retryable; every other non-2xx
+is a configuration problem that retrying cannot fix.
+
+## Framework mails
+
+Registered by importing them. `FRAMEWORK_MAILS` is the list `x mail list` prints.
+
+| id | Input |
+|---|---|
+| `welcome` | `{ name, appName, url }` |
+| `verify-email` | `{ name, url, expiresMinutes }` |
+| `reset-password` | `{ name, url, expiresMinutes }` |
+| `invite` | `{ inviterName, orgName, url, expiresHours }` |
+| `mfa-enrolled` | `{ name, method, at }` |
+| `security-alert` | `{ name, event, ip, at }` |
+
+Translating them = shipping `mail.*` keys in an app catalog. Never edit a template.
+
+## Errors
+
+| Code | Fix |
+|---|---|
+| `X_MAIL_LOCALE_MISSING` | `send(mail, data, { to, locale: ctx.locale })` |
+| `X_MAIL_TEMPLATE_UNKNOWN` | export a `defineMail({ id })` and import it (also raised for an unregistered layout) |
+| `X_MAIL_DUPLICATE` | rename one of two `defineMail({ id })` declarations |
+| `X_MAIL_TEXT_MISSING` | add a text-bearing block to the template |
+| `X_MAIL_DRIVER_UNAVAILABLE` | `setMailDriver(createMemoryDriver())` at boot |
+| `X_MAIL_HEADER_INVALID` | strip CR/LF from the interpolated value before it reaches a header |
+| `X_MAIL_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help |
+
+## Commands
+
+```bash
+bun test packages/mail
+bun run --filter @ultimat3/mail typecheck
+```

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ultimat3/mail",
+  "version": "1.0.0",
+  "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/mail"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/i18n": "1.0.0",
+    "@ultimat3/jobs": "1.0.0",
+    "@ultimat3/schema": "1.0.0",
+    "@ultimat3/time": "1.0.0"
+  }
+}

package/src/base64.ts

@@ -0,0 +1,9 @@
+// Single responsibility: base64 over UTF-8 bytes. RFC 2047 encoded words and SMTP AUTH need the
+// same operation, and `btoa` alone throws above code point 0xFF — so the string is encoded to
+// bytes first and each byte re-packed as one Latin-1 char, which is what `btoa` actually takes.
+
+export function base64Utf8(value: string): string {
+  let binary = '';
+  for (const byte of new TextEncoder().encode(value)) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}

package/src/blocks.d.ts

@@ -0,0 +1,47 @@
+import type { TranslateVars, Translator } from '@ultimat3/i18n';
+export type CalloutTone = 'info' | 'danger';
+export type MailBlock = {
+    readonly kind: 'heading';
+    readonly key: string;
+    readonly vars?: TranslateVars | undefined;
+} | {
+    readonly kind: 'paragraph';
+    readonly key: string;
+    readonly vars?: TranslateVars | undefined;
+} | {
+    readonly kind: 'button';
+    readonly key: string;
+    readonly href: string;
+    readonly vars?: TranslateVars | undefined;
+} | {
+    readonly kind: 'callout';
+    readonly key: string;
+    readonly tone: CalloutTone;
+    readonly vars?: TranslateVars | undefined;
+}
+/** A label key plus an already-localised value (a date, an IP, a method name). */
+ | {
+    readonly kind: 'detail';
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly kind: 'divider';
+};
+/** Block constructors, so a template never hand-writes an object literal or a colour. */
+export declare const blocks: Readonly<{
+    heading: (key: string, vars?: TranslateVars) => MailBlock;
+    paragraph: (key: string, vars?: TranslateVars) => MailBlock;
+    button: (key: string, href: string, vars?: TranslateVars) => MailBlock;
+    callout: (key: string, tone: CalloutTone, vars?: TranslateVars) => MailBlock;
+    detail: (key: string, value: string) => MailBlock;
+    divider: () => MailBlock;
+}>;
+export interface TemplateArgs<I> {
+    readonly data: I;
+    readonly t: Translator;
+    readonly locale: string;
+    /** IANA zone. Every date in a mail is formatted with it — never with the server's zone. */
+    readonly tz: string;
+}
+export type MailTemplate<I> = (args: TemplateArgs<I>) => readonly MailBlock[];
+//# sourceMappingURL=blocks.d.ts.map

package/src/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["blocks.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5C,MAAM,MAAM,SAAS,GACjB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAAE,GAC/F;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC3C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC3C;AACH,kFAAkF;GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,yFAAyF;AACzF,eAAO,MAAM,MAAM;mBACF,MAAM,SAAS,aAAa,KAAG,SAAS;qBACtC,MAAM,SAAS,aAAa,KAAG,SAAS;kBAC3C,MAAM,QAAQ,MAAM,SAAS,aAAa,KAAG,SAAS;mBAMrD,MAAM,QAAQ,WAAW,SAAS,aAAa,KAAG,SAAS;kBAM5D,MAAM,SAAS,MAAM,KAAG,SAAS;mBAClC,SAAS;EACtB,CAAC;AAEH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,CAAC,EAAE,UAAU,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,SAAS,SAAS,EAAE,CAAC"}

package/src/blocks.js

@@ -0,0 +1,23 @@
+// Single responsibility: the vocabulary a template writes in. A mail body is a list of blocks
+// carrying i18n KEYS, never markup and never a colour — that is what makes one template able
+// to produce an HTML part and a text part, and what keeps translation out of the renderer.
+/** Block constructors, so a template never hand-writes an object literal or a colour. */
+export const blocks = Object.freeze({
+    heading: (key, vars) => ({ kind: 'heading', key, vars }),
+    paragraph: (key, vars) => ({ kind: 'paragraph', key, vars }),
+    button: (key, href, vars) => ({
+        kind: 'button',
+        key,
+        href,
+        vars,
+    }),
+    callout: (key, tone, vars) => ({
+        kind: 'callout',
+        key,
+        tone,
+        vars,
+    }),
+    detail: (key, value) => ({ kind: 'detail', key, value }),
+    divider: () => ({ kind: 'divider' }),
+});
+//# sourceMappingURL=blocks.js.map

package/src/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["blocks.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,6FAA6F;AAC7F,2FAA2F;AAyB3F,yFAAyF;AACzF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,OAAO,EAAE,CAAC,GAAW,EAAE,IAAoB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IAC3F,SAAS,EAAE,CAAC,GAAW,EAAE,IAAoB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;IAC/F,MAAM,EAAE,CAAC,GAAW,EAAE,IAAY,EAAE,IAAoB,EAAa,EAAE,CAAC,CAAC;QACvE,IAAI,EAAE,QAAQ;QACd,GAAG;QACH,IAAI;QACJ,IAAI;KACL,CAAC;IACF,OAAO,EAAE,CAAC,GAAW,EAAE,IAAiB,EAAE,IAAoB,EAAa,EAAE,CAAC,CAAC;QAC7E,IAAI,EAAE,SAAS;QACf,GAAG;QACH,IAAI;QACJ,IAAI;KACL,CAAC;IACF,MAAM,EAAE,CAAC,GAAW,EAAE,KAAa,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACnF,OAAO,EAAE,GAAc,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;CAChD,CAAC,CAAC"}

package/src/blocks.ts

@@ -0,0 +1,56 @@
+// Single responsibility: the vocabulary a template writes in. A mail body is a list of blocks
+// carrying i18n KEYS, never markup and never a colour — that is what makes one template able
+// to produce an HTML part and a text part, and what keeps translation out of the renderer.
+
+import type { TranslateVars, Translator } from '@ultimat3/i18n';
+
+export type CalloutTone = 'info' | 'danger';
+
+export type MailBlock =
+  | { readonly kind: 'heading'; readonly key: string; readonly vars?: TranslateVars | undefined }
+  | { readonly kind: 'paragraph'; readonly key: string; readonly vars?: TranslateVars | undefined }
+  | {
+      readonly kind: 'button';
+      readonly key: string;
+      readonly href: string;
+      readonly vars?: TranslateVars | undefined;
+    }
+  | {
+      readonly kind: 'callout';
+      readonly key: string;
+      readonly tone: CalloutTone;
+      readonly vars?: TranslateVars | undefined;
+    }
+  /** A label key plus an already-localised value (a date, an IP, a method name). */
+  | { readonly kind: 'detail'; readonly key: string; readonly value: string }
+  | { readonly kind: 'divider' };
+
+/** Block constructors, so a template never hand-writes an object literal or a colour. */
+export const blocks = Object.freeze({
+  heading: (key: string, vars?: TranslateVars): MailBlock => ({ kind: 'heading', key, vars }),
+  paragraph: (key: string, vars?: TranslateVars): MailBlock => ({ kind: 'paragraph', key, vars }),
+  button: (key: string, href: string, vars?: TranslateVars): MailBlock => ({
+    kind: 'button',
+    key,
+    href,
+    vars,
+  }),
+  callout: (key: string, tone: CalloutTone, vars?: TranslateVars): MailBlock => ({
+    kind: 'callout',
+    key,
+    tone,
+    vars,
+  }),
+  detail: (key: string, value: string): MailBlock => ({ kind: 'detail', key, value }),
+  divider: (): MailBlock => ({ kind: 'divider' }),
+});
+
+export interface TemplateArgs<I> {
+  readonly data: I;
+  readonly t: Translator;
+  readonly locale: string;
+  /** IANA zone. Every date in a mail is formatted with it — never with the server's zone. */
+  readonly tz: string;
+}
+
+export type MailTemplate<I> = (args: TemplateArgs<I>) => readonly MailBlock[];

package/src/catalog.d.ts

@@ -0,0 +1,6 @@
+import { type Catalog, type Locale, type NestedCatalog } from '@ultimat3/i18n';
+export declare const MAIL_CATALOG_SOURCE: NestedCatalog;
+export declare const MAIL_CATALOG: Catalog;
+/** Called at boot next to `registerFrameworkCatalog()`. Idempotent. */
+export declare function registerMailCatalog(locale?: Locale): void;
+//# sourceMappingURL=catalog.d.ts.map

package/src/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["catalog.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,MAAM,EAEX,KAAK,aAAa,EAEnB,MAAM,gBAAgB,CAAC;AAExB,eAAO,MAAM,mBAAmB,EAAE,aAkEjC,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,OAA0C,CAAC;AAEtE,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,MAAuB,GAAG,IAAI,CAEzE"}

package/src/catalog.js

@@ -0,0 +1,78 @@
+// Single responsibility: the English source strings for the keys this package's templates
+// emit. Templates carry keys only; the words live here (and in an app's own catalogs, which
+// are registered after this one and therefore win). Translating a framework mail means
+// shipping `mail.*` in an app catalog — never editing a template.
+import { DEFAULT_LOCALE, loadCatalog, registerCatalog, } from '@ultimat3/i18n';
+export const MAIL_CATALOG_SOURCE = {
+    mail: {
+        footer: {
+            legal: 'You received this message because of activity on your account.',
+            help: 'Questions? Reply to this email and a human will answer.',
+            unsubscribe: 'Unsubscribe',
+        },
+        welcome: {
+            subject: 'Welcome to {appName}',
+            preheader: 'Your {appName} account is ready.',
+            heading: 'Welcome, {name}',
+            body: 'Your {appName} account is ready. Pick up where you left off any time.',
+            cta: 'Open {appName}',
+        },
+        'verify-email': {
+            subject: 'Verify your email address',
+            preheader: 'One click and this address is confirmed.',
+            heading: 'Verify your email, {name}',
+            body: 'Confirm this address so we can secure your account and reach you when it matters.',
+            cta: 'Verify email address',
+            expiry_one: 'This link expires in {count} minute.',
+            expiry_other: 'This link expires in {count} minutes.',
+            ignore: 'If you did not create this account, ignore this message.',
+        },
+        'reset-password': {
+            subject: 'Reset your password',
+            preheader: 'A link to choose a new password.',
+            heading: 'Reset your password, {name}',
+            body: 'Choose a new password. Existing sessions stay signed in until you sign them out.',
+            cta: 'Choose a new password',
+            expiry_one: 'This link expires in {count} minute.',
+            expiry_other: 'This link expires in {count} minutes.',
+            ignore: 'If you did not ask for this, no action is needed — your password is unchanged.',
+        },
+        invite: {
+            subject: '{inviterName} invited you to {orgName}',
+            preheader: 'Your invitation to {orgName}.',
+            heading: 'Join {orgName}',
+            body: '{inviterName} invited you to collaborate in {orgName}.',
+            cta: 'Accept invitation',
+            expiry_one: 'This invitation expires in {count} hour.',
+            expiry_other: 'This invitation expires in {count} hours.',
+        },
+        'mfa-enrolled': {
+            subject: 'Two-factor authentication is on',
+            preheader: 'A new second factor now protects your account.',
+            heading: 'Two-factor is on, {name}',
+            body: 'Every sign-in now needs a second factor as well as your password.',
+            'method-label': 'Method',
+            'method-totp': 'Authenticator app',
+            'method-webauthn': 'Passkey or security key',
+            'method-sms': 'Text message',
+            'at-label': 'Enabled',
+            help: 'If this was not you, remove the factor and change your password immediately.',
+        },
+        'security-alert': {
+            subject: 'Security alert on your account',
+            preheader: 'Confirm recent activity on your account.',
+            heading: 'Security alert, {name}',
+            alert: 'We noticed activity on your account that we want you to confirm.',
+            'event-label': 'Event',
+            'ip-label': 'IP address',
+            'at-label': 'When',
+            help: 'If this was not you, change your password and sign out every other session.',
+        },
+    },
+};
+export const MAIL_CATALOG = loadCatalog(MAIL_CATALOG_SOURCE);
+/** Called at boot next to `registerFrameworkCatalog()`. Idempotent. */
+export function registerMailCatalog(locale = DEFAULT_LOCALE) {
+    registerCatalog(locale, MAIL_CATALOG);
+}
+//# sourceMappingURL=catalog.js.map

package/src/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["catalog.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,4FAA4F;AAC5F,uFAAuF;AACvF,kEAAkE;AAElE,OAAO,EAEL,cAAc,EAEd,WAAW,EAEX,eAAe,GAChB,MAAM,gBAAgB,CAAC;AAExB,MAAM,CAAC,MAAM,mBAAmB,GAAkB;IAChD,IAAI,EAAE;QACJ,MAAM,EAAE;YACN,KAAK,EAAE,gEAAgE;YACvE,IAAI,EAAE,yDAAyD;YAC/D,WAAW,EAAE,aAAa;SAC3B;QACD,OAAO,EAAE;YACP,OAAO,EAAE,sBAAsB;YAC/B,SAAS,EAAE,kCAAkC;YAC7C,OAAO,EAAE,iBAAiB;YAC1B,IAAI,EAAE,uEAAuE;YAC7E,GAAG,EAAE,gBAAgB;SACtB;QACD,cAAc,EAAE;YACd,OAAO,EAAE,2BAA2B;YACpC,SAAS,EAAE,0CAA0C;YACrD,OAAO,EAAE,2BAA2B;YACpC,IAAI,EAAE,mFAAmF;YACzF,GAAG,EAAE,sBAAsB;YAC3B,UAAU,EAAE,sCAAsC;YAClD,YAAY,EAAE,uCAAuC;YACrD,MAAM,EAAE,0DAA0D;SACnE;QACD,gBAAgB,EAAE;YAChB,OAAO,EAAE,qBAAqB;YAC9B,SAAS,EAAE,kCAAkC;YAC7C,OAAO,EAAE,6BAA6B;YACtC,IAAI,EAAE,kFAAkF;YACxF,GAAG,EAAE,uBAAuB;YAC5B,UAAU,EAAE,sCAAsC;YAClD,YAAY,EAAE,uCAAuC;YACrD,MAAM,EAAE,gFAAgF;SACzF;QACD,MAAM,EAAE;YACN,OAAO,EAAE,wCAAwC;YACjD,SAAS,EAAE,+BAA+B;YAC1C,OAAO,EAAE,gBAAgB;YACzB,IAAI,EAAE,wDAAwD;YAC9D,GAAG,EAAE,mBAAmB;YACxB,UAAU,EAAE,0CAA0C;YACtD,YAAY,EAAE,2CAA2C;SAC1D;QACD,cAAc,EAAE;YACd,OAAO,EAAE,iCAAiC;YAC1C,SAAS,EAAE,gDAAgD;YAC3D,OAAO,EAAE,0BAA0B;YACnC,IAAI,EAAE,mEAAmE;YACzE,cAAc,EAAE,QAAQ;YACxB,aAAa,EAAE,mBAAmB;YAClC,iBAAiB,EAAE,yBAAyB;YAC5C,YAAY,EAAE,cAAc;YAC5B,UAAU,EAAE,SAAS;YACrB,IAAI,EAAE,8EAA8E;SACrF;QACD,gBAAgB,EAAE;YAChB,OAAO,EAAE,gCAAgC;YACzC,SAAS,EAAE,0CAA0C;YACrD,OAAO,EAAE,wBAAwB;YACjC,KAAK,EAAE,kEAAkE;YACzE,aAAa,EAAE,OAAO;YACtB,UAAU,EAAE,YAAY;YACxB,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,6EAA6E;SACpF;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAY,WAAW,CAAC,mBAAmB,CAAC,CAAC;AAEtE,uEAAuE;AACvE,MAAM,UAAU,mBAAmB,CAAC,MAAM,GAAW,cAAc;IACjE,eAAe,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;AACxC,CAAC"}

package/src/catalog.ts

@@ -0,0 +1,88 @@
+// Single responsibility: the English source strings for the keys this package's templates
+// emit. Templates carry keys only; the words live here (and in an app's own catalogs, which
+// are registered after this one and therefore win). Translating a framework mail means
+// shipping `mail.*` in an app catalog — never editing a template.
+
+import {
+  type Catalog,
+  DEFAULT_LOCALE,
+  type Locale,
+  loadCatalog,
+  type NestedCatalog,
+  registerCatalog,
+} from '@ultimat3/i18n';
+
+export const MAIL_CATALOG_SOURCE: NestedCatalog = {
+  mail: {
+    footer: {
+      legal: 'You received this message because of activity on your account.',
+      help: 'Questions? Reply to this email and a human will answer.',
+      unsubscribe: 'Unsubscribe',
+    },
+    welcome: {
+      subject: 'Welcome to {appName}',
+      preheader: 'Your {appName} account is ready.',
+      heading: 'Welcome, {name}',
+      body: 'Your {appName} account is ready. Pick up where you left off any time.',
+      cta: 'Open {appName}',
+    },
+    'verify-email': {
+      subject: 'Verify your email address',
+      preheader: 'One click and this address is confirmed.',
+      heading: 'Verify your email, {name}',
+      body: 'Confirm this address so we can secure your account and reach you when it matters.',
+      cta: 'Verify email address',
+      expiry_one: 'This link expires in {count} minute.',
+      expiry_other: 'This link expires in {count} minutes.',
+      ignore: 'If you did not create this account, ignore this message.',
+    },
+    'reset-password': {
+      subject: 'Reset your password',
+      preheader: 'A link to choose a new password.',
+      heading: 'Reset your password, {name}',
+      body: 'Choose a new password. Existing sessions stay signed in until you sign them out.',
+      cta: 'Choose a new password',
+      expiry_one: 'This link expires in {count} minute.',
+      expiry_other: 'This link expires in {count} minutes.',
+      ignore: 'If you did not ask for this, no action is needed — your password is unchanged.',
+    },
+    invite: {
+      subject: '{inviterName} invited you to {orgName}',
+      preheader: 'Your invitation to {orgName}.',
+      heading: 'Join {orgName}',
+      body: '{inviterName} invited you to collaborate in {orgName}.',
+      cta: 'Accept invitation',
+      expiry_one: 'This invitation expires in {count} hour.',
+      expiry_other: 'This invitation expires in {count} hours.',
+    },
+    'mfa-enrolled': {
+      subject: 'Two-factor authentication is on',
+      preheader: 'A new second factor now protects your account.',
+      heading: 'Two-factor is on, {name}',
+      body: 'Every sign-in now needs a second factor as well as your password.',
+      'method-label': 'Method',
+      'method-totp': 'Authenticator app',
+      'method-webauthn': 'Passkey or security key',
+      'method-sms': 'Text message',
+      'at-label': 'Enabled',
+      help: 'If this was not you, remove the factor and change your password immediately.',
+    },
+    'security-alert': {
+      subject: 'Security alert on your account',
+      preheader: 'Confirm recent activity on your account.',
+      heading: 'Security alert, {name}',
+      alert: 'We noticed activity on your account that we want you to confirm.',
+      'event-label': 'Event',
+      'ip-label': 'IP address',
+      'at-label': 'When',
+      help: 'If this was not you, change your password and sign out every other session.',
+    },
+  },
+};
+
+export const MAIL_CATALOG: Catalog = loadCatalog(MAIL_CATALOG_SOURCE);
+
+/** Called at boot next to `registerFrameworkCatalog()`. Idempotent. */
+export function registerMailCatalog(locale: Locale = DEFAULT_LOCALE): void {
+  registerCatalog(locale, MAIL_CATALOG);
+}

package/src/driver-env.ts

@@ -0,0 +1,105 @@
+// Single responsibility: environment → transport. The one place that decides which `MailDriver`
+// a boot installs, so `x dev`, a worker container and any custom host all resolve it identically.
+// The two production transports are useless until something constructs them from a credential;
+// this is that something, and it is keyed on env rather than a config field so the same image
+// deploys to every environment.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+import { createMemoryDriver, type MailDriver } from './driver';
+import { createResendDriver } from './driver-resend';
+import { createSmtpDriver } from './driver-smtp';
+
+/** The keys read here, and nothing else. Named once so docs and tests cannot drift from the code. */
+export const MAIL_ENV_KEYS = ['SMTP_URL', 'RESEND_API_KEY', 'MAIL_FROM', 'MAIL_POOL_SIZE'] as const;
+
+export type MailEnvironment = Readonly<Record<string, string | undefined>>;
+
+export interface MailSelection {
+  readonly driver: MailDriver;
+  /**
+   * Why this driver, in one line: the env key that selected it, or what to set to change it.
+   * A boot prints it, so "which transport is this process using" is never a guess.
+   */
+  readonly detail: string;
+}
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value.trim().length === 0 ? undefined : value.trim();
+
+/**
+ * Both transports put the address in the envelope and in `From:`, so neither can be built
+ * without it. Refused here rather than inside the driver: the cause names the env key that is
+ * missing, which is the thing an operator can actually set.
+ */
+function requireFrom(env: MailEnvironment, selectedBy: string): string {
+  const from = nonEmpty(env['MAIL_FROM']);
+  if (from === undefined) {
+    throw new ConfigInvalidError({
+      cause: `${selectedBy} selects a mail transport, but MAIL_FROM is unset — no envelope sender`,
+      fix: 'set MAIL_FROM="App <no-reply@yourdomain.test>" in .env.production',
+      meta: { selectedBy, missing: 'MAIL_FROM' },
+    });
+  }
+  return from;
+}
+
+/**
+ * `Number('abc')` is `NaN`, and `NaN` reaches the driver as "poolSize: NaN" — an accurate but
+ * useless cause, because the operator set a string in a file and the driver never saw the key.
+ * Parsed at the boundary so the error names `MAIL_POOL_SIZE` instead.
+ */
+function poolSizeFrom(env: MailEnvironment): number | undefined {
+  const raw = nonEmpty(env['MAIL_POOL_SIZE']);
+  if (raw === undefined) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new ConfigInvalidError({
+      cause: `MAIL_POOL_SIZE is "${raw}", which is not a whole number of connections >= 1`,
+      fix: 'set MAIL_POOL_SIZE=4 in .env.production, or unset it to keep the default',
+      meta: { MAIL_POOL_SIZE: raw },
+    });
+  }
+  return parsed;
+}
+
+/**
+ * A credential selects its transport; no credential catches mail in memory. Two credentials is
+ * the one case that cannot be answered by picking a winner — whichever this chose would be the
+ * one an operator did not mean half the time, and mail would silently leave by the wrong path.
+ */
+export function selectMailDriver(env: MailEnvironment): MailSelection {
+  const smtpUrl = nonEmpty(env['SMTP_URL']);
+  const resendKey = nonEmpty(env['RESEND_API_KEY']);
+
+  if (smtpUrl !== undefined && resendKey !== undefined) {
+    throw new ConfigInvalidError({
+      cause: 'SMTP_URL and RESEND_API_KEY are both set — two transports claim the same mail',
+      fix: 'unset one of them in .env.production: a process delivers through exactly one transport',
+      meta: { selected: ['SMTP_URL', 'RESEND_API_KEY'] },
+    });
+  }
+
+  if (smtpUrl !== undefined) {
+    const poolSize = poolSizeFrom(env);
+    return {
+      driver: createSmtpDriver({
+        url: smtpUrl,
+        from: requireFrom(env, 'SMTP_URL'),
+        ...(poolSize === undefined ? {} : { poolSize }),
+      }),
+      detail: 'SMTP_URL',
+    };
+  }
+
+  if (resendKey !== undefined) {
+    return {
+      driver: createResendDriver({ apiKey: resendKey, from: requireFrom(env, 'RESEND_API_KEY') }),
+      detail: 'RESEND_API_KEY',
+    };
+  }
+
+  return {
+    driver: createMemoryDriver(),
+    detail: 'caught in memory — set SMTP_URL or RESEND_API_KEY to deliver',
+  };
+}