@web-ts-toolkit/email-service 0.72.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 +601 -82
- package/index.d.mts +97 -18
- package/index.d.ts +97 -18
- package/index.js +627 -292
- package/index.mjs +624 -292
- package/mongoose.d.mts +7 -4
- package/mongoose.d.ts +7 -4
- package/mongoose.js +589 -286
- package/mongoose.mjs +589 -286
- package/package.json +1 -1
- package/{provider-HisBc6hk.d.mts → provider-CeUryYAf.d.mts} +64 -6
- package/{provider-HisBc6hk.d.ts → provider-CeUryYAf.d.ts} +64 -6
- package/sendgrid.d.mts +1 -1
- package/sendgrid.d.ts +1 -1
- package/sendgrid.js +130 -42
- package/sendgrid.mjs +130 -42
- package/smtp.d.mts +7 -2
- package/smtp.d.ts +7 -2
- package/smtp.js +214 -84
- package/smtp.mjs +214 -84
- package/{store-D4YAI6Rk.d.mts → store-CFasgH3C.d.ts} +88 -17
- package/{store-Vb63Gocz.d.ts → store-DjCqXbPv.d.mts} +88 -17
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
|
-
##
|
|
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.
|
|
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:
|
|
14
|
+
<!-- example: quickstart -->
|
|
13
15
|
|
|
14
16
|
```typescript
|
|
15
|
-
import {
|
|
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();
|
|
44
|
+
|
|
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
|
+
});
|
|
16
56
|
|
|
17
|
-
const
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
24
|
-
|
|
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
|
|
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
|
-
|
|
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,42 +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
|
-
###
|
|
281
|
+
### Schedule a seven-day reminder
|
|
146
282
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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:
|
|
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
|
|
168
|
-
const relay =
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
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.
|
|
177
368
|
|
|
178
369
|
## Configure an SMTP profile
|
|
179
370
|
|
|
180
|
-
Install
|
|
371
|
+
Install the [optional Nodemailer peer](#support-and-limits) to import the SMTP runtime entry. Its profile `key`
|
|
372
|
+
must match the prepared snapshot.
|
|
181
373
|
|
|
182
374
|
<!-- example: smtp-profile -->
|
|
183
375
|
|
|
@@ -195,11 +387,16 @@ const smtp = createSmtpProvider({
|
|
|
195
387
|
and verify the certificate against `servername` (if specified) or `host`, including IP SAN verification for literal
|
|
196
388
|
IPs. `ca` accepts one PEM CA certificate per array entry and replaces Node's default trust roots. `auth: { user, pass }`
|
|
197
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.
|
|
198
393
|
- Use an ASCII DNS host or a literal IP. The adapter uses a cancellable DNS resolver (not OS hosts-file aliases) and
|
|
199
394
|
dials one address. It does not pool, retry or select another server after a failure.
|
|
200
395
|
- `prepare` validates and copies the snapshot and attachment bytes without network I/O. SMTP sends visible To/Cc,
|
|
201
|
-
envelope-only Bcc and no implicit path or URL inputs. Attachments are ordinary MIME leaf parts
|
|
202
|
-
|
|
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.
|
|
203
400
|
- `submit({ signal, timeoutMs })` consumes the prepared submission on a valid call. It closes its connection on abort
|
|
204
401
|
or timeout and never waits indefinitely for a peer. Neither closing the connection nor an `unknown` result means
|
|
205
402
|
the relay discarded the message. `accepted` and `partially_accepted` require a final DATA acknowledgement and mean
|
|
@@ -248,16 +445,21 @@ await memoryStore.ready();
|
|
|
248
445
|
```
|
|
249
446
|
|
|
250
447
|
Share the same instance to exercise competing callers. Each instance loses its state on restart and does not share
|
|
251
|
-
state across processes.
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
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.
|
|
255
451
|
|
|
256
452
|
## Run a worker
|
|
257
453
|
|
|
258
|
-
Bind a caller-ready store to the same scope as the admission service. Pass
|
|
454
|
+
Bind a caller-ready store to the same scope as the admission service. Pass at least one configured provider, not
|
|
259
455
|
credentials in a queue payload. The profile's key, kind and mode must match the frozen snapshot.
|
|
260
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
|
+
|
|
261
463
|
<!-- example: worker -->
|
|
262
464
|
|
|
263
465
|
```typescript
|
|
@@ -278,40 +480,143 @@ function runDue(worker: EmailWorker, signal: AbortSignal) {
|
|
|
278
480
|
```
|
|
279
481
|
|
|
280
482
|
- Your host calls `await runDue(worker, signal)` to do a bounded run.
|
|
281
|
-
Those are the default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
|
|
483
|
+
Those are the V1 default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
|
|
282
484
|
whole run, with a separate bounded finish grace. There is no polling or automatic connection management.
|
|
283
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.
|
|
284
496
|
- The worker prepares the provider payload, validates attachment bytes through your `attachmentResolvers`, and asks
|
|
285
497
|
the optional `rateLimiter` for one permit before making a durable handoff. A worker limiter should be instantiated
|
|
286
498
|
per worker; a shared limiter must enforce the actual shared quota outside the worker. The worker does not wait for
|
|
287
499
|
a deferred permit, refund permits, rerender snapshots, or choose an alternate profile.
|
|
288
|
-
-
|
|
289
|
-
`
|
|
290
|
-
|
|
291
|
-
|
|
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).
|
|
292
507
|
- `await worker.shutdown({ timeoutMs: 15_000 })` permanently closes the worker, not the store. `stopped` means no
|
|
293
508
|
run or provider I/O is active; `pendingCallbacks` counts host promises still held after cancellation. Injected
|
|
294
509
|
stores and providers must honor call deadlines, abort actual I/O and wait for it to settle. A timed-out shutdown
|
|
295
510
|
can be awaited again, and it does not recall bytes already sent.
|
|
296
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
|
+
|
|
297
604
|
## Enqueue and resume a batch
|
|
298
605
|
|
|
299
|
-
Use `
|
|
300
|
-
|
|
301
|
-
|
|
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:
|
|
302
609
|
|
|
303
|
-
<!-- example: batch -->
|
|
610
|
+
<!-- example: batch-admission -->
|
|
304
611
|
|
|
305
612
|
```typescript
|
|
306
|
-
import {
|
|
613
|
+
import { createEmailBatchAdmission } from '@web-ts-toolkit/email-service';
|
|
307
614
|
|
|
308
615
|
const { key: _singleKey, ...command } = welcomeCommand;
|
|
309
|
-
const
|
|
310
|
-
const batch = createEmailBatchService({ service, worker });
|
|
616
|
+
const batch = createEmailBatchAdmission({ service });
|
|
311
617
|
const request = { batchId: 'welcome-run-1', items: [{ itemId: 'notice-1', command }] };
|
|
312
618
|
const admission = await batch.enqueueBatch(request);
|
|
313
619
|
const resumed = await batch.enqueueBatch(request); // Same item identity; replays without preparing again.
|
|
314
|
-
// When the host is ready to process due jobs, call batch.run({ limit: 10, concurrency: 2 }).
|
|
315
620
|
```
|
|
316
621
|
|
|
317
622
|
- An enqueue call validates all 1–100 item envelopes and unique IDs before any lookup or preparation. It admits in
|
|
@@ -326,6 +631,37 @@ const resumed = await batch.enqueueBatch(request); // Same item identity; replay
|
|
|
326
631
|
`enqueue`. It passes the remaining time within that API's 50–60,000 ms range and a signal that can stop work
|
|
327
632
|
sooner. The batch waits for a started item to settle rather than assuming a write was cancelled. A custom
|
|
328
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
|
+
|
|
329
665
|
- `batch.run` is the configured worker's **scope-wide** run, with the same bounds, limiter and report. It can
|
|
330
666
|
process unrelated due jobs in that scope. It neither filters by batch ID nor rewrites envelopes; the local
|
|
331
667
|
grouping ID is not SendGrid's `batch_id`.
|
|
@@ -353,30 +689,80 @@ async function inspectResults(store: EmailStore, jobId: string) {
|
|
|
353
689
|
}
|
|
354
690
|
```
|
|
355
691
|
|
|
356
|
-
-
|
|
357
|
-
|
|
358
|
-
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.
|
|
359
694
|
- Lists contain complete committed projections, including those pending acknowledgement on the job. They order
|
|
360
695
|
newest finish first, then by job and attempt ID. `from` is inclusive; `before` is exclusive. Keep the same scope
|
|
361
|
-
and filters when passing `nextCursor`; page size can change (default 25, range 1–100).
|
|
362
|
-
- `reconcile` and `cleanup` do sequential work (default 20 steps, range 1–100); their counts describe only
|
|
363
|
-
progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
|
|
364
|
-
override 50–60,000 ms). A persistence failure can leave work committed;
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
696
|
+
and filters when passing `nextCursor` as `cursor`; page size can change (V1 default 25, range 1–100).
|
|
697
|
+
- `reconcile` and `cleanup` do sequential work (V1 default 20 steps, range 1–100); their counts describe only
|
|
698
|
+
confirmed progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
|
|
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.
|
|
375
761
|
|
|
376
762
|
## Durable store with Mongoose
|
|
377
763
|
|
|
378
|
-
Install
|
|
379
|
-
|
|
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:
|
|
380
766
|
|
|
381
767
|
<!-- example: mongoose -->
|
|
382
768
|
|
|
@@ -391,7 +777,7 @@ async function openStore(replicaSetUri: string) {
|
|
|
391
777
|
await connection.asPromise();
|
|
392
778
|
const store = createMongooseEmailStore(connection);
|
|
393
779
|
await store.ready();
|
|
394
|
-
return { store, close: () => connection.close() };
|
|
780
|
+
return { connection, store, close: () => connection.close() };
|
|
395
781
|
} catch (error) {
|
|
396
782
|
await connection.close();
|
|
397
783
|
throw error;
|
|
@@ -400,10 +786,10 @@ async function openStore(replicaSetUri: string) {
|
|
|
400
786
|
```
|
|
401
787
|
|
|
402
788
|
- `ready()` must succeed before any store call. It checks server status, replica-set config and startup
|
|
403
|
-
options, reads the collection/index catalog, and installs only missing
|
|
404
|
-
`serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and
|
|
405
|
-
and read/write access to the two private collections. Unsupported topology, validators,
|
|
406
|
-
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.
|
|
407
793
|
- `jobsCollection` and `activitiesCollection` default to `email_jobs` and `email_activities`.
|
|
408
794
|
`jobsModelName` and `activitiesModelName` reserve connection-local names (defaults `EmailJobV1` and
|
|
409
795
|
`EmailActivityV1`); no models are registered. Keep both collections private to this adapter: no manual
|
|
@@ -421,7 +807,148 @@ async function openStore(replicaSetUri: string) {
|
|
|
421
807
|
result data; a provider accepting a submission would not establish inbox delivery. Host driver command
|
|
422
808
|
monitoring can see private BSON; don't enable raw command logging in production.
|
|
423
809
|
|
|
424
|
-
##
|
|
810
|
+
## Opt in to larger SMTP envelopes
|
|
811
|
+
|
|
812
|
+
Omit `smtpCapacity` for V1: **50 total To/Cc/Bcc recipients**, unchanged default SMTP and SendGrid live/sandbox
|
|
813
|
+
behavior, and the existing store definitions. The opt-in is for live SMTP only. It accepts one complete envelope
|
|
814
|
+
per message; it never splits or truncates the envelope. To/Cc stay visible; Bcc stays envelope-only.
|
|
815
|
+
|
|
816
|
+
Choose one **canonical lowercase UUIDv4** for the logical store and an integer `maxRecipients` from **51 to 1,000**.
|
|
817
|
+
Keep that binding in trusted host configuration and pass it as `smtpCapacity` to every factory in that queue:
|
|
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.
|
|
822
|
+
|
|
823
|
+
This example uses both optional peers and an already open [Mongoose connection](#durable-store-with-mongoose).
|
|
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.
|
|
827
|
+
|
|
828
|
+
<!-- example: smtp-capacity -->
|
|
829
|
+
|
|
830
|
+
```typescript
|
|
831
|
+
import type { Connection } from 'mongoose';
|
|
832
|
+
import {
|
|
833
|
+
createEmailAdmin,
|
|
834
|
+
createEmailBatchAdmission,
|
|
835
|
+
createEmailBatchService,
|
|
836
|
+
createEmailRelay,
|
|
837
|
+
createEmailService,
|
|
838
|
+
createEmailTemplateRegistry,
|
|
839
|
+
createEmailWorker,
|
|
840
|
+
defineLocalTemplate,
|
|
841
|
+
type SmtpCapacity,
|
|
842
|
+
} from '@web-ts-toolkit/email-service';
|
|
843
|
+
import { createMongooseEmailStore } from '@web-ts-toolkit/email-service/mongoose';
|
|
844
|
+
import { createSmtpProvider, type SmtpProviderOptions } from '@web-ts-toolkit/email-service/smtp';
|
|
845
|
+
|
|
846
|
+
const smtpCapacity: SmtpCapacity = {
|
|
847
|
+
format: 'smtp-v2',
|
|
848
|
+
namespace: '6d36e018-b27f-4f3d-88d1-9b10ad86aaff',
|
|
849
|
+
maxRecipients: 51,
|
|
850
|
+
};
|
|
851
|
+
|
|
852
|
+
async function configureCapacityLane(connection: Connection, transport: Omit<SmtpProviderOptions, 'smtpCapacity'>) {
|
|
853
|
+
const store = createMongooseEmailStore(connection, { smtpCapacity });
|
|
854
|
+
await store.ready();
|
|
855
|
+
const queue = { scope: 'example-app', store, smtpCapacity };
|
|
856
|
+
const notice = defineLocalTemplate({
|
|
857
|
+
kind: 'handlebars',
|
|
858
|
+
revision: 'v1',
|
|
859
|
+
defaults: { from: { address: 'sender@example.invalid' } },
|
|
860
|
+
subject: { kind: 'inline', content: 'Example notice' },
|
|
861
|
+
text: { kind: 'inline', content: 'Synthetic message' },
|
|
862
|
+
parseInput: () => null,
|
|
863
|
+
parseData: () => ({}),
|
|
864
|
+
prepare: () => ({
|
|
865
|
+
to: Array.from({ length: 51 }, (_, i) => ({ address: `recipient-${i}@example.invalid` })),
|
|
866
|
+
values: {},
|
|
867
|
+
}),
|
|
868
|
+
});
|
|
869
|
+
const registry = createEmailTemplateRegistry({ notice }, { 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] });
|
|
875
|
+
const batch = createEmailBatchService({ service, worker, smtpCapacity });
|
|
876
|
+
const admin = createEmailAdmin(queue);
|
|
877
|
+
const staged = await registry.prepare(queue.scope, {
|
|
878
|
+
templateKey: 'notice',
|
|
879
|
+
input: null,
|
|
880
|
+
intent: 'synthetic-notice',
|
|
881
|
+
key: { kind: 'single', idempotencyKey: 'notice-1' },
|
|
882
|
+
provider: smtp.ref,
|
|
883
|
+
});
|
|
884
|
+
const admission = await relay.enqueuePrepared(staged);
|
|
885
|
+
return { admission, admin, batchAdmission, batch, worker };
|
|
886
|
+
}
|
|
887
|
+
```
|
|
888
|
+
|
|
889
|
+
For development, use `createMemoryEmailStore({ smtpCapacity })` and still await `store.ready()`. Separate backings
|
|
890
|
+
(including independent memory stores) need different UUIDs, even in one process. For local SMTP tests, run a TLS relay
|
|
891
|
+
with a fixture certificate signed by a test CA. For example, supply `host: '127.0.0.1'`, the fixture `port`,
|
|
892
|
+
`tls: 'implicit'`, `servername: 'smtp.loopback.invalid'` (matching the certificate's DNS SAN) and `ca: [fixtureCaPem]`.
|
|
893
|
+
`ca` explicitly trusts the fixture CA instead of the default roots; it does not bypass hostname verification.
|
|
894
|
+
Both implicit TLS and required STARTTLS verify the peer; plaintext mail and plaintext authentication are not supported.
|
|
895
|
+
|
|
896
|
+
### Envelope, queue and relay limits
|
|
897
|
+
|
|
898
|
+
- Count and size checks both apply. The canonical snapshot is capped at **2 MiB and 4,096 JSON values** in the
|
|
899
|
+
opted-in queue (V1 uses a 1 MiB snapshot limit). Envelope fields, metadata, attachment references, and rendered
|
|
900
|
+
bodies share the snapshot budget, including JSON escaping. The individual **512 KiB HTML** and **256 KiB text**
|
|
901
|
+
allowances do not increase. Up to five attachments may supply separate bytes (2 MiB each, 5 MiB total).
|
|
902
|
+
An over-limit snapshot fails with `invalid_snapshot` before insert or provider preflight. On-wire MIME is a
|
|
903
|
+
different size from the snapshot: allow for headers, encoding and attachments when checking the relay's limits.
|
|
904
|
+
- Opted-in workers default to one concurrent job (max two). `run()` defaults to four claims and four maintenance
|
|
905
|
+
steps (each max 16). Admin history pages default to eight activities (max 16); reconciliation and cleanup default
|
|
906
|
+
to four steps (max 16). A bound memory store defaults to eight jobs (max 16); a bound Mongo handle permits at
|
|
907
|
+
most four in-flight primitives. Do not copy larger V1 settings into a capacity queue.
|
|
908
|
+
- Relay recipient limits, reply latency, message size limits and throughput may require choosing a lower cap.
|
|
909
|
+
The adapter waits for each `RCPT TO` reply, even if the relay advertises PIPELINING. For planning, multiply the
|
|
910
|
+
recipient count by a conservative per-reply latency and add time for DNS, connection, TLS, other commands,
|
|
911
|
+
MIME transfer and the final acknowledgement. Leave reserve for jitter and worker/store operations too. At
|
|
912
|
+
60 ms per reply, 1,000 RCPT replies alone use the entire 60-second provider maximum.
|
|
913
|
+
|
|
914
|
+
On verified-TLS loopback, a single 1,000-recipient transaction with 8.18 MiB of synthetic MIME took **5.851 s**
|
|
915
|
+
with 5 ms added per RCPT (15 s provider budget), **26.004 s** with 25 ms, and **50.980 s** with 50 ms (60 s budget).
|
|
916
|
+
These are single samples, not production latency estimates or a guarantee for another relay. The worker's
|
|
917
|
+
`limits.providerTimeoutMs` defaults to 15,000 ms and cannot exceed 60,000 ms; the effective call is further
|
|
918
|
+
clipped by the remaining run and lease windows, including finalization grace and clock margin. Defaults are
|
|
919
|
+
a 30 s run, 60 s lease and 10 s finalization grace. The two extended samples used
|
|
920
|
+
`limits: { providerTimeoutMs: 60_000, leaseMs: 90_000 }` and a 75,000 ms `run({ timeoutMs })` budget, not just a
|
|
921
|
+
higher provider timeout. Measure with representative envelopes and keep headroom; timeouts are not a flow-control
|
|
922
|
+
strategy.
|
|
923
|
+
|
|
924
|
+
After a partial acceptance there is no automatic resend, including to the rejected subset. Only definitive safe
|
|
925
|
+
transient nonacceptance authorizes a submission retry. Timeout or missing acknowledgement can leave an `unknown`
|
|
926
|
+
result; closing a socket does not prove that the relay discarded the message. `write_unconfirmed` is not a rollback.
|
|
927
|
+
Job and activity reads remain redacted. Opted-in activities include group counts and, when known, group/index
|
|
928
|
+
outcomes, not recipient addresses, message content, attachment references, credentials or raw SMTP replies.
|
|
929
|
+
|
|
930
|
+
### Storage, rollout and rollback
|
|
931
|
+
|
|
932
|
+
- `format: 'smtp-v2'` selects a separate **storage** format; the public DTOs still have `version: 1`.
|
|
933
|
+
Every opted-in prepared command, SMTP snapshot, job summary and activity carries its `smtpCapacity` metadata,
|
|
934
|
+
even below 51 recipients. The field is optional in TypeScript so the types still describe V1 data, where it
|
|
935
|
+
must be absent. Neither queue will accept the other's staged values.
|
|
936
|
+
- On MongoDB the binding owns exactly `email_smtp_v2.<namespace>.jobs` and
|
|
937
|
+
`email_smtp_v2.<namespace>.activities`; V1 collection/model name overrides cannot be supplied with this option.
|
|
938
|
+
Call `ready()` before use. It checks both definitions and installs missing collections/indexes; it does not
|
|
939
|
+
alter existing validators, rewrite rows or touch V1 collections. A conflicting cap for an existing namespace
|
|
940
|
+
fails readiness. Keep the pair private and restore it together, offline, under its original binding.
|
|
941
|
+
- Keep the namespace and cap fixed for the lifetime of the backing queue. To change the cap, provision a fresh
|
|
942
|
+
namespace, verify readiness, and change routing for **new** work. Keep older and newer queues separate, each
|
|
943
|
+
with its own matched worker and admin. Third-party stores stay V1 unless they implement the bound storage and
|
|
944
|
+
limits, including checking the exact `StoreCall.smtpCapacity` before each primitive.
|
|
945
|
+
- To roll back, stop routing new work to the opt-in queue. Keep already staged outbox values and jobs on their
|
|
946
|
+
original route. Drain (or park) that lane with matching code and binding for recovery, inspection and retention;
|
|
947
|
+
keep V1 traffic on its existing queue. Do not point an older, V1-only runtime at the opted-in store. Do not retag,
|
|
948
|
+
copy or replay jobs across queues or automatically redrive uncertain work. The original lane's idempotency and
|
|
949
|
+
retention still apply.
|
|
950
|
+
|
|
951
|
+
## Integration entrypoint types
|
|
425
952
|
|
|
426
953
|
The integration types have their own entrypoints:
|
|
427
954
|
|
|
@@ -433,14 +960,6 @@ import type { SendGridProviderOptions } from '@web-ts-toolkit/email-service/send
|
|
|
433
960
|
import type { MongooseEmailStoreOptions } from '@web-ts-toolkit/email-service/mongoose';
|
|
434
961
|
```
|
|
435
962
|
|
|
436
|
-
<!-- prettier-ignore -->
|
|
437
|
-
| Entry | Current surface | Optional peer |
|
|
438
|
-
| --- | --- | --- |
|
|
439
|
-
| `@web-ts-toolkit/email-service` | `EmailError`, `createEmailTemplateRegistry`, `defineLocalTemplate`, `defineSendGridTemplate`, `createEmailService`, `createEmailWorker`, `createEmailBatchService`, `createEmailAdmin`, `createMemoryEmailStore`, and shared contracts | None |
|
|
440
|
-
| `@web-ts-toolkit/email-service/smtp` | `createSmtpProvider`, `SmtpProviderOptions` | Nodemailer `>=10.6.0 <11` (runtime only) |
|
|
441
|
-
| `@web-ts-toolkit/email-service/sendgrid` | `createSendGridProvider`, `SendGridProviderOptions` | None (Node HTTPS) |
|
|
442
|
-
| `@web-ts-toolkit/email-service/mongoose` | `createMongooseEmailStore`, `MongooseEmailStoreOptions` | Mongoose `>=9.12.2 <10` (declarations and caller connection) |
|
|
443
|
-
|
|
444
963
|
The root has no runtime or declaration dependency on the optional peers. A type-only SMTP import does not require
|
|
445
964
|
Nodemailer. The Mongoose runtime module can load without Mongoose, but its declarations reference the peer and
|
|
446
965
|
the factory needs a caller-owned Mongoose connection. No entrypoint opens a connection, registers a model, starts
|