@wtfalch/mailer 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # @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.
+over Lettermint, with a dev transport that writes to disk instead of sending.
 
 ## Install
 
@@ -28,9 +28,9 @@ await send({
     brand: { name: 'Acme' }, // optional
   },
   from: {
-    fromAddress: 'no-reply@acme.wtfalch.dev',
+    fromAddress: 'no-reply@acme.example.com',
     fromName: 'Acme', // optional
-    replyTo: 'support@acme.wtfalch.dev', // optional
+    replyTo: 'support@acme.example.com', // optional
     locale: 'nb', // optional, defaults to 'en' -- picks which language's copy renders
   },
   attachments: [ // optional
@@ -45,9 +45,19 @@ 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`,
+Two env names change that default, in every `NODE_ENV`: with
+`LETTERMINT_API_URL` set (a base URL such as `https://sink.example.com/v1`;
+https, or http for `localhost`, `127.0.0.1` or `[::1]` only) `send()` sends
+through Lettermint's API shape to that server, with the token from
+`LETTERMINT_API_TOKEN` in the `x-lettermint-token` header. This is how a
+stage app, a production build holding real addresses, sends every mail to a
+sink. A malformed URL, or a URL with no token, throws `MailerConfigError`
+when the default transport is built, before any send. The same URL is
+available per transport as `createLettermintTransport({ apiKey, baseUrl })`.
+
+A held key: however you resolve `apiKey` for `createLettermintTransport`,
 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
+org's Lettermint key as a held key from `@wtfalch/keys` and passes it in on
 every call.
 
 ### Locale
@@ -60,22 +70,14 @@ already uses (`WORDS[sender.locale] ?? WORDS.en`).
 
 ### Transports
 
-A held key: however you resolve `apiKey` for either transport below, mailer
+A held key: however you resolve `apiKey` for the 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
+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. `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
@@ -126,7 +128,7 @@ 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' },
+  from: { fromAddress: 'no-reply@acme.example.com', locale: 'nb' },
 });
 ```
 
@@ -142,5 +144,5 @@ From `packages/mailer`:
 pnpm test
 ```
 
-Tests run against the dev transport and a fake `ResendLike` client --
+Tests run against the dev transport and a fake `LettermintLike` client --
 never a live key, never the network.

package/dist/header-safe.js

@@ -7,7 +7,7 @@ function isControlCharCode(code) {
  * 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
+ * name) and this package must not depend on the mail provider's own defence against
  * header injection to reject them (see issue #3).
  */
 function hasControlCharacter(value) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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 { DevTransportOptions, LettermintAttachment, LettermintFetchLike, LettermintLike, LettermintSendPayload, LettermintTransportOptions, OutgoingMail, Transport, } from './transport.js';
+export { createDevTransport, createLettermintTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
 export type { SendOptions } from './send.js';
 export { send } from './send.js';
 export type { TemplateData, TemplateName } from './templates/index.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { DEFAULT_LOCALE, MailerConfigError } from './types.js';
-export { createDevTransport, createLettermintTransport, createResendTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
+export { createDevTransport, createLettermintTransport, defaultTransport, LettermintDomainRefusedError, } 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

@@ -23,7 +23,7 @@ export interface LayoutOptions {
  * 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
+ * returned, since it is not HTML-escaped and reaches the mail provider as a header
  * value -- see `header-safe.ts`.
  */
 export declare function layout(options: LayoutOptions): MailMessage;

package/dist/layout.js

@@ -20,7 +20,7 @@ const BRAND_STYLE = 'margin:0 0 20px;font-size:13px;color:#545b66;text-transform
  * 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
+ * returned, since it is not HTML-escaped and reaches the mail provider as a header
  * value -- see `header-safe.ts`.
  */
 export function layout(options) {

package/dist/transport.d.ts

@@ -2,7 +2,7 @@ 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. */
+    /** Already formatted, e.g. `"Acme <no-reply@acme.example.com>"` or a bare address. */
     readonly from: string;
     readonly replyTo?: string;
     readonly attachments?: readonly Attachment[];
@@ -16,63 +16,10 @@ export interface DevTransportOptions {
 }
 /**
  * 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.
+ * it. Never opens a network connection, so nothing that sends mail needs
+ * a live key to be tested.
  */
 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;
-            /** 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;
-            } | 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") -- 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
@@ -84,6 +31,7 @@ export type LettermintFetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
     body: string;
+    signal?: AbortSignal;
 }) => Promise<{
     ok: boolean;
     status: number;
@@ -93,7 +41,7 @@ export interface LettermintAttachment {
     readonly filename: string;
     /**
      * Snake-case, matching the Sending API's own wire field exactly --
-     * unlike `ResendLike`, `LettermintSendPayload` has no translation step
+     * `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.
      */
@@ -121,7 +69,7 @@ export interface LettermintSendPayload {
 }
 /**
  * The minimal shape this package calls on a Lettermint client: `send`
- * only, the same structural-injection pattern `ResendLike` uses. The
+ * only, a structural interface so a test can inject a fake. 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.
  */
@@ -140,6 +88,12 @@ export interface LettermintTransportOptions {
     /** Injectable `fetch`, used only when building the default client from
      * `apiKey`. Defaults to `globalThis.fetch`. */
     readonly fetch?: LettermintFetchLike;
+    /** The Sending API base URL, without `/send`. Default
+     * `https://api.lettermint.co/v1`. Must be https, except for a local sink
+     * host (`localhost`, `127.0.0.1`, `[::1]`), so a misconfigured value
+     * cannot send mail or the token over plain http. Ignored when `client`
+     * is given. */
+    readonly baseUrl?: string;
 }
 /**
  * Thrown when Lettermint refuses to send because the `from` domain is not
@@ -159,8 +113,8 @@ 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)),
+ * Sends over Lettermint (EU, GDPR; see
+ * [0006](../docs/adr/0006-lettermint-transport.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
@@ -175,10 +129,13 @@ export declare class LettermintDomainRefusedError extends Error {
  */
 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,
- * 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.
+ * When `LETTERMINT_API_URL` is set (in any `NODE_ENV`), returns a Lettermint
+ * transport that sends to that base URL with the token in
+ * `LETTERMINT_API_TOKEN`: how a stage app, a production build holding real
+ * addresses, sends every mail to a sink server. A malformed URL, or a URL
+ * with no token, throws `MailerConfigError` here, before any send.
+ *
+ * Otherwise: `dev` outside `NODE_ENV=production`; in production there is no
+ * default, and `send()` must be given an explicit transport.
  */
 export declare function defaultTransport(): Transport;

package/dist/transport.js

@@ -4,9 +4,8 @@ import { join } from 'node:path';
 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.
+ * it. Never opens a network connection, so nothing that sends mail needs
+ * a live key to be tested.
  */
 export function createDevTransport(options = {}) {
     const dir = options.dir ?? '.mailer/dev';
@@ -20,56 +19,6 @@ 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") -- 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".');
-    }
-    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,
-                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 } : {}),
-                        })),
-                    }
-                    : {}),
-            });
-            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' };
-        },
-    };
-}
 /**
  * Thrown when Lettermint refuses to send because the `from` domain is not
  * one the sending project may use -- either unverified, or verified but
@@ -90,7 +39,33 @@ export class LettermintDomainRefusedError extends Error {
         this.name = 'LettermintDomainRefusedError';
     }
 }
-const LETTERMINT_SEND_URL = 'https://api.lettermint.co/v1/send';
+const LETTERMINT_BASE_URL = 'https://api.lettermint.co/v1';
+const LETTERMINT_TIMEOUT_MS = 30_000;
+const LOCAL_SINK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Validates a Sending API base URL where it is read and returns it without a
+ * trailing slash. Rule: https, or http only for a local sink host. Anything
+ * else throws `MailerConfigError`, so a bad value fails at start, not at the
+ * first send.
+ */
+function parseBaseUrl(raw, source) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new MailerConfigError(`mailer: ${source} is not a valid URL.`);
+    }
+    // A single-label host (a container name such as `acme-stage-sink`) only resolves on the internal network.
+    const local = url.protocol === 'http:' && (LOCAL_SINK_HOSTS.has(url.hostname) || !url.hostname.includes('.'));
+    if (url.protocol !== 'https:' && !local) {
+        throw new MailerConfigError(`mailer: ${source} must be an https URL (http is allowed only for localhost, 127.0.0.1, [::1] or a single-label internal host).`);
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new MailerConfigError(`mailer: ${source} must not carry credentials, a query string or a fragment.`);
+    }
+    return raw.replace(/\/+$/, '');
+}
 /**
  * Matches Lettermint's confirmed domain-restriction refusal message
  * (`LettermintDomainRefusedError`'s own doc comment has the exact quote and
@@ -108,13 +83,14 @@ function defaultLettermintFetch() {
     }
     return globalThis.fetch.bind(globalThis);
 }
-function createLettermintClient(apiKey, fetchImpl) {
+function createLettermintClient(apiKey, fetchImpl, baseUrl) {
     return {
         async send(payload) {
-            const response = await fetchImpl(LETTERMINT_SEND_URL, {
+            const response = await fetchImpl(`${baseUrl}/send`, {
                 method: 'POST',
                 headers: { 'x-lettermint-token': apiKey, 'content-type': 'application/json' },
                 body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(LETTERMINT_TIMEOUT_MS),
             });
             const body = (await response.json());
             if (!response.ok) {
@@ -128,8 +104,8 @@ function createLettermintClient(apiKey, fetchImpl) {
     };
 }
 /**
- * Sends over Lettermint (EU, GDPR -- William's 2026-09-28 choice over
- * Resend, see [0006](../docs/adr/0006-lettermint-transport-resend-optional-peer.md)),
+ * Sends over Lettermint (EU, GDPR; see
+ * [0006](../docs/adr/0006-lettermint-transport.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
@@ -146,8 +122,9 @@ export function createLettermintTransport(options) {
     if (!options.client && !options.apiKey) {
         throw new MailerConfigError('createLettermintTransport needs either "apiKey" or "client".');
     }
+    const baseUrl = options.baseUrl === undefined ? LETTERMINT_BASE_URL : parseBaseUrl(options.baseUrl, 'baseUrl');
     const client = options.client ??
-        createLettermintClient(options.apiKey, options.fetch ?? defaultLettermintFetch());
+        createLettermintClient(options.apiKey, options.fetch ?? defaultLettermintFetch(), baseUrl);
     return {
         async send(message) {
             const { message_id, status } = await client.send({
@@ -172,15 +149,27 @@ export function createLettermintTransport(options) {
     };
 }
 /**
- * `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.
+ * When `LETTERMINT_API_URL` is set (in any `NODE_ENV`), returns a Lettermint
+ * transport that sends to that base URL with the token in
+ * `LETTERMINT_API_TOKEN`: how a stage app, a production build holding real
+ * addresses, sends every mail to a sink server. A malformed URL, or a URL
+ * with no token, throws `MailerConfigError` here, before any send.
+ *
+ * Otherwise: `dev` outside `NODE_ENV=production`; in production there is no
+ * default, and `send()` must be given an explicit transport.
  */
 export function defaultTransport() {
+    const sinkUrl = process.env.LETTERMINT_API_URL;
+    if (sinkUrl) {
+        const baseUrl = parseBaseUrl(sinkUrl, 'LETTERMINT_API_URL');
+        const apiKey = process.env.LETTERMINT_API_TOKEN;
+        if (!apiKey) {
+            throw new MailerConfigError('mailer: LETTERMINT_API_URL is set but LETTERMINT_API_TOKEN is not.');
+        }
+        return createLettermintTransport({ apiKey, baseUrl });
+    }
     if (process.env.NODE_ENV === 'production') {
-        throw new MailerConfigError('send() needs an explicit transport in production: pass { transport: createResendTransport({ apiKey }) }.');
+        throw new MailerConfigError('send() needs an explicit transport in production: pass { transport: createLettermintTransport({ apiKey }) }.');
     }
     return createDevTransport();
 }

