@ultimat3/mail 7.0.0 → 8.0.0

package/CLAUDE.md

@@ -37,6 +37,11 @@
 - No hex outside `MAIL_TOKENS`. Base styling is inlined (clients strip `<style>`); dark mode is
   one `prefers-color-scheme` block keyed on short `data-x` role codes.
 - Never format a date without `options.tz`. The `Date:` header is UTC, stated as `+0000`.
+- **Every "now" in this package comes from a `Clock`, `createMemoryDriver` included** (`As of
+  2026-08-22`). It stamped `at: new Date()`, and `SentMail.at` is what `outbox()`, `lastTo()` and
+  the `/_x` panel ORDER on — so the one fact a test most needs to state was the one it could only
+  observe, and two sends inside one millisecond tied. `createMemoryDriver({ clock })`, the same
+  options shape `@ultimat3/jobs`' identically-named driver takes; omitted, it is `systemClock`.
 - 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. **`retryable` becomes the error's `retry` classification, and

package/README.md

@@ -43,7 +43,7 @@ delivers inline only when `{ sync: true }` is passed or no job driver is configu
 
 | Driver | Use | Behaviour |
 |---|---|---|
-| `createMemoryDriver()` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel |
+| `createMemoryDriver({ clock? })` | dev, tests | retains messages; `outbox()` / `lastTo()` feed the `/_x` mail panel, ordered by `SentMail.at` — pass a `frozenClock()` to choose it |
 | `createLogDriver()` | workers without credentials | one structured line per message through core's `logger`; bodies never logged |
 | `createUnconfiguredDriver(env)` | a deploy that configured no transport | refuses every send with `X_MAIL_CREDENTIAL_MISSING`; delivers nothing and claims nothing |
 | `createSmtpDriver({ url, from })` | prod | real ESMTP over `Bun.connect`: STARTTLS, `AUTH PLAIN`/`LOGIN`, quoted-printable MIME |

package/package.json

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

package/src/driver-resend.ts

@@ -2,7 +2,13 @@
 // MailDriver contract — no SDK, `fetch` is the whole client. Construction fails fast on a
 // missing key or an empty from address, so a misconfiguration never waits for the first send.
 
-import { ConfigInvalidError, EnvMissingError, logger, nanoid } from '@ultimat3/core';
+import {
+  ConfigInvalidError,
+  EnvMissingError,
+  logger,
+  nanoid,
+  renderThrowable,
+} from '@ultimat3/core';
 import type { MailDriver, MailMessage, SendResult } from './driver';
 import { messageHeaders, resultFor } from './driver';
 import { sendFailed } from './errors';
@@ -156,8 +162,10 @@ export function createResendDriver(options: ResendDriverOptions): MailDriver {
       } catch (error) {
         // DNS/TLS/reset, or the timeout firing — none of them got far enough to have a status,
         // and every one of them can succeed unchanged on the job's next attempt.
-        const reason =
-          error instanceof Error ? error.message : 'the request failed before a response';
+        // `renderThrowable`, never `error instanceof Error` and `.message`: `fetch` is injected
+        // and the peer is a third party, so `instanceof` RUNS a `Proxy`'s `getPrototypeOf` trap
+        // and its throw escapes this `catch` — the queue's dead-letter row would lose the code.
+        const reason = renderThrowable(error);
         throw sendFailed({
           driver: 'resend',
           stage: 'request',

package/src/driver-smtp.ts

@@ -7,6 +7,7 @@ import {
   ConfigInvalidError,
   isUltimateError,
   nanoid,
+  renderThrowable,
   systemClock,
 } from '@ultimat3/core';
 import type { SendResult } from './driver';
@@ -210,6 +211,11 @@ export function createSmtpDriver(options: SmtpDriverOptions): MailDriver {
   }
 }
 
+/**
+ * `renderThrowable`, never `instanceof` + `.message` or `String(value)`: both RUN code on the
+ * caught value — a prototype read and a `toString` — and a throw here would escape the `catch`
+ * that exists to keep `X_MAIL_SEND_FAILED` on a dropped connection.
+ */
 function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+  return renderThrowable(error);
 }

package/src/driver.ts

@@ -4,7 +4,13 @@
 // `driver-resend.ts`; swapping one for the other is an `app.config.ts` line and zero template
 // changes.
 
-import { type Environment, nanoid, logger as rootLogger } from '@ultimat3/core';
+import {
+  type Clock,
+  type Environment,
+  nanoid,
+  logger as rootLogger,
+  systemClock,
+} from '@ultimat3/core';
 import { driverUnavailable, mailCredentialMissing } from './errors';
 import { mailIdempotencyKey, mailMessageIdToken } from './idempotency';
 
@@ -94,14 +100,29 @@ export interface MemoryMailDriver extends MailDriver {
   clear(): void;
 }
 
-export function createMemoryDriver(): MemoryMailDriver {
+/**
+ * The same `{ clock }` shape `@ultimat3/jobs`' `createMemoryDriver` takes, deliberately: two
+ * in-memory drivers named the same thing in one test file may not want two spellings of "freeze
+ * time". An options object rather than a positional argument so the next seam is additive.
+ */
+export interface MemoryMailDriverOptions {
+  readonly clock?: Clock;
+}
+
+/**
+ * `at` comes from the clock, never from `new Date()`. `SentMail.at` is what `outbox()` and the
+ * `/_x` panel ORDER on, so a suite asserting which message is newest could only race the wall
+ * clock — two sends inside one millisecond tie, and nothing could state the intended order.
+ */
+export function createMemoryDriver(options: MemoryMailDriverOptions = {}): MemoryMailDriver {
+  const clock = options.clock ?? systemClock;
   const sent: SentMail[] = [];
   return {
     name: 'memory',
     sent,
     send(message: MailMessage): Promise<SendResult> {
       const result = resultFor('memory', message, `mem_${nanoid(12)}`);
-      sent.push({ at: new Date(), message, result });
+      sent.push({ at: clock.now(), message, result });
       return Promise.resolve(result);
     },
     outbox: () => [...sent].reverse(),

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
   MailDriver,
   MailMessage,
   MemoryMailDriver,
+  MemoryMailDriverOptions,
   SendResult,
   SentMail,
 } from './driver';