@wtfalch/mailer 0.1.0 → 0.3.0

package/README.md

@@ -31,7 +31,11 @@ await send({
     fromAddress: 'no-reply@acme.wtfalch.dev',
     fromName: 'Acme', // optional
     replyTo: 'support@acme.wtfalch.dev', // optional
+    locale: 'nb', // optional, defaults to 'en' -- picks which language's copy renders
   },
+  attachments: [ // optional
+    { filename: 'invoice.pdf', contentType: 'application/pdf', content: 'JVBERi0xLjQK...' }, // content is base64
+  ],
   transport: createDevTransport(), // writes to .mailer/dev instead of sending
 });
 ```
@@ -41,20 +45,50 @@ await send({
 missing transport fails loudly instead of silently no-op'ing or making a
 live call with no key.
 
+A held key: however you resolve `apiKey` for `createResendTransport`,
+mailer never fetches or stores it. In the estate, the caller resolves the
+org's Resend key as a held key from `@wtfalch/keys` and passes it in on
+every call.
+
+### Locale
+
+Every template ships English (`en`, the fallback) and Norwegian bokmål
+(`nb`) copy. Set `from.locale` to pick which one renders; leave it unset
+for English. An unrecognised locale falls back to English rather than
+throwing -- the same fallback shape the auth broker's own `compose()`
+already uses (`WORDS[sender.locale] ?? WORDS.en`).
+
 ### Transports
 
+A held key: however you resolve `apiKey` for either transport below, mailer
+never fetches or stores it. In the estate, the caller resolves the org's
+Resend or Lettermint key as a held key from `@wtfalch/keys` and passes it
+in on every call.
+
 - `createDevTransport({ dir })` -- writes each message to
   `<dir>/<timestamp>-<id>.json` (default `dir`: `.mailer/dev`). Never
   opens a network connection.
 - `createResendTransport({ apiKey })` -- sends over Resend. Needs either
   `apiKey` (a plain string -- resolve it yourself, e.g. from
   `@wtfalch/keys`) or `client`, a minimal structural `ResendLike` for
-  injecting a fake in tests.
+  injecting a fake in tests. `resend` is an optional peer dependency
+  (`^4.1.0`) -- install it yourself if you use this transport with `apiKey`;
+  not needed if you always inject `client`, or if you only use
+  `createLettermintTransport` below. Attachments passed to `send()` are
+  forwarded as Resend's own `{ filename, content, content_type }` shape.
+- `createLettermintTransport({ apiKey })` -- sends over Lettermint's
+  Sending API (EU-hosted). Needs either `apiKey` (the org's Lettermint
+  Project API token, `lm_...` -- resolve it yourself, e.g. from
+  `@wtfalch/keys`) or `client`, a minimal structural `LettermintLike` for
+  injecting a fake in tests. Speaks plain `fetch`, no SDK dependency; pass
+  `fetch` to inject your own. If Lettermint refuses the send because the
+  `from` domain is not verified, or not allowed for the sending project, the
+  call rejects with `LettermintDomainRefusedError` rather than a generic
+  `Error`. Attachments passed to `send()` are forwarded as Lettermint's own
+  `{ filename, content, content_type }` shape.
 
 ### Templates
 
-`invitation` is the only template shipped so far:
-
 ```ts
 interface InvitationData {
   organisationName: string;
@@ -65,6 +99,41 @@ interface InvitationData {
 }
 ```
 
+Seven account templates for the flows an auth system needs --
+`verify`, `reset`, `link` (a sign-in link), `invite` (an account invite),
+`email-change`, `email-change-notice` and `email-changed`. The first five
+share one shape; `email-change-notice` and `email-changed` go to the
+address a change does *not* touch (a request notice, and a completed-change
+notice), so they carry no link or code, only the new address to notice:
+
+```ts
+interface AccountMailData {
+  productName: string;
+  url: string;
+  code: string;
+  brand?: { name: string; logoUrl?: string; primaryColor?: string };
+}
+
+interface EmailChangeNoticeData {
+  productName: string;
+  newEmail: string;
+  brand?: { name: string; logoUrl?: string; primaryColor?: string };
+}
+```
+
+```ts
+await send({
+  template: 'verify',
+  to: 'person@example.com',
+  data: { productName: 'Acme', url: 'https://app.example.com/verify/abc', code: '482913' },
+  from: { fromAddress: 'no-reply@acme.wtfalch.dev', locale: 'nb' },
+});
+```
+
+Modelled on the auth broker's own account mail (`auth/broker/src/mail.ts`)
+so a caller there can move to `@wtfalch/mailer` directly -- all seven of
+the broker's `Kind`s are covered.
+
 ## Tests
 
 From `packages/mailer`:

package/dist/header-safe.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Throws `MailerConfigError` if `value` contains a control character, so a
+ * caller-supplied string never reaches a mail header carrying one. Returns
+ * `value` unchanged otherwise, for use inline at each call site.
+ */
+export declare function assertHeaderSafe(value: string, field: string): string;

package/dist/header-safe.js

@@ -0,0 +1,31 @@
+import { MailerConfigError } from './types.js';
+/** The C0 range (0x00-0x1F, which includes CR and LF) plus DEL (0x7F). */
+function isControlCharCode(code) {
+    return code <= 0x1f || code === 0x7f;
+}
+/**
+ * True if `value` contains a CR, LF or any other control character. Checked
+ * by character code rather than a regex, since a header-bound field is
+ * built in part from caller-supplied strings (an inviter's name, an org's
+ * name) and this package must not depend on Resend's own defence against
+ * header injection to reject them (see issue #3).
+ */
+function hasControlCharacter(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (isControlCharCode(code))
+            return true;
+    }
+    return false;
+}
+/**
+ * Throws `MailerConfigError` if `value` contains a control character, so a
+ * caller-supplied string never reaches a mail header carrying one. Returns
+ * `value` unchanged otherwise, for use inline at each call site.
+ */
+export function assertHeaderSafe(value, field) {
+    if (hasControlCharacter(value)) {
+        throw new MailerConfigError(`mailer: "${field}" contains a control character (e.g. CR or LF) and cannot be used in a mail header.`);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-export type { Brand, MailMessage, SenderIdentity, SendResult } from './types.js';
-export { MailerConfigError } from './types.js';
-export type { DevTransportOptions, OutgoingMail, ResendLike, ResendTransportOptions, Transport, } from './transport.js';
-export { createDevTransport, createResendTransport, defaultTransport } from './transport.js';
+export type { Attachment, Brand, Locale, MailMessage, SenderIdentity, SendResult, } from './types.js';
+export { DEFAULT_LOCALE, MailerConfigError } from './types.js';
+export type { DevTransportOptions, LettermintAttachment, LettermintFetchLike, LettermintLike, LettermintSendPayload, LettermintTransportOptions, OutgoingMail, ResendLike, ResendTransportOptions, Transport, } from './transport.js';
+export { createDevTransport, createLettermintTransport, createResendTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
 export type { SendOptions } from './send.js';
 export { send } from './send.js';
 export type { TemplateData, TemplateName } from './templates/index.js';
 export { templates } from './templates/index.js';
 export type { InvitationData } from './templates/invitation.js';
 export { renderInvitation } from './templates/invitation.js';
+export type { AccountMailData, EmailChangeNoticeData } from './templates/account.js';
+export { renderAccountInvite, renderEmailChange, renderEmailChangeNotice, renderEmailChanged, renderReset, renderSignInLink, renderVerify, } from './templates/account.js';

package/dist/index.js

@@ -1,5 +1,6 @@
-export { MailerConfigError } from './types.js';
-export { createDevTransport, createResendTransport, defaultTransport } from './transport.js';
+export { DEFAULT_LOCALE, MailerConfigError } from './types.js';
+export { createDevTransport, createLettermintTransport, createResendTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
 export { send } from './send.js';
 export { templates } from './templates/index.js';
 export { renderInvitation } from './templates/invitation.js';
+export { renderAccountInvite, renderEmailChange, renderEmailChangeNotice, renderEmailChanged, renderReset, renderSignInLink, renderVerify, } from './templates/account.js';

package/dist/layout.d.ts

@@ -1,9 +1,4 @@
 import type { Brand, MailMessage } from './types.js';
-/**
- * The one rule. Ampersand first, or it double-escapes everything after it.
- * Same rule and reason as app-template's `src/lib/marketing/render.ts`.
- */
-export declare function escapeHtml(value: string): string;
 export interface LayoutOptions {
     readonly subject: string;
     /** Already-escaped HTML for the message body. */
@@ -26,5 +21,9 @@ export interface LayoutOptions {
  * Every template is responsible for escaping its own interpolated values
  * with `escapeHtml` before calling this -- the layout only wraps what it is
  * given, except for `brand.name`, which it escapes itself.
+ *
+ * `subject` is checked for CR/LF and other control characters before it is
+ * returned, since it is not HTML-escaped and reaches Resend as a header
+ * value -- see `header-safe.ts`.
  */
 export declare function layout(options: LayoutOptions): MailMessage;

package/dist/layout.js

@@ -1,14 +1,5 @@
-/**
- * The one rule. Ampersand first, or it double-escapes everything after it.
- * Same rule and reason as app-template's `src/lib/marketing/render.ts`.
- */
-export function escapeHtml(value) {
-    return value
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-}
+import { escapeHtml } from '@wtfalch/utils/html';
+import { assertHeaderSafe } from './header-safe.js';
 const BODY_STYLE = 'margin:0;padding:24px;background:#f4f6f8;font-family:-apple-system,Segoe UI,Helvetica,Arial,sans-serif;color:#15181d;line-height:1.6';
 const CARD_STYLE = 'max-width:600px;margin:0 auto;background:#ffffff;padding:28px;border-radius:4px';
 const BRAND_STYLE = 'margin:0 0 20px;font-size:13px;color:#545b66;text-transform:uppercase;letter-spacing:0.04em';
@@ -27,6 +18,10 @@ const BRAND_STYLE = 'margin:0 0 20px;font-size:13px;color:#545b66;text-transform
  * Every template is responsible for escaping its own interpolated values
  * with `escapeHtml` before calling this -- the layout only wraps what it is
  * given, except for `brand.name`, which it escapes itself.
+ *
+ * `subject` is checked for CR/LF and other control characters before it is
+ * returned, since it is not HTML-escaped and reaches Resend as a header
+ * value -- see `header-safe.ts`.
  */
 export function layout(options) {
     const header = options.brand?.name
@@ -42,5 +37,5 @@ export function layout(options) {
         options.bodyHtml,
         '</div></body></html>',
     ].join('');
-    return { subject: options.subject, html, text: options.bodyText };
+    return { subject: assertHeaderSafe(options.subject, 'subject'), html, text: options.bodyText };
 }

package/dist/send.d.ts

@@ -1,6 +1,6 @@
 import { type TemplateData, type TemplateName } from './templates/index.js';
 import { type Transport } from './transport.js';
-import type { SendResult, SenderIdentity } from './types.js';
+import { type Attachment, type SendResult, type SenderIdentity } from './types.js';
 export interface SendOptions<T extends TemplateName> {
     readonly template: T;
     readonly to: string;
@@ -8,6 +8,8 @@ export interface SendOptions<T extends TemplateName> {
     readonly from: SenderIdentity;
     /** Defaults to the dev transport outside production; see `defaultTransport`. */
     readonly transport?: Transport;
+    /** Files to attach, e.g. an invoice or credit note document. Both shipped transports accept these. */
+    readonly attachments?: readonly Attachment[];
 }
 /**
  * One template, rendered and handed to a transport.

package/dist/send.js

@@ -1,5 +1,7 @@
+import { assertHeaderSafe } from './header-safe.js';
 import { templates } from './templates/index.js';
 import { defaultTransport } from './transport.js';
+import { DEFAULT_LOCALE, } from './types.js';
 function formatFrom(identity) {
     return identity.fromName
         ? `${identity.fromName} <${identity.fromAddress}>`
@@ -15,12 +17,13 @@ function formatFrom(identity) {
  */
 export async function send(options) {
     const render = templates[options.template];
-    const message = render(options.data);
+    const message = render(options.data, options.from.locale ?? DEFAULT_LOCALE);
     const transport = options.transport ?? defaultTransport();
     return transport.send({
         ...message,
-        to: options.to,
-        from: formatFrom(options.from),
-        replyTo: options.from.replyTo,
+        to: assertHeaderSafe(options.to, 'to'),
+        from: assertHeaderSafe(formatFrom(options.from), 'from'),
+        replyTo: options.from.replyTo ? assertHeaderSafe(options.from.replyTo, 'replyTo') : undefined,
+        attachments: options.attachments,
     });
 }

package/dist/templates/account.d.ts

@@ -0,0 +1,34 @@
+import { type Brand, type Locale, type MailMessage } from '../types.js';
+/**
+ * Shared shape for every account template that carries a link and a code:
+ * `verify`, `reset`, `link` (sign-in link), `invite` (account invite) and
+ * `email-change`. Modelled on the auth broker's own `Sender`/`Message`
+ * variables (`auth/broker/src/mail.ts`, read for this template's copy and
+ * variables so the broker can move over -- issue #10), rendered in mailer's
+ * own button-plus-fallback-link convention (`templates/invitation.ts`)
+ * rather than the broker's plain-text-only `Message`.
+ */
+export interface AccountMailData {
+    readonly productName: string;
+    readonly url: string;
+    readonly code: string;
+    readonly brand?: Brand;
+}
+/**
+ * `email-change-notice` and `email-changed` both go to the address a
+ * change does NOT touch: no link to click and no code to enter, only
+ * something to notice -- the same exception the broker's own `WORDS` table
+ * carves out for these two kinds (`mail.ts`'s doc comment on `WORDS`).
+ */
+export interface EmailChangeNoticeData {
+    readonly productName: string;
+    readonly newEmail: string;
+    readonly brand?: Brand;
+}
+export declare function renderVerify(data: AccountMailData, locale?: Locale): MailMessage;
+export declare function renderReset(data: AccountMailData, locale?: Locale): MailMessage;
+export declare function renderSignInLink(data: AccountMailData, locale?: Locale): MailMessage;
+export declare function renderAccountInvite(data: AccountMailData, locale?: Locale): MailMessage;
+export declare function renderEmailChange(data: AccountMailData, locale?: Locale): MailMessage;
+export declare function renderEmailChangeNotice(data: EmailChangeNoticeData, locale?: Locale): MailMessage;
+export declare function renderEmailChanged(data: EmailChangeNoticeData, locale?: Locale): MailMessage;

package/dist/templates/account.js

@@ -0,0 +1,171 @@
+import { escapeHtml } from '@wtfalch/utils/html';
+import { layout } from '../layout.js';
+import { DEFAULT_LOCALE } from '../types.js';
+const ACCOUNT_WORDS = {
+    en: {
+        verify: {
+            subject: (p) => `Confirm your email for ${p}`,
+            intro: (p) => `Confirm your email address to finish setting up your ${p} account.`,
+            footer: () => 'If you did not create an account, ignore this message.',
+            cta: 'Confirm email',
+            codeLabel: 'Or enter this code: ',
+            fallbackLinkLabel: 'Or paste this link into your browser: ',
+        },
+        reset: {
+            subject: (p) => `Reset your ${p} password`,
+            intro: (p) => `Choose a new password for ${p}.`,
+            footer: () => 'The link works once and expires. If you did not ask for it, your password is unchanged and you can ignore this message.',
+            cta: 'Reset password',
+            codeLabel: 'Or enter this code: ',
+            fallbackLinkLabel: 'Or paste this link into your browser: ',
+        },
+        link: {
+            subject: (p) => `Sign in to ${p}`,
+            intro: (p) => `Sign in to ${p}.`,
+            footer: () => 'The link works once and expires shortly. If you did not ask to sign in, ignore this message.',
+            cta: 'Sign in',
+            codeLabel: 'Or enter this code: ',
+            fallbackLinkLabel: 'Or paste this link into your browser: ',
+        },
+        invite: {
+            subject: (p) => `You have been added to ${p}`,
+            intro: (p) => `You have been given access to ${p}. Choose a password to finish.`,
+            footer: () => 'If you were not expecting this, ignore the message and no account is usable.',
+            cta: 'Set your password',
+            codeLabel: 'Or enter this code: ',
+            fallbackLinkLabel: 'Or paste this link into your browser: ',
+        },
+        'email-change': {
+            subject: (p) => `Confirm your new email for ${p}`,
+            intro: (p) => `Confirm this address as your new sign-in email for ${p}. Your old address keeps working until you do.`,
+            footer: () => 'If you did not ask to change your email, ignore this message -- nothing changes until you confirm.',
+            cta: 'Confirm new email',
+            codeLabel: 'Or enter this code: ',
+            fallbackLinkLabel: 'Or paste this link into your browser: ',
+        },
+    },
+    nb: {
+        verify: {
+            subject: (p) => `Bekreft e-postadressen din for ${p}`,
+            intro: (p) => `Bekreft e-postadressen din for å fullføre ${p}-kontoen din.`,
+            footer: () => 'Hvis du ikke har opprettet en konto, kan du se bort fra denne meldingen.',
+            cta: 'Bekreft e-post',
+            codeLabel: 'Eller skriv inn denne koden: ',
+            fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        },
+        reset: {
+            subject: (p) => `Tilbakestill passordet ditt for ${p}`,
+            intro: (p) => `Velg et nytt passord for ${p}.`,
+            footer: () => 'Lenken virker én gang og utløper. Hvis du ikke ba om den, er passordet ditt uendret.',
+            cta: 'Tilbakestill passord',
+            codeLabel: 'Eller skriv inn denne koden: ',
+            fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        },
+        link: {
+            subject: (p) => `Logg inn på ${p}`,
+            intro: (p) => `Logg inn på ${p}.`,
+            footer: () => 'Lenken virker én gang og utløper snart. Hvis du ikke ba om å logge inn, kan du se bort fra denne meldingen.',
+            cta: 'Logg inn',
+            codeLabel: 'Eller skriv inn denne koden: ',
+            fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        },
+        invite: {
+            subject: (p) => `Du har fått tilgang til ${p}`,
+            intro: (p) => `Du har fått tilgang til ${p}. Velg et passord for å fullføre.`,
+            footer: () => 'Hvis du ikke ventet dette, kan du se bort fra meldingen; kontoen er ikke i bruk.',
+            cta: 'Velg passord',
+            codeLabel: 'Eller skriv inn denne koden: ',
+            fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        },
+        'email-change': {
+            subject: (p) => `Bekreft den nye e-postadressen din for ${p}`,
+            intro: (p) => `Bekreft denne adressen som den nye påloggingsadressen din for ${p}. Den gamle adressen fungerer fortsatt til du gjør det.`,
+            footer: () => 'Hvis du ikke ba om å endre e-postadressen din, kan du se bort fra denne meldingen -- ingenting endres før du bekrefter.',
+            cta: 'Bekreft ny e-post',
+            codeLabel: 'Eller skriv inn denne koden: ',
+            fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        },
+    },
+};
+function renderAccountMail(kind, data, locale) {
+    const words = (ACCOUNT_WORDS[locale] ?? ACCOUNT_WORDS.en)[kind];
+    const subject = words.subject(data.productName);
+    const bodyHtml = [
+        `<p style="margin:0 0 14px">${escapeHtml(words.intro(data.productName))}</p>`,
+        `<p style="margin:0 0 20px"><a href="${escapeHtml(data.url)}" `,
+        'style="display:inline-block;background:#0e6c70;color:#ffffff;padding:10px 20px;',
+        `border-radius:4px;text-decoration:none">${escapeHtml(words.cta)}</a></p>`,
+        `<p style="margin:0 0 14px;font-size:13px;color:#545b66">${escapeHtml(words.fallbackLinkLabel)}`,
+        `${escapeHtml(data.url)}</p>`,
+        `<p style="margin:0 0 20px;font-size:13px;color:#545b66">${escapeHtml(words.codeLabel)}${escapeHtml(data.code)}</p>`,
+        `<p style="margin:0;font-size:13px;color:#545b66">${escapeHtml(words.footer(data.productName))}</p>`,
+    ].join('');
+    const text = [
+        words.intro(data.productName),
+        '',
+        data.url,
+        '',
+        `${words.codeLabel}${data.code}`,
+        '',
+        words.footer(data.productName),
+    ].join('\n');
+    return layout({ subject, bodyHtml, bodyText: text, brand: data.brand });
+}
+export function renderVerify(data, locale = DEFAULT_LOCALE) {
+    return renderAccountMail('verify', data, locale);
+}
+export function renderReset(data, locale = DEFAULT_LOCALE) {
+    return renderAccountMail('reset', data, locale);
+}
+export function renderSignInLink(data, locale = DEFAULT_LOCALE) {
+    return renderAccountMail('link', data, locale);
+}
+export function renderAccountInvite(data, locale = DEFAULT_LOCALE) {
+    return renderAccountMail('invite', data, locale);
+}
+export function renderEmailChange(data, locale = DEFAULT_LOCALE) {
+    return renderAccountMail('email-change', data, locale);
+}
+const NOTICE_WORDS = {
+    en: {
+        'email-change-notice': {
+            subject: (p) => `Someone requested a new email for your ${p} account`,
+            body: (p, newEmail) => `A request was made to change the sign-in email on your ${p} account to ${newEmail}. Nothing has changed yet -- this address still works, and the change only takes effect if ${newEmail} is confirmed.`,
+            footer: 'If this was not you, please contact us right away -- somebody else may have access to your account.',
+        },
+        'email-changed': {
+            subject: (p) => `Your ${p} sign-in email was changed`,
+            body: (p, newEmail) => `Your ${p} account's sign-in email was changed to ${newEmail}. This address no longer works for signing in.`,
+            footer: 'If you did not make this change, please contact us right away -- somebody else has access to your account.',
+        },
+    },
+    nb: {
+        'email-change-notice': {
+            subject: (p) => `Noen ba om en ny e-postadresse for ${p}-kontoen din`,
+            body: (p, newEmail) => `Det ble bedt om å endre påloggings-e-posten for ${p}-kontoen din til ${newEmail}. Ingenting er endret ennå -- denne adressen fungerer fortsatt, og endringen trer bare i kraft hvis ${newEmail} blir bekreftet.`,
+            footer: 'Hvis dette ikke var deg, kontakt oss med en gang -- noen andre kan ha tilgang til kontoen din.',
+        },
+        'email-changed': {
+            subject: (p) => `Påloggings-e-posten din for ${p} ble endret`,
+            body: (p, newEmail) => `Påloggings-e-posten for ${p}-kontoen din ble endret til ${newEmail}. Denne adressen fungerer ikke lenger for pålogging.`,
+            footer: 'Hvis du ikke gjorde denne endringen, kontakt oss med en gang -- noen andre har tilgang til kontoen din.',
+        },
+    },
+};
+function renderNoticeMail(kind, data, locale) {
+    const words = (NOTICE_WORDS[locale] ?? NOTICE_WORDS.en)[kind];
+    const subject = words.subject(data.productName);
+    const bodyText = words.body(data.productName, data.newEmail);
+    const bodyHtml = [
+        `<p style="margin:0 0 14px">${escapeHtml(bodyText)}</p>`,
+        `<p style="margin:0;font-size:13px;color:#545b66">${escapeHtml(words.footer)}</p>`,
+    ].join('');
+    const text = [bodyText, '', words.footer].join('\n');
+    return layout({ subject, bodyHtml, bodyText: text, brand: data.brand });
+}
+export function renderEmailChangeNotice(data, locale = DEFAULT_LOCALE) {
+    return renderNoticeMail('email-change-notice', data, locale);
+}
+export function renderEmailChanged(data, locale = DEFAULT_LOCALE) {
+    return renderNoticeMail('email-changed', data, locale);
+}