package/dist/types.d.ts

@@ -42,10 +42,8 @@ export interface SenderIdentity {
 }
 /**
  * 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
+ * convention the Lettermint Sending API uses (its
+ * OpenAPI spec, `attachments[].content`, and its official SDKs, which
  * all base64-encode before setting it).
  */
 export interface Attachment {
@@ -62,11 +60,11 @@ export interface MailMessage {
 /** What a transport returns once it has accepted a message. */
 export interface SendResult {
     readonly id: string;
-    readonly transport: 'resend' | 'dev' | 'lettermint';
+    readonly transport: 'dev' | 'lettermint';
 }
 /**
  * `send()` has no usable default (no transport given, and either
- * production with no explicit transport, or a Resend transport built with
+ * production with no explicit transport, or a transport built with
  * neither `apiKey` nor `client`). Thrown rather than a silent no-op or an
  * accidental network call.
  */

package/dist/types.js

@@ -2,7 +2,7 @@
 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
+ * production with no explicit transport, or a transport built with
  * neither `apiKey` nor `client`). Thrown rather than a silent no-op or an
  * accidental network call.
  */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wtfalch/mailer",
-  "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.",
+  "version": "0.5.0",
+  "description": "One send(template, to, data) call for the estate's transactional email, over Lettermint, with a dev transport that writes to disk instead of sending.",
   "repository": {
     "type": "git",
     "url": "https://github.com/wtfalch/mailer",
@@ -33,17 +33,8 @@
   "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"
   }