@sdxc/mail 2026.10.13 → 2026.10.16

package/README.md

@@ -259,6 +259,15 @@ Records every delivery instead of sending it. `options.mime: true` also records
 message. Members: `messages`, `last`, `deliveries` (`RecordedDelivery[]`, each
 `{ message, mime? }`), `lastMime`, `find(predicate)` and `clear()`.
 
+### `@sdxc/mail/print`
+
+#### `new PrintTransport(options: PrintTransportOptions)`
+
+Writes each message to `options.write` instead of sending it, and reports it sent: the envelope,
+subject, date, `Message-ID` and extra headers, then the plain-text body. `options.mime: true`
+writes the raw MIME message instead. It writes only through the function it is given, so it runs
+anywhere: `ctx.stderr` in a command, `(text) => process.stderr.write(text)` in a script.
+
 ### `@sdxc/mail/cloudflare`
 
 #### `new CloudflareTransport(binding: SendEmailBinding)`
@@ -277,7 +286,36 @@ binding.
 Publishes a request-scoped `Mailer` as `context.email` and flushes its queue after `next()`.
 `options` takes `transport` (a `Transport`, or `(context) => Transport` per request), `from`,
 `replyTo?` and `headers?`. Each deferred send logs `mail.sent` or a `mail.send_failed` warning
