@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
|
@@ -1,6 +1,10 @@
|
|
|
1
|
-
import { U as UnixMs,
|
|
1
|
+
import { U as UnixMs, k as AttemptReason, S as SmtpCapacity, a as EmailScope, o as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, n as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, m as ConfiguredEmailProvider, j as AttachmentResolver, g as EmailClock, R as RecipientResult, l as AttemptResult, q as EmailSnapshot, f as PreparedEmailCommand } from './provider-CeUryYAf.js';
|
|
2
2
|
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* Frozen at admission. `maxAttempts` defaults to 3 claims, including quota deferrals with no provider call.
|
|
5
|
+
* Safe transient retries use jittered exponential backoff (default 1 s base, 60 s cap) and any later retry
|
|
6
|
+
* floor from the limiter or provider. No retry is scheduled at or after expiry.
|
|
7
|
+
*/
|
|
4
8
|
type RetryPolicy = {
|
|
5
9
|
maxAttempts: number;
|
|
6
10
|
baseDelayMs: number;
|
|
@@ -34,6 +38,7 @@ type EmailJobState = {
|
|
|
34
38
|
/** Authoritative redacted job state, available without waiting for activity projection. */
|
|
35
39
|
type EmailJobSummary = EmailJobState & {
|
|
36
40
|
readonly version: 1;
|
|
41
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
37
42
|
readonly scope: EmailScope;
|
|
38
43
|
readonly jobId: EmailJobId;
|
|
39
44
|
readonly key: EmailAdmissionKey;
|
|
@@ -60,7 +65,11 @@ type CancelResult = {
|
|
|
60
65
|
} | {
|
|
61
66
|
readonly status: 'not_found';
|
|
62
67
|
};
|
|
63
|
-
/**
|
|
68
|
+
/**
|
|
69
|
+
* Resolve only the current open unknown attempt. Dismiss leaves the outcome unchanged, even after expiry.
|
|
70
|
+
* Redrive requires a retained unexpired snapshot and no previous redrive; it adds one claim on that same
|
|
71
|
+
* snapshot and can duplicate an already accepted message. Quiesce suspected old workers and review evidence first.
|
|
72
|
+
*/
|
|
64
73
|
type ResolveUnknownCommand = {
|
|
65
74
|
jobId: EmailJobId;
|
|
66
75
|
attemptId: EmailAttemptId;
|
|
@@ -75,7 +84,10 @@ type ResolveUnknownResult = {
|
|
|
75
84
|
readonly job: EmailJobSummary;
|
|
76
85
|
};
|
|
77
86
|
|
|
78
|
-
/**
|
|
87
|
+
/**
|
|
88
|
+
* A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local.
|
|
89
|
+
* A deferral consumes a claim without calling `submit`; `retryAfterMs` is a floor, not a wait in the run.
|
|
90
|
+
*/
|
|
79
91
|
type EmailRateLimiter = {
|
|
80
92
|
scope: 'worker' | 'shared';
|
|
81
93
|
tryAcquire(request: {
|
|
@@ -102,27 +114,39 @@ type EmailWorkerLimits = {
|
|
|
102
114
|
type EmailRunOptions = CallOptions & {
|
|
103
115
|
limit?: number;
|
|
104
116
|
concurrency?: number;
|
|
117
|
+
/** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
|
|
105
118
|
maintenanceLimit?: number;
|
|
106
119
|
};
|
|
107
120
|
type EmailRunEntry = {
|
|
108
121
|
readonly operation: 'claim' | 'recover' | 'expire';
|
|
109
122
|
readonly jobId: EmailJobId;
|
|
110
123
|
readonly attemptId?: EmailAttemptId;
|
|
124
|
+
/** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
|
|
111
125
|
readonly status: JobDisposition | 'retry_scheduled' | 'unconfirmed';
|
|
126
|
+
/**
|
|
127
|
+
* `profile_unavailable` is terminal `failed`; the attempt did not submit.
|
|
128
|
+
* Replaying the same command does not reopen the job.
|
|
129
|
+
*/
|
|
112
130
|
readonly reason?: AttemptReason | 'attempts_exhausted';
|
|
131
|
+
/** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
|
|
113
132
|
readonly providerInvoked: boolean;
|
|
114
133
|
};
|
|
115
134
|
type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
|
|
116
135
|
/** This run's confirmed progress, not an inventory of the whole queue. */
|
|
117
136
|
type EmailRunReport = {
|
|
118
|
-
|
|
137
|
+
/**
|
|
138
|
+
* On `expiry_maintenance_required`, schedule another run for the same scope with a positive
|
|
139
|
+
* `maintenanceLimit` (the default does this). A backlog may need several bounded runs; retrying
|
|
140
|
+
* with zero maintenance alone does not clear it. The stop does not prove live work is waiting.
|
|
141
|
+
*/
|
|
142
|
+
readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity' | 'expiry_maintenance_required';
|
|
119
143
|
readonly items: readonly EmailRunEntry[];
|
|
120
144
|
readonly counts: {
|
|
121
145
|
readonly claimed: number;
|
|
122
146
|
readonly recovered: number;
|
|
123
147
|
readonly expiredInSweep: number;
|
|
124
148
|
readonly providerCalls: number;
|
|
125
|
-
/** Full plus partial acceptance; sandbox
|
|
149
|
+
/** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
|
|
126
150
|
readonly submitted: number;
|
|
127
151
|
readonly retryScheduled: number;
|
|
128
152
|
readonly accepted: number;
|
|
@@ -144,16 +168,33 @@ type EmailShutdownReport = {
|
|
|
144
168
|
};
|
|
145
169
|
interface EmailWorker {
|
|
146
170
|
readonly scope: EmailScope;
|
|
147
|
-
|
|
171
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
172
|
+
/**
|
|
173
|
+
* Do bounded work in this scope without filtering claims by provider profile.
|
|
174
|
+
* The host schedules runs; only one run per instance may be active.
|
|
175
|
+
*/
|
|
148
176
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
149
177
|
/** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
|
|
150
178
|
shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
|
|
151
179
|
}
|
|
152
|
-
/**
|
|
180
|
+
/**
|
|
181
|
+
* Dependencies for a bounded worker. Workers sharing a queue and scope compete for jobs.
|
|
182
|
+
* Install new profiles and their resolvers on every competing worker before producers use them,
|
|
183
|
+
* and keep old ones until their work drains. The host must verify coverage across processes.
|
|
184
|
+
* Fleets that cannot share configuration need separately routed scopes or queues.
|
|
185
|
+
*/
|
|
153
186
|
type EmailWorkerOptions = {
|
|
154
187
|
scope: EmailScope;
|
|
188
|
+
/** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
|
|
189
|
+
smtpCapacity?: SmtpCapacity;
|
|
155
190
|
store: EmailStore;
|
|
191
|
+
/**
|
|
192
|
+
* Supply at least one configured profile; an empty array throws `invalid_config` at construction.
|
|
193
|
+
* Profile keys must be unique within this worker. Every competing worker needs the exact kind,
|
|
194
|
+
* key and mode of every active profile in its scope. Workers never substitute another profile.
|
|
195
|
+
*/
|
|
156
196
|
providers: readonly ConfiguredEmailProvider[];
|
|
197
|
+
/** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
|
|
157
198
|
attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
|
|
158
199
|
rateLimiter?: EmailRateLimiter;
|
|
159
200
|
clock?: EmailClock;
|
|
@@ -163,6 +204,9 @@ type EmailWorkerOptions = {
|
|
|
163
204
|
/** Redacted projection of a finalized attempt; never a queue payload or a delivery receipt. */
|
|
164
205
|
type EmailActivity = {
|
|
165
206
|
readonly version: 1;
|
|
207
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
208
|
+
/** Present in opted-in history; counts refer to the original To, Cc and Bcc groups, never addresses. */
|
|
209
|
+
readonly recipientCounts?: Readonly<Record<RecipientResult['group'], number>>;
|
|
166
210
|
readonly scope: EmailScope;
|
|
167
211
|
readonly jobId: EmailJobId;
|
|
168
212
|
readonly attemptId: EmailAttemptId;
|
|
@@ -188,7 +232,7 @@ type EmailActivityPage = {
|
|
|
188
232
|
readonly items: readonly EmailActivity[];
|
|
189
233
|
readonly nextCursor?: string;
|
|
190
234
|
};
|
|
191
|
-
/** One sequential sweep;
|
|
235
|
+
/** One sequential sweep; V1 defaults to 20 (1–100); SMTP opt-in defaults to 4 (1–16). */
|
|
192
236
|
type MaintenanceOptions = CallOptions & {
|
|
193
237
|
limit?: number;
|
|
194
238
|
};
|
|
@@ -211,21 +255,29 @@ type CleanupReport = {
|
|
|
211
255
|
};
|
|
212
256
|
interface EmailAdmin {
|
|
213
257
|
readonly scope: EmailScope;
|
|
214
|
-
/** Read the job and its latest authoritative outcome, even before
|
|
258
|
+
/** Read the job and its latest authoritative outcome, even before projection. Use this to verify a current hold. */
|
|
215
259
|
getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
|
|
216
260
|
/** Cancel only before irreversible handoff and expiry; no remote recall. */
|
|
217
261
|
cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
|
|
218
|
-
/**
|
|
262
|
+
/**
|
|
263
|
+
* Dismiss or requeue the exact open unknown attempt. Redrive can duplicate a previously accepted submission.
|
|
264
|
+
* After `write_unconfirmed`, check the current job's `resolutions` for the exact attempt and action.
|
|
265
|
+
*/
|
|
219
266
|
resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
|
|
220
|
-
/**
|
|
267
|
+
/**
|
|
268
|
+
* Read committed activities even before source ACK. History is not an inventory of open holds.
|
|
269
|
+
* V1 default/max: 25/100; SMTP opt-in: 8/16.
|
|
270
|
+
*/
|
|
221
271
|
listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
|
|
222
|
-
/** Project from the authoritative ledger
|
|
272
|
+
/** Project from the authoritative ledger. Does not recover leases or send mail. */
|
|
223
273
|
reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
|
|
224
274
|
/** Prune or retire settled, fully projected jobs after their retention windows. */
|
|
225
275
|
cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
|
|
226
276
|
}
|
|
227
277
|
type EmailAdminOptions = {
|
|
228
278
|
scope: EmailScope;
|
|
279
|
+
/** Must match the store. Opted-in history stays redacted and cursors remain bound to this tuple. */
|
|
280
|
+
smtpCapacity?: SmtpCapacity;
|
|
229
281
|
store: EmailStore;
|
|
230
282
|
/** Best effort after a new confirmed projection ACK. One unresolved callback per admin; no wait or retry. */
|
|
231
283
|
onActivity?: (activity: EmailActivity) => Awaitable<void>;
|
|
@@ -234,6 +286,8 @@ type EmailAdminOptions = {
|
|
|
234
286
|
type StoreCall = {
|
|
235
287
|
signal: AbortSignal;
|
|
236
288
|
timeoutMs: number;
|
|
289
|
+
/** An opted-in store must check this exact binding before every primitive. V1 calls omit it. */
|
|
290
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
237
291
|
};
|
|
238
292
|
type StoreNext<T> = {
|
|
239
293
|
readonly status: 'applied';
|
|
@@ -270,6 +324,10 @@ type ClaimedEmail = {
|
|
|
270
324
|
readonly ordinal: number;
|
|
271
325
|
readonly manual: boolean;
|
|
272
326
|
};
|
|
327
|
+
/** A full claim window of due, expired jobs may hide eligible work. The signal itself makes no write. */
|
|
328
|
+
type StoreClaimNext<T = ClaimedEmail> = StoreNext<T> | {
|
|
329
|
+
readonly status: 'expiry_maintenance_required';
|
|
330
|
+
};
|
|
273
331
|
type AttemptCommit = {
|
|
274
332
|
readonly jobId: EmailJobId;
|
|
275
333
|
readonly attemptId: EmailAttemptId;
|
|
@@ -292,14 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
|
|
|
292
350
|
/**
|
|
293
351
|
* Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
|
|
294
352
|
* time for durable guards. Do not report an unconfirmed write as a definite miss or fall back to memory.
|
|
353
|
+
* See the installed README for the versioned adapter contracts and current follow-ups.
|
|
295
354
|
*/
|
|
296
355
|
interface EmailStore {
|
|
356
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
357
|
+
/** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
|
|
297
358
|
ready(options?: CallOptions): Promise<void>;
|
|
298
359
|
findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
|
|
299
360
|
readonly job: EmailJobSummary;
|
|
300
361
|
readonly fingerprint: string;
|
|
301
362
|
} | null>;
|
|
302
|
-
/**
|
|
363
|
+
/**
|
|
364
|
+
* `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints.
|
|
365
|
+
* On a miss, new SMTP inserts require leaf attachments (no `message/*` or `multipart/*`).
|
|
366
|
+
*/
|
|
303
367
|
insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
|
|
304
368
|
readonly status: 'inserted';
|
|
305
369
|
readonly job: EmailJobSummary;
|
|
@@ -308,11 +372,16 @@ interface EmailStore {
|
|
|
308
372
|
}>;
|
|
309
373
|
findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
|
|
310
374
|
findAttempt(scope: EmailScope, jobId: EmailJobId, attemptId: EmailAttemptId, call: StoreCall): Promise<AttemptCommit | null>;
|
|
375
|
+
/**
|
|
376
|
+
* Claim within a bounded window. `expiry_maintenance_required` means every candidate slot was filled
|
|
377
|
+
* by a confirmed expired queued job, not that more jobs necessarily exist. Run bounded `expireNext`
|
|
378
|
+
* calls in the same scope (or run a worker with a positive `maintenanceLimit`), then retry.
|
|
379
|
+
*/
|
|
311
380
|
claimNext(scope: EmailScope, claim: {
|
|
312
381
|
attemptId: EmailAttemptId;
|
|
313
382
|
token: LeaseToken;
|
|
314
383
|
leaseMs: number;
|
|
315
|
-
}, call: StoreCall): Promise<
|
|
384
|
+
}, call: StoreCall): Promise<StoreClaimNext>;
|
|
316
385
|
/** Null on a fenced operation is a definite miss, never a lost ACK. */
|
|
317
386
|
renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
|
|
318
387
|
/** A timely positive ACK of this exact mutation is required to authorize submission. */
|
|
@@ -337,10 +406,12 @@ interface EmailStore {
|
|
|
337
406
|
}
|
|
338
407
|
/** Settings for a single-process, non-durable development/test store. */
|
|
339
408
|
type MemoryEmailStoreOptions = {
|
|
409
|
+
/** Opt into the SMTP queue format. Assign a different namespace to each independent backing. */
|
|
410
|
+
smtpCapacity?: SmtpCapacity;
|
|
340
411
|
/** Store wall time governs transitions; elapsed time enforces call budgets. Defaults to system time. */
|
|
341
412
|
clock?: EmailClock;
|
|
342
|
-
/**
|
|
413
|
+
/** Across all scopes: default 256, range 1–4,096 (SMTP opt-in: default 8, range 1–16). */
|
|
343
414
|
maxJobs?: number;
|
|
344
415
|
};
|
|
345
416
|
|
|
346
|
-
export type { AttemptCommit as A,
|
|
417
|
+
export type { AttemptCommit as A, StoreClaimNext as B, CancelResult as C, StoreNext as D, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };
|
|
@@ -1,6 +1,10 @@
|
|
|
1
|
-
import { U as UnixMs,
|
|
1
|
+
import { U as UnixMs, k as AttemptReason, S as SmtpCapacity, a as EmailScope, o as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, n as EmailAttemptId, B as SubmissionOutcome, e as CallOptions, A as Awaitable, m as ConfiguredEmailProvider, j as AttachmentResolver, g as EmailClock, R as RecipientResult, l as AttemptResult, q as EmailSnapshot, f as PreparedEmailCommand } from './provider-CeUryYAf.mjs';
|
|
2
2
|
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* Frozen at admission. `maxAttempts` defaults to 3 claims, including quota deferrals with no provider call.
|
|
5
|
+
* Safe transient retries use jittered exponential backoff (default 1 s base, 60 s cap) and any later retry
|
|
6
|
+
* floor from the limiter or provider. No retry is scheduled at or after expiry.
|
|
7
|
+
*/
|
|
4
8
|
type RetryPolicy = {
|
|
5
9
|
maxAttempts: number;
|
|
6
10
|
baseDelayMs: number;
|
|
@@ -34,6 +38,7 @@ type EmailJobState = {
|
|
|
34
38
|
/** Authoritative redacted job state, available without waiting for activity projection. */
|
|
35
39
|
type EmailJobSummary = EmailJobState & {
|
|
36
40
|
readonly version: 1;
|
|
41
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
37
42
|
readonly scope: EmailScope;
|
|
38
43
|
readonly jobId: EmailJobId;
|
|
39
44
|
readonly key: EmailAdmissionKey;
|
|
@@ -60,7 +65,11 @@ type CancelResult = {
|
|
|
60
65
|
} | {
|
|
61
66
|
readonly status: 'not_found';
|
|
62
67
|
};
|
|
63
|
-
/**
|
|
68
|
+
/**
|
|
69
|
+
* Resolve only the current open unknown attempt. Dismiss leaves the outcome unchanged, even after expiry.
|
|
70
|
+
* Redrive requires a retained unexpired snapshot and no previous redrive; it adds one claim on that same
|
|
71
|
+
* snapshot and can duplicate an already accepted message. Quiesce suspected old workers and review evidence first.
|
|
72
|
+
*/
|
|
64
73
|
type ResolveUnknownCommand = {
|
|
65
74
|
jobId: EmailJobId;
|
|
66
75
|
attemptId: EmailAttemptId;
|
|
@@ -75,7 +84,10 @@ type ResolveUnknownResult = {
|
|
|
75
84
|
readonly job: EmailJobSummary;
|
|
76
85
|
};
|
|
77
86
|
|
|
78
|
-
/**
|
|
87
|
+
/**
|
|
88
|
+
* A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local.
|
|
89
|
+
* A deferral consumes a claim without calling `submit`; `retryAfterMs` is a floor, not a wait in the run.
|
|
90
|
+
*/
|
|
79
91
|
type EmailRateLimiter = {
|
|
80
92
|
scope: 'worker' | 'shared';
|
|
81
93
|
tryAcquire(request: {
|
|
@@ -102,27 +114,39 @@ type EmailWorkerLimits = {
|
|
|
102
114
|
type EmailRunOptions = CallOptions & {
|
|
103
115
|
limit?: number;
|
|
104
116
|
concurrency?: number;
|
|
117
|
+
/** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
|
|
105
118
|
maintenanceLimit?: number;
|
|
106
119
|
};
|
|
107
120
|
type EmailRunEntry = {
|
|
108
121
|
readonly operation: 'claim' | 'recover' | 'expire';
|
|
109
122
|
readonly jobId: EmailJobId;
|
|
110
123
|
readonly attemptId?: EmailAttemptId;
|
|
124
|
+
/** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
|
|
111
125
|
readonly status: JobDisposition | 'retry_scheduled' | 'unconfirmed';
|
|
126
|
+
/**
|
|
127
|
+
* `profile_unavailable` is terminal `failed`; the attempt did not submit.
|
|
128
|
+
* Replaying the same command does not reopen the job.
|
|
129
|
+
*/
|
|
112
130
|
readonly reason?: AttemptReason | 'attempts_exhausted';
|
|
131
|
+
/** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
|
|
113
132
|
readonly providerInvoked: boolean;
|
|
114
133
|
};
|
|
115
134
|
type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
|
|
116
135
|
/** This run's confirmed progress, not an inventory of the whole queue. */
|
|
117
136
|
type EmailRunReport = {
|
|
118
|
-
|
|
137
|
+
/**
|
|
138
|
+
* On `expiry_maintenance_required`, schedule another run for the same scope with a positive
|
|
139
|
+
* `maintenanceLimit` (the default does this). A backlog may need several bounded runs; retrying
|
|
140
|
+
* with zero maintenance alone does not clear it. The stop does not prove live work is waiting.
|
|
141
|
+
*/
|
|
142
|
+
readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity' | 'expiry_maintenance_required';
|
|
119
143
|
readonly items: readonly EmailRunEntry[];
|
|
120
144
|
readonly counts: {
|
|
121
145
|
readonly claimed: number;
|
|
122
146
|
readonly recovered: number;
|
|
123
147
|
readonly expiredInSweep: number;
|
|
124
148
|
readonly providerCalls: number;
|
|
125
|
-
/** Full plus partial acceptance; sandbox
|
|
149
|
+
/** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
|
|
126
150
|
readonly submitted: number;
|
|
127
151
|
readonly retryScheduled: number;
|
|
128
152
|
readonly accepted: number;
|
|
@@ -144,16 +168,33 @@ type EmailShutdownReport = {
|
|
|
144
168
|
};
|
|
145
169
|
interface EmailWorker {
|
|
146
170
|
readonly scope: EmailScope;
|
|
147
|
-
|
|
171
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
172
|
+
/**
|
|
173
|
+
* Do bounded work in this scope without filtering claims by provider profile.
|
|
174
|
+
* The host schedules runs; only one run per instance may be active.
|
|
175
|
+
*/
|
|
148
176
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
149
177
|
/** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
|
|
150
178
|
shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
|
|
151
179
|
}
|
|
152
|
-
/**
|
|
180
|
+
/**
|
|
181
|
+
* Dependencies for a bounded worker. Workers sharing a queue and scope compete for jobs.
|
|
182
|
+
* Install new profiles and their resolvers on every competing worker before producers use them,
|
|
183
|
+
* and keep old ones until their work drains. The host must verify coverage across processes.
|
|
184
|
+
* Fleets that cannot share configuration need separately routed scopes or queues.
|
|
185
|
+
*/
|
|
153
186
|
type EmailWorkerOptions = {
|
|
154
187
|
scope: EmailScope;
|
|
188
|
+
/** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
|
|
189
|
+
smtpCapacity?: SmtpCapacity;
|
|
155
190
|
store: EmailStore;
|
|
191
|
+
/**
|
|
192
|
+
* Supply at least one configured profile; an empty array throws `invalid_config` at construction.
|
|
193
|
+
* Profile keys must be unique within this worker. Every competing worker needs the exact kind,
|
|
194
|
+
* key and mode of every active profile in its scope. Workers never substitute another profile.
|
|
195
|
+
*/
|
|
156
196
|
providers: readonly ConfiguredEmailProvider[];
|
|
197
|
+
/** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
|
|
157
198
|
attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
|
|
158
199
|
rateLimiter?: EmailRateLimiter;
|
|
159
200
|
clock?: EmailClock;
|
|
@@ -163,6 +204,9 @@ type EmailWorkerOptions = {
|
|
|
163
204
|
/** Redacted projection of a finalized attempt; never a queue payload or a delivery receipt. */
|
|
164
205
|
type EmailActivity = {
|
|
165
206
|
readonly version: 1;
|
|
207
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
208
|
+
/** Present in opted-in history; counts refer to the original To, Cc and Bcc groups, never addresses. */
|
|
209
|
+
readonly recipientCounts?: Readonly<Record<RecipientResult['group'], number>>;
|
|
166
210
|
readonly scope: EmailScope;
|
|
167
211
|
readonly jobId: EmailJobId;
|
|
168
212
|
readonly attemptId: EmailAttemptId;
|
|
@@ -188,7 +232,7 @@ type EmailActivityPage = {
|
|
|
188
232
|
readonly items: readonly EmailActivity[];
|
|
189
233
|
readonly nextCursor?: string;
|
|
190
234
|
};
|
|
191
|
-
/** One sequential sweep;
|
|
235
|
+
/** One sequential sweep; V1 defaults to 20 (1–100); SMTP opt-in defaults to 4 (1–16). */
|
|
192
236
|
type MaintenanceOptions = CallOptions & {
|
|
193
237
|
limit?: number;
|
|
194
238
|
};
|
|
@@ -211,21 +255,29 @@ type CleanupReport = {
|
|
|
211
255
|
};
|
|
212
256
|
interface EmailAdmin {
|
|
213
257
|
readonly scope: EmailScope;
|
|
214
|
-
/** Read the job and its latest authoritative outcome, even before
|
|
258
|
+
/** Read the job and its latest authoritative outcome, even before projection. Use this to verify a current hold. */
|
|
215
259
|
getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
|
|
216
260
|
/** Cancel only before irreversible handoff and expiry; no remote recall. */
|
|
217
261
|
cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
|
|
218
|
-
/**
|
|
262
|
+
/**
|
|
263
|
+
* Dismiss or requeue the exact open unknown attempt. Redrive can duplicate a previously accepted submission.
|
|
264
|
+
* After `write_unconfirmed`, check the current job's `resolutions` for the exact attempt and action.
|
|
265
|
+
*/
|
|
219
266
|
resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
|
|
220
|
-
/**
|
|
267
|
+
/**
|
|
268
|
+
* Read committed activities even before source ACK. History is not an inventory of open holds.
|
|
269
|
+
* V1 default/max: 25/100; SMTP opt-in: 8/16.
|
|
270
|
+
*/
|
|
221
271
|
listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
|
|
222
|
-
/** Project from the authoritative ledger
|
|
272
|
+
/** Project from the authoritative ledger. Does not recover leases or send mail. */
|
|
223
273
|
reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
|
|
224
274
|
/** Prune or retire settled, fully projected jobs after their retention windows. */
|
|
225
275
|
cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
|
|
226
276
|
}
|
|
227
277
|
type EmailAdminOptions = {
|
|
228
278
|
scope: EmailScope;
|
|
279
|
+
/** Must match the store. Opted-in history stays redacted and cursors remain bound to this tuple. */
|
|
280
|
+
smtpCapacity?: SmtpCapacity;
|
|
229
281
|
store: EmailStore;
|
|
230
282
|
/** Best effort after a new confirmed projection ACK. One unresolved callback per admin; no wait or retry. */
|
|
231
283
|
onActivity?: (activity: EmailActivity) => Awaitable<void>;
|
|
@@ -234,6 +286,8 @@ type EmailAdminOptions = {
|
|
|
234
286
|
type StoreCall = {
|
|
235
287
|
signal: AbortSignal;
|
|
236
288
|
timeoutMs: number;
|
|
289
|
+
/** An opted-in store must check this exact binding before every primitive. V1 calls omit it. */
|
|
290
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
237
291
|
};
|
|
238
292
|
type StoreNext<T> = {
|
|
239
293
|
readonly status: 'applied';
|
|
@@ -270,6 +324,10 @@ type ClaimedEmail = {
|
|
|
270
324
|
readonly ordinal: number;
|
|
271
325
|
readonly manual: boolean;
|
|
272
326
|
};
|
|
327
|
+
/** A full claim window of due, expired jobs may hide eligible work. The signal itself makes no write. */
|
|
328
|
+
type StoreClaimNext<T = ClaimedEmail> = StoreNext<T> | {
|
|
329
|
+
readonly status: 'expiry_maintenance_required';
|
|
330
|
+
};
|
|
273
331
|
type AttemptCommit = {
|
|
274
332
|
readonly jobId: EmailJobId;
|
|
275
333
|
readonly attemptId: EmailAttemptId;
|
|
@@ -292,14 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
|
|
|
292
350
|
/**
|
|
293
351
|
* Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
|
|
294
352
|
* time for durable guards. Do not report an unconfirmed write as a definite miss or fall back to memory.
|
|
353
|
+
* See the installed README for the versioned adapter contracts and current follow-ups.
|
|
295
354
|
*/
|
|
296
355
|
interface EmailStore {
|
|
356
|
+
readonly smtpCapacity?: SmtpCapacity;
|
|
357
|
+
/** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
|
|
297
358
|
ready(options?: CallOptions): Promise<void>;
|
|
298
359
|
findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
|
|
299
360
|
readonly job: EmailJobSummary;
|
|
300
361
|
readonly fingerprint: string;
|
|
301
362
|
} | null>;
|
|
302
|
-
/**
|
|
363
|
+
/**
|
|
364
|
+
* `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints.
|
|
365
|
+
* On a miss, new SMTP inserts require leaf attachments (no `message/*` or `multipart/*`).
|
|
366
|
+
*/
|
|
303
367
|
insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
|
|
304
368
|
readonly status: 'inserted';
|
|
305
369
|
readonly job: EmailJobSummary;
|
|
@@ -308,11 +372,16 @@ interface EmailStore {
|
|
|
308
372
|
}>;
|
|
309
373
|
findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
|
|
310
374
|
findAttempt(scope: EmailScope, jobId: EmailJobId, attemptId: EmailAttemptId, call: StoreCall): Promise<AttemptCommit | null>;
|
|
375
|
+
/**
|
|
376
|
+
* Claim within a bounded window. `expiry_maintenance_required` means every candidate slot was filled
|
|
377
|
+
* by a confirmed expired queued job, not that more jobs necessarily exist. Run bounded `expireNext`
|
|
378
|
+
* calls in the same scope (or run a worker with a positive `maintenanceLimit`), then retry.
|
|
379
|
+
*/
|
|
311
380
|
claimNext(scope: EmailScope, claim: {
|
|
312
381
|
attemptId: EmailAttemptId;
|
|
313
382
|
token: LeaseToken;
|
|
314
383
|
leaseMs: number;
|
|
315
|
-
}, call: StoreCall): Promise<
|
|
384
|
+
}, call: StoreCall): Promise<StoreClaimNext>;
|
|
316
385
|
/** Null on a fenced operation is a definite miss, never a lost ACK. */
|
|
317
386
|
renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
|
|
318
387
|
/** A timely positive ACK of this exact mutation is required to authorize submission. */
|
|
@@ -337,10 +406,12 @@ interface EmailStore {
|
|
|
337
406
|
}
|
|
338
407
|
/** Settings for a single-process, non-durable development/test store. */
|
|
339
408
|
type MemoryEmailStoreOptions = {
|
|
409
|
+
/** Opt into the SMTP queue format. Assign a different namespace to each independent backing. */
|
|
410
|
+
smtpCapacity?: SmtpCapacity;
|
|
340
411
|
/** Store wall time governs transitions; elapsed time enforces call budgets. Defaults to system time. */
|
|
341
412
|
clock?: EmailClock;
|
|
342
|
-
/**
|
|
413
|
+
/** Across all scopes: default 256, range 1–4,096 (SMTP opt-in: default 8, range 1–16). */
|
|
343
414
|
maxJobs?: number;
|
|
344
415
|
};
|
|
345
416
|
|
|
346
|
-
export type { AttemptCommit as A,
|
|
417
|
+
export type { AttemptCommit as A, StoreClaimNext as B, CancelResult as C, StoreNext as D, EmailJobSummary as E, HandoffGrant as H, JobDisposition as J, LeaseGrant as L, MemoryEmailStoreOptions as M, OwnerFence as O, ProjectionPermit as P, RetryPolicy as R, StoreAdmission as S, UnknownResolution as U, EmailRunOptions as a, EmailRunReport as b, EmailWorker as c, EmailStore as d, RetentionPolicy as e, EmailWorkerOptions as f, EmailAdminOptions as g, EmailAdmin as h, ClaimedEmail as i, CleanupReport as j, CleanupStep as k, EmailActivity as l, EmailActivityPage as m, EmailActivityQuery as n, EmailJobState as o, EmailRateLimiter as p, EmailRunEntry as q, EmailShutdownReport as r, EmailWorkerLimits as s, LeaseToken as t, MaintenanceOptions as u, MaintenanceStop as v, ReconcileReport as w, ResolveUnknownCommand as x, ResolveUnknownResult as y, StoreCall as z };
|