mail-time 4.0.0 → 5.0.0

package/README.md

@@ -1,17 +1,25 @@
 
 # MailTime
 
-[![npm version](https://img.shields.io/npm/v/mail-time.svg?label=mail-time)](https://www.npmjs.com/package/mail-time)
-[![CI](https://img.shields.io/github/actions/workflow/status/veliovgroup/mail-time/ci.yml?branch=master)](https://github.com/veliovgroup/mail-time/actions)
-[![license](https://img.shields.io/npm/l/mail-time.svg)](LICENSE)
-[![GitHub Sponsors](https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor)](https://github.com/sponsors/dr-dimitru)
-[![Donate](https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/veliovgroup)
+[![npm version][badge-npm-v]][npm-url]
+[![npm downloads][badge-npm-dm]][npm-url]
+[![CI][badge-ci]][ci-url]
+[![bundle size][badge-size]][size-url]
+[![Coverage][badge-cov]](#testing)
+[![License: BSD-3-Clause][badge-license]][license-url]
+[![Node.js][badge-node]][node-url]
+[![TypeScript][badge-ts]][ts-url]
+[![Bun][badge-bun]][bun-url]
+[![Meteor][badge-meteor]][meteor-url]
+[![dependencies][badge-deps]][deps-url]
+[![Sponsor][badge-sponsor]][sponsor-url]
+[![Donate][badge-donate]][donate-url]
 
 Bulletproof email queue for [horizontally scaled](#sending-emails-from-a-cluster) Node.js & Bun apps. Built on top of [`nodemailer`](https://github.com/nodemailer/nodemailer) and [`josk`](https://github.com/veliovgroup/josk). Single runtime dependency, ESM + CJS, full TypeScript declarations.
 
 `MailTime` runs in one of two modes:
 
-- **`server`** — drains the queue and sends emails via SMTP. The cluster-aware lease guarantees exactly one server sends each email even when many are running.
+- **`server`** — drains the queue and sends emails via SMTP. Per-row leases let one worker claim each attempt even when many are running.
 - **`client`** — only enqueues emails. Use for app servers in a "dedicated mail micro-service" topology.
 
 Many clients + one or more servers coexist behind the same `prefix` in the same store.
@@ -21,14 +29,14 @@ Many clients + one or more servers coexist behind the same `prefix` in the same
 - 🏢 **Horizontally scaled** — synchronize one queue across N processes/hosts/DCs.
 - 🔁 **Multi-SMTP rotation** — `backup` (failover) and `balancer` (round-robin) strategies.
 - 💪 **Built-in retries** — storage-backed retry with per-letter transport pinning.
-- 🎯 **Per-recipient retries** — when a multi-`to` send is partially rejected, only the un-accepted addresses are retried; delivered ones never see a duplicate.
+- 🎯 **Per-recipient retries** — when a multi-`to` send is partially rejected, later attempts exclude accepted addresses.
 - 📮 **Email concatenation** — fold same-`to` emails arriving inside a window into one letter.
 - 🎛️ **One-line setup** — built-in [presets](#settings-presets) for `transactional`, `otp`, `newsletter`, `marketing`, `notifications`, `alerts`.
 - 🛢️ **Three first-party storages** — MongoDB, Redis, PostgreSQL. Plus a [custom-adapter contract](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).
 - 📦 **Bun ≥ 1.1.0 & Node ≥ 20.9.0** — same code, both runtimes.
 - 🤖 **Ships with AI agent skills** — see [AI agent skills](#ai-agent-skills) below.
 - 📐 **Hand-tuned ESM + CJS + TypeScript declarations**.
-- 🧪 **95%+ Jest coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
+- 🧪 **99%+ Jest line coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
 
 ## How it works
 
@@ -76,7 +84,7 @@ MailTime keeps every letter in the queue until SMTP confirms delivery.
 
 ### Sending emails from a cluster
 
-Most apps schedule recurring emails (daily digest, weekly summary). On a single server this is trivial. In a cluster, every node would otherwise send the same email N times. MailTime's lease prevents the duplicate sends.
+Most apps schedule recurring emails (daily digest, weekly summary). On a single server this is trivial. In a cluster, every node would otherwise send the same email N times. MailTime's lease prevents concurrent duplicate claims. SMTP acceptance and queue completion cannot be one atomic transaction: a worker crash between them can still cause a later retry. See [reliability boundary](https://github.com/veliovgroup/mail-time/blob/master/docs/tuning.md#reliability-boundary).
 
 ```ascii
 |===================THE=CLUSTER===================| |=QUEUE=|
@@ -131,7 +139,7 @@ bun add mail-time nodemailer
 > `nodemailer` and adapter drivers are peers (not bundled) so you can pin your own versions.
 
 > [!IMPORTANT]
-> Upgrading from v3? See [Migration from 3.x](#migration-from-3x) and the full [v4.0.0 release notes](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md).
+> Upgrading? See the [Migrations](#migrations) table below for links to the detailed guides.
 
 For Meteor.js usage see [docs/meteor.md](https://github.com/veliovgroup/mail-time/blob/master/docs/meteor.md).
 
@@ -140,16 +148,22 @@ For Meteor.js usage see [docs/meteor.md](https://github.com/veliovgroup/mail-tim
 MailTime ships a Claude / Copilot / Cursor / Codex / Gemini-ready skill bundle. Install it once in your project (or globally) and your AI agent will reach for the right preset, adapter, and pitfall list without you having to paste docs into the chat.
 
 ```sh
-# Install the MailTime skill into the current project:
+# Install the MailTime skill globally:
+npx skills add veliovgroup/mail-time -g
+
+# Or install the MailTime skill into the current project:
 npx skills add veliovgroup/mail-time
 
 # Recommended: also install the JoSk skill — MailTime is built on JoSk,
 # and deep scheduler questions resolve through JoSk's contract.
-npx skills add veliovgroup/josk
+npx skills add veliovgroup/josk -g
 ```
 
 The `npx skills` CLI ([vercel-labs/skills](https://github.com/vercel-labs/skills)) supports 50+ AI coding agents. Pass `-g` to install user-wide, or `-a claude-code` to target a specific agent. The bundled MailTime skill covers the public API, every queue adapter, the preset table, tuning levers, and common pitfalls — it's the same material as the README and `docs/`, structured for an LLM.
 
+> [!NOTE]
+> The skill source is **not** shipped in the npm tarball — it's distributed via GitHub and consumed only by AI tooling.
+
 ## Quick start
 
 Three things every MailTime needs: a connected storage **client**, one or more **nodemailer transports** (server only), and a **`josk.adapter`** that points at the scheduler storage (server only). Past that, reach for a [preset](#settings-presets) instead of hand-tuning every knob.
@@ -257,9 +271,26 @@ process.on('SIGTERM', async () => {
 });
 ```
 
-Or explicitly: `mailQueue.destroy(); await mailQueue.drain();`
+`destroy()` without `{ drain: true }` stops immediately: in-flight completions make no storage writes and their claims recover after `sendingTimeout`. Use it for forced teardown, not graceful shutdown.
+
+#### Pause / resume a server (backpressure)
+
+`pause()` stops this **server** instance from competing for the queue-drain lease without tearing it down (unlike `destroy()`). In-flight SMTP sends finish; other `server` instances keep draining. `resume()` resumes and triggers an immediate scan.
 
-`destroy()` is idempotent and stops the scheduler. Always call it from tests; pair with `drain()` when iterate-driven sends ran.
+```js
+mailQueue.pause();              // stop draining on this pod
+// ...SMTP provider rate-limit clears / maintenance window ends...
+mailQueue.resume();             // resume; an immediate scan kicks off
+
+mailQueue.isPaused;             // boolean
+(await mailQueue.ping()).paused // boolean — observable in health checks
+
+// Stop draining AND wait for in-flight sends to settle:
+mailQueue.pause();
+await mailQueue.drain();
+```
+
+Both return `boolean` and are no-ops (returning `false`) on `client` instances or after `destroy()`. Use for SMTP rate-limit backpressure, rolling deploys, or quota windows.
 
 ## Storage layouts
 
@@ -267,7 +298,7 @@ Queue storage and scheduler storage can be the same store or different ones. Use
 
 | Queue    | Scheduler (`josk`) | Best for                                     |
 | -------- | ------------------ | -------------------------------------------- |
-| Postgres | Postgres           | Multi-DC, mixed clocks, strict exactly-once. |
+| Postgres | Postgres           | Multi-DC, mixed clocks, strongest consistency. |
 | Redis    | Redis              | High-throughput single-region.               |
 | Mongo    | Mongo              | Apps already on Mongo (especially Meteor).   |
 | Mongo    | Redis              | Durable letter storage + sub-second polling. |
@@ -305,11 +336,11 @@ const mailTime = new MailTime(mailTimePreset('otp', {
 | Preset          | Shape                                                                                                                                              | Best for                                                                                |
 | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
 | `transactional` | `retries: 30`, `retryDelay: 10s`, `concatEmails: false`, `concurrency: 1`, `josk.zombieTime: 120s`                                                 | Receipts, password resets, account changes, welcome emails.                             |
-| `otp`           | `retries: 5`, `retryDelay: 2s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 4`, `sendingTimeout: 60s`                      | Sign-in codes, 2FA, verification codes — stale OTPs aren't worth resending forever.     |
+| `otp`           | `retries: 5`, `retryDelay: 2s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 4`, `sendingTimeout: 2min`                     | Sign-in codes, 2FA, verification codes — stale OTPs aren't worth resending forever.     |
 | `newsletter`    | `concatEmails: true` with a 5-minute fold window, `concatSubject: 'Your updates'`, `retries: 5`, `retryDelay: 60s`, `concurrency: 2`, `sendingTimeout: 10min`, `josk.zombieTime: 5min` | Scheduled digests, weekly summaries, "what's new" emails.                               |
 | `marketing`     | `retries: 10`, `retryDelay: 30s`, `concatEmails: false`, `concurrency: 5`, `josk.zombieTime: 3min`                                                 | Promotional / campaign blasts where each letter is unique.                              |
 | `notifications` | `concatEmails: true` with a 60-second fold window, `concatSubject: 'New activity'`, `retries: 8`, `retryDelay: 30s`, `concurrency: 3`, `josk.zombieTime: 3min` | App / social activity (likes, mentions, follows) where bursts collapse into one letter. |
-| `alerts`        | `retries: 20`, `retryDelay: 5s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 2`, `sendingTimeout: 60s`                     | Ops / admin alerts: monitoring, error reports, escalations.                             |
+| `alerts`        | `retries: 20`, `retryDelay: 5s`, snappy `revolvingInterval: 1024` + jitter `256/1024`, `concurrency: 2`, `sendingTimeout: 2min`                     | Ops / admin alerts: monitoring, error reports, escalations.                             |
 
 Presets are equally useful on `type: 'client'` instances — keys that don't apply to the client role are simply ignored.
 
@@ -338,8 +369,12 @@ Defaults fit moderate traffic in a single region. Reach for a [preset](#settings
 | Option                                         | Default          | Change when                                                                                                                        |
 | ---------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | `mode`                                         | `'batch'`        | `'one'` to claim a single row per tick (fairness over throughput across cluster nodes)                                             |
-| `concurrency`                                  | `1`              | Raise to send N emails in parallel per instance. Bounded by your SMTP / API rate limits. The CAS on `isSending` keeps it safe.     |
-| `sendingTimeout`                               | `300000` (5 min) | Stale-lock recovery window. Must exceed worst-case SMTP roundtrip; lower it only when you're confident sends never take that long. |
+| `concurrency`                                  | `1`              | Raise to send N emails in parallel per instance. CAS blocks concurrent claims; SMTP rate limits still apply.                     |
+| `sendingTimeout`                               | `300000` (5 min) | Stale-lock recovery window. Must exceed worst-case SMTP roundtrip; MailTime logs a warning below `120000`. |
+| `renewClaim`                                   | `sendingTimeout / 3` | Set `false` to go back to a single stamp at claim time. Lower it if your storage round-trip is slow relative to `sendingTimeout`. |
+| `maxRenewals`                                  | `10`             | Renewal-attempt ceiling. Recovery begins `sendingTimeout` after last successful stamp; with responsive storage this is roughly `sendingTimeout + maxRenewals × renewClaim`. |
+| `shouldFailOver`                               | —                | Set when your transport can tell "never delivered" from "may have been delivered" — see [Transport fail-over](#transport-fail-over). |
+| `strictPayload`                                | `false`          | Turn on when anything other than your own app can write to the queue storage. |
 | `revolvingInterval`                            | `1536` ms        | Lower → faster pickup; higher → less scheduler I/O                                                                                 |
 | `josk.minRevolvingDelay` / `maxRevolvingDelay` | `512` / `2048`   | Lower both → snappier polls, more storage load                                                                                     |
 | `josk.zombieTime`                              | `60000`          | **Never below 60s.** Iterate releases the JoSk lease as soon as scanning ends — only a stalled storage scan can blow this.         |
@@ -352,12 +387,54 @@ Defaults fit moderate traffic in a single region. Reach for a [preset](#settings
 
 For deeper JoSk semantics (lease lifecycle, scheduler adapters, recurring tasks), install the JoSk skill: **`npx skills add veliovgroup/josk`**.
 
+## Transport fail-over
+
+`backup` rotates after `failsToNext` failures. Veto rotation when an MTA may already hold the message:
+
+```js
+new MailTime({
+  // ...
+  shouldFailOver: (error) => error?.code !== 'EMESSAGE', // nodemailer: rejected after DATA
+});
+```
+
+Transports may also set `error.mayFailOver = false`. Retry timing stays unchanged. Edge cases: [v4.1 → v5 migration guide](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md#shouldfailovererror-info-email).
+
+## Queue payload trust
+
+`raw` is always refused. Use `strictPayload` when queue writers should not control attachments, URLs, envelope, DKIM, or other nodemailer capabilities:
+
+```js
+new MailTime({
+  // ...
+  strictPayload: true,
+  allowedMailFields: ['attachments'], // optional allowlist extension
+});
+```
+
+`strictPayload` also forces `disableFileAccess` and `disableUrlAccess`. Threat model and built-in allowlist: [v4.1 → v5 migration guide](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md#strictpayload--allowedmailfields).
+
+## Resolving the sender
+
+`from` receives selected transport plus `{ index, from }`:
+
+```js
+new MailTime({
+  // ...
+  from: (transport, details) => `"Acme" <${details.from}>`,
+});
+```
+
+Use `details.from`, not `transport.options.from`, for class-instance transports. `MailTime.transportFrom(transport)` exposes same resolution. Details: [v4.1 → v5 migration guide](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md#fromtransport-details-and-mailtimetransportfrom).
+
 ## Templates
 
 Two Mustache-like placeholder forms:
 
-- `{{key}}` — string interpolation, strips HTML from the value (safe for plain text).
-- `{{{key}}}` — raw HTML interpolation.
+- `{{key}}` — string interpolation. **HTML-escaped** in HTML contexts (`html`, `template`, `concatDelimiter`); verbatim in `text` bodies and subject headers, which are not HTML.
+- `{{{key}}}` — raw interpolation, never escaped. Only use it for values you produced yourself.
+
+Migration behavior: [v4.1 → v5 template escaping](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md#2-key-escapes-html-instead-of-stripping-tags).
 
 Every `sendMail` option is available inside `text`, `html`, and the wrapping template:
 
@@ -408,12 +485,17 @@ await mailQueue.sendMail({
 | `concatDelay`                 | `number` (ms)                                       | `60000`                    | Fold window.                                                                                                                                                                                |
 | `revolvingInterval`           | `number` (ms)                                       | `1536`                     | Queue iteration interval.                                                                                                                                                                   |
 | `mode`                        | `'one' \| 'batch'`                                  | `'batch'`                  | `'batch'` claims every due row per tick; `'one'` claims a single row per tick.                                                                                                              |
-| `concurrency`                 | `number`                                            | `1`                        | Parallel SMTPs per instance. The CAS on `isSending` prevents duplicate delivery.                                                                                                            |
-| `sendingTimeout`              | `number` (ms)                                       | `300000`                   | Window after which a stuck `isSending=true` row becomes eligible again. Must exceed worst-case SMTP roundtrip.                                                                              |
+| `concurrency`                 | `number`                                            | `1`                        | Parallel SMTPs per instance. CAS blocks concurrent claims for one row.                                                                                                                      |
+| `sendingTimeout`              | `number` (ms)                                       | `300000`                   | Window after which a stuck `isSending=true` row becomes eligible again. Must exceed worst-case SMTP roundtrip; values below `120000` log a warning.                                          |
+| `renewClaim`                  | `boolean \| number` (ms)                            | `sendingTimeout / 3`       | Re-stamp `sendingAt` on the claimed row while its SMTP roundtrip runs, so a slow-but-healthy send never loses its lock to a recovery worker. `false` restores the v4 single-stamp behaviour. |
+| `maxRenewals`                 | `number`                                            | `10`                       | Renewal-attempt budget per send. Recovery begins `sendingTimeout` after last successful stamp; slow renewal writes can extend elapsed time beyond the nominal interval calculation.          |
+| `shouldFailOver`              | `(error, info, email) => boolean`                   | —                          | Veto rotating to the next transport for this failure. Default: rotate unless the error carries `mayFailOver === false`. See [Transport fail-over](#transport-fail-over).                     |
+| `strictPayload`               | `boolean`                                           | `false`                    | Narrow every queued letter to `allowedMailFields` and force nodemailer's `disableFileAccess` / `disableUrlAccess`. See [Queue payload trust](#queue-payload-trust).                          |
+| `allowedMailFields`           | `string[]`                                          | —                          | Extra field names permitted under `strictPayload` (added to the built-in allowlist).                                                                                                        |
 | `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport via `transport.verify()` once at `ready()`. Failing transports are marked unusable, surfaced through `onError(error, null, { transportIndex, phase: 'verify' })`, and skipped during rotation/fallback. Throws from `ready()` if **every** transport fails. Transports without a `verify()` method are treated as healthy. |
 | `template`                    | `string`                                            | `'{{{html}}}'`             | Default envelope.                                                                                                                                                                           |
 | `prefix`                      | `string`                                            | `''`                       | Queue namespace. **Same** on every `client` and `server` for one logical queue; **different** per email class. Inherited by the queue adapter; JoSk scheduler uses `mailTimeQueue<prefix>`. |
-| `from`                        | `string \| (transport) => string`                   | —                          | Strongly recommended for spam-passing `From:` formatting.                                                                                                                                   |
+| `from`                        | `string \| (transport, details) => string`          | —                          | Strongly recommended for spam-passing `From:` formatting. `details` is `{ index, from }` — see [Resolving the sender](#resolving-the-sender).                                                |
 | `debug`                       | `boolean`                                           | `false`                    | Verbose logs.                                                                                                                                                                               |
 | `onSent(email, info)`         | `function`                                          | —                          | Called once the task is fully delivered. `email.mailOptions[i].accepted` lists every address that got through (across all attempts).                                                        |
 | `onError(error, email, info)` | `function`                                          | —                          | Called once the retry budget is exhausted with at least one un-accepted recipient. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `info = { transportIndex, phase: 'verify' }`. |
@@ -428,6 +510,7 @@ await mailQueue.sendMail({
 | `minRevolvingDelay`       | `512`             | Lower bound of poll window.                                                                                    |
 | `maxRevolvingDelay`       | `2048`            | Upper bound.                                                                                                   |
 | `zombieTime`              | `60000`           | Re-claim if `queue.iterate()` runs longer than this. **Do not drop below 60s.**                                |
+| `lockLeaseTime`           | `30000`           | JoSk scheduler lease TTL. JoSk floors it at `2 * maxRevolvingDelay + 1000`; increase for slow storage claim batches. Separate from `zombieTime`, which controls task recovery. |
 | `execute`                 | `'batch'`         | JoSk scheduler batching; low impact for MailTime (one interval task per instance).                             |
 | `concurrency`             | `Infinity`        | Cap overlapping JoSk handler runs on **this** process (`1` if ticks pile up).                                  |
 | `autoClear`               | `false`           | Remove orphan tasks from storage.                                                                              |
@@ -443,10 +526,12 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 - `send(opts)` — alias of `sendMail`.
 - `cancelMail(uuidOrPromise)` → `Promise<boolean>`. Accepts the `uuid` or the `Promise<string>` from `sendMail`.
 - `cancel(uuid)` — alias of `cancelMail`.
-- `ping()` → `Promise<{status, code, statusCode, error?}>`. Pings scheduler then queue.
+- `ping()` → `Promise<{status, code, statusCode, paused?, error?}>`. Pings scheduler then queue; `paused` reflects `isPaused`.
 - `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects with `.cause` on storage failure.
-- `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Stops scheduler. Idempotent. Use `destroy({ drain: true })` or `await drain()` after `destroy()` for graceful shutdown.
+- `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Stops scheduler. Idempotent. Use `await destroy({ drain: true })` for graceful shutdown; plain `destroy()` aborts completion writes.
 - `drain()` → `Promise<void>`. Resolves once every in-flight SMTP attempt finishes. Useful in tests and graceful-shutdown paths.
+- `pause()` / `resume()` → `boolean`. Server-only reversible backpressure; no-ops on `client` or after `destroy()`. See [Shutdown](#6-shutdown).
+- `isPaused` → `boolean`. Read-only; always `false` on `client`.
 
 ### Queue constructors
 
@@ -467,19 +552,19 @@ For custom adapters see [docs/queue-api.md](https://github.com/veliovgroup/mail-
 ### Static
 
 - `MailTime.Template` — get/set the default HTML envelope template.
+- `MailTime.transportFrom(transport)` → `string | undefined`. Resolves a transport's sender address across `options.from`, `transporter.options.from`, `_defaults.from`, and `_options.from`, accepting both `'a@b.c'` and `{ name, address }`. Returns the first *usable* address; `undefined` when none resolves. Same value the `from(transport, details)` callback receives as `details.from`.
 
-## Migration from 3.x
+## Migrations
 
-Full v4 highlights, adapter changes, and type exports live in [docs/migration-v3-v4.md](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md). Quick checklist:
+Upgrade checklists, adapter contract changes, and rollout notes live in the docs (no duplication here):
 
-1. **Node ≥ 20.9.0**, Bun ≥ 1.1.0. Bump your runtime first.
-2. **Swap adapter imports** to the new `MongoQueue` / `RedisQueue` / `PostgresQueue` constructors.
-3. **Pass `josk`** — it's now required for `type: 'server'`.
-4. **`josk.zombieTime` default raised to `60000` ms** (was `32786`). Set it explicitly if you relied on the old value.
-5. **Custom queue adapters** — `update`'s claim guard now triggers on `{ isSending: true, sendingAt, tries }` (was `{ isSent: true, tries }`) and must include the stale-lock-recovery clause `(isSending === false OR sendingAt <= now - sendingTimeout)`. The iterate path must call `await mailTimeInstance.___dispatch(row)` instead of `___send` and honor `opts.limit` / `opts.sendingTimeout`. See [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md) and [`adapters/blank-example.js`](https://github.com/veliovgroup/mail-time/blob/master/adapters/blank-example.js).
-6. **Default behavior unchanged** — `concurrency: 1` keeps the post-upgrade send rate identical to v3. Opt into parallel sends by raising `concurrency`.
+| From | To  | Full guide |
+|------|-----|------------|
+| 3.x  | 4.1 | [v3 → v4](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md) |
+| 4.0  | 4.1 | [v4.0 → v4.1](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4-v4.1.md) |
+| 4.1  | 5.0 | [v4.1 → v5](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md) |
 
-New v4 surface to opt into: [`mailTimePreset`](#settings-presets), `concurrency`, `mode`, `sendingTimeout`, `drain()`, per-recipient retries, and the [AI agent skills](#ai-agent-skills) bundle.
+New in v4 (opt-in): `mailTimePreset`, `concurrency`/`mode`, `sendingTimeout`, `drain()`/`pause()`/`resume()`, per-recipient handling, AI skills bundle.
 
 ## Testing
 
@@ -524,3 +609,28 @@ Mixed clusters (some Node, some Bun) share one schedule under the same `prefix`
 - [PayPal](https://paypal.me/veliovgroup).
 - Try [☄️ meteor-files.com](https://meteor-files.com/?ref=github-mail-time-repo-footer).
 - Try [▲ ostr.io](https://ostr.io?ref=github-mail-time-repo-footer) for server monitoring, web analytics, web-CRON, and SEO pre-rendering.
+
+[npm-url]: https://www.npmjs.com/package/mail-time
+[badge-npm-v]: https://img.shields.io/npm/v/mail-time.svg
+[badge-npm-dm]: https://img.shields.io/npm/dm/mail-time.svg
+[badge-ci]: https://github.com/veliovgroup/mail-time/actions/workflows/ci.yml/badge.svg?branch=master
+[ci-url]: https://github.com/veliovgroup/mail-time/actions/workflows/ci.yml
+[badge-size]: https://img.shields.io/bundlephobia/minzip/mail-time
+[size-url]: https://bundlephobia.com/package/mail-time
+[badge-cov]: https://img.shields.io/badge/coverage-~99%25-brightgreen
+[badge-license]: https://img.shields.io/badge/License-BSD%203--Clause-blue.svg
+[license-url]: LICENSE
+[badge-node]: https://img.shields.io/node/v/mail-time
+[node-url]: https://nodejs.org/
+[badge-ts]: https://img.shields.io/badge/TypeScript-ready-blue
+[ts-url]: #quick-start
+[badge-bun]: https://img.shields.io/badge/Bun-%3E%3D1.1.0-black?logo=bun
+[bun-url]: #bun
+[badge-meteor]: https://img.shields.io/badge/Meteor-ostrio%3Amailer-DE4F4F
+[meteor-url]: https://packosphere.com/ostrio/mailer
+[badge-deps]: https://img.shields.io/badge/dependencies-1-brightgreen
+[deps-url]: https://www.npmjs.com/package/mail-time?activeTab=dependencies
+[badge-sponsor]: https://img.shields.io/github/sponsors/dr-dimitru?label=Sponsor
+[sponsor-url]: https://github.com/sponsors/dr-dimitru
+[badge-donate]: https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white
+[donate-url]: https://paypal.me/veliovgroup

package/adapters/mongo.js

@@ -228,10 +228,13 @@ class MongoQueue {
         cursor.limit(limit);
       }
 
-      while (await cursor.hasNext()) {
-        await this.mailTimeInstance.___dispatch(await cursor.next());
+      try {
+        while (await cursor.hasNext()) {
+          await this.mailTimeInstance.___dispatch(await cursor.next());
+        }
+      } finally {
+        await cursor.close().catch(() => {});
       }
-      await cursor.close();
     } catch (iterateError) {
       logError('[iterate] [while/await] [iterateError]', iterateError);
     }

package/adapters/postgres.js

@@ -1,3 +1,4 @@
+import { createHash } from 'crypto';
 import {
   debug,
   logError,
@@ -26,7 +27,21 @@ import {
  */
 
 const DEFAULT_PREFIX = 'default';
-const setupLockId = 93824519;
+
+// Two-key advisory lock, mirroring josk's PostgresAdapter: a stable MailTime namespace
+// plus a per-prefix hash. `pg_advisory_lock(int4, int4)` lives in its own keyspace, isolated
+// from single-int callers in the same database; distinct prefixes get distinct lock IDs, so
+// co-tenant MailTime queues no longer serialize each other's schema setup.
+const ADVISORY_LOCK_NAMESPACE = 0x4D61696C; // 'Mail' in ASCII as int32
+
+/**
+ * @internal
+ * @param {string} prefix
+ * @returns {number} signed int32 hash of the prefix string
+ */
+const advisoryLockKeyFor = (prefix) => {
+  return createHash('sha256').update(prefix).digest().readInt32BE(0);
+};
 
 const fieldMap = {
   to: 'to_address',
@@ -129,7 +144,8 @@ class PostgresQueue {
 
   /** @internal */
   async __setup() {
-    await this.client.query('SELECT pg_advisory_lock($1)', [setupLockId]);
+    const advisoryLockKey = advisoryLockKeyFor(this.prefix);
+    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
 
     try {
       await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
@@ -160,7 +176,7 @@ class PostgresQueue {
       await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_pending_to
         ON mail_time_queue (prefix, to_address, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
-      await this.client.query('SELECT pg_advisory_unlock($1)', [setupLockId]);
+      await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
     }
   }
 

package/helpers.js

@@ -1,15 +1,43 @@
 const hasOwn = Object.prototype.hasOwnProperty;
 
+/**
+ * @name hasOwnProp - `Object.hasOwn` (ES2022) polyfill.
+ * @function
+ * @param {object} obj
+ * @param {PropertyKey} key
+ * @returns {boolean} `true` if the object has the property, `false` otherwise.
+ */
+const hasOwnProp = (obj, key) => hasOwn.call(obj, key);
+
+/**
+ * @name debug - Debug logging.
+ * @function
+ * @param {boolean} isDebug
+ * @param {...any} args
+ * @returns {void}
+ */
 const debug = (isDebug, ...args) => {
   if (isDebug) {
     console.info('[DEBUG] [mail-time]', `${new Date()}`, ...args);
   }
 };
 
+/**
+ * @name logError - Error logging.
+ * @function
+ * @param {...any} args
+ * @returns {void}
+ */
 const logError = (...args) => {
   console.error('[ERROR] [mail-time]', `${new Date()}`, ...args);
 };
 
+/**
+ * @name isPlainObject - Check whether a value is a plain object (literal or `Object.create(null)`).
+ * @function
+ * @param {any} value
+ * @returns {boolean} `true` for plain objects, `false` for `null`, arrays, class instances, and primitives.
+ */
 const isPlainObject = (value) => {
   if (value === null || typeof value !== 'object') {
     return false;
@@ -19,11 +47,15 @@ const isPlainObject = (value) => {
 };
 
 /**
- * Minimal deep-merge sufficient for nodemailer-shaped mail options:
+ * @name deepMerge - Minimal deep-merge sufficient for nodemailer-shaped mail options:
  * - plain objects merge key-by-key
  * - arrays concatenate
  * - other values (strings, numbers, Date, Buffer, streams, classes) replace
  * Source values override target values.
+ * @function
+ * @param {any} target - Base value; merged into a shallow clone when a plain object, otherwise ignored.
+ * @param {any} source - Overriding value; returns `target` unchanged when not a plain object.
+ * @returns {any} The merged result (a new object), or `target` when `source` is not a plain object.
  */
 const deepMerge = (target, source) => {
   if (!isPlainObject(source)) {
@@ -49,9 +81,13 @@ const deepMerge = (target, source) => {
 };
 
 /**
- * Order-insensitive deep equality. Treats arrays as multisets and
+ * @name equals - Order-insensitive deep equality. Treats arrays as multisets and
  * objects as unordered maps. Designed for the small `mailOptions`
  * shape used by MailTime's email concatenation dedup.
+ * @function
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean} `true` when `a` and `b` are deeply equal ignoring array/key order.
  */
 const equals = (a, b) => {
   if (a === b) {
@@ -110,9 +146,11 @@ const equals = (a, b) => {
 };
 
 /**
- * Extract the email part of a nodemailer-shaped recipient entry.
+ * @name extractEmail - Extract the email part of a nodemailer-shaped recipient entry.
  * Accepts `'a@x.com'`, `'Name <a@x.com>'`, or `{ name, address }`.
- * Returns the address lowercased, or `null` when none can be parsed.
+ * @function
+ * @param {string|{name?: string, address?: string}|null|undefined} entry
+ * @returns {string|null} The address lowercased and trimmed, or `null` when none can be parsed.
  */
 const extractEmail = (entry) => {
   if (!entry) {
@@ -129,7 +167,10 @@ const extractEmail = (entry) => {
 };
 
 /**
- * Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @name toAddressList - Normalize a `to`/`cc`/`bcc` field into a flat list of lowercase addresses.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @returns {string[]} Flat list of parsed lowercase addresses; empty when `field` is falsy or unparseable.
  */
 const toAddressList = (field) => {
   if (!field) {
@@ -150,9 +191,13 @@ const toAddressList = (field) => {
 };
 
 /**
- * Remove entries whose extracted address is in `acceptedSet` from a
- * nodemailer `to`/`cc`/`bcc` field. Returns `void 0` when the filtered
- * array would be empty or the single string is dropped.
+ * @name filterAddressField - Remove entries whose extracted address is in `acceptedSet` from a
+ * nodemailer `to`/`cc`/`bcc` field.
+ * @function
+ * @param {string|Array<string|{name?: string, address?: string}>|null|undefined} field
+ * @param {Set<string>} acceptedSet - Lowercase addresses to drop.
+ * @returns {string|Array|undefined} The filtered field, or `void 0` when the filtered array would be
+ * empty or the single string is dropped. Returns `field` unchanged when `acceptedSet` is empty.
  */
 const filterAddressField = (field, acceptedSet) => {
   if (!field || !(acceptedSet instanceof Set) || acceptedSet.size === 0) {
@@ -175,19 +220,61 @@ const filterAddressField = (field, acceptedSet) => {
   return field;
 };
 
+const HTML_ESCAPES = {
+  '&': '&amp;',
+  '<': '&lt;',
+  '>': '&gt;',
+  '"': '&quot;',
+  "'": '&#39;',
+};
+
+/**
+ * @name escapeHtml - Escape the five HTML-significant characters.
+ * @function
+ * @param {string} value
+ * @returns {string} `value` safe to interpolate into HTML text or an attribute value.
+ */
+const escapeHtml = (value) => {
+  return `${value}`.replace(/[&<>"']/g, (char) => HTML_ESCAPES[char]);
+};
+
+/**
+ * @name isSendClaimUpdate - Detect an atomic send-claim update (`{ isSending: true, tries: N }`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj` claims a row for sending.
+ */
 const isSendClaimUpdate = (updateObj) => {
   return updateObj && updateObj.isSending === true && typeof updateObj.tries === 'number';
 };
 
+/**
+ * @name isSendLeaseGuardedUpdate - Detect an update guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseGuardedUpdate = (updateObj) => {
   return updateObj && typeof updateObj.leaseTries === 'number' && typeof updateObj.leaseSendingAt === 'number';
 };
 
+/**
+ * @name isAppendMailOptionUpdate - Detect an update that appends a mail option (for email concatenation).
+ * @function
+ * @param {object} updateObj
+ * @returns {boolean} `true` when `updateObj.appendMailOption` is set.
+ */
 const isAppendMailOptionUpdate = (updateObj) => {
   return updateObj && updateObj.appendMailOption !== void 0;
 };
 
-/** Strip MailTime-internal update keys before persisting to storage. */
+/**
+ * @name stripInternalUpdateMeta - Strip MailTime-internal update keys before persisting to storage.
+ * @function
+ * @param {object} updateObj
+ * @returns {object} A shallow clone without `leaseTries`, `leaseSendingAt`, and `appendMailOption`.
+ */
 const stripInternalUpdateMeta = (updateObj) => {
   const out = { ...updateObj };
   delete out.leaseTries;
@@ -196,13 +283,22 @@ const stripInternalUpdateMeta = (updateObj) => {
   return out;
 };
 
+/**
+ * @name isSendLeaseRemove - Detect a remove guarded by a send lease
+ * (carries `leaseTries` and `leaseSendingAt`).
+ * @function
+ * @param {object} opts
+ * @returns {boolean} `true` when both lease guard fields are present numbers.
+ */
 const isSendLeaseRemove = (opts) => {
   return opts && typeof opts.leaseTries === 'number' && typeof opts.leaseSendingAt === 'number';
 };
 
 export {
   debug,
+  escapeHtml,
   logError,
+  hasOwnProp,
   isPlainObject,
   deepMerge,
   equals,