@ultimat3/mail 22.3.6 → 22.5.0

package/CLAUDE.md

@@ -22,12 +22,19 @@
 | `mime.ts` | `MailMessage` → RFC 5322: header order, RFC 2047, folding, quoted-printable |
 | `base64.ts` | base64 over UTF-8 bytes, shared by RFC 2047 and SMTP AUTH |
 | `job.ts` | `sendMailJob` and the envelope schema |
+| `transform.ts` | `setMailTransform`: the app's outbound hook, run once per `send()` before the key |
 | `idempotency.ts` | `mailIdempotencyKey` — apart from `job.ts` because the transports need it too |
 | `catalog.ts` | English source strings for `mail.*`. Data, not code |
 | `html.ts` | escaping + `safeUrl`. The only place that builds an attribute |
 
 ## Rules
 
+- **The transform runs in `send()` only, AFTER render and BEFORE `mailIdempotencyKey`** (`As of
+  2026-09-26`): the key, the queue row and every job retry carry the transformed bytes, and the job
+  never re-runs it. Not in `renderMessage` (previews). It rewrites `subject`/`html`/`text` only; its
+  result is re-checked by `assertHeaderSafe`; a throw or a malformed result is
+  `X_MAIL_TRANSFORM_FAILED` and nothing is sent. None installed ⇒ the same object, byte-identical.
+
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineMail` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
   every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.

package/README.md

@@ -23,6 +23,30 @@ await send(receiptMail, { name: user.name, url }, { to: user.email, locale: ctx.
 `send` validates `data` through the mail's schema, renders, then enqueues `mail.send`. It
 delivers inline only when `{ sync: true }` is passed or no job driver is configured.
 
+### The outbound transform
+
+`setMailTransform(fn)` installs one app-level hook, run once per `send()` after render and before
+the idempotency key is minted — so the key, the queue row and every retry carry its bytes, and a
+job retry never re-runs it. It rewrites `{ subject, html, text }` (never recipients or headers) and
+receives `{ mailName, to, idempotencyKey, locale }`, where `idempotencyKey` is the UNtransformed
+key: key a tracking row on it and a re-called `send()` gets the same pixel id and dedupes. A throw
+or a malformed result is `X_MAIL_TRANSFORM_FAILED` and nothing is sent. `setMailTransform(undefined)`
+removes it; with none installed a send is byte-identical to before.
+
+```ts
+import { type MailRendered, type MailTransformMeta, setMailTransform } from '@ultimat3/mail';
+
+declare const TRACKED: ReadonlySet<string>;
+declare function addPixelAndWrapLinks(
+  rendered: MailRendered,
+  meta: MailTransformMeta,
+): Promise<MailRendered>;
+
+setMailTransform(async (rendered, meta) =>
+  TRACKED.has(meta.mailName) ? await addPixelAndWrapLinks(rendered, meta) : rendered,
+);
+```
+
 ## Rules
 
 | Rule | Why |
@@ -126,6 +150,7 @@ Translating them = shipping `mail.*` keys in an app catalog. Never edit a templa
 | `X_MAIL_CREDENTIAL_MISSING` | set `SMTP_URL` (or `RESEND_API_KEY`) and `MAIL_FROM` in the deployment — an operations one |
 | `X_MAIL_HEADER_INVALID` | strip CR/LF from the interpolated value before it reaches a header |
 | `X_MAIL_ADDRESS_INVALID` | pass a bare `addr-spec` — an envelope address may hold no control character and no `<`/`>` |
+| `X_MAIL_TRANSFORM_FAILED` | the `setMailTransform` hook threw or returned no `{ subject, html, text }` — fix the hook; the mail was not sent |
 | `X_MAIL_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help — and so does `error.retry`, which is what `sendMailJob` acts on: `terminal` dead-letters a 550 or a rejected credential at attempt 1 instead of sending it four more times |
 
 ### Error classes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "22.3.6",
+  "version": "22.5.0",
   "description": "Transactional email as data: one template renders HTML and text, sent through a job.",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.3.6",
