@wtfalch/mailer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Tallis Falch
+
+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,77 @@
+# @wtfalch/mailer
+
+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.
+
+## Install
+
+```sh
+pnpm add @wtfalch/mailer
+```
+
+## Use
+
+Call `send()` with a template name, the recipient, that template's data,
+and who the message is from:
+
+```ts
+import { createDevTransport, send } from '@wtfalch/mailer';
+
+await send({
+  template: 'invitation',
+  to: 'person@example.com',
+  data: {
+    organisationName: 'Acme',
+    inviterName: 'Jordan',
+    acceptUrl: 'https://app.example.com/invite/abc123',
+    roleName: 'Editor', // optional
+    brand: { name: 'Acme' }, // optional
+  },
+  from: {
+    fromAddress: 'no-reply@acme.wtfalch.dev',
+    fromName: 'Acme', // optional
+    replyTo: 'support@acme.wtfalch.dev', // optional
+  },
+  transport: createDevTransport(), // writes to .mailer/dev instead of sending
+});
+```
+
+`transport` is optional. Left out, `send()` uses the dev transport outside
+`NODE_ENV=production` and throws `MailerConfigError` in production -- a
+missing transport fails loudly instead of silently no-op'ing or making a
+live call with no key.
+
+### Transports
+
+- `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.
+
+### Templates
+
+`invitation` is the only template shipped so far:
+
+```ts
+interface InvitationData {
+  organisationName: string;
+  inviterName: string;
+  acceptUrl: string;
+  roleName?: string;
+  brand?: { name: string; logoUrl?: string; primaryColor?: string };
+}
+```
+
+## Tests
+
+From `packages/mailer`:
+
+```sh
+pnpm test
+```
+
+Tests run against the dev transport and a fake `ResendLike` client --
+never a live key, never the network.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+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 { 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';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { MailerConfigError } from './types.js';
+export { createDevTransport, createResendTransport, defaultTransport } from './transport.js';
+export { send } from './send.js';
+export { templates } from './templates/index.js';
+export { renderInvitation } from './templates/invitation.js';

package/dist/layout.d.ts

@@ -0,0 +1,30 @@
+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. */
+    readonly bodyHtml: string;
+    readonly bodyText: string;
+    readonly brand?: Brand;
+}
+/**
+ * Every template's shared wrapper.
+ *
+ * **Inline styles only, no `<style>` block.** A mail client will not load a
+ * stylesheet and several ignore a `<style>` tag outright -- the same reason
+ * app-template's hand-rolled renderer gives for skipping both. No template
+ * engine either: the whole output is a handful of tags with inline styles,
+ * a library to produce it would be more surface than the thing it produces.
+ *
+ * **A text part is always produced.** A message with no plain alternative
+ * scores worse with every spam filter there is.
+ *
+ * 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.
+ */
+export declare function layout(options: LayoutOptions): MailMessage;

package/dist/layout.js

@@ -0,0 +1,46 @@
+/**
+ * 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;');
+}
+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';
+/**
+ * Every template's shared wrapper.
+ *
+ * **Inline styles only, no `<style>` block.** A mail client will not load a
+ * stylesheet and several ignore a `<style>` tag outright -- the same reason
+ * app-template's hand-rolled renderer gives for skipping both. No template
+ * engine either: the whole output is a handful of tags with inline styles,
+ * a library to produce it would be more surface than the thing it produces.
+ *
+ * **A text part is always produced.** A message with no plain alternative
+ * scores worse with every spam filter there is.
+ *
+ * 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.
+ */
+export function layout(options) {
+    const header = options.brand?.name
+        ? `<p style="${BRAND_STYLE}">${escapeHtml(options.brand.name)}</p>`
+        : '';
+    const html = [
+        '<!doctype html><html><body style="',
+        BODY_STYLE,
+        '"><div style="',
+        CARD_STYLE,
+        '">',
+        header,
+        options.bodyHtml,
+        '</div></body></html>',
+    ].join('');
+    return { subject: options.subject, html, text: options.bodyText };
+}

package/dist/send.d.ts

@@ -0,0 +1,20 @@
+import { type TemplateData, type TemplateName } from './templates/index.js';
+import { type Transport } from './transport.js';
+import type { SendResult, SenderIdentity } from './types.js';
+export interface SendOptions<T extends TemplateName> {
+    readonly template: T;
+    readonly to: string;
+    readonly data: TemplateData<T>;
+    readonly from: SenderIdentity;
+    /** Defaults to the dev transport outside production; see `defaultTransport`. */
+    readonly transport?: Transport;
+}
+/**
+ * One template, rendered and handed to a transport.
+ *
+ * `transport` defaults to the dev transport outside production and throws
+ * `MailerConfigError` in production, so a missing config fails loudly
+ * instead of a silent no-op or an accidental live send (see
+ * `transport.ts`, `defaultTransport`).
+ */
+export declare function send<T extends TemplateName>(options: SendOptions<T>): Promise<SendResult>;

package/dist/send.js

@@ -0,0 +1,26 @@
+import { templates } from './templates/index.js';
+import { defaultTransport } from './transport.js';
+function formatFrom(identity) {
+    return identity.fromName
+        ? `${identity.fromName} <${identity.fromAddress}>`
+        : identity.fromAddress;
+}
+/**
+ * One template, rendered and handed to a transport.
+ *
+ * `transport` defaults to the dev transport outside production and throws
+ * `MailerConfigError` in production, so a missing config fails loudly
+ * instead of a silent no-op or an accidental live send (see
+ * `transport.ts`, `defaultTransport`).
+ */
+export async function send(options) {
+    const render = templates[options.template];
+    const message = render(options.data);
+    const transport = options.transport ?? defaultTransport();
+    return transport.send({
+        ...message,
+        to: options.to,
+        from: formatFrom(options.from),
+        replyTo: options.from.replyTo,
+    });
+}

package/dist/templates/index.d.ts

@@ -0,0 +1,12 @@
+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).
+ */
+export declare const templates: {
+    readonly invitation: typeof renderInvitation;
+};
+export type TemplateName = keyof typeof templates;
+export type TemplateData<T extends TemplateName> = T extends 'invitation' ? InvitationData : never;

package/dist/templates/index.js

@@ -0,0 +1,10 @@
+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).
+ */
+export const templates = {
+    invitation: renderInvitation,
+};

package/dist/templates/invitation.d.ts

@@ -0,0 +1,16 @@
+import type { Brand, 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
+ * anything (`src/app/org/[tenantId]/members/actions.ts:52-54`,
+ * `src/lib/authz/invitations.ts:246-247`). Wiring `send('invitation', ...)`
+ * in at that call site is what this template is for.
+ */
+export interface InvitationData {
+    readonly organisationName: string;
+    readonly inviterName: string;
+    readonly acceptUrl: string;
+    readonly roleName?: string;
+    readonly brand?: Brand;
+}
+export declare function renderInvitation(data: InvitationData): MailMessage;

package/dist/templates/invitation.js

@@ -0,0 +1,20 @@
+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)}` : '';
+    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 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: ',
+        `${escapeHtml(data.acceptUrl)}</p>`,
+    ].join('');
+    const text = [
+        `${data.inviterName} invited you to join ${data.organisationName}${data.roleName ? ` as ${data.roleName}` : ''}.`,
+        '',
+        `Accept: ${data.acceptUrl}`,
+    ].join('\n');
+    return layout({ subject, bodyHtml, bodyText: text, brand: data.brand });
+}

