@wtfalch/mailer 0.4.0 → 0.6.0

package/README.md

@@ -1,7 +1,7 @@
 # @wtfalch/mailer
 
 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.
+over Lettermint.
 
 ## Install
 
@@ -15,7 +15,7 @@ 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';
+import { createLettermintTransport, send } from '@wtfalch/mailer';
 
 await send({
   template: 'invitation',
@@ -36,15 +36,36 @@ await send({
   attachments: [ // optional
     { filename: 'invoice.pdf', contentType: 'application/pdf', content: 'JVBERi0xLjQK...' }, // content is base64
   ],
-  transport: createDevTransport(), // writes to .mailer/dev instead of sending
+  transport: createLettermintTransport({ apiKey }), // resolved by the caller, e.g. from @wtfalch/keys
 });
 ```
 
-`transport` is optional. Left out, `send()` uses the dev transport outside
-`NODE_ENV=production` and throws `MailerConfigError` in production -- a
+`transport` is optional. Left out, `send()` calls `defaultTransport()`,
+which throws `MailerConfigError` unless `MAIL_SINK_URL` or `LETTERMINT_API_URL` is set -- a
 missing transport fails loudly instead of silently no-op'ing or making a
 live call with no key.
 
+`MAIL_SINK_URL` (a Mailpit base URL such as `http://acme-stage-sink:8025`;
+https, or http for `localhost`, `127.0.0.1`, `[::1]` or a single-label
+internal host) makes the default transport post every message to
+`<MAIL_SINK_URL>/api/v1/send` in Mailpit's send-API JSON, with no token
+header. It wins over every setting below, `LETTERMINT_API_TOKEN` included,
+so a stage app never reaches the real provider. A malformed URL throws
+`MailerConfigError` when the default transport is built, before any send.
+The same transport is `createMailpitTransport({ baseUrl })`. A non-2xx answer
+throws a fixed message with the status, never the response body or the mail.
+
+Otherwise two env names set 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, or the local stack
+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 Lettermint key as a held key from `@wtfalch/keys` and passes it in on
@@ -65,9 +86,6 @@ never fetches or stores it. In the estate, the caller resolves the org's
 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.
 - `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

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, Transport, } from './transport.js';
-export { createDevTransport, createLettermintTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
+export type { LettermintAttachment, LettermintFetchLike, LettermintLike, LettermintSendPayload, LettermintTransportOptions, MailpitTransportOptions, OutgoingMail, Transport, } from './transport.js';
+export { createLettermintTransport, createMailpitTransport, 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, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
+export { createLettermintTransport, createMailpitTransport, defaultTransport, LettermintDomainRefusedError, } from './transport.js';
 export { send } from './send.js';
 export { templates } from './templates/index.js';
 export { renderInvitation } from './templates/invitation.js';

package/dist/send.d.ts

@@ -6,17 +6,17 @@ export interface SendOptions<T extends TemplateName> {
     readonly to: string;
     readonly data: TemplateData<T>;
     readonly from: SenderIdentity;
-    /** Defaults to the dev transport outside production; see `defaultTransport`. */
+    /** Defaults to `defaultTransport()`, which needs `LETTERMINT_API_URL` or throws. */
     readonly transport?: Transport;
-    /** Files to attach, e.g. an invoice or credit note document. Both shipped transports accept these. */
+    /** Files to attach, e.g. an invoice or credit note document. The shipped transport accepts these. */
     readonly attachments?: readonly Attachment[];
 }
 /**
  * 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`).
+ * `transport` defaults to `defaultTransport()`, which throws
+ * `MailerConfigError` unless `LETTERMINT_API_URL` is set, 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