-    "@ultimat3/i18n": "22.3.6",
-    "@ultimat3/jobs": "22.3.6",
-    "@ultimat3/schema": "22.3.6",
-    "@ultimat3/time": "22.3.6"
+    "@ultimat3/core": "22.5.0",
+    "@ultimat3/i18n": "22.5.0",
+    "@ultimat3/jobs": "22.5.0",
+    "@ultimat3/schema": "22.5.0",
+    "@ultimat3/time": "22.5.0"
   }
 }

package/src/errors.ts

@@ -20,6 +20,7 @@ export const MAIL_ERROR_CODES = [
   'X_MAIL_HEADER_INVALID',
   'X_MAIL_ADDRESS_INVALID',
   'X_MAIL_SEND_FAILED',
+  'X_MAIL_TRANSFORM_FAILED',
 ] as const;
 
 export type MailErrorCode = (typeof MAIL_ERROR_CODES)[number];
@@ -34,6 +35,7 @@ export const MAIL_ERROR_TITLES: Readonly<Record<MailErrorCode, string>> = {
   X_MAIL_HEADER_INVALID: 'a header value carries a line break',
   X_MAIL_ADDRESS_INVALID: 'an envelope address could restructure the SMTP command line',
   X_MAIL_SEND_FAILED: 'the mail transport refused the message',
+  X_MAIL_TRANSFORM_FAILED: 'the app mail transform threw or returned no message',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -302,3 +304,16 @@ export const sendFailed = (failure: SendFailure): MailError =>
       ...(failure.status === undefined ? {} : { status: failure.status }),
     },
   });
+
+/**
+ * The app's `setMailTransform` hook threw, or handed back something that is not a message. The
+ * send FAILS: delivering the untransformed mail would be a send the app believes was tracked (or
+ * rewritten) and was not, and nothing downstream could tell the difference.
+ */
+export const transformFailed = (mailId: string, reason: string): MailError =>
+  new MailError({
+    code: 'X_MAIL_TRANSFORM_FAILED',
+    cause: `the mail transform failed for "${mailId}": ${reason} — the mail was not sent`,
+    fix: `make the setMailTransform() hook return { subject, html, text } strings for "${mailId}" (return the rendered argument unchanged for a mail it does not track), then retry the send`,
+    meta: { mailId },
+  });

package/src/index.ts

@@ -58,6 +58,7 @@ export {
   sendFailed,
   templateUnknown,
   textMissing,
+  transformFailed,
 } from './errors';
 export { assertHeaderSafe } from './header-safety';
 
