@wtfalch/mailer 0.4.0 → 0.5.0

package/README.md

@@ -45,6 +45,16 @@ await send({
 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
+`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 Lettermint key as a held key from `@wtfalch/keys` and passes it in on

package/dist/transport.d.ts

@@ -31,6 +31,7 @@ export type LettermintFetchLike = (url: string, init: {
     method: string;
     headers: Record<string, string>;
     body: string;
+    signal?: AbortSignal;
 }) => Promise<{
     ok: boolean;
     status: number;
@@ -87,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
@@ -122,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 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 `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

@@ -39,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
@@ -57,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) {
@@ -95,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({
@@ -121,13 +149,25 @@ 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 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 `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: createLettermintTransport({ apiKey }) }.');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/mailer",
-  "version": "0.4.0",
+  "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",