package/dist/transport.d.ts

@@ -0,0 +1,68 @@
+import { 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;
+}
+export interface Transport {
+    send(message: OutgoingMail): Promise<SendResult>;
+}
+export interface DevTransportOptions {
+    /** Directory messages are written to. Default: `.mailer/dev`. */
+    readonly dir?: string;
+}
+/**
+ * Writes every message to `<dir>/<timestamp>-<id>.json` instead of sending
+ * it. Never opens a network connection -- the gap the estate had nowhere:
+ * `outbox.ts` and `queue.ts` both call `new Resend()` unconditionally, so
+ * nothing that sends mail could be tested without a live key.
+ */
+export declare function createDevTransport(options?: DevTransportOptions): Transport;
+/**
+ * The minimal shape this package calls on a Resend client: `emails.send`
+ * only, with the fields mailer actually sets. The real `Resend` class
+ * satisfies this structurally, and so does a fake with no network access,
+ * which is what this package's own tests inject (never a real key, never a
+ * real send -- see `transport.test.ts`).
+ */
+export interface ResendLike {
+    emails: {
+        send(payload: {
+            from: string;
+            to: string;
+            subject: string;
+            html: string;
+            text: string;
+            reply_to?: string;
+        }): Promise<{
+            data: {
+                id: string;
+            } | null;
+            error: {
+                message: string;
+            } | null;
+        }>;
+    };
+}
+export interface ResendTransportOptions {
+    /** The Resend API key. The caller resolves this 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?: ResendLike;
+}
+/**
+ * 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").
+ */
+export declare function createResendTransport(options: ResendTransportOptions): Transport;
+/**
+ * `dev`, unconditionally, outside `NODE_ENV=production`. In production
+ * there is no default: `send()` must be given an explicit transport,
+ * because mailer never holds a Resend API key of its own to fall back to.
+ * Calling `send()` in production with no transport is a configuration bug,
+ * not a silent no-op and not an accidental live send.
+ */
+export declare function defaultTransport(): Transport;

package/dist/transport.js

@@ -0,0 +1,64 @@
+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
+ * it. Never opens a network connection -- the gap the estate had nowhere:
+ * `outbox.ts` and `queue.ts` both call `new Resend()` unconditionally, so
+ * nothing that sends mail could be tested without a live key.
+ */
+export function createDevTransport(options = {}) {
+    const dir = options.dir ?? '.mailer/dev';
+    return {
+        async send(message) {
+            mkdirSync(dir, { recursive: true });
+            const id = randomUUID();
+            const path = join(dir, `${Date.now()}-${id}.json`);
+            writeFileSync(path, JSON.stringify(message, null, 2));
+            return { id, transport: 'dev' };
+        },
+    };
+}
+/**
+ * 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").
+ */
+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);
+    return {
+        async send(message) {
+            const { data, error } = await client.emails.send({
+                from: message.from,
+                to: message.to,
+                subject: message.subject,
+                html: message.html,
+                text: message.text,
+                ...(message.replyTo ? { reply_to: message.replyTo } : {}),
+            });
+            if (error)
+                throw new Error(`mailer: resend refused the message: ${error.message}`);
+            if (!data)
+                throw new Error('mailer: resend returned no data and no error');
+            return { id: data.id, transport: 'resend' };
+        },
+    };
+}
+/**
+ * `dev`, unconditionally, outside `NODE_ENV=production`. In production
+ * there is no default: `send()` must be given an explicit transport,
+ * because mailer never holds a Resend API key of its own to fall back to.
+ * Calling `send()` in production with no transport is a configuration bug,
+ * not a silent no-op and not an accidental live send.
+ */
+export function defaultTransport() {
+    if (process.env.NODE_ENV === 'production') {
+        throw new MailerConfigError('send() needs an explicit transport in production: pass { transport: createResendTransport({ apiKey }) }.');
+    }
+    return createDevTransport();
+}

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The org's brand for the shared layout: plain data, resolved by the
+ * caller (from `@wtfalch/design`, `@wtfalch/house`, or an org's own theme
+ * row) and passed in. No dependency on either package here -- v1 ships no
+ * second template that would need more than a name, so a deeper
+ * integration is a README follow-up, not built now.
+ */
+export interface Brand {
+    readonly name: string;
+    readonly logoUrl?: string;
+    readonly primaryColor?: string;
+}
+/**
+ * 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").
+ */
+export interface SenderIdentity {
+    readonly fromAddress: string;
+    readonly fromName?: string;
+    readonly replyTo?: string;
+}
+/** One rendered message: subject, HTML, and a required plain-text part. */
+export interface MailMessage {
+    readonly subject: string;
+    readonly html: string;
+    readonly text: string;
+}
+/** What a transport returns once it has accepted a message. */
+export interface SendResult {
+    readonly id: string;
+    readonly transport: 'resend' | 'dev';
+}
+/**
+ * `send()` has no usable default (no transport given, and either
+ * production with no explicit transport, or a Resend transport built with
+ * neither `apiKey` nor `client`). Thrown rather than a silent no-op or an
+ * accidental network call.
+ */
+export declare class MailerConfigError extends Error {
+    constructor(message: string);
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * `send()` has no usable default (no transport given, and either
+ * production with no explicit transport, or a Resend transport built with
+ * neither `apiKey` nor `client`). Thrown rather than a silent no-op or an
+ * accidental network call.
+ */
+export class MailerConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MailerConfigError';
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@wtfalch/mailer",
+  "version": "0.1.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",
+    "url": "https://github.com/wtfalch/mailer",
+    "directory": "packages/mailer"
+  },
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "resend": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}