@ultimat3/mail 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -39,8 +39,14 @@
 - Never format a date without `options.tz`. The `Date:` header is UTC, stated as `+0000`.
 - New block kind: `MailBlock` + `blocks` + `htmlOf` + `textOf`, same commit.
 - A transport failure is `sendFailed({ stage, status, retryable, fix })` — never a bare throw, and
-  never a `retryable` guess. `stage` is the `SendStage` union in `errors.ts`; a new step goes there
-  first. The transient set is 4xx over SMTP, and 408/409/425/429 + 5xx over HTTP — that HTTP set
+  never a `retryable` guess. **`retryable` becomes the error's `retry` classification, and
+  `X_MAIL_SEND_FAILED` is REGISTERED** (`registerErrorRetry`, `As of 2026-08`) — both halves, because
+  `classifyThrown` honours a per-instance `terminal` only for a registered code. It rode in `meta`
+  alone and nothing read it, so `sendMailJob` spent all five attempts on a 401 or a 550 hard bounce
+  while its own `cause` said retrying cannot help. `errors.test.ts` asserts it through the QUEUE's
+  `nextRetryForError`, never against the table.
+  `stage` is the `SendStage` union in `errors.ts`; a new step goes there first.
+  The transient set is 4xx over SMTP, and 408/409/425/429 + 5xx over HTTP — that HTTP set
   lives in `RETRYABLE_STATUSES` (`driver-resend.ts`) and is edited there, never restated.
 - A transport is selected from the environment by `selectMailDriver`, never from an `app.config.ts`
   field — nothing loads that file's contents at runtime, so a `mail:` config block would be a

package/README.md

@@ -125,7 +125,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_SEND_FAILED` | the `cause` names the stage, the provider's status and whether a retry can help |
+| `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 |
 
 ## Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mail",
-  "version": "2.0.0",
+  "version": "4.0.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": "2.0.0",
-    "@ultimat3/i18n": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/schema": "2.0.0",
-    "@ultimat3/time": "2.0.0"
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/i18n": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/schema": "4.0.0",
+    "@ultimat3/time": "4.0.0"
   }
 }

package/src/catalog.ts

