@web-ts-toolkit/email-service 0.0.0-stage → 0.72.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/LICENSE +201 -0
- package/README.md +446 -2
- package/index.d.mts +206 -0
- package/index.d.ts +206 -0
- package/index.js +4289 -0
- package/index.mjs +4244 -0
- package/mongoose.d.mts +24 -0
- package/mongoose.d.ts +24 -0
- package/mongoose.js +3045 -0
- package/mongoose.mjs +3020 -0
- package/package.json +89 -4
- package/provider-HisBc6hk.d.mts +183 -0
- package/provider-HisBc6hk.d.ts +183 -0
- package/sendgrid.d.mts +18 -0
- package/sendgrid.d.ts +18 -0
- package/sendgrid.js +1437 -0
- package/sendgrid.mjs +1410 -0
- package/smtp.d.mts +28 -0
- package/smtp.d.ts +28 -0
- package/smtp.js +1449 -0
- package/smtp.mjs +1412 -0
- package/store-D4YAI6Rk.d.mts +346 -0
- package/store-Vb63Gocz.d.ts +346 -0
package/index.d.mts
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-HisBc6hk.mjs';
|
|
2
|
+
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint, S as SendGridSnapshot, y as SmtpSnapshot, z as SubmissionOutcome, B as SubmissionStage, T as TemplateIdentity } from './provider-HisBc6hk.mjs';
|
|
3
|
+
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-D4YAI6Rk.mjs';
|
|
4
|
+
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-D4YAI6Rk.mjs';
|
|
5
|
+
|
|
6
|
+
/** Safe, stable diagnostics; no application data or transport-response text. */
|
|
7
|
+
type EmailErrorCode = 'invalid_config' | 'invalid_command' | 'invalid_input' | 'invalid_data' | 'invalid_snapshot' | 'preparation_failed' | 'template_not_found' | 'template_source' | 'template_render' | 'provider_mismatch' | 'expired' | 'idempotency_conflict' | 'not_found' | 'resolution_conflict' | 'store_capacity' | 'store_unavailable' | 'store_incompatible' | 'write_unconfirmed' | 'invalid_cursor' | 'aborted' | 'deadline' | 'busy' | 'closed';
|
|
8
|
+
/** Compare `.code`, not class identity, across separately loaded ESM and CommonJS builds. */
|
|
9
|
+
declare class EmailError extends Error {
|
|
10
|
+
/** `write_unconfirmed` does not mean that a dispatched mutation failed to commit. */
|
|
11
|
+
readonly code: EmailErrorCode;
|
|
12
|
+
constructor(code: EmailErrorCode);
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
type PrepareContext = {
|
|
16
|
+
readonly scope: EmailScope;
|
|
17
|
+
readonly key: EmailAdmissionKey;
|
|
18
|
+
readonly templateKey: string;
|
|
19
|
+
readonly provider: ProviderRef;
|
|
20
|
+
readonly now: UnixMs;
|
|
21
|
+
readonly signal: AbortSignal;
|
|
22
|
+
};
|
|
23
|
+
/** Host-generated fields. Only From and Reply-To can come from template defaults. */
|
|
24
|
+
type PreparedFields<D extends JsonObject> = Partial<EmailEnvelope> & {
|
|
25
|
+
values: D;
|
|
26
|
+
expiresAt?: UnixMs;
|
|
27
|
+
priority?: number;
|
|
28
|
+
attachments?: readonly AttachmentRef[];
|
|
29
|
+
correlation?: Correlation;
|
|
30
|
+
};
|
|
31
|
+
/** Trusted, explicitly configured content. Do not derive file paths from command input. */
|
|
32
|
+
type LocalSource = {
|
|
33
|
+
kind: 'inline';
|
|
34
|
+
content: string;
|
|
35
|
+
} | {
|
|
36
|
+
kind: 'file';
|
|
37
|
+
path: string;
|
|
38
|
+
} | {
|
|
39
|
+
kind: 'async';
|
|
40
|
+
load: (context: {
|
|
41
|
+
signal: AbortSignal;
|
|
42
|
+
}) => Awaitable<string>;
|
|
43
|
+
};
|
|
44
|
+
type TemplateDefinition<I, D extends JsonObject> = {
|
|
45
|
+
revision: string;
|
|
46
|
+
defaults?: Pick<Partial<EmailEnvelope>, 'from' | 'replyTo'>;
|
|
47
|
+
/** Synchronously validate the host's opaque business input. */
|
|
48
|
+
parseInput: (input: unknown) => I;
|
|
49
|
+
/** Synchronously validate or normalize a detached JSON object. Return a new object to change it. */
|
|
50
|
+
parseData: (data: unknown) => D;
|
|
51
|
+
/** May run again after a crash or overlapping admission misses; keep side effects idempotent. */
|
|
52
|
+
prepare: (input: NoInfer<I>, context: PrepareContext) => Awaitable<PreparedFields<NoInfer<D>>>;
|
|
53
|
+
};
|
|
54
|
+
type LocalTemplateConfig = {
|
|
55
|
+
kind: 'handlebars';
|
|
56
|
+
subject: LocalSource;
|
|
57
|
+
} & ({
|
|
58
|
+
html: LocalSource;
|
|
59
|
+
text?: LocalSource;
|
|
60
|
+
} | {
|
|
61
|
+
html?: LocalSource;
|
|
62
|
+
text: LocalSource;
|
|
63
|
+
});
|
|
64
|
+
type SendGridTemplateConfig = {
|
|
65
|
+
kind: 'sendgrid';
|
|
66
|
+
templateId: string;
|
|
67
|
+
};
|
|
68
|
+
type LocalTemplate<I, D extends JsonObject> = TemplateDefinition<I, D> & LocalTemplateConfig;
|
|
69
|
+
type SendGridTemplate<I, D extends JsonObject> = TemplateDefinition<I, D> & SendGridTemplateConfig;
|
|
70
|
+
type TemplateMap = Readonly<Record<string, Omit<TemplateDefinition<never, JsonObject>, 'parseInput'> & {
|
|
71
|
+
parseInput: (input: unknown) => unknown;
|
|
72
|
+
} & (LocalTemplateConfig | SendGridTemplateConfig)>>;
|
|
73
|
+
type TemplateDefinitions<T extends TemplateMap> = T & {
|
|
74
|
+
[K in keyof T]: TemplateDefinition<ReturnType<T[K]['parseInput']>, ReturnType<T[K]['parseData']>>;
|
|
75
|
+
};
|
|
76
|
+
/** The key determines the input and provider kind. `intent` describes stable business meaning, not rendered data. */
|
|
77
|
+
type TemplateCommand<T extends TemplateMap> = {
|
|
78
|
+
[K in keyof T & string]: {
|
|
79
|
+
templateKey: K;
|
|
80
|
+
input: ReturnType<T[K]['parseInput']>;
|
|
81
|
+
provider: Extract<ProviderRef, {
|
|
82
|
+
kind: T[K]['kind'] extends 'handlebars' ? 'smtp' : 'sendgrid';
|
|
83
|
+
}>;
|
|
84
|
+
intent: JsonValue;
|
|
85
|
+
scheduleAt?: UnixMs;
|
|
86
|
+
};
|
|
87
|
+
}[keyof T & string];
|
|
88
|
+
/** A typed command with scoped idempotency. Keep its `key` and `intent` stable when retrying admission. */
|
|
89
|
+
type EmailCommand<T extends TemplateMap> = TemplateCommand<T> & {
|
|
90
|
+
key: EmailAdmissionKey;
|
|
91
|
+
};
|
|
92
|
+
type TemplateRegistryOptions = {
|
|
93
|
+
clock?: EmailClock;
|
|
94
|
+
cacheEntries?: number;
|
|
95
|
+
maxPending?: number;
|
|
96
|
+
/** Trusted synchronous Handlebars helpers registered only in this registry. */
|
|
97
|
+
helpers?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
|
|
98
|
+
};
|
|
99
|
+
interface EmailTemplateRegistry<T extends TemplateMap> {
|
|
100
|
+
/** Prepare a detached snapshot without using a queue or contacting a provider. */
|
|
101
|
+
prepare(scope: EmailScope, command: EmailCommand<T>, options?: CallOptions): Promise<PreparedEmailCommand>;
|
|
102
|
+
/** Evict one or all compilation cache entries and fence their prior in-flight loads. */
|
|
103
|
+
invalidate(templateKey?: keyof T & string): void;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Type a local template. Input and data are inferred from the parsers; the registry validates the configuration. */
|
|
107
|
+
declare function defineLocalTemplate<I, D extends JsonObject>(definition: LocalTemplate<I, D>): LocalTemplate<I, D>;
|
|
108
|
+
/** Type a SendGrid template from its input/data parsers. Does not register or pin a remote template version. */
|
|
109
|
+
declare function defineSendGridTemplate<I, D extends JsonObject>(definition: SendGridTemplate<I, D>): SendGridTemplate<I, D>;
|
|
110
|
+
/** Copy trusted template configuration into an isolated registry. Preparation never contacts a provider or queue. */
|
|
111
|
+
declare function createEmailTemplateRegistry<const T extends TemplateMap>(definitions: TemplateDefinitions<T>, options?: TemplateRegistryOptions): EmailTemplateRegistry<T>;
|
|
112
|
+
|
|
113
|
+
type AdmissionResult = {
|
|
114
|
+
readonly status: 'enqueued' | 'replayed';
|
|
115
|
+
readonly job: EmailJobSummary;
|
|
116
|
+
};
|
|
117
|
+
interface EmailService<T extends TemplateMap> {
|
|
118
|
+
readonly scope: EmailScope;
|
|
119
|
+
/** Admit or replay by scoped stable intent; a committed replay does not prepare again. */
|
|
120
|
+
enqueue(command: EmailCommand<T>, options?: CallOptions): Promise<AdmissionResult>;
|
|
121
|
+
/** Relay the same scoped outbox snapshot unchanged. Does not join a host transaction, rerender, or extend expiry. */
|
|
122
|
+
enqueuePrepared(command: PreparedEmailCommand, options?: CallOptions): Promise<AdmissionResult>;
|
|
123
|
+
}
|
|
124
|
+
type EmailServiceOptions<T extends TemplateMap> = {
|
|
125
|
+
scope: EmailScope;
|
|
126
|
+
store: EmailStore;
|
|
127
|
+
registry: EmailTemplateRegistry<T>;
|
|
128
|
+
retry?: Partial<RetryPolicy>;
|
|
129
|
+
retention?: Partial<RetentionPolicy>;
|
|
130
|
+
};
|
|
131
|
+
type EmailBatchItem<T extends TemplateMap> = {
|
|
132
|
+
itemId: string;
|
|
133
|
+
command: TemplateCommand<T>;
|
|
134
|
+
};
|
|
135
|
+
type EmailBatchResult = {
|
|
136
|
+
readonly batchId: string;
|
|
137
|
+
readonly items: readonly (({
|
|
138
|
+
readonly itemId: string;
|
|
139
|
+
} & AdmissionResult) | {
|
|
140
|
+
readonly itemId: string;
|
|
141
|
+
readonly status: 'failed';
|
|
142
|
+
readonly code: EmailErrorCode;
|
|
143
|
+
} | {
|
|
144
|
+
readonly itemId: string;
|
|
145
|
+
readonly status: 'not_started';
|
|
146
|
+
})[];
|
|
147
|
+
readonly counts: {
|
|
148
|
+
readonly enqueued: number;
|
|
149
|
+
readonly replayed: number;
|
|
150
|
+
readonly failed: number;
|
|
151
|
+
readonly notStarted: number;
|
|
152
|
+
readonly persistenceFailures: number;
|
|
153
|
+
};
|
|
154
|
+
};
|
|
155
|
+
interface EmailBatchService<T extends TemplateMap> {
|
|
156
|
+
/**
|
|
157
|
+
* Validate 1–100 items up front, then admit them in input order under one timeout (default 30 seconds).
|
|
158
|
+
* Replay the same batch/item IDs and intent to resume; earlier writes aren't rolled back on a failure.
|
|
159
|
+
*/
|
|
160
|
+
enqueueBatch(batch: {
|
|
161
|
+
batchId: string;
|
|
162
|
+
items: readonly EmailBatchItem<T>[];
|
|
163
|
+
}, options?: CallOptions): Promise<EmailBatchResult>;
|
|
164
|
+
/** Run the same scope-wide worker, not a second delivery loop or a batch filter. */
|
|
165
|
+
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
166
|
+
}
|
|
167
|
+
type EmailBatchServiceOptions<T extends TemplateMap> = {
|
|
168
|
+
/** Must share the worker's scope and underlying store. */
|
|
169
|
+
service: EmailService<T>;
|
|
170
|
+
worker: EmailWorker;
|
|
171
|
+
};
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Scope-bound admission only. Call `store.ready()` yourself; neither method contacts a mail provider.
|
|
175
|
+
* After `write_unconfirmed`, retry the same scoped key and intent: the original insert may have committed.
|
|
176
|
+
*/
|
|
177
|
+
declare function createEmailService<T extends TemplateMap>(options: EmailServiceOptions<T>): EmailService<T>;
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Create a scope-bound worker for a caller-ready store and exact provider profiles. The host schedules
|
|
181
|
+
* bounded `run` calls; nothing polls on construction. `shutdown` is permanent and never closes the store.
|
|
182
|
+
* A one-shot provider call requires a timely durable handoff acknowledgement, not a later read of a marker.
|
|
183
|
+
*/
|
|
184
|
+
declare function createEmailWorker(options: EmailWorkerOptions): EmailWorker;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Compose a same-scope admission service and worker. Wire both to the same underlying store.
|
|
188
|
+
* Enqueue is sequential and resumable by batch/item ID, not atomic. `run` serves the whole scope.
|
|
189
|
+
*/
|
|
190
|
+
declare function createEmailBatchService<T extends TemplateMap>(options: EmailBatchServiceOptions<T>): EmailBatchService<T>;
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* Inspect and maintain redacted history in one scope on a caller-ready store. The host authorizes requests
|
|
194
|
+
* and schedules maintenance. No admin operation submits mail; explicit redrive only requeues an eligible
|
|
195
|
+
* unknown job for a future worker run and can duplicate a previously accepted submission.
|
|
196
|
+
*/
|
|
197
|
+
declare function createEmailAdmin(options: EmailAdminOptions): EmailAdmin;
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Single-process V1 store for tests and development. State is lost on restart and is not shared across
|
|
201
|
+
* instances or processes. Capacity is global across scopes; it never evicts a protected job or acts as
|
|
202
|
+
* a fallback for another store. Uses the injected clock's wall time for store guards.
|
|
203
|
+
*/
|
|
204
|
+
declare function createMemoryEmailStore(options?: MemoryEmailStoreOptions): EmailStore;
|
|
205
|
+
|
|
206
|
+
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|
package/index.d.ts
ADDED
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
import { J as JsonObject, E as EmailEnvelope, a as EmailScope, b as EmailAdmissionKey, P as ProviderRef, U as UnixMs, A as Awaitable, c as AttachmentRef, C as Correlation, d as JsonValue, e as CallOptions, f as PreparedEmailCommand, g as EmailClock } from './provider-HisBc6hk.js';
|
|
2
|
+
export { h as AttachmentResolution, i as AttachmentResolver, j as AttemptReason, k as AttemptResult, l as ConfiguredEmailProvider, m as EmailAttemptId, n as EmailJobId, o as EmailProvider, p as EmailSnapshot, M as Mailbox, q as PreparedEmailSubmission, r as ProviderCall, s as ProviderReason, t as ProviderResult, u as ProviderSubmission, R as RecipientResult, v as ResolvedAttachment, w as RetryClass, x as RetryHint, S as SendGridSnapshot, y as SmtpSnapshot, z as SubmissionOutcome, B as SubmissionStage, T as TemplateIdentity } from './provider-HisBc6hk.js';
|
|
3
|
+
import { E as EmailJobSummary, a as EmailRunOptions, b as EmailRunReport, c as EmailWorker, d as EmailStore, R as RetryPolicy, e as RetentionPolicy, f as EmailWorkerOptions, g as EmailAdminOptions, h as EmailAdmin, M as MemoryEmailStoreOptions } from './store-Vb63Gocz.js';
|
|
4
|
+
export { A as AttemptCommit, C as CancelResult, i as ClaimedEmail, j as CleanupReport, k as CleanupStep, l as EmailActivity, m as EmailActivityPage, n as EmailActivityQuery, o as EmailJobState, p as EmailRateLimiter, q as EmailRunEntry, r as EmailShutdownReport, s as EmailWorkerLimits, H as HandoffGrant, J as JobDisposition, L as LeaseGrant, t as LeaseToken, u as MaintenanceOptions, v as MaintenanceStop, O as OwnerFence, P as ProjectionPermit, w as ReconcileReport, x as ResolveUnknownCommand, y as ResolveUnknownResult, S as StoreAdmission, z as StoreCall, B as StoreNext, U as UnknownResolution } from './store-Vb63Gocz.js';
|
|
5
|
+
|
|
6
|
+
/** Safe, stable diagnostics; no application data or transport-response text. */
|
|
7
|
+
type EmailErrorCode = 'invalid_config' | 'invalid_command' | 'invalid_input' | 'invalid_data' | 'invalid_snapshot' | 'preparation_failed' | 'template_not_found' | 'template_source' | 'template_render' | 'provider_mismatch' | 'expired' | 'idempotency_conflict' | 'not_found' | 'resolution_conflict' | 'store_capacity' | 'store_unavailable' | 'store_incompatible' | 'write_unconfirmed' | 'invalid_cursor' | 'aborted' | 'deadline' | 'busy' | 'closed';
|
|
8
|
+
/** Compare `.code`, not class identity, across separately loaded ESM and CommonJS builds. */
|
|
9
|
+
declare class EmailError extends Error {
|
|
10
|
+
/** `write_unconfirmed` does not mean that a dispatched mutation failed to commit. */
|
|
11
|
+
readonly code: EmailErrorCode;
|
|
12
|
+
constructor(code: EmailErrorCode);
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
type PrepareContext = {
|
|
16
|
+
readonly scope: EmailScope;
|
|
17
|
+
readonly key: EmailAdmissionKey;
|
|
18
|
+
readonly templateKey: string;
|
|
19
|
+
readonly provider: ProviderRef;
|
|
20
|
+
readonly now: UnixMs;
|
|
21
|
+
readonly signal: AbortSignal;
|
|
22
|
+
};
|
|
23
|
+
/** Host-generated fields. Only From and Reply-To can come from template defaults. */
|
|
24
|
+
type PreparedFields<D extends JsonObject> = Partial<EmailEnvelope> & {
|
|
25
|
+
values: D;
|
|
26
|
+
expiresAt?: UnixMs;
|
|
27
|
+
priority?: number;
|
|
28
|
+
attachments?: readonly AttachmentRef[];
|
|
29
|
+
correlation?: Correlation;
|
|
30
|
+
};
|
|
31
|
+
/** Trusted, explicitly configured content. Do not derive file paths from command input. */
|
|
32
|
+
type LocalSource = {
|
|
33
|
+
kind: 'inline';
|
|
34
|
+
content: string;
|
|
35
|
+
} | {
|
|
36
|
+
kind: 'file';
|
|
37
|
+
path: string;
|
|
38
|
+
} | {
|
|
39
|
+
kind: 'async';
|
|
40
|
+
load: (context: {
|
|
41
|
+
signal: AbortSignal;
|
|
42
|
+
}) => Awaitable<string>;
|
|
43
|
+
};
|
|
44
|
+
type TemplateDefinition<I, D extends JsonObject> = {
|
|
45
|
+
revision: string;
|
|
46
|
+
defaults?: Pick<Partial<EmailEnvelope>, 'from' | 'replyTo'>;
|
|
47
|
+
/** Synchronously validate the host's opaque business input. */
|
|
48
|
+
parseInput: (input: unknown) => I;
|
|
49
|
+
/** Synchronously validate or normalize a detached JSON object. Return a new object to change it. */
|
|
50
|
+
parseData: (data: unknown) => D;
|
|
51
|
+
/** May run again after a crash or overlapping admission misses; keep side effects idempotent. */
|
|
52
|
+
prepare: (input: NoInfer<I>, context: PrepareContext) => Awaitable<PreparedFields<NoInfer<D>>>;
|
|
53
|
+
};
|
|
54
|
+
type LocalTemplateConfig = {
|
|
55
|
+
kind: 'handlebars';
|
|
56
|
+
subject: LocalSource;
|
|
57
|
+
} & ({
|
|
58
|
+
html: LocalSource;
|
|
59
|
+
text?: LocalSource;
|
|
60
|
+
} | {
|
|
61
|
+
html?: LocalSource;
|
|
62
|
+
text: LocalSource;
|
|
63
|
+
});
|
|
64
|
+
type SendGridTemplateConfig = {
|
|
65
|
+
kind: 'sendgrid';
|
|
66
|
+
templateId: string;
|
|
67
|
+
};
|
|
68
|
+
type LocalTemplate<I, D extends JsonObject> = TemplateDefinition<I, D> & LocalTemplateConfig;
|
|
69
|
+
type SendGridTemplate<I, D extends JsonObject> = TemplateDefinition<I, D> & SendGridTemplateConfig;
|
|
70
|
+
type TemplateMap = Readonly<Record<string, Omit<TemplateDefinition<never, JsonObject>, 'parseInput'> & {
|
|
71
|
+
parseInput: (input: unknown) => unknown;
|
|
72
|
+
} & (LocalTemplateConfig | SendGridTemplateConfig)>>;
|
|
73
|
+
type TemplateDefinitions<T extends TemplateMap> = T & {
|
|
74
|
+
[K in keyof T]: TemplateDefinition<ReturnType<T[K]['parseInput']>, ReturnType<T[K]['parseData']>>;
|
|
75
|
+
};
|
|
76
|
+
/** The key determines the input and provider kind. `intent` describes stable business meaning, not rendered data. */
|
|
77
|
+
type TemplateCommand<T extends TemplateMap> = {
|
|
78
|
+
[K in keyof T & string]: {
|
|
79
|
+
templateKey: K;
|
|
80
|
+
input: ReturnType<T[K]['parseInput']>;
|
|
81
|
+
provider: Extract<ProviderRef, {
|
|
82
|
+
kind: T[K]['kind'] extends 'handlebars' ? 'smtp' : 'sendgrid';
|
|
83
|
+
}>;
|
|
84
|
+
intent: JsonValue;
|
|
85
|
+
scheduleAt?: UnixMs;
|
|
86
|
+
};
|
|
87
|
+
}[keyof T & string];
|
|
88
|
+
/** A typed command with scoped idempotency. Keep its `key` and `intent` stable when retrying admission. */
|
|
89
|
+
type EmailCommand<T extends TemplateMap> = TemplateCommand<T> & {
|
|
90
|
+
key: EmailAdmissionKey;
|
|
91
|
+
};
|
|
92
|
+
type TemplateRegistryOptions = {
|
|
93
|
+
clock?: EmailClock;
|
|
94
|
+
cacheEntries?: number;
|
|
95
|
+
maxPending?: number;
|
|
96
|
+
/** Trusted synchronous Handlebars helpers registered only in this registry. */
|
|
97
|
+
helpers?: Readonly<Record<string, (...args: unknown[]) => unknown>>;
|
|
98
|
+
};
|
|
99
|
+
interface EmailTemplateRegistry<T extends TemplateMap> {
|
|
100
|
+
/** Prepare a detached snapshot without using a queue or contacting a provider. */
|
|
101
|
+
prepare(scope: EmailScope, command: EmailCommand<T>, options?: CallOptions): Promise<PreparedEmailCommand>;
|
|
102
|
+
/** Evict one or all compilation cache entries and fence their prior in-flight loads. */
|
|
103
|
+
invalidate(templateKey?: keyof T & string): void;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** Type a local template. Input and data are inferred from the parsers; the registry validates the configuration. */
|
|
107
|
+
declare function defineLocalTemplate<I, D extends JsonObject>(definition: LocalTemplate<I, D>): LocalTemplate<I, D>;
|
|
108
|
+
/** Type a SendGrid template from its input/data parsers. Does not register or pin a remote template version. */
|
|
109
|
+
declare function defineSendGridTemplate<I, D extends JsonObject>(definition: SendGridTemplate<I, D>): SendGridTemplate<I, D>;
|
|
110
|
+
/** Copy trusted template configuration into an isolated registry. Preparation never contacts a provider or queue. */
|
|
111
|
+
declare function createEmailTemplateRegistry<const T extends TemplateMap>(definitions: TemplateDefinitions<T>, options?: TemplateRegistryOptions): EmailTemplateRegistry<T>;
|
|
112
|
+
|
|
113
|
+
type AdmissionResult = {
|
|
114
|
+
readonly status: 'enqueued' | 'replayed';
|
|
115
|
+
readonly job: EmailJobSummary;
|
|
116
|
+
};
|
|
117
|
+
interface EmailService<T extends TemplateMap> {
|
|
118
|
+
readonly scope: EmailScope;
|
|
119
|
+
/** Admit or replay by scoped stable intent; a committed replay does not prepare again. */
|
|
120
|
+
enqueue(command: EmailCommand<T>, options?: CallOptions): Promise<AdmissionResult>;
|
|
121
|
+
/** Relay the same scoped outbox snapshot unchanged. Does not join a host transaction, rerender, or extend expiry. */
|
|
122
|
+
enqueuePrepared(command: PreparedEmailCommand, options?: CallOptions): Promise<AdmissionResult>;
|
|
123
|
+
}
|
|
124
|
+
type EmailServiceOptions<T extends TemplateMap> = {
|
|
125
|
+
scope: EmailScope;
|
|
126
|
+
store: EmailStore;
|
|
127
|
+
registry: EmailTemplateRegistry<T>;
|
|
128
|
+
retry?: Partial<RetryPolicy>;
|
|
129
|
+
retention?: Partial<RetentionPolicy>;
|
|
130
|
+
};
|
|
131
|
+
type EmailBatchItem<T extends TemplateMap> = {
|
|
132
|
+
itemId: string;
|
|
133
|
+
command: TemplateCommand<T>;
|
|
134
|
+
};
|
|
135
|
+
type EmailBatchResult = {
|
|
136
|
+
readonly batchId: string;
|
|
137
|
+
readonly items: readonly (({
|
|
138
|
+
readonly itemId: string;
|
|
139
|
+
} & AdmissionResult) | {
|
|
140
|
+
readonly itemId: string;
|
|
141
|
+
readonly status: 'failed';
|
|
142
|
+
readonly code: EmailErrorCode;
|
|
143
|
+
} | {
|
|
144
|
+
readonly itemId: string;
|
|
145
|
+
readonly status: 'not_started';
|
|
146
|
+
})[];
|
|
147
|
+
readonly counts: {
|
|
148
|
+
readonly enqueued: number;
|
|
149
|
+
readonly replayed: number;
|
|
150
|
+
readonly failed: number;
|
|
151
|
+
readonly notStarted: number;
|
|
152
|
+
readonly persistenceFailures: number;
|
|
153
|
+
};
|
|
154
|
+
};
|
|
155
|
+
interface EmailBatchService<T extends TemplateMap> {
|
|
156
|
+
/**
|
|
157
|
+
* Validate 1–100 items up front, then admit them in input order under one timeout (default 30 seconds).
|
|
158
|
+
* Replay the same batch/item IDs and intent to resume; earlier writes aren't rolled back on a failure.
|
|
159
|
+
*/
|
|
160
|
+
enqueueBatch(batch: {
|
|
161
|
+
batchId: string;
|
|
162
|
+
items: readonly EmailBatchItem<T>[];
|
|
163
|
+
}, options?: CallOptions): Promise<EmailBatchResult>;
|
|
164
|
+
/** Run the same scope-wide worker, not a second delivery loop or a batch filter. */
|
|
165
|
+
run(options?: EmailRunOptions): Promise<EmailRunReport>;
|
|
166
|
+
}
|
|
167
|
+
type EmailBatchServiceOptions<T extends TemplateMap> = {
|
|
168
|
+
/** Must share the worker's scope and underlying store. */
|
|
169
|
+
service: EmailService<T>;
|
|
170
|
+
worker: EmailWorker;
|
|
171
|
+
};
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Scope-bound admission only. Call `store.ready()` yourself; neither method contacts a mail provider.
|
|
175
|
+
* After `write_unconfirmed`, retry the same scoped key and intent: the original insert may have committed.
|
|
176
|
+
*/
|
|
177
|
+
declare function createEmailService<T extends TemplateMap>(options: EmailServiceOptions<T>): EmailService<T>;
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Create a scope-bound worker for a caller-ready store and exact provider profiles. The host schedules
|
|
181
|
+
* bounded `run` calls; nothing polls on construction. `shutdown` is permanent and never closes the store.
|
|
182
|
+
* A one-shot provider call requires a timely durable handoff acknowledgement, not a later read of a marker.
|
|
183
|
+
*/
|
|
184
|
+
declare function createEmailWorker(options: EmailWorkerOptions): EmailWorker;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Compose a same-scope admission service and worker. Wire both to the same underlying store.
|
|
188
|
+
* Enqueue is sequential and resumable by batch/item ID, not atomic. `run` serves the whole scope.
|
|
189
|
+
*/
|
|
190
|
+
declare function createEmailBatchService<T extends TemplateMap>(options: EmailBatchServiceOptions<T>): EmailBatchService<T>;
|
|
191
|
+
|
|
192
|
+
/**
|
|
193
|
+
* Inspect and maintain redacted history in one scope on a caller-ready store. The host authorizes requests
|
|
194
|
+
* and schedules maintenance. No admin operation submits mail; explicit redrive only requeues an eligible
|
|
195
|
+
* unknown job for a future worker run and can duplicate a previously accepted submission.
|
|
196
|
+
*/
|
|
197
|
+
declare function createEmailAdmin(options: EmailAdminOptions): EmailAdmin;
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Single-process V1 store for tests and development. State is lost on restart and is not shared across
|
|
201
|
+
* instances or processes. Capacity is global across scopes; it never evicts a protected job or acts as
|
|
202
|
+
* a fallback for another store. Uses the injected clock's wall time for store guards.
|
|
203
|
+
*/
|
|
204
|
+
declare function createMemoryEmailStore(options?: MemoryEmailStoreOptions): EmailStore;
|
|
205
|
+
|
|
206
|
+
export { type AdmissionResult, AttachmentRef, Awaitable, CallOptions, Correlation, EmailAdmin, EmailAdminOptions, EmailAdmissionKey, type EmailBatchItem, type EmailBatchResult, type EmailBatchService, type EmailBatchServiceOptions, EmailClock, type EmailCommand, EmailEnvelope, EmailError, type EmailErrorCode, EmailJobSummary, EmailRunOptions, EmailRunReport, EmailScope, type EmailService, type EmailServiceOptions, EmailStore, type EmailTemplateRegistry, EmailWorker, EmailWorkerOptions, JsonObject, JsonValue, type LocalSource, type LocalTemplate, type LocalTemplateConfig, MemoryEmailStoreOptions, type PrepareContext, PreparedEmailCommand, type PreparedFields, ProviderRef, RetentionPolicy, RetryPolicy, type SendGridTemplate, type SendGridTemplateConfig, type TemplateCommand, type TemplateDefinition, type TemplateDefinitions, type TemplateMap, type TemplateRegistryOptions, UnixMs, createEmailAdmin, createEmailBatchService, createEmailService, createEmailTemplateRegistry, createEmailWorker, createMemoryEmailStore, defineLocalTemplate, defineSendGridTemplate };
|