@web-ts-toolkit/email-service 0.72.0 → 0.73.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 +148 -10
- package/index.d.mts +15 -7
- package/index.d.ts +15 -7
- package/index.js +479 -246
- package/index.mjs +479 -246
- package/mongoose.d.mts +7 -4
- package/mongoose.d.ts +7 -4
- package/mongoose.js +546 -280
- package/mongoose.mjs +546 -280
- package/package.json +1 -1
- package/{provider-HisBc6hk.d.mts → provider-DC_av0SQ.d.mts} +17 -1
- package/{provider-HisBc6hk.d.ts → provider-DC_av0SQ.d.ts} +17 -1
- package/sendgrid.d.mts +1 -1
- package/sendgrid.d.ts +1 -1
- package/sendgrid.js +116 -32
- package/sendgrid.mjs +116 -32
- package/smtp.d.mts +3 -1
- package/smtp.d.ts +3 -1
- package/smtp.js +138 -38
- package/smtp.mjs +138 -38
- package/{store-D4YAI6Rk.d.mts → store-Bi5iZ910.d.ts} +18 -4
- package/{store-Vb63Gocz.d.ts → store-DlABKTjt.d.mts} +18 -4
package/README.md
CHANGED
|
@@ -170,14 +170,17 @@ function relayReminder(store: EmailStore, email: PreparedEmailCommand) {
|
|
|
170
170
|
}
|
|
171
171
|
```
|
|
172
172
|
|
|
173
|
-
Relay validates the
|
|
173
|
+
Relay validates the staged DTO, its hashes, and its scope. It does not join your transaction, rerender, refresh expiry,
|
|
174
174
|
or send. Mark your outbox row relayed only after `enqueued` or `replayed`. If an acknowledgement is lost, relay the
|
|
175
|
-
same persisted snapshot under the same scoped key; do not prepare a replacement. Keep the
|
|
176
|
-
idempotency window. Restrict access to the staged payload; the returned job summary contains
|
|
175
|
+
same persisted snapshot under the same scoped key and queue configuration; do not prepare a replacement. Keep the
|
|
176
|
+
relay within the idempotency window. Restrict access to the staged payload; the returned job summary contains
|
|
177
|
+
neither bodies nor addresses.
|
|
177
178
|
|
|
178
179
|
## Configure an SMTP profile
|
|
179
180
|
|
|
180
181
|
Install `nodemailer@">=10.6.0 <11"` to import the SMTP runtime entry. Its profile `key` must match the prepared snapshot.
|
|
182
|
+
The default is 50 total To/Cc/Bcc recipients; see [SMTP capacity opt-in](#opt-in-to-larger-smtp-envelopes) for a separate
|
|
183
|
+
queue that can admit larger envelopes.
|
|
181
184
|
|
|
182
185
|
<!-- example: smtp-profile -->
|
|
183
186
|
|
|
@@ -248,7 +251,7 @@ await memoryStore.ready();
|
|
|
248
251
|
```
|
|
249
252
|
|
|
250
253
|
Share the same instance to exercise competing callers. Each instance loses its state on restart and does not share
|
|
251
|
-
state across processes.
|
|
254
|
+
state across processes. The V1 job limit (default 256) is shared across scopes; a full store rejects new jobs instead of
|
|
252
255
|
evicting retained ones. This is not a fallback for durable persistence. The `EmailStore` methods are private lifecycle
|
|
253
256
|
primitives for adapters and tests, not application-facing routes. Claims include sensitive snapshots and ownership
|
|
254
257
|
tokens; do not log or expose them. Store operations alone never contact a provider.
|
|
@@ -278,7 +281,7 @@ function runDue(worker: EmailWorker, signal: AbortSignal) {
|
|
|
278
281
|
```
|
|
279
282
|
|
|
280
283
|
- 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
|
|
284
|
+
Those are the V1 default work limits; set lower limits when appropriate. `timeoutMs` defaults to 30 seconds for the
|
|
282
285
|
whole run, with a separate bounded finish grace. There is no polling or automatic connection management.
|
|
283
286
|
One run per instance is allowed. Different instances can share a queue. `idle` is not a whole-queue inventory.
|
|
284
287
|
- The worker prepares the provider payload, validates attachment bytes through your `attachmentResolvers`, and asks
|
|
@@ -358,9 +361,9 @@ async function inspectResults(store: EmailStore, jobId: string) {
|
|
|
358
361
|
responses or ownership tokens. Activities are submission history, not inbox delivery receipts or inputs to a resend.
|
|
359
362
|
- Lists contain complete committed projections, including those pending acknowledgement on the job. They order
|
|
360
363
|
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). Pages are not snapshots.
|
|
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
|
+
and filters when passing `nextCursor`; page size can change (V1 default 25, range 1–100). Pages are not snapshots.
|
|
365
|
+
- `reconcile` and `cleanup` do sequential work (V1 default 20 steps, range 1–100); their counts describe only
|
|
366
|
+
confirmed progress in that call. All admin methods accept `signal` and one whole-call `timeoutMs` (default 10 seconds,
|
|
364
367
|
override 50–60,000 ms). A persistence failure can leave work committed; a later maintenance call safely resumes it.
|
|
365
368
|
An optional `onActivity` runs after a new confirmed projection ACK, without waiting for its returned promise.
|
|
366
369
|
If one callback is already pending, later notifications are skipped, not queued or retried.
|
|
@@ -391,7 +394,7 @@ async function openStore(replicaSetUri: string) {
|
|
|
391
394
|
await connection.asPromise();
|
|
392
395
|
const store = createMongooseEmailStore(connection);
|
|
393
396
|
await store.ready();
|
|
394
|
-
return { store, close: () => connection.close() };
|
|
397
|
+
return { connection, store, close: () => connection.close() };
|
|
395
398
|
} catch (error) {
|
|
396
399
|
await connection.close();
|
|
397
400
|
throw error;
|
|
@@ -421,6 +424,141 @@ async function openStore(replicaSetUri: string) {
|
|
|
421
424
|
result data; a provider accepting a submission would not establish inbox delivery. Host driver command
|
|
422
425
|
monitoring can see private BSON; don't enable raw command logging in production.
|
|
423
426
|
|
|
427
|
+
## Opt in to larger SMTP envelopes
|
|
428
|
+
|
|
429
|
+
Omit `smtpCapacity` for V1: **50 total To/Cc/Bcc recipients**, unchanged default SMTP and SendGrid live/sandbox
|
|
430
|
+
behavior, and the existing store definitions. The opt-in is for live SMTP only. It accepts one complete envelope
|
|
431
|
+
per message; it never splits or truncates the envelope. To/Cc stay visible; Bcc stays envelope-only.
|
|
432
|
+
|
|
433
|
+
Choose one **canonical lowercase UUIDv4** for the logical store and an integer `maxRecipients` from **51 to 1,000**.
|
|
434
|
+
Keep that binding in trusted host configuration and pass it as `smtpCapacity` to every factory in that queue:
|
|
435
|
+
registry, store, admission service, each SMTP profile, worker, batch facade and admin. They compare the tuple by
|
|
436
|
+
value and take frozen copies. Do not read it from request data or infer it from a snapshot or a worker setting.
|
|
437
|
+
Factory mismatches fail with `invalid_config`. There is no new environment setting; the host still supplies relay
|
|
438
|
+
credentials separately.
|
|
439
|
+
|
|
440
|
+
This example uses both optional peers and an already open [Mongoose connection](#durable-store-with-mongoose).
|
|
441
|
+
It queues 51 synthetic addresses and does not run the worker. Replace the example UUID with one assigned to your
|
|
442
|
+
store; do not generate a new UUID on startup.
|
|
443
|
+
|
|
444
|
+
<!-- example: smtp-capacity -->
|
|
445
|
+
|
|
446
|
+
```typescript
|
|
447
|
+
import type { Connection } from 'mongoose';
|
|
448
|
+
import {
|
|
449
|
+
createEmailAdmin,
|
|
450
|
+
createEmailBatchService,
|
|
451
|
+
createEmailService,
|
|
452
|
+
createEmailTemplateRegistry,
|
|
453
|
+
createEmailWorker,
|
|
454
|
+
defineLocalTemplate,
|
|
455
|
+
type SmtpCapacity,
|
|
456
|
+
} from '@web-ts-toolkit/email-service';
|
|
457
|
+
import { createMongooseEmailStore } from '@web-ts-toolkit/email-service/mongoose';
|
|
458
|
+
import { createSmtpProvider, type SmtpProviderOptions } from '@web-ts-toolkit/email-service/smtp';
|
|
459
|
+
|
|
460
|
+
const smtpCapacity: SmtpCapacity = {
|
|
461
|
+
format: 'smtp-v2',
|
|
462
|
+
namespace: '6d36e018-b27f-4f3d-88d1-9b10ad86aaff',
|
|
463
|
+
maxRecipients: 51,
|
|
464
|
+
};
|
|
465
|
+
|
|
466
|
+
async function configureCapacityLane(connection: Connection, relay: Omit<SmtpProviderOptions, 'smtpCapacity'>) {
|
|
467
|
+
const scope = 'example-app';
|
|
468
|
+
const store = createMongooseEmailStore(connection, { smtpCapacity });
|
|
469
|
+
await store.ready();
|
|
470
|
+
const notice = defineLocalTemplate({
|
|
471
|
+
kind: 'handlebars',
|
|
472
|
+
revision: 'v1',
|
|
473
|
+
defaults: { from: { address: 'sender@example.invalid' } },
|
|
474
|
+
subject: { kind: 'inline', content: 'Example notice' },
|
|
475
|
+
text: { kind: 'inline', content: 'Synthetic message' },
|
|
476
|
+
parseInput: () => null,
|
|
477
|
+
parseData: () => ({}),
|
|
478
|
+
prepare: () => ({
|
|
479
|
+
to: Array.from({ length: 51 }, (_, i) => ({ address: `recipient-${i}@example.invalid` })),
|
|
480
|
+
values: {},
|
|
481
|
+
}),
|
|
482
|
+
});
|
|
483
|
+
const registry = createEmailTemplateRegistry({ notice }, { smtpCapacity });
|
|
484
|
+
const service = createEmailService({ scope, store, registry, smtpCapacity });
|
|
485
|
+
const smtp = createSmtpProvider({ ...relay, smtpCapacity });
|
|
486
|
+
const worker = createEmailWorker({ scope, store, providers: [smtp], smtpCapacity });
|
|
487
|
+
const batch = createEmailBatchService({ service, worker, smtpCapacity });
|
|
488
|
+
const admin = createEmailAdmin({ scope, store, smtpCapacity });
|
|
489
|
+
const admission = await service.enqueue({
|
|
490
|
+
templateKey: 'notice',
|
|
491
|
+
input: null,
|
|
492
|
+
intent: 'synthetic-notice',
|
|
493
|
+
key: { kind: 'single', idempotencyKey: 'notice-1' },
|
|
494
|
+
provider: smtp.ref,
|
|
495
|
+
});
|
|
496
|
+
return { admission, admin, batch, worker };
|
|
497
|
+
}
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
For development, use `createMemoryEmailStore({ smtpCapacity })` and still await `store.ready()`. Separate backings
|
|
501
|
+
(including independent memory stores) need different UUIDs, even in one process. For local SMTP tests, run a TLS relay
|
|
502
|
+
with a fixture certificate signed by a test CA. For example, supply `host: '127.0.0.1'`, the fixture `port`,
|
|
503
|
+
`tls: 'implicit'`, `servername: 'smtp.loopback.invalid'` (matching the certificate's DNS SAN) and `ca: [fixtureCaPem]`.
|
|
504
|
+
`ca` explicitly trusts the fixture CA instead of the default roots; it does not bypass hostname verification.
|
|
505
|
+
Both implicit TLS and required STARTTLS verify the peer; plaintext mail and plaintext authentication are not supported.
|
|
506
|
+
|
|
507
|
+
### Envelope, queue and relay limits
|
|
508
|
+
|
|
509
|
+
- Count and size checks both apply. The canonical snapshot is capped at **2 MiB and 4,096 JSON values** in the
|
|
510
|
+
opted-in queue (V1 uses a 1 MiB snapshot limit). Envelope fields, metadata, attachment references, and rendered
|
|
511
|
+
bodies share the snapshot budget, including JSON escaping. The individual **512 KiB HTML** and **256 KiB text**
|
|
512
|
+
allowances do not increase. Up to five attachments may supply separate bytes (2 MiB each, 5 MiB total).
|
|
513
|
+
An over-limit snapshot fails with `invalid_snapshot` before insert or provider preflight. On-wire MIME is a
|
|
514
|
+
different size from the snapshot: allow for headers, encoding and attachments when checking the relay's limits.
|
|
515
|
+
- Opted-in workers default to one concurrent job (max two). `run()` defaults to four claims and four maintenance
|
|
516
|
+
steps (each max 16). Admin history pages default to eight activities (max 16); reconciliation and cleanup default
|
|
517
|
+
to four steps (max 16). A bound memory store defaults to eight jobs (max 16); a bound Mongo handle permits at
|
|
518
|
+
most four in-flight primitives. Do not copy larger V1 settings into a capacity queue.
|
|
519
|
+
- Relay recipient limits, reply latency, message size limits and throughput may require choosing a lower cap.
|
|
520
|
+
The adapter waits for each `RCPT TO` reply, even if the relay advertises PIPELINING. For planning, multiply the
|
|
521
|
+
recipient count by a conservative per-reply latency and add time for DNS, connection, TLS, other commands,
|
|
522
|
+
MIME transfer and the final acknowledgement. Leave reserve for jitter and worker/store operations too. At
|
|
523
|
+
60 ms per reply, 1,000 RCPT replies alone use the entire 60-second provider maximum.
|
|
524
|
+
|
|
525
|
+
On verified-TLS loopback, a single 1,000-recipient transaction with 8.18 MiB of synthetic MIME took **5.851 s**
|
|
526
|
+
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).
|
|
527
|
+
These are single samples, not production latency estimates or a guarantee for another relay. The worker's
|
|
528
|
+
`limits.providerTimeoutMs` defaults to 15,000 ms and cannot exceed 60,000 ms; the effective call is further
|
|
529
|
+
clipped by the remaining run and lease windows, including finalization grace and clock margin. Defaults are
|
|
530
|
+
a 30 s run, 60 s lease and 10 s finalization grace. The two extended samples used
|
|
531
|
+
`limits: { providerTimeoutMs: 60_000, leaseMs: 90_000 }` and a 75,000 ms `run({ timeoutMs })` budget, not just a
|
|
532
|
+
higher provider timeout. Measure with representative envelopes and keep headroom; timeouts are not a flow-control
|
|
533
|
+
strategy.
|
|
534
|
+
|
|
535
|
+
After a partial acceptance there is no automatic resend, including to the rejected subset. Only definitive safe
|
|
536
|
+
transient nonacceptance authorizes a submission retry. Timeout or missing acknowledgement can leave an `unknown`
|
|
537
|
+
result; closing a socket does not prove that the relay discarded the message. `write_unconfirmed` is not a rollback.
|
|
538
|
+
Job and activity reads remain redacted. Opted-in activities include group counts and, when known, group/index
|
|
539
|
+
outcomes, not recipient addresses, message content, attachment references, credentials or raw SMTP replies.
|
|
540
|
+
|
|
541
|
+
### Storage, rollout and rollback
|
|
542
|
+
|
|
543
|
+
- `format: 'smtp-v2'` selects a separate **storage** format; the public DTOs still have `version: 1`.
|
|
544
|
+
Every opted-in prepared command, SMTP snapshot, job summary and activity carries its `smtpCapacity` metadata,
|
|
545
|
+
even below 51 recipients. The field is optional in TypeScript so the types still describe V1 data, where it
|
|
546
|
+
must be absent. Neither queue will accept the other's staged values.
|
|
547
|
+
- On MongoDB the binding owns exactly `email_smtp_v2.<namespace>.jobs` and
|
|
548
|
+
`email_smtp_v2.<namespace>.activities`; V1 collection/model name overrides cannot be supplied with this option.
|
|
549
|
+
Call `ready()` before use. It checks both definitions and installs missing collections/indexes; it does not
|
|
550
|
+
alter existing validators, rewrite rows or touch V1 collections. A conflicting cap for an existing namespace
|
|
551
|
+
fails readiness. Keep the pair private and restore it together, offline, under its original binding.
|
|
552
|
+
- Keep the namespace and cap fixed for the lifetime of the backing queue. To change the cap, provision a fresh
|
|
553
|
+
namespace, verify readiness, and change routing for **new** work. Keep older and newer queues separate, each
|
|
554
|
+
with its own matched worker and admin. Third-party stores stay V1 unless they implement the bound storage and
|
|
555
|
+
limits, including checking the exact `StoreCall.smtpCapacity` before each primitive.
|
|
556
|
+
- To roll back, stop routing new work to the opt-in queue. Keep already staged outbox values and jobs on their
|
|
557
|
+
original route. Drain (or park) that lane with matching code and binding for recovery, inspection and retention;
|
|
558
|
+
keep V1 traffic on its existing queue. Do not point an older, V1-only runtime at the opted-in store. Do not retag,
|
|
559
|
+
copy or replay jobs across queues or automatically redrive uncertain work. The original lane's idempotency and
|
|
560
|
+
retention still apply.
|
|
561
|
+
|
|
424
562
|
## Integration entrypoints
|
|
425
563
|
|
|
426
564
|
The integration types have their own entrypoints:
|
|
@@ -436,7 +574,7 @@ import type { MongooseEmailStoreOptions } from '@web-ts-toolkit/email-service/mo
|
|
|
436
574
|
<!-- prettier-ignore -->
|
|
437
575
|
| Entry | Current surface | Optional peer |
|
|
438
576
|
| --- | --- | --- |
|
|
439
|
-
| `@web-ts-toolkit/email-service` | `EmailError`, `createEmailTemplateRegistry`, `defineLocalTemplate`, `defineSendGridTemplate`, `createEmailService`, `createEmailWorker`, `createEmailBatchService`, `createEmailAdmin`, `createMemoryEmailStore`, and shared contracts | None |
|
|
577
|
+
| `@web-ts-toolkit/email-service` | `EmailError`, `createEmailTemplateRegistry`, `defineLocalTemplate`, `defineSendGridTemplate`, `createEmailService`, `createEmailWorker`, `createEmailBatchService`, `createEmailAdmin`, `createMemoryEmailStore`, and shared contracts including `SmtpCapacity` | None |
|
|
440
578
|
| `@web-ts-toolkit/email-service/smtp` | `createSmtpProvider`, `SmtpProviderOptions` | Nodemailer `>=10.6.0 <11` (runtime only) |
|
|
441
579
|
| `@web-ts-toolkit/email-service/sendgrid` | `createSendGridProvider`, `SendGridProviderOptions` | None (Node HTTPS) |
|
|
442
580
|
| `@web-ts-toolkit/email-service/mongoose` | `createMongooseEmailStore`, `MongooseEmailStoreOptions` | Mongoose `>=9.12.2 <10` (declarations and caller connection) |
|
package/index.d.mts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-
|
|
2
|
-
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint,
|
|
3
|
-
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-
|
|
4
|
-
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-
|
|
1
|
+
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, S as SmtpCapacity, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-DC_av0SQ.mjs';
|
|
2
|
+
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint, y as SendGridSnapshot, z as SmtpSnapshot, B as SubmissionOutcome, D as SubmissionStage, T as TemplateIdentity } from './provider-DC_av0SQ.mjs';
|
|
3
|
+
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-DlABKTjt.mjs';
|
|
4
|
+
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-DlABKTjt.mjs';
|
|
5
5
|
|
|
6
6
|
/** Safe, stable diagnostics; no application data or transport-response text. */
|
|
7
7
|
type EmailErrorCode = 'invalid_config' | 'invalid_command' | 'invalid_input' | 'invalid_data' | 'invalid_snapshot' | 'preparation_failed' | 'template_not_found' | 'template_source' | 'template_render' | 'provider_mismatch' | 'expired' | 'idempotency_conflict' | 'not_found' | 'resolution_conflict' | 'store_capacity' | 'store_unavailable' | 'store_incompatible' | 'write_unconfirmed' | 'invalid_cursor' | 'aborted' | 'deadline' | 'busy' | 'closed';
|
|
@@ -90,6 +90,8 @@ type EmailCommand<T extends TemplateMap> = TemplateCommand<T> & {
|
|
|
90
90
|
key: EmailAdmissionKey;
|
|
91
91
|
};
|
|
92
92
|
type TemplateRegistryOptions = {
|
|
93
|
+
/** Prepare only local SMTP messages under this binding. Use the same tuple for their admission. */
|
|
94
|
+
smtpCapacity?: SmtpCapacity;
|
|
93
95
|
clock?: EmailClock;
|
|
94
96
|
cacheEntries?: number;
|
|
95
97
|
maxPending?: number;
|
|
@@ -97,6 +99,7 @@ type TemplateRegistryOptions = {
|
|
|
97
99
|
helpers?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
|
|
98
100
|
};
|
|
99
101
|
interface EmailTemplateRegistry<T extends TemplateMap> {
|
|
102
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
100
103
|
/** Prepare a detached snapshot without using a queue or contacting a provider. */
|
|
101
104
|
prepare(scope: EmailScope, command: EmailCommand<T>, options?: CallOptions): Promise<PreparedEmailCommand>;
|
|
102
105
|
/** Evict one or all compilation cache entries and fence their prior in-flight loads. */
|
|
@@ -116,6 +119,7 @@ type AdmissionResult = {
|
|
|
116
119
|
};
|
|
117
120
|
interface EmailService<T extends TemplateMap> {
|
|
118
121
|
readonly scope: EmailScope;
|
|
122
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
119
123
|
/** Admit or replay by scoped stable intent; a committed replay does not prepare again. */
|
|
120
124
|
enqueue(command: EmailCommand<T>, options?: CallOptions): Promise<AdmissionResult>;
|
|
121
125
|
/** Relay the same scoped outbox snapshot unchanged. Does not join a host transaction, rerender, or extend expiry. */
|
|
@@ -123,6 +127,8 @@ interface EmailService<T extends TemplateMap> {
|
|
|
123
127
|
}
|
|
124
128
|
type EmailServiceOptions<T extends TemplateMap> = {
|
|
125
129
|
scope: EmailScope;
|
|
130
|
+
/** Must match the registry and store. Relay staged commands only through their original binding. */
|
|
131
|
+
smtpCapacity?: SmtpCapacity;
|
|
126
132
|
store: EmailStore;
|
|
127
133
|
registry: EmailTemplateRegistry<T>;
|
|
128
134
|
retry?: Partial<RetryPolicy>;
|
|
@@ -165,9 +171,11 @@ interface EmailBatchService<T extends TemplateMap> {
|
|
|
165
171
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
166
172
|
}
|
|
167
173
|
type EmailBatchServiceOptions<T extends TemplateMap> = {
|
|
168
|
-
/** Must share the worker's scope and
|
|
174
|
+
/** Must share the worker's scope, underlying store and SMTP capacity binding, if enabled. */
|
|
169
175
|
service: EmailService<T>;
|
|
170
176
|
worker: EmailWorker;
|
|
177
|
+
/** Pass the exact tuple explicitly when the service and worker are opted in. */
|
|
178
|
+
smtpCapacity?: SmtpCapacity;
|
|
171
179
|
};
|
|
172
180
|
|
|
173
181
|
/**
|
|
@@ -197,10 +205,10 @@ declare function createEmailBatchService<T extends TemplateMap>(options: EmailBa
|
|
|
197
205
|
declare function createEmailAdmin(options: EmailAdminOptions): EmailAdmin;
|
|
198
206
|
|
|
199
207
|
/**
|
|
200
|
-
* Single-process
|
|
208
|
+
* Single-process store for tests and development. State is lost on restart and is not shared across
|
|
201
209
|
* instances or processes. Capacity is global across scopes; it never evicts a protected job or acts as
|
|
202
210
|
* a fallback for another store. Uses the injected clock's wall time for store guards.
|
|
203
211
|
*/
|
|
204
212
|
declare function createMemoryEmailStore(options?: MemoryEmailStoreOptions): EmailStore;
|
|
205
213
|
|
|
206
|
-
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|
|
214
|
+
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, SmtpCapacity, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|
package/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-
|
|
2
|
-
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint,
|
|
3
|
-
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-
|
|
4
|
-
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-
|
|
1
|
+
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, S as SmtpCapacity, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-DC_av0SQ.js';
|
|
2
|
+
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint, y as SendGridSnapshot, z as SmtpSnapshot, B as SubmissionOutcome, D as SubmissionStage, T as TemplateIdentity } from './provider-DC_av0SQ.js';
|
|
3
|
+
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-Bi5iZ910.js';
|
|
4
|
+
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-Bi5iZ910.js';
|
|
5
5
|
|
|
6
6
|
/** Safe, stable diagnostics; no application data or transport-response text. */
|
|
7
7
|
type EmailErrorCode = 'invalid_config' | 'invalid_command' | 'invalid_input' | 'invalid_data' | 'invalid_snapshot' | 'preparation_failed' | 'template_not_found' | 'template_source' | 'template_render' | 'provider_mismatch' | 'expired' | 'idempotency_conflict' | 'not_found' | 'resolution_conflict' | 'store_capacity' | 'store_unavailable' | 'store_incompatible' | 'write_unconfirmed' | 'invalid_cursor' | 'aborted' | 'deadline' | 'busy' | 'closed';
|
|
@@ -90,6 +90,8 @@ type EmailCommand<T extends TemplateMap> = TemplateCommand<T> & {
|
|
|
90
90
|
key: EmailAdmissionKey;
|
|
91
91
|
};
|
|
92
92
|
type TemplateRegistryOptions = {
|
|
93
|
+
/** Prepare only local SMTP messages under this binding. Use the same tuple for their admission. */
|
|
94
|
+
smtpCapacity?: SmtpCapacity;
|
|
93
95
|
clock?: EmailClock;
|
|
94
96
|
cacheEntries?: number;
|
|
95
97
|
maxPending?: number;
|
|
@@ -97,6 +99,7 @@ type TemplateRegistryOptions = {
|
|
|
97
99
|
helpers?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
|
|
98
100
|
};
|
|
99
101
|
interface EmailTemplateRegistry<T extends TemplateMap> {
|
|
102
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
100
103
|
/** Prepare a detached snapshot without using a queue or contacting a provider. */
|
|
101
104
|
prepare(scope: EmailScope, command: EmailCommand<T>, options?: CallOptions): Promise<PreparedEmailCommand>;
|
|
102
105
|
/** Evict one or all compilation cache entries and fence their prior in-flight loads. */
|
|
@@ -116,6 +119,7 @@ type AdmissionResult = {
|
|
|
116
119
|
};
|
|
117
120
|
interface EmailService<T extends TemplateMap> {
|
|
118
121
|
readonly scope: EmailScope;
|
|
122
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
119
123
|
/** Admit or replay by scoped stable intent; a committed replay does not prepare again. */
|
|
120
124
|
enqueue(command: EmailCommand<T>, options?: CallOptions): Promise<AdmissionResult>;
|
|
121
125
|
/** Relay the same scoped outbox snapshot unchanged. Does not join a host transaction, rerender, or extend expiry. */
|
|
@@ -123,6 +127,8 @@ interface EmailService<T extends TemplateMap> {
|
|
|
123
127
|
}
|
|
124
128
|
type EmailServiceOptions<T extends TemplateMap> = {
|
|
125
129
|
scope: EmailScope;
|
|
130
|
+
/** Must match the registry and store. Relay staged commands only through their original binding. */
|
|
131
|
+
smtpCapacity?: SmtpCapacity;
|
|
126
132
|
store: EmailStore;
|
|
127
133
|
registry: EmailTemplateRegistry<T>;
|
|
128
134
|
retry?: Partial<RetryPolicy>;
|
|
@@ -165,9 +171,11 @@ interface EmailBatchService<T extends TemplateMap> {
|
|
|
165
171
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
166
172
|
}
|
|
167
173
|
type EmailBatchServiceOptions<T extends TemplateMap> = {
|
|
168
|
-
/** Must share the worker's scope and
|
|
174
|
+
/** Must share the worker's scope, underlying store and SMTP capacity binding, if enabled. */
|
|
169
175
|
service: EmailService<T>;
|
|
170
176
|
worker: EmailWorker;
|
|
177
|
+
/** Pass the exact tuple explicitly when the service and worker are opted in. */
|
|
178
|
+
smtpCapacity?: SmtpCapacity;
|
|
171
179
|
};
|
|
172
180
|
|
|
173
181
|
/**
|
|
@@ -197,10 +205,10 @@ declare function createEmailBatchService<T extends TemplateMap>(options: EmailBa
|
|
|
197
205
|
declare function createEmailAdmin(options: EmailAdminOptions): EmailAdmin;
|
|
198
206
|
|
|
199
207
|
/**
|
|
200
|
-
* Single-process
|
|
208
|
+
* Single-process store for tests and development. State is lost on restart and is not shared across
|
|
201
209
|
* instances or processes. Capacity is global across scopes; it never evicts a protected job or acts as
|
|
202
210
|
* a fallback for another store. Uses the injected clock's wall time for store guards.
|
|
203
211
|
*/
|
|
204
212
|
declare function createMemoryEmailStore(options?: MemoryEmailStoreOptions): EmailStore;
|
|
205
213
|
|
|
206
|
-
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|
|
214
|
+
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, SmtpCapacity, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|