@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 +476 -95
- package/index.d.mts +87 -16
- package/index.d.ts +87 -16
- package/index.js +179 -77
- package/index.mjs +176 -77
- package/mongoose.d.mts +2 -2
- package/mongoose.d.ts +2 -2
- package/mongoose.js +60 -23
- package/mongoose.mjs +60 -23
- package/package.json +1 -1
- package/{provider-DC_av0SQ.d.mts → provider-CeUryYAf.d.mts} +48 -6
- package/{provider-DC_av0SQ.d.ts → provider-CeUryYAf.d.ts} +48 -6
- package/sendgrid.d.mts +1 -1
- package/sendgrid.d.ts +1 -1
- package/sendgrid.js +29 -25
- package/sendgrid.mjs +29 -25
- package/smtp.d.mts +5 -2
- package/smtp.d.ts +5 -2
- package/smtp.js +91 -61
- package/smtp.mjs +91 -61
- package/{store-Bi5iZ910.d.ts → store-CFasgH3C.d.ts} +72 -15
- package/{store-DlABKTjt.d.mts → store-DjCqXbPv.d.mts} +72 -15
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();
|
|
16
44
|
|
|
17
|
-
const
|
|
18
|
-
const
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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,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
|
-
###
|
|
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
|
-
|
|
177
|
-
|
|
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
|
|
182
|
-
|
|
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
|
|
205
|
-
|
|
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
|
|
255
|
-
|
|
256
|
-
|
|
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
|
|
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
|
-
-
|
|
292
|
-
`
|
|
293
|
-
|
|
294
|
-
|
|
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 `
|
|
303
|
-
|
|
304
|
-
|
|
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 {
|
|
613
|
+
import { createEmailBatchAdmission } from '@web-ts-toolkit/email-service';
|
|
310
614
|
|
|
311
615
|
const { key: _singleKey, ...command } = welcomeCommand;
|
|
312
|
-
const
|
|
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
|
-
-
|
|
360
|
-
|
|
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).
|
|
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;
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
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
|
|
382
|
-
|
|
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
|
|
407
|
-
`serverStatus`, `replSetGetConfig`, `getCmdLineOpts`, collection/index inspection and
|
|
408
|
-
and read/write access to the two private collections. Unsupported topology, validators,
|
|
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,
|
|
436
|
-
value and take frozen copies. Do not read it from request data or infer
|
|
437
|
-
Factory mismatches fail with `invalid_config`. There is no new environment
|
|
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
|
|
442
|
-
|
|
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,
|
|
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({
|
|
485
|
-
const
|
|
486
|
-
const
|
|
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(
|
|
489
|
-
const
|
|
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
|
-
|
|
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
|
|
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
|