-on the current log.
+on the current log. It publishes under the `CurrentMailer` context key, exported here and from
+`./middleware/cli`, so `ctx.get(CurrentMailer)` reads the same mailer in a route or a command.
+
+### `@sdxc/mail/middleware/cli`
+
+#### `mail(options: MailCommandOptions): CommandMiddleware` (default export)
+
+Publishes a `Mailer` as `ctx.email` on an [`@sdxc/cli`](https://www.npmjs.com/package/@sdxc/cli)
+command, so an admin command resends a message with the templates a route uses. `options` takes
+the router entry's fields, with `transport` a `Transport` or `(ctx) => Transport` per run. The
+queue flushes after the handler and each send is logged as in the router entry; a failed deferred
+send also fails the run with its error. On a laptop, pass a `PrintTransport` writing to the
+command's stderr, so a local run shows each message and never emails a real user.
+
+```typescript
+import { createCLI } from "@sdxc/cli";
+import mail from "@sdxc/mail/middleware/cli";
+import { PrintTransport } from "@sdxc/mail/print";
+
+let cli = createCLI({
+	name: "app",
+	commands,
+	middleware: [
+		mail({
+			transport: (ctx) => new PrintTransport({ write: (text) => ctx.stderr(text) }),
+			from: { email: "no-reply@example.com" },
+		}),
+	],
+});
+```
 
 ### `@sdxc/mail/unsubscribe`
 

package/dist/cli.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@sdxc/cli` middleware that publishes the app's mailer to a command as `ctx.email`, so an admin
+ * command resends an invitation or a receipt with the same templates a route uses, through
+ * whichever transport the app passes for where the command runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { AnyCommandContext, CommandMiddleware } from "@sdxc/cli";
+import type { MailerOptions } from "./mailer.js";
+import type { Transport } from "./types.js";
+import { CurrentMailer } from "./context.js";
+import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
+/** Options that configure the command-line mail middleware. */
+export interface MailCommandOptions extends Omit<MailerOptions, "transport"> {
+    /**
+     * Transport used for delivery, or a factory that resolves one per run from the command's
+     * context, such as one that reads `ctx.flags.remote` to pick the production transport.
+     */
+    transport: Transport | ((ctx: AnyCommandContext) => Transport);
+}
+/**
+ * Publishes a mailer as `ctx.email` for the run. Messages queued with `later()` send once the
+ * handler returns, each outcome is recorded on the run's log, and a failed deferred send fails
+ * the run, so whoever ran the command sees that a message never left.
+ *
+ * @param options - Transport and sender configuration; see {@link MailCommandOptions}.
+ * @returns A middleware that installs `ctx.email`.
+ * @example createCLI({ name: "app", commands, middleware: [mail({ transport: new MemoryTransport(), from: SENDER })] });
+ */
+export default function mail(options: MailCommandOptions): CommandMiddleware<{
+    key: typeof CurrentMailer;
+    value: Mailer;
+    property: "email";
+}>;

package/dist/cli.js

@@ -0,0 +1,62 @@
+/**
+ * `@sdxc/cli` middleware that publishes the app's mailer to a command as `ctx.email`, so an admin
+ * command resends an invitation or a receipt with the same templates a route uses, through
+ * whichever transport the app passes for where the command runs.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { currentLog } from "@sdxc/logger";
+import { failure, isFailure } from "@sdxc/result";
+import { CurrentMailer } from "./context.js";
+import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
+/**
+ * Publishes a mailer as `ctx.email` for the run. Messages queued with `later()` send once the
+ * handler returns, each outcome is recorded on the run's log, and a failed deferred send fails
+ * the run, so whoever ran the command sees that a message never left.
+ *
+ * @param options - Transport and sender configuration; see {@link MailCommandOptions}.
+ * @returns A middleware that installs `ctx.email`.
+ * @example createCLI({ name: "app", commands, middleware: [mail({ transport: new MemoryTransport(), from: SENDER })] });
+ */
+export default function mail(options) {
+    return async (ctx, next) => {
+        let transport = typeof options.transport === "function" ? options.transport(ctx) : options.transport;
+        let mailer = new Mailer({
+            transport,
+            from: options.from,
+            replyTo: options.replyTo,
+            headers: options.headers,
+        });
+        ctx.set(CurrentMailer, mailer, { property: "email" });
+        let failed;
+        try {
+            await next();
+        }
+        finally {
+            failed = await flush(mailer);
+        }
+        if (failed !== undefined)
+            return failure(failed);
+    };
+}
+/**
+ * Sends the mailer's deferred queue, recording each outcome on the run's log.
+ *
+ * @returns The first send's error, or `undefined` when every message left.
+ */
+async function flush(mailer) {
+    let log = currentLog();
+    let failed;
+    for (let result of await mailer.flush()) {
+        if (isFailure(result)) {
+            log?.warn("mail.send_failed", { error: result.error.message });
+            failed ??= result.error;
+        }
+        else {
+            log?.set({ mail: { sent: true } }).note("mail.sent", { message_id: result.data.messageId });
+        }
+    }
+    return failed;
+}

package/dist/context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The context key the router and command-line middleware publish the mailer under, so code that
+ * reads it by key sends through the same mailer whichever host it runs in.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Mailer } from "./mailer.js";
+/** The mailer the current invocation sends through, installed as `ctx.email`. */
+export declare const CurrentMailer: {
+    defaultValue?: Mailer;
+};

package/dist/context.js

@@ -0,0 +1,10 @@
+/**
+ * The context key the router and command-line middleware publish the mailer under, so code that
+ * reads it by key sends through the same mailer whichever host it runs in.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createContextKey } from "remix/router";
+/** The mailer the current invocation sends through, installed as `ctx.email`. */
+export const CurrentMailer = createContextKey();

package/dist/middleware.d.ts

@@ -11,6 +11,7 @@
 import type { Middleware, RequestContext } from "remix/router";
 import type { Address, Transport } from "./types.js";
 import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
 /**
  * Declared here, in an imported module rather than an ambient .d.ts, so the
  * augmentation is applied in consuming projects that import the middleware.
@@ -40,10 +41,9 @@ export interface MailMiddlewareOptions {
     headers?: Record<string, string>;
 }
 /**
- * Creates a middleware that publishes a request-scoped mailer as `context.email`,
- * resolving a container-based transport once per request. The `later()` queue
- * flushes in a `finally` after `next()`; the response is already decided by then,
- * so a failed deferred send is a warning on the invocation's log rather than an error.
+ * Publishes a request-scoped mailer as `context.email`, under the {@link CurrentMailer} key the
+ * command-line entry shares. The `later()` queue flushes after `next()`, when the response is
+ * already decided, so a failed deferred send is a warning on the invocation's log.
  *
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.

package/dist/middleware.js

@@ -10,12 +10,13 @@
  */
 import { currentLog } from "@sdxc/logger";
 import { isFailure } from "@sdxc/result";
+import { CurrentMailer } from "./context.js";
 import { Mailer } from "./mailer.js";
+export { CurrentMailer } from "./context.js";
 /**
- * Creates a middleware that publishes a request-scoped mailer as `context.email`,
- * resolving a container-based transport once per request. The `later()` queue
- * flushes in a `finally` after `next()`; the response is already decided by then,
- * so a failed deferred send is a warning on the invocation's log rather than an error.
+ * Publishes a request-scoped mailer as `context.email`, under the {@link CurrentMailer} key the
+ * command-line entry shares. The `later()` queue flushes after `next()`, when the response is
+ * already decided, so a failed deferred send is a warning on the invocation's log.
  *
  * @param options - Transport and sender configuration; see {@link MailMiddlewareOptions}.
  * @returns A middleware that populates `context.email`.
@@ -31,7 +32,7 @@ export default function mail(options) {
             replyTo: options.replyTo,
             headers: options.headers,
         });
-        context.email = mailer;
+        context.set(CurrentMailer, mailer, { property: "email" });
         try {
             return await next();
         }

package/dist/print.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transport that prints each message instead of delivering it, for development and command
+ * lines run against local data: the message shows where the developer is looking and never
+ * reaches a real inbox. It writes through a function it is given, so it runs on any runtime.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Result } from "@sdxc/result";
+import type { MailError } from "./errors.js";
+import type { NormalizedMessage, SentMessage, Transport } from "./types.js";
+/** Where a print transport writes, and in which form. */
+export interface PrintTransportOptions {
+    /**
+     * Receives each printed message as one string ending in a newline, such as `ctx.stderr`
+     * in a command or `(text) => process.stderr.write(text)` in a script.
+     */
+    write: (text: string) => void;
+    /**
+     * Print the raw MIME message, headers and every part, instead of the readable summary.
+     * @default false
+     */
+    mime?: boolean;
+}
+/**
+ * Transport that writes each message to `options.write` and reports it sent. The summary lists
+ * the envelope, the subject, the date, the `Message-ID` and any extra headers, then the
+ * plain-text body (the HTML one when a message has no text).
+ *
+ * @example new Mailer({ transport: new PrintTransport({ write: (text) => ctx.stderr(text) }), from: SENDER });
+ * @example new PrintTransport({ write: (text) => process.stderr.write(text), mime: true });
+ */
+export declare class PrintTransport implements Transport {
+    #private;
+    /**
+     * Creates the transport.
+     *
+     * @param options - Where to write and in which form; see {@link PrintTransportOptions}.
+     */
+    constructor(options: PrintTransportOptions);
+    /**
+     * Prints the message and reports success.
+     *
+     * @param message - The normalized message to print.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    send(message: NormalizedMessage): Promise<Result<SentMessage, MailError>>;
+}

package/dist/print.js

@@ -0,0 +1,72 @@
+/**
+ * Transport that prints each message instead of delivering it, for development and command
+ * lines run against local data: the message shows where the developer is looking and never
+ * reaches a real inbox. It writes through a function it is given, so it runs on any runtime.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { success } from "@sdxc/result";
+import { buildMimeMessage } from "./mime.js";
+/**
+ * Transport that writes each message to `options.write` and reports it sent. The summary lists
+ * the envelope, the subject, the date, the `Message-ID` and any extra headers, then the
+ * plain-text body (the HTML one when a message has no text).
+ *
+ * @example new Mailer({ transport: new PrintTransport({ write: (text) => ctx.stderr(text) }), from: SENDER });
+ * @example new PrintTransport({ write: (text) => process.stderr.write(text), mime: true });
+ */
+export class PrintTransport {
+    /** The function each printed message goes to. */
+    #write;
+    /** Whether messages print as raw MIME. */
+    #mime;
+    /**
+     * Creates the transport.
+     *
+     * @param options - Where to write and in which form; see {@link PrintTransportOptions}.
+     */
+    constructor(options) {
+        this.#write = options.write;
+        this.#mime = options.mime ?? false;
+    }
+    /**
+     * Prints the message and reports success.
+     *
+     * @param message - The normalized message to print.
+     * @returns Success carrying the message's own `Message-ID`, since no provider assigned one.
+     */
+    async send(message) {
+        this.#write(this.#mime ? ensureNewline(buildMimeMessage(message)) : summarize(message));
+        return success({ messageId: message.messageId });
+    }
+}
+/** The readable form of a message: one header per line, a blank line, then the body. */
+function summarize(message) {
+    let lines = [`From: ${formatAddresses([message.from])}`, `To: ${formatAddresses(message.to)}`];
+    if (message.cc.length > 0)
+        lines.push(`Cc: ${formatAddresses(message.cc)}`);
+    if (message.bcc.length > 0)
+        lines.push(`Bcc: ${formatAddresses(message.bcc)}`);
+    if (message.replyTo.length > 0)
+        lines.push(`Reply-To: ${formatAddresses(message.replyTo)}`);
+    lines.push(`Subject: ${message.subject}`);
+    lines.push(`Date: ${message.date.toUTCString()}`);
+    lines.push(`Message-ID: ${message.messageId}`);
+    for (let [name, value] of Object.entries(message.headers))
+        lines.push(`${name}: ${value}`);
+    let body = message.text ?? message.html ?? "";
+    return `${lines.join("\n")}\n\n${ensureNewline(body)}`;
+}
+/** Mailboxes as a mail client shows them: `Name <email>`, or the bare address without a name. */
+function formatAddresses(addresses) {
+    return addresses
+        .map((address) => address.name === undefined || address.name === ""
+        ? address.email
+        : `${address.name} <${address.email}>`)
+        .join(", ");
+}
+/** `text` ending in exactly one newline, so consecutive messages never run together. */
+function ensureNewline(text) {
+    return text.endsWith("\n") ? text : `${text}\n`;
+}

package/package.json

@@ -1,27 +1,37 @@
 {
 	"name": "@sdxc/mail",
-	"version": "2026.10.13",
+	"version": "2026.10.16",
 	"description": "Transport-agnostic transactional email with pluggable transports and remix/component rendering",
 	"license": "MIT",
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
+		"./cloudflare": "./dist/cloudflare.js",
 		"./markdown": "./dist/markdown.js",
 		"./memory": "./dist/memory.js",
+		"./print": "./dist/print.js",
 		"./middleware": "./dist/middleware.js",
-		"./cloudflare": "./dist/cloudflare.js",
+		"./middleware/cli": "./dist/cli.js",
 		"./unsubscribe": "./dist/unsubscribe.js"
 	},
 	"dependencies": {
 		"@sdxc/crypto": "2026.10.13",
-		"@sdxc/highlight": "2026.10.13",
-		"@sdxc/logger": "2026.10.13",
-		"@sdxc/markdown": "2026.10.13",
+		"@sdxc/highlight": "2026.10.16",
+		"@sdxc/logger": "2026.10.16",
+		"@sdxc/markdown": "2026.10.16",
 		"@sdxc/result": "2026.10.13",
-		"@sdxc/uuid": "2026.10.13",
+		"@sdxc/uuid": "2026.10.13"
+	},
+	"peerDependencies": {
+		"@sdxc/cli": "2026.10.16",
 		"remix": "3.0.0"
 	},
-	"gitHead": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"peerDependenciesMeta": {
+		"@sdxc/cli": {
+			"optional": true
+		}
+	},
+	"gitHead": "1e547d8431568f5ed9bdb079ca3046c936240fde",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -30,7 +40,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/mail"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/mail",
+	"homepage": "https://sdxc.dev/api/mail",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"