@web-ts-toolkit/email-service 0.73.0 → 0.74.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,24 +4,151 @@ Typed email preparation, queue admission and bounded submission for Node.js 24 o
4
4
  content for SMTP or validate SendGrid dynamic-template data. Preparation alone does not enqueue, and admission never
5
5
  sends mail.
6
6
 
7
- ## Imports
7
+ ## Quickstart: enqueue and inspect a synthetic submission
8
8
 
9
9
  Install with `pnpm add @web-ts-toolkit/email-service`. Use named imports (or destructure `require()` in CommonJS).
10
- There is no default export. Preparation, admission, and the memory store need neither optional peer.
10
+ There is no default export. This standalone example uses no optional peers, credentials, or network. Save it as
11
+ `receipt.mts` and run `node receipt.mts`, or compile it as an ES module with TypeScript's `NodeNext` settings.
12
+ The provider is a test double for this one-recipient template: it **fabricates acceptance** and never sends mail.
11
13
 
12
- <!-- example: errors -->
14
+ <!-- example: quickstart -->
13
15
 
14
16
  ```typescript
15
- import { EmailError, type EmailErrorCode } from '@web-ts-toolkit/email-service';
17
+ import {
18
+ createEmailAdmin,
19
+ createEmailService,
20
+ createEmailTemplateRegistry,
21
+ createEmailWorker,
22
+ createMemoryEmailStore,
23
+ defineLocalTemplate,
24
+ type EmailProvider,
25
+ type SmtpSnapshot,
26
+ } from '@web-ts-toolkit/email-service';
27
+
28
+ const receipt = defineLocalTemplate({
29
+ kind: 'handlebars',
30
+ revision: 'v1',
31
+ defaults: { from: { address: 'sender@example.invalid' } },
32
+ subject: { kind: 'inline', content: 'Payment received' },
33
+ text: { kind: 'inline', content: 'Thank you for your payment.' },
34
+ parseInput(value) {
35
+ if (value !== null) throw new Error('Expected null');
36
+ return value;
37
+ },
38
+ parseData: () => ({}),
39
+ prepare: () => ({ to: [{ address: 'buyer@example.invalid' }], values: {} }),
40
+ });
41
+ const registry = createEmailTemplateRegistry({ receipt });
42
+ const store = createMemoryEmailStore();
43
+ await store.ready();
16
44
 
17
- const error = new EmailError('write_unconfirmed');
18
- const code: EmailErrorCode = error.code;
19
- // An unconfirmed write may have committed. Do not treat it as a definite failure.
20
- console.log(code);
45
+ const queue = { scope: 'example-app', store };
46
+ const service = createEmailService({ ...queue, registry });
47
+ const ref = { kind: 'smtp', key: 'receipt-test', mode: 'live' } as const;
48
+ const eventId = 'order-paid-6042'; // A stable, opaque ID from the host's business event, not a new ID on retry.
49
+ const admission = await service.enqueue({
50
+ templateKey: 'receipt',
51
+ input: null,
52
+ key: { kind: 'single', idempotencyKey: `receipt-${eventId}` },
53
+ intent: { purpose: 'receipt', eventId },
54
+ provider: ref,
55
+ });
56
+
57
+ const syntheticSmtp: EmailProvider<SmtpSnapshot> = {
58
+ ref, // Match the frozen kind, key and mode exactly.
59
+ prepare() {
60
+ return {
61
+ async submit({ signal }) {
62
+ signal.throwIfAborted();
63
+ return {
64
+ outcome: 'accepted',
65
+ retry: 'never',
66
+ stage: 'data',
67
+ reason: 'smtp_accepted',
68
+ recipients: [{ group: 'to', index: 0, status: 'accepted' }],
69
+ };
70
+ },
71
+ };
72
+ },
73
+ };
74
+ const worker = createEmailWorker({ ...queue, providers: [syntheticSmtp] });
75
+ try {
76
+ const report = await worker.run({ limit: 1 });
77
+ const job = await createEmailAdmin(queue).getJob(admission.job.jobId);
78
+ console.log(JSON.stringify({ admission: admission.status, submitted: report.counts.submitted, job }));
79
+ } finally {
80
+ const shutdown = await worker.shutdown();
81
+ if (shutdown.status !== 'stopped') throw new Error('Worker shutdown deadline elapsed');
82
+ }
21
83
  ```
22
84
 