package/dist/templates/index.d.ts

@@ -1,12 +1,19 @@
+import { type AccountMailData, type EmailChangeNoticeData, renderAccountInvite, renderEmailChange, renderEmailChangeNotice, renderEmailChanged, renderReset, renderSignInLink, renderVerify } from './account.js';
 import { type InvitationData, renderInvitation } from './invitation.js';
 /**
  * Every template this package ships, by name. Adding one is additive to
- * this map and to the surface lock; v1 ships one, `invitation` -- the
- * README names sign-in links, alerts and forum notifications as future
- * templates, not built here (see .claude/campaign/2026-09-22-v1.md, Findings).
+ * this map and to the surface lock. v1 shipped one, `invitation`; v2 adds
+ * all seven of the auth broker's own `Kind` union names (issue #10).
  */
 export declare const templates: {
     readonly invitation: typeof renderInvitation;
+    readonly verify: typeof renderVerify;
+    readonly reset: typeof renderReset;
+    readonly link: typeof renderSignInLink;
+    readonly invite: typeof renderAccountInvite;
+    readonly 'email-change': typeof renderEmailChange;
+    readonly 'email-change-notice': typeof renderEmailChangeNotice;
+    readonly 'email-changed': typeof renderEmailChanged;
 };
 export type TemplateName = keyof typeof templates;