@@ -96,7 +97,6 @@ export {
 export type { RenderableMail, RenderedMail, RenderOptions } from './render';
 export { renderMail, textOf } from './render';
 export type { SmtpConnector, SmtpStream } from './smtp-client';
-
 export {
   FRAMEWORK_MAILS,
   type InviteInput,
@@ -119,3 +119,5 @@ export {
   welcomeInput,
   welcomeMail,
 } from './templates';
+export type { MailRendered, MailTransform, MailTransformMeta } from './transform';
+export { mailTransform, setMailTransform } from './transform';

package/src/mail.ts

@@ -14,6 +14,7 @@ import { mailIdempotencyKey } from './idempotency';
 import { sendMailJob } from './job';
 import { BASE_LAYOUT } from './layout';
 import { type RenderableMail, renderMail } from './render';
+import { applyMailTransform } from './transform';
 
 export interface MailDefinition<I> extends RenderableMail<I> {
   readonly id: string;
@@ -160,7 +161,9 @@ export async function send<I>(
   data: I,
   options: SendOptions,
 ): Promise<SendResult> {
-  const message = renderMessage(mail, data, options);
+  // Transform BEFORE the key: the key, the queue row and every retry carry the transformed bytes,
+  // and the job never re-runs the hook. Not in `renderMessage`, which previews call.
+  const message = await applyMailTransform(renderMessage(mail, data, options));
   const key = mailIdempotencyKey(message);
   const queue = jobDriver();
 

package/src/transform.ts

@@ -0,0 +1,108 @@
+// Single responsibility: the app-level OUTBOUND hook — `setMailTransform(fn)` — run once per
+// `send()`, after render and before the idempotency key is minted, so the key, the queue row and
+// every retry all carry the transformed bytes. An app adds an open pixel or rewrites its own links
+// here; the framework only guarantees WHEN it runs, what it sees, and that a failure never ships.
+
+import type { MailMessage } from './driver';
+import { transformFailed } from './errors';
+import { assertHeaderSafe } from './header-safety';
+import { mailIdempotencyKey } from './idempotency';
+
+/** The parts a transform may rewrite. Never the recipients, the sender or the headers. */
+export interface MailRendered {
+  readonly subject: string;
+  readonly html: string;
+  readonly text: string;
+}
+
+export interface MailTransformMeta {
+  /** The mail's `defineMail({ id })` — an app allowlists on it (auth mail is never tracked). */
+  readonly mailName: string;
+  readonly to: readonly string[];
+  /**
+   * The key of the UNtransformed message — the caller's `idempotencyKey` when it gave one, the
+   * content digest otherwise. Stable across a re-called `send()` of the same mail, so an app keys
+   * its tracking row on it and returns the SAME pixel id: the transformed bytes, and therefore the
+   * final key the queue and the provider dedupe on, then match too.
+   */
+  readonly idempotencyKey: string;
+  readonly locale: string;
+}
+
+/**
+ * Deterministic for a given `meta.idempotencyKey`, or a re-called `send()` is a second mail. May be
+ * async (an app records its tracking row). A throw fails the send with `X_MAIL_TRANSFORM_FAILED`.
+ */
+export type MailTransform = (
+  rendered: MailRendered,
+  meta: MailTransformMeta,
+) => MailRendered | Promise<MailRendered>;
+
+let ambient: MailTransform | undefined;
+
+/** Install the app's transform; `undefined` removes it. One per process, like `setMailDriver`. */
+export function setMailTransform(transform: MailTransform | undefined): void {
+  ambient = transform;
+}
+
+export function mailTransform(): MailTransform | undefined {
+  return ambient;
+}
+
+/**
+ * The message `send()` keys and delivers. With no transform installed this returns the SAME
+ * object — every app that never calls `setMailTransform` is byte-identical to before.
+ */
+export async function applyMailTransform(message: MailMessage): Promise<MailMessage> {
+  const transform = ambient;
+  if (transform === undefined) return message;
+  const meta: MailTransformMeta = Object.freeze({
+    mailName: message.mailId,
+    to: Object.freeze([...message.to]),
+    idempotencyKey: mailIdempotencyKey(message),
+    locale: message.locale,
+  });
+  const rendered: MailRendered = Object.freeze({
+    subject: message.subject,
+    html: message.html,
+    text: message.text,
+  });
+  // Reading the result is inside the same guard as the call: a returned object whose `subject`
+  // getter throws is a failed transform too, never a raw error escaping `send()`.
+  let next: MailRendered | undefined;
+  try {
+    next = asRendered(await transform(rendered, meta));
+  } catch (error) {
+    throw transformFailed(message.mailId, `it threw (${describe(error)})`);
+  }
+  if (next === undefined) {
+    throw transformFailed(message.mailId, 'it returned no { subject, html, text } strings');
+  }
+  if (next.text.trim() === '') {
+    throw transformFailed(message.mailId, 'it returned an empty text part');
+  }
+  const transformed: MailMessage = { ...message, ...next };
+  // The subject is the transform's to change, so the header rule is re-checked on what it returned.
+  assertHeaderSafe(transformed);
+  return transformed;
+}
+
+function asRendered(value: unknown): MailRendered | undefined {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const { subject, html, text } = value as Record<string, unknown>;
+  if (typeof subject !== 'string' || typeof html !== 'string' || typeof text !== 'string') {
+    return undefined;
+  }
+  return { subject, html, text };
+}
+
+/**
+ * What KIND of value was thrown, from a closed list — never its message and never its `name`,
+ * which are the app's strings and may carry a recipient address.
+ */
+const KNOWN_ERRORS = new Set(['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError']);
+
+function describe(error: unknown): string {
+  if (error instanceof Error) return KNOWN_ERRORS.has(error.name) ? error.name : 'an Error';
+  return typeof error;
+}