@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.
@@ -1,6 +1,10 @@
1
- import { U as UnixMs, j as AttemptReason, a as EmailScope, n as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, m as EmailAttemptId, z as SubmissionOutcome, e as CallOptions, A as Awaitable, l as ConfiguredEmailProvider, i as AttachmentResolver, g as EmailClock, k as AttemptResult, p as EmailSnapshot, f as PreparedEmailCommand } from './provider-HisBc6hk.mjs';
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
- /** Ordinary attempt budget and capped exponential backoff, frozen at admission. */
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
- /** Redrive permits one extra claim on the same snapshot and can duplicate an already accepted message. */
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
- /** A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local. */
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
- readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity';
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 validations do not count. */
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
- /** Do bounded work in this scope. The host schedules runs; only one run per instance may be active. */
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
- /** Dependencies for a bounded worker; provider profile keys must be unique. */
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; limit defaults to 20 and accepts 1–100. */
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 an activity is projected. */
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
- /** Dismiss or requeue an exact unknown attempt. Redrive can duplicate a previously accepted submission. */
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
- /** Read a bounded page of committed activities (default 25, max 100), even if the source ACK is pending. */
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; no send can result from this operation. */
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
- /** `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints. */
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<StoreNext<ClaimedEmail>>;
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
- /** Capacity across all scopes in this instance; default 256, range 1–4096. */
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, StoreNext as B, CancelResult as C, 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 };
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, j as AttemptReason, a as EmailScope, n as EmailJobId, b as EmailAdmissionKey, P as ProviderRef, T as TemplateIdentity, C as Correlation, m as EmailAttemptId, z as SubmissionOutcome, e as CallOptions, A as Awaitable, l as ConfiguredEmailProvider, i as AttachmentResolver, g as EmailClock, k as AttemptResult, p as EmailSnapshot, f as PreparedEmailCommand } from './provider-HisBc6hk.js';
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
- /** Ordinary attempt budget and capped exponential backoff, frozen at admission. */
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
- /** Redrive permits one extra claim on the same snapshot and can duplicate an already accepted message. */
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
- /** A shared limiter must enforce the actual quota across workers/processes; a worker limiter is instance-local. */
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
- readonly stop: MaintenanceStop | 'shutdown' | 'callback_capacity';
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 validations do not count. */
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
- /** Do bounded work in this scope. The host schedules runs; only one run per instance may be active. */
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
- /** Dependencies for a bounded worker; provider profile keys must be unique. */
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; limit defaults to 20 and accepts 1–100. */
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 an activity is projected. */
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
- /** Dismiss or requeue an exact unknown attempt. Redrive can duplicate a previously accepted submission. */
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
- /** Read a bounded page of committed activities (default 25, max 100), even if the source ACK is pending. */
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; no send can result from this operation. */
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
- /** `duplicate` confirms a scoped admission-key collision; read the current winner and compare fingerprints. */
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<StoreNext<ClaimedEmail>>;
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
- /** Capacity across all scopes in this instance; default 256, range 1–4096. */
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, StoreNext as B, CancelResult as C, 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 };
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 };