@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
|
@@ -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;
|
|
@@ -61,7 +65,11 @@ type CancelResult = {
|
|
|
61
65
|
} | {
|
|
62
66
|
readonly status: 'not_found';
|
|
63
67
|
};
|
|
64
|
-
/**
|
|
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
|
+
*/
|
|
65
73
|
type ResolveUnknownCommand = {
|
|
66
74
|
jobId: EmailJobId;
|
|
67
75
|
attemptId: EmailAttemptId;
|
|
@@ -76,7 +84,10 @@ type ResolveUnknownResult = {
|
|
|
76
84
|
readonly job: EmailJobSummary;
|
|
77
85
|
};
|
|
78
86
|
|
|
79
|
-
/**
|
|
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
|
+
*/
|
|
80
91
|
type EmailRateLimiter = {
|
|
81
92
|
scope: 'worker' | 'shared';
|
|
82
93
|
tryAcquire(request: {
|
|
@@ -103,27 +114,39 @@ type EmailWorkerLimits = {
|
|
|
103
114
|
type EmailRunOptions = CallOptions & {
|
|
104
115
|
limit?: number;
|
|
105
116
|
concurrency?: number;
|
|
117
|
+
/** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
|
|
106
118
|
maintenanceLimit?: number;
|
|
107
119
|
};
|
|
108
120
|
type EmailRunEntry = {
|
|
109
121
|
readonly operation: 'claim' | 'recover' | 'expire';
|
|
110
122
|
readonly jobId: EmailJobId;
|
|
111
123
|
readonly attemptId?: EmailAttemptId;
|
|
124
|
+
/** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
|
|
112
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
|
+
*/
|
|
113
130
|
readonly reason?: AttemptReason | 'attempts_exhausted';
|
|
131
|
+
/** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
|
|
114
132
|
readonly providerInvoked: boolean;
|
|
115
133
|
};
|
|
116
134
|
type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
|
|
117
135
|
/** This run's confirmed progress, not an inventory of the whole queue. */
|
|
118
136
|
type EmailRunReport = {
|
|
119
|
-
|
|
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';
|
|
120
143
|
readonly items: readonly EmailRunEntry[];
|
|
121
144
|
readonly counts: {
|
|
122
145
|
readonly claimed: number;
|
|
123
146
|
readonly recovered: number;
|
|
124
147
|
readonly expiredInSweep: number;
|
|
125
148
|
readonly providerCalls: number;
|
|
126
|
-
/** Full plus partial acceptance; sandbox
|
|
149
|
+
/** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
|
|
127
150
|
readonly submitted: number;
|
|
128
151
|
readonly retryScheduled: number;
|
|
129
152
|
readonly accepted: number;
|
|
@@ -146,18 +169,32 @@ type EmailShutdownReport = {
|
|
|
146
169
|
interface EmailWorker {
|
|
147
170
|
readonly scope: EmailScope;
|
|
148
171
|
readonly smtpCapacity?: SmtpCapacity;
|
|
149
|
-
/**
|
|
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
|
+
*/
|
|
150
176
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
151
177
|
/** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
|
|
152
178
|
shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
|
|
153
179
|
}
|
|
154
|
-
/**
|
|
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
|
+
*/
|
|
155
186
|
type EmailWorkerOptions = {
|
|
156
187
|
scope: EmailScope;
|
|
157
188
|
/** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
|
|
158
189
|
smtpCapacity?: SmtpCapacity;
|
|
159
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
|
+
*/
|
|
160
196
|
providers: readonly ConfiguredEmailProvider[];
|
|
197
|
+
/** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
|
|
161
198
|
attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
|
|
162
199
|
rateLimiter?: EmailRateLimiter;
|
|
163
200
|
clock?: EmailClock;
|
|
@@ -218,15 +255,21 @@ type CleanupReport = {
|
|
|
218
255
|
};
|
|
219
256
|
interface EmailAdmin {
|
|
220
257
|
readonly scope: EmailScope;
|
|
221
|
-
/** 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. */
|
|
222
259
|
getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
|
|
223
260
|
/** Cancel only before irreversible handoff and expiry; no remote recall. */
|
|
224
261
|
cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
|
|
225
|
-
/**
|
|
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
|
+
*/
|
|
226
266
|
resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
|
|
227
|
-
/**
|
|
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
|
+
*/
|
|
228
271
|
listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
|
|
229
|
-
/** Project from the authoritative ledger
|
|
272
|
+
/** Project from the authoritative ledger. Does not recover leases or send mail. */
|
|
230
273
|
reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
|
|
231
274
|
/** Prune or retire settled, fully projected jobs after their retention windows. */
|
|
232
275
|
cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
|
|
@@ -281,6 +324,10 @@ type ClaimedEmail = {
|
|
|
281
324
|
readonly ordinal: number;
|
|
282
325
|
readonly manual: boolean;
|
|
283
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
|
+
};
|
|
284
331
|
type AttemptCommit = {
|
|
285
332
|
readonly jobId: EmailJobId;
|
|
286
333
|
readonly attemptId: EmailAttemptId;
|
|
@@ -303,15 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
|
|
|
303
350
|
/**
|
|
304
351
|
* Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
|
|
305
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.
|
|
306
354
|
*/
|
|
307
355
|
interface EmailStore {
|
|
308
356
|
readonly smtpCapacity?: SmtpCapacity;
|
|
357
|
+
/** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
|
|
309
358
|
ready(options?: CallOptions): Promise<void>;
|
|
310
359
|
findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
|
|
311
360
|
readonly job: EmailJobSummary;
|
|
312
361
|
readonly fingerprint: string;
|
|
313
362
|
} | null>;
|
|
314
|
-
/**
|
|
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
|
+
*/
|
|
315
367
|
insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
|
|
316
368
|
readonly status: 'inserted';
|
|
317
369
|
readonly job: EmailJobSummary;
|
|
@@ -320,11 +372,16 @@ interface EmailStore {
|
|
|
320
372
|
}>;
|
|
321
373
|
findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
|
|
322
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
|
+
*/
|
|
323
380
|
claimNext(scope: EmailScope, claim: {
|
|
324
381
|
attemptId: EmailAttemptId;
|
|
325
382
|
token: LeaseToken;
|
|
326
383
|
leaseMs: number;
|
|
327
|
-
}, call: StoreCall): Promise<
|
|
384
|
+
}, call: StoreCall): Promise<StoreClaimNext>;
|
|
328
385
|
/** Null on a fenced operation is a definite miss, never a lost ACK. */
|
|
329
386
|
renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
|
|
330
387
|
/** A timely positive ACK of this exact mutation is required to authorize submission. */
|
|
@@ -357,4 +414,4 @@ type MemoryEmailStoreOptions = {
|
|
|
357
414
|
maxJobs?: number;
|
|
358
415
|
};
|
|
359
416
|
|
|
360
|
-
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;
|
|
@@ -61,7 +65,11 @@ type CancelResult = {
|
|
|
61
65
|
} | {
|
|
62
66
|
readonly status: 'not_found';
|
|
63
67
|
};
|
|
64
|
-
/**
|
|
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
|
+
*/
|
|
65
73
|
type ResolveUnknownCommand = {
|
|
66
74
|
jobId: EmailJobId;
|
|
67
75
|
attemptId: EmailAttemptId;
|
|
@@ -76,7 +84,10 @@ type ResolveUnknownResult = {
|
|
|
76
84
|
readonly job: EmailJobSummary;
|
|
77
85
|
};
|
|
78
86
|
|
|
79
|
-
/**
|
|
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
|
+
*/
|
|
80
91
|
type EmailRateLimiter = {
|
|
81
92
|
scope: 'worker' | 'shared';
|
|
82
93
|
tryAcquire(request: {
|
|
@@ -103,27 +114,39 @@ type EmailWorkerLimits = {
|
|
|
103
114
|
type EmailRunOptions = CallOptions & {
|
|
104
115
|
limit?: number;
|
|
105
116
|
concurrency?: number;
|
|
117
|
+
/** Max steps for each of lease recovery and queued expiry before claims. Zero skips both sweeps. */
|
|
106
118
|
maintenanceLimit?: number;
|
|
107
119
|
};
|
|
108
120
|
type EmailRunEntry = {
|
|
109
121
|
readonly operation: 'claim' | 'recover' | 'expire';
|
|
110
122
|
readonly jobId: EmailJobId;
|
|
111
123
|
readonly attemptId?: EmailAttemptId;
|
|
124
|
+
/** `unconfirmed` does not prove rollback or non-submission. Read the current job for a durable `unknown`. */
|
|
112
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
|
+
*/
|
|
113
130
|
readonly reason?: AttemptReason | 'attempts_exhausted';
|
|
131
|
+
/** A recovery reporting `false` says nothing about whether the previous owner called the provider. */
|
|
114
132
|
readonly providerInvoked: boolean;
|
|
115
133
|
};
|
|
116
134
|
type MaintenanceStop = 'limit' | 'idle' | 'contended' | 'aborted' | 'deadline' | 'store_error';
|
|
117
135
|
/** This run's confirmed progress, not an inventory of the whole queue. */
|
|
118
136
|
type EmailRunReport = {
|
|
119
|
-
|
|
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';
|
|
120
143
|
readonly items: readonly EmailRunEntry[];
|
|
121
144
|
readonly counts: {
|
|
122
145
|
readonly claimed: number;
|
|
123
146
|
readonly recovered: number;
|
|
124
147
|
readonly expiredInSweep: number;
|
|
125
148
|
readonly providerCalls: number;
|
|
126
|
-
/** Full plus partial acceptance; sandbox
|
|
149
|
+
/** Full plus partial submission acceptance; not sandbox validation or inbox delivery. */
|
|
127
150
|
readonly submitted: number;
|
|
128
151
|
readonly retryScheduled: number;
|
|
129
152
|
readonly accepted: number;
|
|
@@ -146,18 +169,32 @@ type EmailShutdownReport = {
|
|
|
146
169
|
interface EmailWorker {
|
|
147
170
|
readonly scope: EmailScope;
|
|
148
171
|
readonly smtpCapacity?: SmtpCapacity;
|
|
149
|
-
/**
|
|
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
|
+
*/
|
|
150
176
|
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
151
177
|
/** Stop permanently. `stopped` means no active run or provider I/O, not remote recall. */
|
|
152
178
|
shutdown(options?: Pick<CallOptions, 'timeoutMs'>): Promise<EmailShutdownReport>;
|
|
153
179
|
}
|
|
154
|
-
/**
|
|
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
|
+
*/
|
|
155
186
|
type EmailWorkerOptions = {
|
|
156
187
|
scope: EmailScope;
|
|
157
188
|
/** Must match the store and every profile. Only live SMTP profiles are allowed with this option. */
|
|
158
189
|
smtpCapacity?: SmtpCapacity;
|
|
159
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
|
+
*/
|
|
160
196
|
providers: readonly ConfiguredEmailProvider[];
|
|
197
|
+
/** Supply a resolver for every `resolverKey` used by work in this scope on each competing worker. */
|
|
161
198
|
attachmentResolvers?: Readonly<Record<string, AttachmentResolver>>;
|
|
162
199
|
rateLimiter?: EmailRateLimiter;
|
|
163
200
|
clock?: EmailClock;
|
|
@@ -218,15 +255,21 @@ type CleanupReport = {
|
|
|
218
255
|
};
|
|
219
256
|
interface EmailAdmin {
|
|
220
257
|
readonly scope: EmailScope;
|
|
221
|
-
/** 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. */
|
|
222
259
|
getJob(jobId: EmailJobId, options?: CallOptions): Promise<EmailJobSummary | null>;
|
|
223
260
|
/** Cancel only before irreversible handoff and expiry; no remote recall. */
|
|
224
261
|
cancel(jobId: EmailJobId, options?: CallOptions): Promise<CancelResult>;
|
|
225
|
-
/**
|
|
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
|
+
*/
|
|
226
266
|
resolveUnknown(command: ResolveUnknownCommand, options?: CallOptions): Promise<ResolveUnknownResult>;
|
|
227
|
-
/**
|
|
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
|
+
*/
|
|
228
271
|
listActivities(query?: EmailActivityQuery, options?: CallOptions): Promise<EmailActivityPage>;
|
|
229
|
-
/** Project from the authoritative ledger
|
|
272
|
+
/** Project from the authoritative ledger. Does not recover leases or send mail. */
|
|
230
273
|
reconcile(options?: MaintenanceOptions): Promise<ReconcileReport>;
|
|
231
274
|
/** Prune or retire settled, fully projected jobs after their retention windows. */
|
|
232
275
|
cleanup(options?: MaintenanceOptions): Promise<CleanupReport>;
|
|
@@ -281,6 +324,10 @@ type ClaimedEmail = {
|
|
|
281
324
|
readonly ordinal: number;
|
|
282
325
|
readonly manual: boolean;
|
|
283
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
|
+
};
|
|
284
331
|
type AttemptCommit = {
|
|
285
332
|
readonly jobId: EmailJobId;
|
|
286
333
|
readonly attemptId: EmailAttemptId;
|
|
@@ -303,15 +350,20 @@ type CleanupStep = 'payload_pruned' | 'retirement_started' | 'purged';
|
|
|
303
350
|
/**
|
|
304
351
|
* Scoped atomic lifecycle operations, not generic CRUD. Enforce scope in every row operation and use store
|
|
305
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.
|
|
306
354
|
*/
|
|
307
355
|
interface EmailStore {
|
|
308
356
|
readonly smtpCapacity?: SmtpCapacity;
|
|
357
|
+
/** Call before use. Of the bundled stores, only V1 memory allows skipping readiness for legacy callers. */
|
|
309
358
|
ready(options?: CallOptions): Promise<void>;
|
|
310
359
|
findAdmission(scope: EmailScope, key: EmailAdmissionKey, call: StoreCall): Promise<{
|
|
311
360
|
readonly job: EmailJobSummary;
|
|
312
361
|
readonly fingerprint: string;
|
|
313
362
|
} | null>;
|
|
314
|
-
/**
|
|
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
|
+
*/
|
|
315
367
|
insert(scope: EmailScope, admission: StoreAdmission, call: StoreCall): Promise<{
|
|
316
368
|
readonly status: 'inserted';
|
|
317
369
|
readonly job: EmailJobSummary;
|
|
@@ -320,11 +372,16 @@ interface EmailStore {
|
|
|
320
372
|
}>;
|
|
321
373
|
findJob(scope: EmailScope, jobId: EmailJobId, call: StoreCall): Promise<EmailJobSummary | null>;
|
|
322
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
|
+
*/
|
|
323
380
|
claimNext(scope: EmailScope, claim: {
|
|
324
381
|
attemptId: EmailAttemptId;
|
|
325
382
|
token: LeaseToken;
|
|
326
383
|
leaseMs: number;
|
|
327
|
-
}, call: StoreCall): Promise<
|
|
384
|
+
}, call: StoreCall): Promise<StoreClaimNext>;
|
|
328
385
|
/** Null on a fenced operation is a definite miss, never a lost ACK. */
|
|
329
386
|
renew(scope: EmailScope, fence: OwnerFence, leaseMs: number, call: StoreCall): Promise<LeaseGrant | null>;
|
|
330
387
|
/** A timely positive ACK of this exact mutation is required to authorize submission. */
|
|
@@ -357,4 +414,4 @@ type MemoryEmailStoreOptions = {
|
|
|
357
414
|
maxJobs?: number;
|
|
358
415
|
};
|
|
359
416
|
|
|
360
|
-
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 };
|