@@ -82,7 +82,27 @@ export const MAIL_CATALOG_SOURCE: NestedCatalog = {
 
 export const MAIL_CATALOG: Catalog = loadCatalog(MAIL_CATALOG_SOURCE);
 
-/** Called at boot next to `registerFrameworkCatalog()`. Idempotent. */
-export function registerMailCatalog(locale: Locale = DEFAULT_LOCALE): void {
-  registerCatalog(locale, MAIL_CATALOG);
+/** The one locale these strings are written in. */
+export const MAIL_CATALOG_LOCALE: Locale = DEFAULT_LOCALE;
+
+/**
+ * Register the mail templates' own strings under the ONE locale they are written in.
+ *
+ * **No locale parameter, and that is the fix**: this catalog is English, so `registerMailCatalog('es')`
+ * seated English subjects and headings under `es` where `isMiss` then read FALSE — a fallback locale
+ * chain wearing registration as a disguise, the same defect `registerFrameworkCatalog` carried until
+ * it lost its own parameter. A locale argument is now a compile error rather than a silent one.
+ *
+ * **Call it once, at boot.** This is NOT idempotent, and the comment here claimed it was:
+ * `registerCatalog` merges the existing entry first and its argument second, so a second call after
+ * an app has overridden `mail.*` keys puts the English strings back on top of exactly the keys that
+ * app cared enough to translate. Guarding on "has this locale a catalog" — the shape
+ * `registerFrameworkCatalog` uses — cannot work here, because the framework catalog has already
+ * claimed this locale by the time mail registers; a guard by CONTENT needs an i18n primitive that
+ * does not exist, and remembering the call in a module flag goes stale the moment
+ * `resetCatalogs()` runs (`packages/testing/src/registry-snapshot.ts`), which would silently stop
+ * registering altogether. Stating the limit beats inventing a guard that fails quietly.
+ */
+export function registerMailCatalog(): void {
+  registerCatalog(MAIL_CATALOG_LOCALE, MAIL_CATALOG);
 }

package/src/driver.ts

@@ -6,7 +6,7 @@
 
 import { type Environment, nanoid, logger as rootLogger } from '@ultimat3/core';
 import { driverUnavailable, mailCredentialMissing } from './errors';
-import { mailIdempotencyKey } from './idempotency';
+import { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 
 /** The rendered envelope. Everything a transport needs; nothing it does not. */
 export interface MailMessage {
@@ -156,6 +156,14 @@ export function isUnconfiguredDriver(driver: MailDriver): boolean {
 /**
  * Structured log line per message through core's `logger` — the default for a worker that
  * has no credentials yet. Bodies are never logged; a mail body is user data.
+ *
+ * `to` is a COUNT and the correlation handle is the message-id TOKEN, not the idempotency key —
+ * and the second half is the one that was wrong. `mailIdempotencyKey` is
+ * `mail:<id>:<recipients joined>:<digest>`, so logging it put the `to` addresses in the line in
+ * plaintext, one field after the count that exists to keep them out, against
+ * `packages/mail/CLAUDE.md`'s "Recipient addresses stay out of logs". `mailMessageIdToken` is the
+ * framework's existing spelling for the same key digested — it was written for exactly this
+ * reason and says so — and it correlates just as well, because it is stable per message.
  */
 export function createLogDriver(logger = rootLogger): MailDriver {
   return {
@@ -167,7 +175,7 @@ export function createLogDriver(logger = rootLogger): MailDriver {
         to: message.to.length,
         subject: message.subject,
         locale: message.locale,
-        idempotencyKey: result.idempotencyKey,
+        idempotencyToken: mailMessageIdToken(message),
       });
       return Promise.resolve(result);
     },

package/src/errors.ts

@@ -2,7 +2,13 @@
 // Mail fails in production, not in tests — a wrong locale, an empty text part or an
 // unconfigured driver must name the exact call site edit that repairs it.
 
-import { type Environment, registerErrorCodes, UltimateError } from '@ultimat3/core';
+import {
+  type Environment,
+  type ErrorRetry,
+  registerErrorCodes,
+  registerErrorRetry,
+  UltimateError,
+} from '@ultimat3/core';
 
 export const MAIL_ERROR_CODES = [
   'X_MAIL_LOCALE_MISSING',
@@ -37,11 +43,35 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(MAIL_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
+/**
+ * The one code in this package a queue may retry, and it is registered rather than merely written
+ * down: `classifyThrown` reads a per-instance `terminal` only for a code somebody REGISTERED, so a
+ * table with no `registerErrorRetry` call behind it lets `sendMailJob` spend all five attempts on
+ * a 401 or a 550 hard bounce — the `cause` saying "permanent, retrying cannot help" while the
+ * worker retries it four more times.
+ *
+ * `retryable` is the table entry because a transport that cannot say is a transport that timed out;
+ * the permanent half arrives as the per-instance override `sendFailed` passes below, the shape
+ * `@ultimat3/scraping` uses for `X_SCRAPE_HTTP_FAILED`. Every other code here is a wiring or
+ * content fault that fails identically forever, and takes core's `terminal` default.
+ */
+export const MAIL_ERROR_RETRY = {
+  X_MAIL_SEND_FAILED: 'retryable',
+} as const satisfies Readonly<Partial<Record<MailErrorCode, ErrorRetry>>>;
+
+registerErrorRetry(MAIL_ERROR_RETRY);
+
 export interface MailErrorInit {
   readonly code: MailErrorCode;
   readonly cause: string;
   readonly fix: string;
   readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * Per-instance override of the table above, for the one code that is genuinely both: a 421
+   * greylist and a 550 hard bounce are the same code, and only the transport that saw the reply
+   * knows which one it was.
+   */
+  readonly retry?: ErrorRetry | undefined;
 }
 
 export class MailError extends UltimateError {
@@ -54,6 +84,7 @@ export class MailError extends UltimateError {
       fix: init.fix,
       docs: `https://ultimate.dev/errors/${init.code}`,
       meta: init.meta,
+      ...(init.retry === undefined ? {} : { retry: init.retry }),
     });
   }
 }
@@ -220,6 +251,10 @@ export interface SendFailure {
 export const sendFailed = (failure: SendFailure): MailError =>
   new MailError({
     code: 'X_MAIL_SEND_FAILED',
+    // The classification the queue acts on. `meta.retryable` below is an operator-facing FACT and
+    // nothing reads it to make a decision — `nextRetryForError` reads `error.retry`, so a failure
+    // that only reported itself in `meta` was a failure the worker retried anyway.
+    retry: failure.retryable ? 'retryable' : 'terminal',
     cause:
       `${failure.driver} refused the message at ${failure.stage}` +
       `${failure.status === undefined ? '' : ` (${failure.status})`}: ${failure.detail} — ` +

package/src/index.ts

@@ -7,7 +7,12 @@ export { t } from '@ultimat3/schema';
 export type { CalloutTone, MailBlock, MailTemplate, TemplateArgs } from './blocks';
 export { blocks } from './blocks';
 
-export { MAIL_CATALOG, MAIL_CATALOG_SOURCE, registerMailCatalog } from './catalog';
+export {
+  MAIL_CATALOG,
+  MAIL_CATALOG_LOCALE,
+  MAIL_CATALOG_SOURCE,
+  registerMailCatalog,
+} from './catalog';
 export type {
   MailDriver,
   MailMessage,
@@ -49,6 +54,7 @@ export {
   layoutUnknown,
   localeMissing,
   MAIL_ERROR_CODES,
+  MAIL_ERROR_RETRY,
   MAIL_ERROR_TITLES,
   MailError,
   mailCredentialMissing,