@wtfalch/mailer 0.5.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,24 +36,35 @@ 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.
 
-Two env names change that default, in every `NODE_ENV`: with
+`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, 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 })`.
+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
@@ -75,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
@@ -128,14 +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;
 /**
- * When `LETTERMINT_API_URL` is set (in any `NODE_ENV`), returns a Lettermint
+ * 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, sends every mail to a sink server. A malformed URL, or a URL
- * with no token, throws `MailerConfigError` here, before any send.
+ * 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: `dev` outside `NODE_ENV=production`; in production there is no
- * default, and `send()` must be given an explicit transport.
+ * 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
@@ -148,17 +128,78 @@ 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() };
+}
 /**
- * When `LETTERMINT_API_URL` is set (in any `NODE_ENV`), returns a Lettermint
+ * 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' };
+        },
+    };
+}
+/**
+ * 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, sends every mail to a sink server. A malformed URL, or a URL
- * with no token, throws `MailerConfigError` here, before any send.
+ * 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: `dev` outside `NODE_ENV=production`; in production there is no
- * default, and `send()` must be given an explicit transport.
+ * 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() {
+    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');
@@ -168,8 +209,5 @@ export function defaultTransport() {
         }
         return createLettermintTransport({ apiKey, baseUrl });
     }
-    if (process.env.NODE_ENV === 'production') {
-        throw new MailerConfigError('send() needs an explicit transport in production: pass { transport: createLettermintTransport({ apiKey }) }.');
-    }
-    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.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.",
+  "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",