-export type TemplateData<T extends TemplateName> = T extends 'invitation' ? InvitationData : never;
+export type TemplateData<T extends TemplateName> = T extends 'invitation' ? InvitationData : T extends 'email-change-notice' | 'email-changed' ? EmailChangeNoticeData : T extends 'verify' | 'reset' | 'link' | 'invite' | 'email-change' ? AccountMailData : never;

package/dist/templates/index.js

@@ -1,10 +1,17 @@
+import { renderAccountInvite, renderEmailChange, renderEmailChangeNotice, renderEmailChanged, renderReset, renderSignInLink, renderVerify, } from './account.js';
 import { renderInvitation } from './invitation.js';
 /**
  * Every template this package ships, by name. Adding one is additive to
- * this map and to the surface lock; v1 ships one, `invitation` -- the
- * README names sign-in links, alerts and forum notifications as future
- * templates, not built here (see .claude/campaign/2026-09-22-v1.md, Findings).
+ * this map and to the surface lock. v1 shipped one, `invitation`; v2 adds
+ * all seven of the auth broker's own `Kind` union names (issue #10).
  */
 export const templates = {
     invitation: renderInvitation,
+    verify: renderVerify,
+    reset: renderReset,
+    link: renderSignInLink,
+    invite: renderAccountInvite,
+    'email-change': renderEmailChange,
+    'email-change-notice': renderEmailChangeNotice,
+    'email-changed': renderEmailChanged,
 };