23
- Compare `.code`, not class identity, if your application loads both builds.
24
- `PreparedEmailCommand` describes the sensitive, versioned outbox payload. Treat it like queue data, not a log record.
85
+ Expect `enqueued`, one synthetic submission and a redacted job with `latestAttempt.outcome: 'accepted'`.
86
+ With a real provider, acceptance confirms submission to that provider, not inbox delivery. SendGrid sandbox
87
+ validation is not submission.
88
+
89
+ The host owns business rules, scheduling and authorization. Use `createEmailService` or
90
+ [`createEmailBatchAdmission`](#enqueue-and-resume-a-batch) in producers, [`createEmailRelay`](#stage-a-host-owned-outbox)
91
+ for prepared outboxes, `createEmailWorker` for delivery, and `createEmailAdmin` for operations. They can run in
92
+ separate processes using the same backing queue and authorized scope, with the same binding when
93
+ [opting into SMTP capacity](#opt-in-to-larger-smtp-envelopes).
94
+
95
+ ## Support and limits
96
+
97
+ <!-- prettier-ignore -->
98
+ | Choose | Entrypoint / optional peer | Support and limits |
99
+ | --- | --- | --- |
100
+ | Local Handlebars → SMTP | Root `defineLocalTemplate`; `/smtp` `createSmtpProvider` needs Nodemailer `>=10.6.0 <11` at runtime | Verified TLS, live only. 50 total To/Cc/Bcc by default; [opt in](#opt-in-to-larger-smtp-envelopes) for 51–1,000. |
101
+ | Hosted SendGrid → HTTPS | Root `defineSendGridTemplate`; `/sendgrid` `createSendGridProvider`, no SDK or peer | Mail Send live or sandbox, V1 queue only. Freezes the template ID and data, not the active remote template version. |
102
+ | Memory queue | Root `createMemoryEmailStore`, no optional peer | Single instance, one process, non-durable. V1 defaults to 256 total jobs across scopes; no eviction to make room. |
103
+ | Durable MongoDB queue | `/mongoose` `createMongooseEmailStore`, caller-owned Mongoose `>=9.12.2 <10` connection | Writable MongoDB 8.x WiredTiger replica set with journaled majority; [topology and catalog privileges](#durable-store-with-mongoose) and private collection read/write access. |
104
+ | Custom provider | Root `EmailProvider` | Supported protocols only. No I/O in `prepare`; one-shot, deadline- and abort-aware `submit` with [normalized evidence](#implement-a-custom-provider), not raw replies. |
105
+ | Custom store | Root `EmailStore` | Scoped, bounded, atomic operations on store time. Enforce durable handoff and lease fencing, write confirmation, projection and retention; see [V1 transaction primitives][store-v1]. |
106
+
107
+ Always `await store.ready()` before use. Default V1 memory still allows legacy callers to skip it; SMTP-capacity
108
+ memory and MongoDB require it. Do not substitute memory when a durable store is unavailable.
109
+
110
+ The [V1 Store contract][store-v1] and [SMTP opt-in compatibility contract][store-smtp] are pinned historical
111
+ baselines. Use the installed declarations and this README for the current contract: the
112
+ [`StoreClaimNext` expiry signal](#run-a-worker) and [new-only SMTP attachment check](#configure-an-smtp-profile)
113
+ override the historical claim and insert rules. For opt-in stores also enforce the
114
+ [exact `StoreCall.smtpCapacity` binding and smaller bounds](#storage-rollout-and-rollback). For the public API,
115
+ the current peer ranges above and the template and provider typing, producer-only APIs and nonempty worker
116
+ requirements below supersede the corresponding historical examples.
117
+
118
+ [store-v1]: https://github.com/egose/web-ts-toolkit/blob/39848121d8b5746960078cac83949caaf26a9d9c/docs/task-artifacts/email-service/20261118-223259-email-service-package/v1-contract.md#store-adapter-transaction-primitives
119
+ [store-smtp]: https://github.com/egose/web-ts-toolkit/blob/39848121d8b5746960078cac83949caaf26a9d9c/docs/task-artifacts/email-service/20261120-214514-email-service-smtp-capacity/implementation-contract.md#factory-and-request-boundary
120
+
121
+ ## Handle errors by code
122
+
123
+ Check a known `.code` on a caught `unknown`, not `instanceof EmailError`. A subpath can throw a different
124
+ class than the root even within the same module format (all ESM or all CommonJS).
125
+
126
+ <!-- example: errors -->
127
+
128
+ ```typescript
129
+ import type { EmailErrorCode } from '@web-ts-toolkit/email-service';
130
+ import { createSendGridProvider, type SendGridProviderOptions } from '@web-ts-toolkit/email-service/sendgrid';
131
+
132
+ function hasEmailCode(error: unknown, code: EmailErrorCode): boolean {
133
+ if (typeof error !== 'object' || error === null) return false;
134
+ try {
135
+ return Object.getOwnPropertyDescriptor(error, 'code')?.value === code; // Read only an own data property.
136
+ } catch {
137
+ return false; // A thrown proxy can reject property inspection.
138
+ }
139
+ }
140
+
141
+ function configureSendGrid(options: SendGridProviderOptions) {
142
+ try {
143
+ return createSendGridProvider(options);
144
+ } catch (error: unknown) {
145
+ if (hasEmailCode(error, 'invalid_config')) {
146
+ return null; // Report a configuration failure without logging the options or the exception.
147
+ }
148
+ throw error; // Unexpected failure; do not assume it is a retryable package error.
149
+ }
150
+ }
151
+ ```
25
152
 
26
153
  ## Prepare a local template
27
154
 
@@ -30,7 +157,7 @@ Render an SMTP snapshot without Nodemailer, a store, or a network connection:
30
157
  <!-- example: local -->
31
158
 
32
159
  ```typescript
33
- import { createEmailTemplateRegistry, defineLocalTemplate } from '@web-ts-toolkit/email-service';
160
+ import { createEmailTemplateRegistry, defineLocalTemplate, type TemplateMap } from '@web-ts-toolkit/email-service';
34
161
 
35
162
  const welcome = defineLocalTemplate({
36
163
  kind: 'handlebars',
@@ -43,7 +170,7 @@ const welcome = defineLocalTemplate({
43
170
  return input;
44
171
  },
45
172
  prepare(name) {
46
- return { to: [{ address: 'recipient@example.invalid' }], values: { name } };
173
+ return { to: [{ address: 'recipient@example.invalid' }], values: { name: name.trim() } };
47
174
  },
48
175
  parseData(data) {
49
176
  if (!data || typeof data !== 'object' || !('name' in data) || typeof data.name !== 'string') {
@@ -53,10 +180,11 @@ const welcome = defineLocalTemplate({
53
180
  },
54
181
  });
55
182
 
56
- const registry = createEmailTemplateRegistry({ welcome });
183
+ const templates = { welcome } satisfies TemplateMap;
184
+ const registry = createEmailTemplateRegistry(templates);
57
185
  const welcomeCommand = {
58
186
  templateKey: 'welcome',
59
- input: '<Example>',
187
+ input: ' <Example> ',
60
188
  intent: { name: '<Example>' },
61
189
  key: { kind: 'single', idempotencyKey: 'welcome-1' },
62
190
  provider: { kind: 'smtp', key: 'standard-smtp', mode: 'live' },
@@ -66,7 +194,15 @@ const prepared = await registry.prepare('example-app', welcomeCommand);
66
194
 
67
195
  The snapshot has a plain-text subject and escaped HTML. `prepare` does not admit a job.
68
196
 
69
- Keep `parseInput` and `parseData` synchronous. Preparation can be async and may run again after a crash; keep
197
+ Use `satisfies TemplateMap` instead of annotating the definitions as `TemplateMap`. This keeps literal keys and their
198
+ input and provider types for the registry, service and batch. A widened `TemplateCommand<TemplateMap>` accepts either
199
+ provider, but cannot check keys or inputs against a specific registry.
200
+
201
+ `parseInput` synchronously validates the command's declared input shape at runtime. Its return type is the type callers
202
+ must supply as `command.input`. Normalize prepared values in `prepare` (here, `name.trim()`), rather than using
203
+ `parseInput` to convert from a different raw input shape.
204
+
205
+ Keep `parseData` synchronous too. Preparation can be async and may run again after a crash; keep
70
206
  side effects idempotent. `intent` is explicit, stable business meaning, not the generated message. Configure only
71
207
  trusted sources and helpers. HTML values escape by default; this is not sanitization. To update advertised local
72
208
  content, change its revision and create a new registry; `registry.invalidate(key?)` only refreshes the local cache.
@@ -142,45 +278,98 @@ console.log(first.job.jobId === again.job.jobId); // true
142
278
  insert and any confirmation share that budget. `retry` and `retention` are optional policy overrides frozen on the
143
279
  first insert; replay does not change them. Never put personal data or secrets into IDs or correlation tokens.
144
280
 
145
- ### Stage a host-owned outbox
281
+ ### Schedule a seven-day reminder
146
282
 
147
- Prepare before the business write. Pass `stagedReminder` from the SendGrid example as `email`. Your `commit`
148
- implementation saves the business change and the versioned, sensitive `email` value in **one host transaction**.
149
- Only after commit does your relay read that value and enqueue it on the caller-ready queue store:
283
+ `scheduleAt` is the earliest eligible time, not a timer. Both it and `expiresAt` are Unix milliseconds.
284
+ Expiry defaults to **24 hours from preparation**, so a seven-day schedule needs an explicit later expiry.
285
+ Set `expiresAt` in `prepare`: it must be strictly after preparation and `scheduleAt`, and at most **30 days
286
+ from preparation**. This example reuses `reminder` from the SendGrid template example and a caller-ready V1
287
+ store. It admits a sandbox reminder when the booking is recorded, without starting a worker:
150
288
 
151
- <!-- example: outbox -->
289
+ <!-- example: scheduled-reminder -->
152
290
 
153
291
  ```typescript
154
292
  import {
155
293
  createEmailService,
156
294
  createEmailTemplateRegistry,
295
+ defineSendGridTemplate,
157
296
  type EmailStore,
158
- type PreparedEmailCommand,
159
297
  } from '@web-ts-toolkit/email-service';
160
298
 
299
+ const dayMs = 86_400_000;
300
+ const sevenDayReminder = defineSendGridTemplate({
301
+ ...reminder,
302
+ async prepare(hours, context) {
303
+ return { ...(await reminder.prepare(hours, context)), expiresAt: context.now + 8 * dayMs };
304
+ },
305
+ });
306
+ const scheduledRegistry = createEmailTemplateRegistry({ reminder: sevenDayReminder });
307
+
308
+ function enqueueSevenDayReminder(store: EmailStore, booking: { eventId: string; recordedAt: number }) {
309
+ const service = createEmailService({ scope: 'example-app', store, registry: scheduledRegistry });
310
+ return service.enqueue({
311
+ templateKey: 'reminder',
312
+ input: 7 * 24,
313
+ key: { kind: 'single', idempotencyKey: `seven-day-reminder-${booking.eventId}` },
314
+ intent: { purpose: 'booking-reminder', eventId: booking.eventId, daysAfterBooking: 7 },
315
+ scheduleAt: booking.recordedAt + 7 * dayMs,
316
+ provider: { kind: 'sendgrid', key: 'validation', mode: 'sandbox' },
317
+ });
318
+ }
319
+ ```
320
+
321
+ Pass the original event ID and timestamp on replay, not a fresh `Date.now()`; the schedule is part of the
322
+ fingerprint. `PrepareContext` provides `now`, not `scheduleAt`; if your expiry depends on a variable schedule,
323
+ pass the needed timestamp in your validated input. The expiry is frozen in the prepared snapshot: relay,
324
+ same-key replay, worker retries, and redrive do not extend it. Expiry prevents a new launch; it cannot recall
325
+ one already in progress.
326
+
327
+ ### Stage a host-owned outbox
328
+
329
+ Prepare before the business write. Pass `stagedReminder` from the SendGrid example as `email`. Your `commit`
330
+ implementation saves the business change and the versioned, sensitive `email` value in **one host transaction**.
331
+ Only after commit does your relay read that value and enqueue it on the caller-ready queue store. The relay process
332
+ does not need a template registry, worker, or delivery credentials. Treat `PreparedEmailCommand` like queue data,
333
+ not a log record:
334
+
335
+ <!-- example: outbox -->
336
+
337
+ ```typescript
338
+ import { createEmailRelay, type EmailRelayOptions, type PreparedEmailCommand } from '@web-ts-toolkit/email-service';
339
+
161
340
  type CommitReminder = (row: { reminderId: string; email: PreparedEmailCommand }) => Promise<void>;
162
341
 
163
342
  async function writeReminder(reminderId: string, email: PreparedEmailCommand, commit: CommitReminder) {
164
343
  await commit({ reminderId, email });
165
344
  }
166
345
 
167
- function relayReminder(store: EmailStore, email: PreparedEmailCommand) {
168
- const relay = createEmailService({ scope: 'example-app', store, registry: createEmailTemplateRegistry({}) });
169
- return relay.enqueuePrepared(email);
346
+ function makeReminderRelay(store: EmailRelayOptions['store']) {
347
+ const relay = createEmailRelay({ scope: 'example-app', store });
348
+ return (row: { email: PreparedEmailCommand }) => relay.enqueuePrepared(row.email);
170
349
  }
171
350
  ```
172
351
 
173
- Relay validates the staged DTO, its hashes, and its scope. It does not join your transaction, rerender, refresh expiry,
174
- or send. Mark your outbox row relayed only after `enqueued` or `replayed`. If an acknowledgement is lost, relay the
175
- same persisted snapshot under the same scoped key and queue configuration; do not prepare a replacement. Keep the
176
- relay within the idempotency window. Restrict access to the staged payload; the returned job summary contains
177
- neither bodies nor addresses.
352
+ Create the relay once and call the returned function for each committed outbox row. It validates the snapshot,
353
+ hashes, scope and binding before looking up the key. A retained match replays even after snapshot expiry; an
354
+ expired snapshot for a new job is rejected. Relay does not join your transaction, rerender, refresh expiry, or
355
+ send. `createEmailService` also exposes the same `enqueuePrepared` method if your process already has a registry.
356
+
357
+ Older staged SMTP snapshots with `message/*` or `multipart/*` attachments still replay a retained match, but fail
358
+ with `invalid_snapshot` on a new admission. Treat this as an outbox validation error, not a transient send failure
359
+ or proof that an earlier uncertain write did not commit. Resolve any uncertain admission under the original key.
360
+ For an unadmitted entry, use your outbox recovery process to fix the attachment format and stage it again.
361
+ Previously admitted rows stay readable but the bundled SMTP adapter still rejects those attachments. Replay
362
+ neither changes their snapshots nor reopens terminal jobs for delivery.
363
+
364
+ Mark your outbox row relayed only after `enqueued` or `replayed`. If an acknowledgement is lost, relay the same
365
+ persisted snapshot under its original scoped key and queue binding; do not prepare a replacement. Keep the relay
366
+ within the idempotency window. Restrict access to the staged payload; the returned job summary contains neither
367
+ bodies nor addresses.
178
368
 
179
369
  ## Configure an SMTP profile
180
370
 
181
- Install `nodemailer@">=10.6.0 <11"` to import the SMTP runtime entry. Its profile `key` must match the prepared snapshot.
182
- The default is 50 total To/Cc/Bcc recipients; see [SMTP capacity opt-in](#opt-in-to-larger-smtp-envelopes) for a separate
183
- queue that can admit larger envelopes.
371
+ Install the [optional Nodemailer peer](#support-and-limits) to import the SMTP runtime entry. Its profile `key`
372
+ must match the prepared snapshot.
184
373
 
185
374
  <!-- example: smtp-profile -->
186
375
 
@@ -198,11 +387,16 @@ const smtp = createSmtpProvider({
198
387
  and verify the certificate against `servername` (if specified) or `host`, including IP SAN verification for literal
199
388
  IPs. `ca` accepts one PEM CA certificate per array entry and replaces Node's default trust roots. `auth: { user, pass }`
200
389
  uses advertised ESMTP PLAIN or LOGIN only over verified TLS; there is no plaintext fallback.
390
+ - The client greeting is fixed: `EHLO email.invalid` before and after the required STARTTLS upgrade, or once over
391
+ implicit TLS. `servername` is for remote TLS SNI and certificate verification; it does not change EHLO.
392
+ Relays requiring a different EHLO name are not supported.
201
393
  - Use an ASCII DNS host or a literal IP. The adapter uses a cancellable DNS resolver (not OS hosts-file aliases) and
202
394
  dials one address. It does not pool, retry or select another server after a failure.
203
395
  - `prepare` validates and copies the snapshot and attachment bytes without network I/O. SMTP sends visible To/Cc,
204
- envelope-only Bcc and no implicit path or URL inputs. Attachments are ordinary MIME leaf parts, not nested message
205
- or multipart MIME structures.
396
+ envelope-only Bcc and no implicit path or URL inputs. Attachments are ordinary MIME leaf parts.
397
+ Both SMTP queue modes reject `message/*` and `multipart/*` refs with `invalid_snapshot` during new registry
398
+ preparation or admission, before they can be persisted or resolved by a worker. Direct SMTP preparation still
399
+ refuses these types. SendGrid behavior is unchanged.
206
400
  - `submit({ signal, timeoutMs })` consumes the prepared submission on a valid call. It closes its connection on abort
207
401
  or timeout and never waits indefinitely for a peer. Neither closing the connection nor an `unknown` result means
208
402
  the relay discarded the message. `accepted` and `partially_accepted` require a final DATA acknowledgement and mean
@@ -251,16 +445,21 @@ await memoryStore.ready();
251
445
  ```
252
446
 
253
447
  Share the same instance to exercise competing callers. Each instance loses its state on restart and does not share
254
- state across processes. The V1 job limit (default 256) is shared across scopes; a full store rejects new jobs instead of
255
- evicting retained ones. This is not a fallback for durable persistence. The `EmailStore` methods are private lifecycle
256
- primitives for adapters and tests, not application-facing routes. Claims include sensitive snapshots and ownership
257
- tokens; do not log or expose them. Store operations alone never contact a provider.
448
+ state across processes. The `EmailStore` methods are private lifecycle primitives for adapters and tests, not
449
+ application-facing routes. Claims include sensitive snapshots and ownership tokens; do not log or expose them.
450
+ Store operations alone never contact a provider.
258
451
 
259
452
  ## Run a worker
260
453
 
261
- Bind a caller-ready store to the same scope as the admission service. Pass the configured provider instances, not
454
+ Bind a caller-ready store to the same scope as the admission service. Pass at least one configured provider, not
262
455
  credentials in a queue payload. The profile's key, kind and mode must match the frozen snapshot.
263
456
 
457
+ **Migrating an empty V1 worker:** `providers: []` now throws `invalid_config` at construction, as it already did
458
+ with `smtpCapacity`. No queue or provider work starts. If you only enqueue batches, replace the empty worker and
459
+ combined facade with [`createEmailBatchAdmission({ service })`](#enqueue-and-resume-a-batch) (pass `smtpCapacity`
460
+ if configured). For already prepared commands, [`createEmailRelay`](#stage-a-host-owned-outbox) needs no worker
461
+ or template registry.
462
+
264
463
  <!-- example: worker -->
265
464
 
266
465
  ```typescript
@@ -284,37 +483,140 @@ function runDue(worker: EmailWorker, signal: AbortSignal) {
284
483
  Those are the V1 default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
285
484
  whole run, with a separate bounded finish grace. There is no polling or automatic connection management.
286
485
  One run per instance is allowed. Different instances can share a queue. `idle` is not a whole-queue inventory.
486
+ - On `report.stop === 'expiry_maintenance_required'`, the entire bounded claim window was filled with expired
487
+ queued jobs. There may be live work behind them. Schedule another run for the **same scope** with a positive
488
+ `maintenanceLimit` (or omit it for the default: 10 in V1, 4 with `smtpCapacity`). Keep scheduling bounded runs
489
+ if the backlog takes more than one sweep. `maintenanceLimit: 0` skips both recovery and queued expiry; repeatedly
490
+ running with zero maintenance won't clear the expired prefix. A follow-up run can submit eligible mail as usual.
491
+ - This stop is new for both bundled queues. Handle it in exhaustive switches on `EmailRunReport.stop` (including
492
+ `batch.run()`); direct `EmailStore.claimNext()` consumers can use `StoreClaimNext` and call bounded `expireNext()`
493
+ in the same scope before retrying. Existing custom stores can keep returning the previous `StoreNext` statuses.
494
+ Pair updated bundled stores with updated workers when passing store objects in-process: older workers report
495
+ the new result as a store error. There is no persisted-data or Mongo catalog migration.
287
496
  - The worker prepares the provider payload, validates attachment bytes through your `attachmentResolvers`, and asks
288
497
  the optional `rateLimiter` for one permit before making a durable handoff. A worker limiter should be instantiated
289
498
  per worker; a shared limiter must enforce the actual shared quota outside the worker. The worker does not wait for
290
499
  a deferred permit, refund permits, rerender snapshots, or choose an alternate profile.
291
- - A missing or late handoff acknowledgement never permits a send. A finish write error is not evidence of rejection.
292
- `unconfirmed` means the worker could not prove the stored attempt outcome; `unknown` is a stored result that is
293
- never automatically retried. `submitted` counts full and partial acceptance, not sandbox validation or inbox
294
- delivery. An application that explicitly redrives unknown work must accept possible duplicates.
500
+ - `retry.maxAttempts` defaults to **3 claims**, not three provider calls. Three rate deferrals can end in
501
+ `attempts_exhausted` with zero provider calls. For safe transient results with claims left, the retry time is the
502
+ later of jittered exponential backoff (default base 1 s, cap 60 s) and any valid limiter or provider retry floor.
503
+ No retry is scheduled at or after expiry. Pace worker runs for your quota; there is no separate deferral budget.
504
+ - A missing or late handoff acknowledgement never permits a send. A finish write error is not proof of rejection.
505
+ `submitted` counts full and partial acceptance, not sandbox validation. Neither partial nor unknown outcomes
506
+ automatically resend; see [recovery](#recover-unresolved-submissions).
295
507
  - `await worker.shutdown({ timeoutMs: 15_000 })` permanently closes the worker, not the store. `stopped` means no
296
508
  run or provider I/O is active; `pendingCallbacks` counts host promises still held after cancellation. Injected
297
509
  stores and providers must honor call deadlines, abort actual I/O and wait for it to settle. A timed-out shutdown
298
510
  can be awaited again, and it does not recall bytes already sent.
299
511
 
512
+ ### Roll out a provider profile in a shared scope
513
+
514
+ Workers on the same queue and scope compete for eligible jobs. Claims do not filter by profile, even when every
515
+ worker has providers configured. Each worker needs an exact match for every active provider reference (kind, key
516
+ and mode) and an `attachmentResolvers` entry for every `resolverKey` its jobs can reference. Startup checks only
517
+ the local configuration; the host must verify that all workers on the route have what they need.
518
+
519
+ For example, workers A and B share the `example-app` scope on one queue. Existing jobs use a live `smtp` profile
520
+ with key `standard-smtp` and may reference the `files-v1` resolver. New jobs will use a live `smtp` profile with
521
+ key `next-smtp` and the `files-v2` resolver. Use a distinct profile key so the two profiles can coexist.
522
+
523
+ 1. Replace worker A with one configured for **both** profiles and resolvers. B still has only the old
524
+ configuration, so producers must continue using `standard-smtp` and `files-v1`.
525
+ 2. Replace worker B with the same dual configuration. Confirm that no worker still claiming in `example-app`
526
+ lacks either profile or resolver.
527
+ 3. Only now switch producers of new work to `next-smtp` and `files-v2`. Keep both routes on both workers while the
528
+ old work drains, including access to its referenced attachment versions.
529
+ 4. Remove `standard-smtp` and `files-v1` only after nothing still needs them. Account for scheduled jobs, retries,
530
+ in-flight claims, staged outbox entries that can still be relayed, and any eligible `unknown` jobs you intend to
531
+ explicitly redrive. A run reporting `idle` does not prove the old work has drained.
532
+
533
+ If the fleets cannot share configuration, keep one on `example-app` and route the other to `example-app-next` in
534
+ the same store, or use separate backing queues. Bind each fleet's producers, relays and workers to the matching
535
+ scope and queue. Leave already staged and admitted work on its original route.
536
+
537
+ A missing or mismatched profile is a terminal pre-handoff failure: `failed` with reason `profile_unavailable`
538
+ and no provider submission on that attempt. The worker does not retry the job or switch profiles. After you
539
+ fix the configuration, replaying the same scoped command under the same key returns `replayed` with the existing
540
+ failed job while its identity is retained; it does not reopen the job. Changing the command's provider reference
541
+ under that key results in `idempotency_conflict`.
542
+
543
+ ### Implement a custom provider
544
+
545
+ Use `EmailProvider<SmtpSnapshot>` or `EmailProvider<SendGridSnapshot>` to implement one of the supported
546
+ protocols. Keep `prepare` synchronous and free of I/O. This SMTP test double matches the `standard-smtp` profile
547
+ from the local template example. Use it only with an isolated test queue: it records synthetic acceptance and
548
+ sends nothing.
549
+
550
+ <!-- example: custom-provider -->
551
+
552
+ ```typescript
553
+ import {
554
+ createSmtpAcceptanceResult,
555
+ EmailError,
556
+ type EmailProvider,
557
+ type ProviderResult,
558
+ type SmtpSnapshot,
559
+ } from '@web-ts-toolkit/email-service';
560
+
561
+ const syntheticSmtp: EmailProvider<SmtpSnapshot> = {
562
+ ref: { kind: 'smtp', key: 'standard-smtp', mode: 'live' },
563
+ prepare({ snapshot: { envelope } }) {
564
+ const recipients = (['to', 'cc', 'bcc'] as const).flatMap((group) =>
565
+ envelope[group].map((_, index) => ({ group, index, status: 'accepted' as const })),
566
+ );
567
+ let submitted = false;
568
+ return {
569
+ async submit({ signal }): Promise<ProviderResult> {
570
+ if (submitted) throw new EmailError('closed');
571
+ submitted = true;
572
+ if (signal.aborted) {
573
+ return { outcome: 'unknown', retry: 'never', stage: 'connect', reason: 'provider_aborted' };
574
+ }
575
+ return createSmtpAcceptanceResult(recipients);
576
+ },
577
+ };
578
+ },
579
+ };
580
+ ```
581
+
582
+ For the test queue above, pass `[syntheticSmtp]` to `makeWorker(store, profiles)` in place of a real SMTP adapter.
583
+ A real `submit` must be one-shot, honor `signal` and `timeoutMs`, and settle only once it cannot perform more
584
+ send I/O. Report SMTP acceptance or partial acceptance only after the final DATA acknowledgement, with one
585
+ entry per envelope recipient (group and zero-based index; use To/Cc/Bcc order with `smtpCapacity`). If you
586
+ cannot establish what happened, report `unknown`, not a safe retry.
587
+
588
+ **Migrating custom TypeScript providers:** `ProviderResult` now ties `outcome`, `retry`, `stage`, and metadata to
589
+ `reason`. Return a complete result in each branch rather than assembling those fields independently or casting
590
+ from `AttemptResult`. Annotate `submit` with `Promise<ProviderResult>` as above or use `satisfies ProviderResult`
591
+ on a result literal. A literal `smtp_accepted` result needs a nonempty tuple of accepted recipients. For a dynamic
592
+ list or any `smtp_partial` result, call `createSmtpAcceptanceResult(recipients, messageId?)` from the root
593
+ (no optional peer). It copies and freezes the evidence without reordering it, and returns `smtp_partial` only
594
+ when both statuses are present. Empty, all-rejected, or malformed evidence throws `invalid_command`; an
595
+ all-rejected list is not acceptance. Omit `messageId` unless it is `<${attemptId}@email.invalid>` for this attempt.
596
+ Only live `sendgrid_accepted` can include `providerMessageId`, and only `sendgrid_throttled` can include a
597
+ provider `retryHint` (`delayMs`, `notBefore`, or both). Sandbox success is `sendgrid_validated`, not
598
+ `sendgrid_accepted`.
599
+
600
+ This tightens the TypeScript contract without changing stored formats or submission semantics. The worker still
601
+ checks evidence against the actual envelope and profile mode. Invalid evidence after handoff becomes `unknown` with reason
602
+ `transport_uncertain`; it never authorizes an automatic resend.
603
+
300
604
  ## Enqueue and resume a batch
301
605
 
302
- Use `createEmailBatchService` with a service and worker bound to the **same scope and underlying store**.
303
- Each item is a template command without a standalone `key`. Using `welcomeCommand`, `service`, `store`, `smtp`
304
- and `makeWorker` from the preceding examples:
606
+ Use `createEmailBatchAdmission` in a producer process. It takes the bound admission `service` from the enqueue
607
+ example and only exposes `enqueueBatch`. No worker, delivery credentials, or optional peer is needed for the memory
608
+ example. Each item is a template command without a standalone `key`. Using `welcomeCommand` from above:
305
609
 
306
- <!-- example: batch -->
610
+ <!-- example: batch-admission -->
307
611
 
308
612
  ```typescript
309
- import { createEmailBatchService } from '@web-ts-toolkit/email-service';
613
+ import { createEmailBatchAdmission } from '@web-ts-toolkit/email-service';
310
614
 
311
615
  const { key: _singleKey, ...command } = welcomeCommand;
312
- const worker = makeWorker(store, [smtp]);
313
- const batch = createEmailBatchService({ service, worker });
616
+ const batch = createEmailBatchAdmission({ service });
314
617
  const request = { batchId: 'welcome-run-1', items: [{ itemId: 'notice-1', command }] };
315
618
  const admission = await batch.enqueueBatch(request);
316
619
  const resumed = await batch.enqueueBatch(request); // Same item identity; replays without preparing again.
317
- // When the host is ready to process due jobs, call batch.run({ limit: 10, concurrency: 2 }).
318
620
  ```
319
621
 
320
622
  - An enqueue call validates all 1–100 item envelopes and unique IDs before any lookup or preparation. It admits in
@@ -329,6 +631,37 @@ const resumed = await batch.enqueueBatch(request); // Same item identity; replay
329
631
  `enqueue`. It passes the remaining time within that API's 50–60,000 ms range and a signal that can stop work
330
632
  sooner. The batch waits for a started item to settle rather than assuming a write was cancelled. A custom
331
633
  service must honor these limits and settle its I/O; one that does not cooperate can keep the batch pending.
634
+
635
+ ### Combine batch admission and delivery
636
+
637
+ If the same process also runs delivery, `createEmailBatchService` adds the configured worker's `run` to the same
638
+ `enqueueBatch` operation. Build both components from the same backing configuration, using a single store instance
639
+ for memory or matching durable queue settings. Matching scope and capacity do not prove two stores share a backing.
640
+ This is an alternative to the producer example, using `registry`, `welcomeCommand` and `smtp` from above:
641
+
642
+ <!-- example: batch -->
643
+
644
+ ```typescript
645
+ import {
646
+ createEmailBatchService,
647
+ createEmailService,
648
+ createEmailWorker,
649
+ createMemoryEmailStore,
650
+ } from '@web-ts-toolkit/email-service';
651
+
652
+ const store = createMemoryEmailStore();
653
+ await store.ready();
654
+ const queue = { scope: 'example-app', store };
655
+ const service = createEmailService({ ...queue, registry });
656
+ const worker = createEmailWorker({ ...queue, providers: [smtp] });
657
+ const batch = createEmailBatchService({ service, worker });
658
+ const { key: _singleKey, ...command } = welcomeCommand;
659
+ const request = { batchId: 'welcome-run-1', items: [{ itemId: 'notice-1', command }] };
660
+ const admission = await batch.enqueueBatch(request);
661
+ const resumed = await batch.enqueueBatch(request);
662
+ // When the host is ready to process due jobs, call batch.run({ limit: 10, concurrency: 2 }).
663
+ ```
664
+
332
665
  - `batch.run` is the configured worker's **scope-wide** run, with the same bounds, limiter and report. It can
333
666
  process unrelated due jobs in that scope. It neither filters by batch ID nor rewrites envelopes; the local
334
667
  grouping ID is not SendGrid's `batch_id`.
@@ -356,30 +689,80 @@ async function inspectResults(store: EmailStore, jobId: string) {
356
689
  }
357
690
  ```
358
691
 
359
- - Authorize requests in your application; a scope or cursor is not authentication. Results contain only redacted
360
- metadata, fixed diagnostic codes, and reliably known recipient indexes, never queue snapshots, addresses, provider
361
- responses or ownership tokens. Activities are submission history, not inbox delivery receipts or inputs to a resend.
692
+ - Results contain redacted metadata, fixed diagnostic codes and reliably known recipient indexes, never queue
693
+ snapshots, addresses, raw responses or ownership tokens. Activities describe past attempts, not current holds.
362
694
  - Lists contain complete committed projections, including those pending acknowledgement on the job. They order
363
695
  newest finish first, then by job and attempt ID. `from` is inclusive; `before` is exclusive. Keep the same scope
364
- and filters when passing `nextCursor`; page size can change (V1 default 25, range 1–100). Pages are not snapshots.
696
+ and filters when passing `nextCursor` as `cursor`; page size can change (V1 default 25, range 1–100).
365
697
  - `reconcile` and `cleanup` do sequential work (V1 default 20 steps, range 1–100); their counts describe only
366
698
  confirmed progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
367
- override 50–60,000 ms). A persistence failure can leave work committed; a later maintenance call safely resumes it.
368
- An optional `onActivity` runs after a new confirmed projection ACK, without waiting for its returned promise.
369
- If one callback is already pending, later notifications are skipped, not queued or retried.
370
- - `cancel(jobId)` cannot recall mail after handoff. `resolveUnknown({ jobId, attemptId, action: 'dismiss' })` closes
371
- the hold without changing the outcome. Explicit `'redrive'` with `acknowledgeDuplicateRisk: true` can requeue an
372
- eligible unknown job once for a future worker run. Quiesce suspected old workers and review provider evidence
373
- first: redrive can duplicate an accepted submission, and the admin never submits the message itself. After
374
- `write_unconfirmed`, read the current job or repeat the exact same action; do not assume it rolled back.
375
- - Retention is frozen at admission (default 7 days for payloads and 30 days each for history and idempotency).
376
- Cleanup holds unresolved unknowns and unacknowledged history, prunes settled payloads when eligible, and only
377
- removes the replay guard after all retention windows and the projection drain, once activities have been deleted.
699
+ override 50–60,000 ms). A persistence failure can leave work committed; later bounded maintenance can resume it.
700
+ `onActivity` is best effort after a newly confirmed projection ACK: if one callback is pending, later
701
+ notifications are skipped, not queued or retried.
702
+
703
+ ### Recover unresolved submissions
704
+
705
+ Use the original caller-ready store, authorized scope and `smtpCapacity` binding (if enabled). The host
706
+ authorizes reads and actions; IDs and cursors are not credentials. There is no API that lists all current holds.
707
+
708
+ 1. **Record IDs.** Persist the original queue/scope, opaque host reference and `job.jobId` from `enqueued` or
709
+ `replayed` before acknowledging the host item or marking an outbox row relayed. For batches, save successful
710
+ jobs alongside their batch/item IDs. Resume uncertain admissions only within the replay window and on the
711
+ original route with the same key and intent (same staged command for a relay; same batch/item IDs and intents
712
+ for a batch). Don't replay completed commands to find an ID: after purge they can enqueue anew. Record scoped
713
+ job/attempt IDs (when present), operation, status and reason from worker `items`, including recovery and uncertainty. Keep `stop` and
714
+ `counts.persistenceFailures`: a lost claim ACK may have no item. Restrict access and omit private payloads.
715
+ 2. **Read current state.** `unconfirmed` means the worker could not confirm the stored outcome;
716
+ `write_unconfirmed` means a write may have committed. Neither proves rollback or non-submission. A `handed_off`
717
+ lease does not prove provider invocation, and `providerInvoked: false` on recovery says nothing about the old
718
+ owner. Read `admin.getJob(jobId)` even before projection. Act only on a terminal `unknown` with `unknownOpen: true`
719
+ and `latestAttempt.outcome === 'unknown'`. Take the ID from `latestAttempt` and match it to any candidate attempt
720
+ from a report or activity. On a changed attempt, failed read or `null`, do not act on stale evidence. A missing
721
+ job does not prove non-submission.
722
+ 3. **If IDs are missing, look for candidates, not a complete worklist.** Check host records first. Run bounded
723
+ `admin.reconcile({ limit: 4, timeoutMs: 10_000 })` passes before paging. They project attempts without recovering
724
+ leases or sending; back off on contention and surface failures. Set a fixed `finishedAt` window in Unix ms
725
+ (`from` inclusive, `before` exclusive), then page `admin.listActivities({ from, before, limit: 8 })`.
726
+ Use a shared deadline signal and cap passes, pages and reads (e.g. three pages and 24 `getJob` calls).
727
+ Filter for `activity.result.outcome === 'unknown'`, deduplicate by scoped job/attempt and recheck the exact
728
+ open attempt with `getJob`.
729
+ Save the route, filters and opaque cursor after accounting for a whole page; resume an interrupted page from
730
+ its start. Cursors mark positions, not snapshots or watermarks. Later projections can appear before your
731
+ bookmark and older holds outside the window; history can also be purged. Revisit overlapping or older
732
+ windows from the first page within budget. Idle reconciliation or an empty/final page cannot rule out holds
733
+ (e.g. unprojected attempts or leases); report gaps and escalate if you need a complete inventory.
734
+ 4. **Let a healthy worker recover an expired lease only if delivery is authorized.** If still leased, wait for
735
+ the owner or quiesce suspected old workers: stop scheduling and verify no runs or provider I/O remain
736
+ (`shutdown()` returns `stopped`, not `deadline`, or equivalent host confirmation). After store-time lease
737
+ expiry, run a bounded worker in the original scope with positive `maintenanceLimit`. Pre-handoff recovery
738
+ can safely retry within policy; post-handoff recovery records `unknown`. Even `limit: 1` can send unrelated
739
+ mail; there is no recovery-only admin run. Re-read the job and check authorized provider evidence for that
740
+ attempt. Missing provider logs do not prove rejection.
741
+ 5. **Resolve the exact open attempt, or leave it open.** Re-read immediately before acting.
742
+ `admin.resolveUnknown({ jobId, attemptId, action: 'dismiss' })` closes the hold without sending or changing
743
+ the outcome, even after expiry. Dismissal does not assert acceptance or rejection; cancellation cannot recall mail.
744
+ Do not redrive confirmed acceptance. Only after quiescing suspected old workers, reviewing evidence and
745
+ accepting the risk of duplicate submission should an authorized operator call
746
+ `admin.resolveUnknown({ jobId, attemptId, action: 'redrive', acknowledgeDuplicateRisk: true })`.
747
+ Redrive requires a retained snapshot, store time before the original `expiresAt`, and no previous redrive.
748
+ It requeues the same snapshot with **one extra claim**, not a send guarantee, automatic retry or expiry
749
+ extension. A future worker needs the matching profile and resolvers. A second unknown can only be dismissed;
750
+ never bypass the guards with a fresh key. Audit the actor and exact scoped decision. On `write_unconfirmed`,
751
+ read `job.resolutions` for the same attempt/action; if absent and still eligible, retry only that exact
752
+ authorized command within budget. `resolved` confirms a new decision; `replayed` confirms the prior decision
753
+ and returns the current job, which may have advanced. On `not_found`, `resolution_conflict` or `expired`,
754
+ stop and re-read.
755
+ 6. **Schedule projection and cleanup separately from delivery.** Open unknowns retain payload, history and
756
+ identity even after expiry. Frozen retention minimums (defaults: payload 7 days, history and idempotency
757
+ 30 days each) start at dismissal or a settled terminal result after redrive. All attempts need projection
758
+ ACKs before payload pruning. Schedule bounded `admin.cleanup({ limit: 4 })` calls: after the retention windows
759
+ and projection drain, cleanup deletes activities before purging the job and replay guard. It never clears an
760
+ open hold.
378
761
 
379
762
  ## Durable store with Mongoose
380
763
 
381
- Install `mongoose@">=9.12.2 <10"` alongside the package. Supply an open connection (not the global default)
382
- to a writable MongoDB 8.x WiredTiger replica set with journaled majority enabled.
764
+ Install the [optional Mongoose peer](#support-and-limits) and open a caller-owned connection
765
+ (not the global default) to the supported replica set:
383
766
 
384
767
  <!-- example: mongoose -->
385
768
 
@@ -403,10 +786,10 @@ async function openStore(replicaSetUri: string) {
403
786
  ```
404
787
 
405
788
  - `ready()` must succeed before any store call. It checks server status, replica-set config and startup
406
- options, reads the collection/index catalog, and installs only missing V1 definitions. The principal needs
407
- `serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and creation as applicable,
408
- and read/write access to the two private collections. Unsupported topology, validators, collations, model
409
- aliases and conflicting or extra indexes are not adopted or repaired.
789
+ options, reads the collection/index catalog, and installs only missing definitions for the selected format.
790
+ The principal needs `serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and
791
+ creation as applicable, and read/write access to the two private collections. Unsupported topology, validators,
792
+ collations, model aliases and conflicting or extra indexes are not adopted or repaired.
410
793
  - `jobsCollection` and `activitiesCollection` default to `email_jobs` and `email_activities`.
411
794
  `jobsModelName` and `activitiesModelName` reserve connection-local names (defaults `EmailJobV1` and
412
795
  `EmailActivityV1`); no models are registered. Keep both collections private to this adapter: no manual
@@ -432,14 +815,15 @@ per message; it never splits or truncates the envelope. To/Cc stay visible; Bcc
432
815
 
433
816
  Choose one **canonical lowercase UUIDv4** for the logical store and an integer `maxRecipients` from **51 to 1,000**.
434
817
  Keep that binding in trusted host configuration and pass it as `smtpCapacity` to every factory in that queue:
435
- registry, store, admission service, each SMTP profile, worker, batch facade and admin. They compare the tuple by
436
- value and take frozen copies. Do not read it from request data or infer it from a snapshot or a worker setting.
437
- Factory mismatches fail with `invalid_config`. There is no new environment setting; the host still supplies relay
438
- credentials separately.
818
+ registry, store, admission service, prepared relay, batch admission or combined batch service, each SMTP profile,
819
+ worker and admin. They compare the tuple by value and take frozen copies. Do not read it from request data or infer
820
+ it from a snapshot or a worker setting. Factory mismatches fail with `invalid_config`. There is no new environment
821
+ setting; the host still supplies SMTP credentials separately where delivery runs.
439
822
 
440
823
  This example uses both optional peers and an already open [Mongoose connection](#durable-store-with-mongoose).
441
- It queues 51 synthetic addresses and does not run the worker. Replace the example UUID with one assigned to your
442
- store; do not generate a new UUID on startup.
824
+ It prepares and relays a snapshot for 51 synthetic addresses without running the worker. In production,
825
+ [stage and commit the snapshot in the host outbox](#stage-a-host-owned-outbox) before relaying. Replace the
826
+ example UUID with one assigned to your store; do not generate a new UUID on startup.
443
827
 
444
828
  <!-- example: smtp-capacity -->
445
829
 
@@ -447,7 +831,9 @@ store; do not generate a new UUID on startup.
447
831
  import type { Connection } from 'mongoose';
448
832
  import {
449
833
  createEmailAdmin,
834
+ createEmailBatchAdmission,
450
835
  createEmailBatchService,
836
+ createEmailRelay,
451
837
  createEmailService,
452
838
  createEmailTemplateRegistry,
453
839
  createEmailWorker,
@@ -463,10 +849,10 @@ const smtpCapacity: SmtpCapacity = {
463
849
  maxRecipients: 51,
464
850
  };
465
851
 
466
- async function configureCapacityLane(connection: Connection, relay: Omit<SmtpProviderOptions, 'smtpCapacity'>) {
467
- const scope = 'example-app';
852
+ async function configureCapacityLane(connection: Connection, transport: Omit<SmtpProviderOptions, 'smtpCapacity'>) {
468
853
  const store = createMongooseEmailStore(connection, { smtpCapacity });
469
854
  await store.ready();
855
+ const queue = { scope: 'example-app', store, smtpCapacity };
470
856
  const notice = defineLocalTemplate({
471
857
  kind: 'handlebars',
472
858
  revision: 'v1',
@@ -481,19 +867,22 @@ async function configureCapacityLane(connection: Connection, relay: Omit<SmtpPro
481
867
  }),
482
868
  });
483
869
  const registry = createEmailTemplateRegistry({ notice }, { smtpCapacity });
484
- const service = createEmailService({ scope, store, registry, smtpCapacity });
485
- const smtp = createSmtpProvider({ ...relay, smtpCapacity });
486
- const worker = createEmailWorker({ scope, store, providers: [smtp], smtpCapacity });
870
+ const service = createEmailService({ ...queue, registry });
871
+ const relay = createEmailRelay(queue);
872
+ const batchAdmission = createEmailBatchAdmission({ service, smtpCapacity });
873
+ const smtp = createSmtpProvider({ ...transport, smtpCapacity });
874
+ const worker = createEmailWorker({ ...queue, providers: [smtp] });
487
875
  const batch = createEmailBatchService({ service, worker, smtpCapacity });
488
- const admin = createEmailAdmin({ scope, store, smtpCapacity });
489
- const admission = await service.enqueue({
876
+ const admin = createEmailAdmin(queue);
877
+ const staged = await registry.prepare(queue.scope, {
490
878
  templateKey: 'notice',
491
879
  input: null,
492
880
  intent: 'synthetic-notice',
493
881
  key: { kind: 'single', idempotencyKey: 'notice-1' },
494
882
  provider: smtp.ref,
495
883
  });
496
- return { admission, admin, batch, worker };
884
+ const admission = await relay.enqueuePrepared(staged);
885
+ return { admission, admin, batchAdmission, batch, worker };
497
886
  }
498
887
  ```
499
888
 
@@ -559,7 +948,7 @@ outcomes, not recipient addresses, message content, attachment references, crede
559
948
  copy or replay jobs across queues or automatically redrive uncertain work. The original lane's idempotency and
560
949
  retention still apply.
561
950
 
562
- ## Integration entrypoints
951
+ ## Integration entrypoint types
563
952
 
564
953
  The integration types have their own entrypoints:
565
954
 
@@ -571,14 +960,6 @@ import type { SendGridProviderOptions } from '@web-ts-toolkit/email-service/send
571
960
  import type { MongooseEmailStoreOptions } from '@web-ts-toolkit/email-service/mongoose';
572
961
  ```
573
962
 
574
- <!-- prettier-ignore -->
575
- | Entry | Current surface | Optional peer |
576
- | --- | --- | --- |
577
- | `@web-ts-toolkit/email-service` | `EmailError`, `createEmailTemplateRegistry`, `defineLocalTemplate`, `defineSendGridTemplate`, `createEmailService`, `createEmailWorker`, `createEmailBatchService`, `createEmailAdmin`, `createMemoryEmailStore`, and shared contracts including `SmtpCapacity` | None |
578
- | `@web-ts-toolkit/email-service/smtp` | `createSmtpProvider`, `SmtpProviderOptions` | Nodemailer `>=10.6.0 <11` (runtime only) |
579
- | `@web-ts-toolkit/email-service/sendgrid` | `createSendGridProvider`, `SendGridProviderOptions` | None (Node HTTPS) |
580
- | `@web-ts-toolkit/email-service/mongoose` | `createMongooseEmailStore`, `MongooseEmailStoreOptions` | Mongoose `>=9.12.2 <10` (declarations and caller connection) |
581
-
582
963
  The root has no runtime or declaration dependency on the optional peers. A type-only SMTP import does not require
583
964
  Nodemailer. The Mongoose runtime module can load without Mongoose, but its declarations reference the peer and
584
965
  the factory needs a caller-owned Mongoose connection. No entrypoint opens a connection, registers a model, starts