@@ -10,10 +10,10 @@ function formatFrom(identity) {
 /**
  * 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`).
+ * `transport` defaults to `defaultTransport()`, which throws
+ * `MailerConfigError` unless `LETTERMINT_API_URL` is set, 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];

package/dist/transport.d.ts

@@ -10,16 +10,6 @@ export interface OutgoingMail extends MailMessage {
 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, 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 `fetch` to speak Lettermint's
  * Sending API directly -- the same no-SDK, injectable-`fetch` posture
@@ -31,6 +21,7 @@ export type LettermintFetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
     body: string;
+    signal?: AbortSignal;
 }) => Promise<{
     ok: boolean;
     status: number;
@@ -87,6 +78,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
@@ -121,11 +118,38 @@ export declare class LettermintDomainRefusedError extends Error {
  * the network.
  */
 export declare function createLettermintTransport(options: LettermintTransportOptions): Transport;
+export interface MailpitTransportOptions {
+    /** The Mailpit base URL without `/api/v1/send`, e.g. `http://acme-stage-sink:8025`.
+     * Same rule as the Lettermint base URL: https, or http for a local or
+     * single-label internal host. A malformed value throws `MailerConfigError`. */
+    readonly baseUrl: string;
+    /** Injectable `fetch`. Defaults to `globalThis.fetch`. */
+    readonly fetch?: LettermintFetchLike;
+}
+/**
+ * Sends to a Mailpit server's send API (`POST <baseUrl>/api/v1/send`,
+ * https://mailpit.axllent.org/docs/api-v1/view.html#post-/api/v1/send), the
+ * stage mail sink. Sends no token header: a stage app holds no mail
+ * provider token. A non-2xx answer throws a fixed message with the status
+ * only, never the response body or the message content.
+ */
+export declare function createMailpitTransport(options: MailpitTransportOptions): 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 mail 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 `MAIL_SINK_URL` is set, returns a Mailpit transport to
+ * that URL. It wins over every other setting, `LETTERMINT_API_TOKEN` included,
+ * so a stage app never reaches the real provider. A malformed URL throws
+ * `MailerConfigError` here, before any send.
+ *
+ * Otherwise, 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, or the local stack sends every mail to a sink server. A
+ * malformed URL, or a URL with no token, throws `MailerConfigError` here,
+ * before any send.
+ *
+ * Otherwise throws `MailerConfigError`: this package ships no stand-in
+ * transport (docs/adr/0008-remove-dev-transport.md), so `send()` must be
+ * given an explicit transport, or the caller must point `LETTERMINT_API_URL`
+ * at a sink.
  */
 export declare function defaultTransport(): Transport;

package/dist/transport.js

@@ -1,24 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import { mkdirSync, writeFileSync } from 'node:fs';
-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, so nothing that sends mail needs
- * a live key to be tested.
- */
-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' };
-        },
-    };
-}
 /**
  * Thrown when Lettermint refuses to send because the `from` domain is not
  * one the sending project may use -- either unverified, or verified but
@@ -39,7 +19,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
@@ -57,13 +63,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) {
@@ -95,8 +102,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({
@@ -120,16 +128,86 @@ export function createLettermintTransport(options) {
         },
     };
 }
+/** Splits `Name <addr>` or a bare address into Mailpit's `{ Email, Name }`. */
+function toMailpitAddress(formatted) {
+    const match = /^(.*)<([^<>]+)>\s*$/.exec(formatted);
+    if (!match)
+        return { Email: formatted.trim(), Name: '' };
+    return { Email: match[2].trim(), Name: match[1].trim() };
+}
+/**
+ * Sends to a Mailpit server's send API (`POST <baseUrl>/api/v1/send`,
+ * https://mailpit.axllent.org/docs/api-v1/view.html#post-/api/v1/send), the
+ * stage mail sink. Sends no token header: a stage app holds no mail
+ * provider token. A non-2xx answer throws a fixed message with the status
+ * only, never the response body or the message content.
+ */
+export function createMailpitTransport(options) {
+    const baseUrl = parseBaseUrl(options.baseUrl, 'baseUrl');
+    const fetchImpl = options.fetch ?? defaultLettermintFetch();
+    return {
+        async send(message) {
+            const payload = {
+                From: toMailpitAddress(message.from),
+                To: [toMailpitAddress(message.to)],
+                Subject: message.subject,
+                Text: message.text,
+                HTML: message.html,
+                ...(message.replyTo ? { ReplyTo: [toMailpitAddress(message.replyTo)] } : {}),
+                ...(message.attachments
+                    ? {
+                        Attachments: message.attachments.map((attachment) => ({
+                            Filename: attachment.filename,
+                            Content: attachment.content,
+                            ...(attachment.contentType ? { ContentType: attachment.contentType } : {}),
+                        })),
+                    }
+                    : {}),
+            };
+            const response = await fetchImpl(`${baseUrl}/api/v1/send`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(LETTERMINT_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                throw new Error(`mailer: the mail sink refused the message (status ${response.status}).`);
+            }
+            const body = (await response.json());
+            return { id: body.ID ?? 'unknown', transport: 'mailpit' };
+        },
+    };
+}
 /**
- * `dev`, unconditionally, outside `NODE_ENV=production`. In production
- * there is no default: `send()` must be given an explicit transport,
- * because mailer never holds a mail 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 `MAIL_SINK_URL` is set, returns a Mailpit transport to
+ * that URL. It wins over every other setting, `LETTERMINT_API_TOKEN` included,
+ * so a stage app never reaches the real provider. A malformed URL throws
+ * `MailerConfigError` here, before any send.
+ *
+ * Otherwise, 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, or the local stack sends every mail to a sink server. A
+ * malformed URL, or a URL with no token, throws `MailerConfigError` here,
+ * before any send.
+ *
+ * Otherwise throws `MailerConfigError`: this package ships no stand-in
+ * transport (docs/adr/0008-remove-dev-transport.md), so `send()` must be
+ * given an explicit transport, or the caller must point `LETTERMINT_API_URL`
+ * at a sink.
  */
 export function defaultTransport() {
-    if (process.env.NODE_ENV === 'production') {
-        throw new MailerConfigError('send() needs an explicit transport in production: pass { transport: createLettermintTransport({ apiKey }) }.');
+    const mailSinkUrl = process.env.MAIL_SINK_URL;
+    if (mailSinkUrl)
+        return createMailpitTransport({ baseUrl: mailSinkUrl });
+    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 });
     }
-    return createDevTransport();
+    throw new MailerConfigError('send() needs an explicit transport: pass { transport: createLettermintTransport({ apiKey }) }, or set MAIL_SINK_URL (or LETTERMINT_API_URL) to reach a sink.');
 }

package/dist/types.d.ts

@@ -60,7 +60,7 @@ export interface MailMessage {
 /** What a transport returns once it has accepted a message. */
 export interface SendResult {
     readonly id: string;
-    readonly transport: 'dev' | 'lettermint';
+    readonly transport: 'lettermint' | 'mailpit';
 }
 /**
  * `send()` has no usable default (no transport given, and either

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wtfalch/mailer",
-  "version": "0.4.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.",
+  "version": "0.6.0",
+  "description": "One send(template, to, data) call for the estate's transactional email, over Lettermint.",
   "repository": {
     "type": "git",
     "url": "https://github.com/wtfalch/mailer",