package/dist/templates/invitation.d.ts

@@ -1,4 +1,4 @@
-import type { Brand, MailMessage } from '../types.js';
+import { type Brand, type Locale, type MailMessage } from '../types.js';
 /**
  * The estate's real first consumer: app-template's invite action creates
  * the invitation row and returns "Invitation sent" without ever sending
@@ -13,4 +13,4 @@ export interface InvitationData {
     readonly roleName?: string;
     readonly brand?: Brand;
 }
-export declare function renderInvitation(data: InvitationData): MailMessage;
+export declare function renderInvitation(data: InvitationData, locale?: Locale): MailMessage;

package/dist/templates/invitation.js

@@ -1,20 +1,42 @@
-import { escapeHtml, layout } from '../layout.js';
-export function renderInvitation(data) {
-    const subject = `${data.inviterName} invited you to ${data.organisationName}`;
-    const roleLine = data.roleName ? ` as ${escapeHtml(data.roleName)}` : '';
+import { escapeHtml } from '@wtfalch/utils/html';
+import { layout } from '../layout.js';
+import { DEFAULT_LOCALE } from '../types.js';
+const WORDS = {
+    en: {
+        subject: (inviter, org) => `${inviter} invited you to ${org}`,
+        intro: (inviter, org) => `${escapeHtml(inviter)} invited you to join <strong>${escapeHtml(org)}</strong>`,
+        roleSuffix: (role) => ` as ${escapeHtml(role)}`,
+        cta: 'Accept invitation',
+        fallbackLinkLabel: 'Or paste this link into your browser: ',
+        textIntro: (inviter, org, role) => `${inviter} invited you to join ${org}${role ? ` as ${role}` : ''}.`,
+        textAccept: 'Accept',
+    },
+    nb: {
+        subject: (inviter, org) => `${inviter} har invitert deg til ${org}`,
+        intro: (inviter, org) => `${escapeHtml(inviter)} har invitert deg til å bli med i <strong>${escapeHtml(org)}</strong>`,
+        roleSuffix: (role) => ` som ${escapeHtml(role)}`,
+        cta: 'Godta invitasjon',
+        fallbackLinkLabel: 'Eller lim inn denne lenken i nettleseren din: ',
+        textIntro: (inviter, org, role) => `${inviter} har invitert deg til å bli med i ${org}${role ? ` som ${role}` : ''}.`,
+        textAccept: 'Godta',
+    },
+};
+export function renderInvitation(data, locale = DEFAULT_LOCALE) {
+    const words = WORDS[locale] ?? WORDS.en;
+    const subject = words.subject(data.inviterName, data.organisationName);
+    const roleLine = data.roleName ? words.roleSuffix(data.roleName) : '';
     const bodyHtml = [
-        `<p style="margin:0 0 14px">${escapeHtml(data.inviterName)} invited you to join `,
-        `<strong>${escapeHtml(data.organisationName)}</strong>${roleLine}.</p>`,
+        `<p style="margin:0 0 14px">${words.intro(data.inviterName, data.organisationName)}${roleLine}.</p>`,
         `<p style="margin:0 0 20px"><a href="${escapeHtml(data.acceptUrl)}" `,
         'style="display:inline-block;background:#0e6c70;color:#ffffff;padding:10px 20px;',
-        'border-radius:4px;text-decoration:none">Accept invitation</a></p>',
-        '<p style="margin:0;font-size:13px;color:#545b66">Or paste this link into your browser: ',
+        `border-radius:4px;text-decoration:none">${escapeHtml(words.cta)}</a></p>`,
+        `<p style="margin:0;font-size:13px;color:#545b66">${escapeHtml(words.fallbackLinkLabel)}`,
         `${escapeHtml(data.acceptUrl)}</p>`,
     ].join('');
     const text = [
-        `${data.inviterName} invited you to join ${data.organisationName}${data.roleName ? ` as ${data.roleName}` : ''}.`,
+        words.textIntro(data.inviterName, data.organisationName, data.roleName),
         '',
-        `Accept: ${data.acceptUrl}`,
+        `${words.textAccept}: ${data.acceptUrl}`,
     ].join('\n');
     return layout({ subject, bodyHtml, bodyText: text, brand: data.brand });
 }

package/dist/transport.d.ts

@@ -1,10 +1,11 @@
-import { type MailMessage, type SendResult } from './types.js';
+import { type Attachment, type MailMessage, type SendResult } from './types.js';
 /** A rendered message, addressed and ready for a transport. */
 export interface OutgoingMail extends MailMessage {
     readonly to: string;
     /** Already formatted, e.g. `"Acme <no-reply@acme.wtfalch.dev>"` or a bare address. */
     readonly from: string;
     readonly replyTo?: string;
+    readonly attachments?: readonly Attachment[];
 }
 export interface Transport {
     send(message: OutgoingMail): Promise<SendResult>;
@@ -36,6 +37,14 @@ export interface ResendLike {
             html: string;
             text: string;
             reply_to?: string;
+            /** Resend's own field names: `content` is base64 (or a Buffer), `content_type` is
+             * optional and derived from `filename` when absent --
+             * https://resend.com/docs/api-reference/emails/send-email. */
+            attachments?: Array<{
+                filename: string;
+                content: string;
+                content_type?: string;
+            }>;
         }): Promise<{
             data: {
                 id: string;
@@ -55,9 +64,116 @@ export interface ResendTransportOptions {
 /**
  * Sends over Resend. The one place in the estate that imports the `resend`
  * package (README: "This package is the one place that knows about
- * Resend").
+ * Resend") -- and, since [0006](../docs/adr/0006-lettermint-transport-resend-optional-peer.md),
+ * it imports it lazily: `resend` is now an optional peer, not a runtime
+ * dependency, so a consumer that only ever passes `client` (every test in
+ * this repo, and any caller that only sends over Lettermint) never needs
+ * the package installed at all. The `import('resend')` below runs at most
+ * once per transport, on the first `send()` call, only when no `client` was
+ * given.
  */
 export declare function createResendTransport(options: ResendTransportOptions): Transport;
+/**
+ * The minimal shape this package calls on `fetch` to speak Lettermint's
+ * Sending API directly -- the same no-SDK, injectable-`fetch` posture
+ * `@wtfalch/payments`'s Stripe/Vipps adapters take (payments ADR 0003,
+ * `packages/payments/src/http.ts`'s `FetchLike`). No `lettermint` npm
+ * package is a dependency of this package.
+ */
+export type LettermintFetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface LettermintAttachment {
+    readonly filename: string;
+    /**
+     * Snake-case, matching the Sending API's own wire field exactly --
+     * unlike `ResendLike`, `LettermintSendPayload` has no translation step
+     * before `JSON.stringify` (`createLettermintClient`'s `send`), so this
+     * interface's own field names ARE the request body's JSON keys.
+     */
+    readonly content_type?: string;
+    /**
+     * Base64-encoded attachment bytes. The Sending API's own OpenAPI spec
+     * gives `content` no encoding note beyond its type (`string`), but every
+     * official SDK base64-encodes before setting it, and the inline-images
+     * guide states it explicitly for that sibling field:
+     * https://lettermint.co/docs/guides/send-email-with-nodejs,
+     * https://lettermint.co/docs/platform/emails/inline-images.
+     */
+    readonly content: string;
+}
+/** The Sending API's own request shape for `POST /send`, per
+ * https://lettermint.co/docs/api-reference/sending/0.0.1/lettermint-sending-openapi.json. */
+export interface LettermintSendPayload {
+    readonly from: string;
+    readonly to: readonly string[];
+    readonly subject: string;
+    readonly html?: string;
+    readonly text?: string;
+    readonly reply_to?: readonly string[];
+    readonly attachments?: readonly LettermintAttachment[];
+}
+/**
+ * The minimal shape this package calls on a Lettermint client: `send`
+ * only, the same structural-injection pattern `ResendLike` uses. The
+ * default client (built from `apiKey`) satisfies this over plain `fetch`;
+ * a fake with no network access is what this package's own tests inject.
+ */
+export interface LettermintLike {
+    send(payload: LettermintSendPayload): Promise<{
+        message_id: string | null;
+        status: string;
+    }>;
+}
+export interface LettermintTransportOptions {
+    /** The org's Lettermint Project API token (`lm_...`), resolved by the
+     * caller from `@wtfalch/keys`; mailer never fetches or stores it. */
+    readonly apiKey?: string;
+    /** A client to use instead of constructing one from `apiKey` -- how tests inject a fake. */
+    readonly client?: LettermintLike;
+    /** Injectable `fetch`, used only when building the default client from
+     * `apiKey`. Defaults to `globalThis.fetch`. */
+    readonly fetch?: LettermintFetchLike;
+}
+/**
+ * Thrown when Lettermint refuses to send because the `from` domain is not
+ * one the sending project may use -- either unverified, or verified but
+ * restricted to other Lettermint projects on the team (a Lettermint domain
+ * is unrestricted across a team by default, per foundry's own Lettermint
+ * research, `.plans/2026-09-28-lettermint-api.md` §2/§6, so this refusal is
+ * real and opt-in, not the common case). Lettermint's own confirmed wording
+ * for the restriction case: "The domain 'mail.acme.com' is not available
+ * for use by this project." --
+ * https://lettermint.co/docs/platform/domains/project-limits. A caller
+ * (foundry's provisioning retry, or an org's own admin UI) needs to tell
+ * this refusal apart from a transient failure, hence a typed error rather
+ * than the generic one below.
+ */
+export declare class LettermintDomainRefusedError extends Error {
+    constructor(message: string);
+}
+/**
+ * Sends over Lettermint (EU, GDPR -- William's 2026-09-28 choice over
+ * Resend, see [0006](../docs/adr/0006-lettermint-transport-resend-optional-peer.md)),
+ * via plain `fetch` against Lettermint's Sending API. Base URL, auth header
+ * and request/response shapes:
+ * https://lettermint.co/docs/api-reference/sending/0.0.1/lettermint-sending-openapi.json
+ * (confirmed by direct fetch of that spec, and cross-checked against
+ * foundry's own Lettermint research, `.plans/2026-09-28-lettermint-api.md`
+ * §1: base URL `https://api.lettermint.co/v1`, Sending API auth header
+ * `x-lettermint-token: <project_token>`, a Project API token prefixed
+ * `lm_...`). Same no-SDK, `fetch`-injection posture as
+ * `@wtfalch/payments` (payments ADR 0003) -- no `lettermint` npm package is
+ * a dependency of this package, so this transport's own tests never touch
+ * the network.
+ */
+export declare function createLettermintTransport(options: LettermintTransportOptions): Transport;
 /**
  * `dev`, unconditionally, outside `NODE_ENV=production`. In production
  * there is no default: `send()` must be given an explicit transport,

package/dist/transport.js

@@ -1,7 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { Resend } from 'resend';
 import { MailerConfigError } from './types.js';
 /**
  * Writes every message to `<dir>/<timestamp>-<id>.json` instead of sending
@@ -24,15 +23,28 @@ export function createDevTransport(options = {}) {
 /**
  * Sends over Resend. The one place in the estate that imports the `resend`
  * package (README: "This package is the one place that knows about
- * Resend").
+ * Resend") -- and, since [0006](../docs/adr/0006-lettermint-transport-resend-optional-peer.md),
+ * it imports it lazily: `resend` is now an optional peer, not a runtime
+ * dependency, so a consumer that only ever passes `client` (every test in
+ * this repo, and any caller that only sends over Lettermint) never needs
+ * the package installed at all. The `import('resend')` below runs at most
+ * once per transport, on the first `send()` call, only when no `client` was
+ * given.
  */
 export function createResendTransport(options) {
     if (!options.client && !options.apiKey) {
         throw new MailerConfigError('createResendTransport needs either "apiKey" or "client".');
     }
-    const client = options.client ?? new Resend(options.apiKey);
+    let resolvedClient;
+    function resolveClient() {
+        if (options.client)
+            return Promise.resolve(options.client);
+        resolvedClient ??= import('resend').then(({ Resend }) => new Resend(options.apiKey));
+        return resolvedClient;
+    }
     return {
         async send(message) {
+            const client = await resolveClient();
             const { data, error } = await client.emails.send({
                 from: message.from,
                 to: message.to,
@@ -40,6 +52,15 @@ export function createResendTransport(options) {
                 html: message.html,
                 text: message.text,
                 ...(message.replyTo ? { reply_to: message.replyTo } : {}),
+                ...(message.attachments
+                    ? {
+                        attachments: message.attachments.map((attachment) => ({
+                            filename: attachment.filename,
+                            content: attachment.content,
+                            ...(attachment.contentType ? { content_type: attachment.contentType } : {}),
+                        })),
+                    }
+                    : {}),
             });
             if (error)
                 throw new Error(`mailer: resend refused the message: ${error.message}`);
@@ -49,6 +70,107 @@ export function createResendTransport(options) {
         },
     };
 }
+/**
+ * Thrown when Lettermint refuses to send because the `from` domain is not
+ * one the sending project may use -- either unverified, or verified but
+ * restricted to other Lettermint projects on the team (a Lettermint domain
+ * is unrestricted across a team by default, per foundry's own Lettermint
+ * research, `.plans/2026-09-28-lettermint-api.md` §2/§6, so this refusal is
+ * real and opt-in, not the common case). Lettermint's own confirmed wording
+ * for the restriction case: "The domain 'mail.acme.com' is not available
+ * for use by this project." --
+ * https://lettermint.co/docs/platform/domains/project-limits. A caller
+ * (foundry's provisioning retry, or an org's own admin UI) needs to tell
+ * this refusal apart from a transient failure, hence a typed error rather
+ * than the generic one below.
+ */
+export class LettermintDomainRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LettermintDomainRefusedError';
+    }
+}
+const LETTERMINT_SEND_URL = 'https://api.lettermint.co/v1/send';
+/**
+ * Matches Lettermint's confirmed domain-restriction refusal message
+ * (`LettermintDomainRefusedError`'s own doc comment has the exact quote and
+ * source) and the same shape of wording for an unverified domain. The
+ * unverified-domain case is inferred, not independently confirmed against
+ * a live error response -- the fetched docs and OpenAPI spec are silent on
+ * its exact status code and message (`.plans/2026-09-28-lettermint-api.md`
+ * §6, "unknown -- no fetched page states or shows an error example for
+ * that case").
+ */
+const DOMAIN_REFUSAL = /\bdomain\b.*\b(not available|not verified|not allowed)/i;
+function defaultLettermintFetch() {
+    if (typeof globalThis.fetch !== 'function') {
+        throw new MailerConfigError('mailer: no global fetch available; pass { fetch } explicitly to createLettermintTransport.');
+    }
+    return globalThis.fetch.bind(globalThis);
+}
+function createLettermintClient(apiKey, fetchImpl) {
+    return {
+        async send(payload) {
+            const response = await fetchImpl(LETTERMINT_SEND_URL, {
+                method: 'POST',
+                headers: { 'x-lettermint-token': apiKey, 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+            });
+            const body = (await response.json());
+            if (!response.ok) {
+                const message = body.message ?? `lettermint answered ${response.status} with no message`;
+                if (DOMAIN_REFUSAL.test(message))
+                    throw new LettermintDomainRefusedError(message);
+                throw new Error(`mailer: lettermint refused the message: ${message}`);
+            }
+            return { message_id: body.message_id ?? null, status: body.status ?? 'unknown' };
+        },
+    };
+}
+/**
+ * Sends over Lettermint (EU, GDPR -- William's 2026-09-28 choice over
+ * Resend, see [0006](../docs/adr/0006-lettermint-transport-resend-optional-peer.md)),
+ * via plain `fetch` against Lettermint's Sending API. Base URL, auth header
+ * and request/response shapes:
+ * https://lettermint.co/docs/api-reference/sending/0.0.1/lettermint-sending-openapi.json
+ * (confirmed by direct fetch of that spec, and cross-checked against
+ * foundry's own Lettermint research, `.plans/2026-09-28-lettermint-api.md`
+ * §1: base URL `https://api.lettermint.co/v1`, Sending API auth header
+ * `x-lettermint-token: <project_token>`, a Project API token prefixed
+ * `lm_...`). Same no-SDK, `fetch`-injection posture as
+ * `@wtfalch/payments` (payments ADR 0003) -- no `lettermint` npm package is
+ * a dependency of this package, so this transport's own tests never touch
+ * the network.
+ */
+export function createLettermintTransport(options) {
+    if (!options.client && !options.apiKey) {
+        throw new MailerConfigError('createLettermintTransport needs either "apiKey" or "client".');
+    }
+    const client = options.client ??
+        createLettermintClient(options.apiKey, options.fetch ?? defaultLettermintFetch());
+    return {
+        async send(message) {
+            const { message_id, status } = await client.send({
+                from: message.from,
+                to: [message.to],
+                subject: message.subject,
+                html: message.html,
+                text: message.text,
+                ...(message.replyTo ? { reply_to: [message.replyTo] } : {}),
+                ...(message.attachments
+                    ? {
+                        attachments: message.attachments.map((attachment) => ({
+                            filename: attachment.filename,
+                            content: attachment.content,
+                            ...(attachment.contentType ? { content_type: attachment.contentType } : {}),
+                        })),
+                    }
+                    : {}),
+            });
+            return { id: message_id ?? status, transport: 'lettermint' };
+        },
+    };
+}
 /**
  * `dev`, unconditionally, outside `NODE_ENV=production`. In production
  * there is no default: `send()` must be given an explicit transport,

package/dist/types.d.ts

@@ -10,15 +10,48 @@ export interface Brand {
     readonly logoUrl?: string;
     readonly primaryColor?: string;
 }
+/**
+ * Every language a template ships copy for. `en` ships first and is the
+ * fallback every template's own `WORDS`-style table falls back to when
+ * `locale` is unset or not one of these -- the same fallback shape the auth
+ * broker's own `compose()` already uses (`auth/broker/src/mail.ts`:
+ * `WORDS[sender.locale] ?? WORDS.en`). Adding a third language is a
+ * template-by-template change, not an API change, so it is not locked here.
+ */
+export type Locale = 'en' | 'nb';
+/** `send()`'s own default when `from.locale` is unset. */
+export declare const DEFAULT_LOCALE: Locale;
 /**
  * Who a message is from, per organisation. The host resolves the domain,
  * from address and reply-to (its own org settings, or a default); mailer
  * never stores or looks one up -- it has no store (see README, "No store").
+ *
+ * `locale` picks which language's copy a template renders, with an English
+ * fallback (`DEFAULT_LOCALE`) -- the same field the auth broker's own
+ * `Sender` already carries (`auth/broker/src/mail.ts`), so moving a caller
+ * from the broker's `compose()` to mailer's `send()` is a like-for-like
+ * swap. Placed on `SenderIdentity` rather than on `send()`'s own options
+ * because every template call already threads `from` through, and an org's
+ * outbound language is a property of who is sending, not of one message.
  */
 export interface SenderIdentity {
     readonly fromAddress: string;
     readonly fromName?: string;
     readonly replyTo?: string;
+    readonly locale?: Locale;
+}
+/**
+ * One file attached to a send. `content` is base64-encoded bytes -- the
+ * convention both transports' real APIs use (Resend:
+ * https://resend.com/docs/api-reference/emails/send-email, "Content of an
+ * attached file, passed as a buffer or Base64 string"; Lettermint's Sending
+ * API OpenAPI spec, `attachments[].content`, and its official SDKs, which
+ * all base64-encode before setting it).
+ */
+export interface Attachment {
+    readonly filename: string;
+    readonly contentType?: string;
+    readonly content: string;
 }
 /** One rendered message: subject, HTML, and a required plain-text part. */
 export interface MailMessage {
@@ -29,7 +62,7 @@ export interface MailMessage {
 /** What a transport returns once it has accepted a message. */
 export interface SendResult {
     readonly id: string;
-    readonly transport: 'resend' | 'dev';
+    readonly transport: 'resend' | 'dev' | 'lettermint';
 }
 /**
  * `send()` has no usable default (no transport given, and either

package/dist/types.js

@@ -1,3 +1,5 @@
+/** `send()`'s own default when `from.locale` is unset. */
+export const DEFAULT_LOCALE = 'en';
 /**
  * `send()` has no usable default (no transport given, and either
  * production with no explicit transport, or a Resend transport built with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/mailer",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "One send(template, to, data) call for the estate's transactional email, over Resend, with a dev transport that writes to disk instead of sending.",
   "repository": {
     "type": "git",
@@ -9,11 +9,7 @@
   },
   "license": "MIT",
   "type": "module",
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -28,17 +24,27 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "pnpm build"
+  },
   "dependencies": {
+    "@wtfalch/utils": "0.1.0"
+  },
+  "peerDependencies": {
     "resend": "^4.1.0"
   },
+  "peerDependenciesMeta": {
+    "resend": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^22",
+    "resend": "^4.1.0",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
   }
-}
+}