@bernierllc/email-manager 0.1.1
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 +5 -0
- package/README.md +534 -0
- package/dist/email-manager.d.ts +134 -0
- package/dist/email-manager.d.ts.map +1 -0
- package/dist/email-manager.js +360 -0
- package/dist/email-manager.js.map +1 -0
- package/dist/index.d.ts +7 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -0
- package/dist/managers/email-analytics.d.ts +92 -0
- package/dist/managers/email-analytics.d.ts.map +1 -0
- package/dist/managers/email-analytics.js +375 -0
- package/dist/managers/email-analytics.js.map +1 -0
- package/dist/managers/email-scheduler.d.ts +81 -0
- package/dist/managers/email-scheduler.d.ts.map +1 -0
- package/dist/managers/email-scheduler.js +288 -0
- package/dist/managers/email-scheduler.js.map +1 -0
- package/dist/managers/provider-manager.d.ts +104 -0
- package/dist/managers/provider-manager.d.ts.map +1 -0
- package/dist/managers/provider-manager.js +436 -0
- package/dist/managers/provider-manager.js.map +1 -0
- package/dist/managers/template-manager.d.ts +65 -0
- package/dist/managers/template-manager.d.ts.map +1 -0
- package/dist/managers/template-manager.js +314 -0
- package/dist/managers/template-manager.js.map +1 -0
- package/dist/types.d.ts +507 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +60 -0
- package/dist/types.js.map +1 -0
- package/dist/utils/simple-template-engine.d.ts +27 -0
- package/dist/utils/simple-template-engine.d.ts.map +1 -0
- package/dist/utils/simple-template-engine.js +61 -0
- package/dist/utils/simple-template-engine.js.map +1 -0
- package/package.json +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
Copyright (c) 2025 Bernier LLC
|
|
2
|
+
|
|
3
|
+
This file is licensed to the client under a limited-use license.
|
|
4
|
+
The client may use and modify this code *only within the scope of the project it was delivered for*.
|
|
5
|
+
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
|
package/README.md
ADDED
|
@@ -0,0 +1,534 @@
|
|
|
1
|
+
# @bernierllc/email-manager
|
|
2
|
+
|
|
3
|
+
A comprehensive email management service that orchestrates email sending, template management, scheduling, and analytics. This service integrates with `@bernierllc/email-sender`, `@bernierllc/template-engine`, and `@bernierllc/magic-link` to provide a complete email solution.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
### 🚀 **Email Orchestration**
|
|
8
|
+
- **Multi-provider support** with automatic failover
|
|
9
|
+
- **Template-based emails** with dynamic content rendering
|
|
10
|
+
- **Email scheduling** with retry logic
|
|
11
|
+
- **Batch email processing** for bulk operations
|
|
12
|
+
|
|
13
|
+
### 📝 **Template Management**
|
|
14
|
+
- **CRUD operations** for email templates
|
|
15
|
+
- **Template versioning** and lifecycle management
|
|
16
|
+
- **Variable validation** and syntax checking
|
|
17
|
+
- **Category-based organization**
|
|
18
|
+
|
|
19
|
+
### 🔧 **Provider Management**
|
|
20
|
+
- **Multi-provider configuration** (SendGrid, Mailgun, AWS SES, SMTP, Postmark)
|
|
21
|
+
- **Provider health monitoring** and status tracking
|
|
22
|
+
- **Rate limiting** and usage tracking
|
|
23
|
+
- **Automatic failover** between providers
|
|
24
|
+
|
|
25
|
+
### 📊 **Analytics & Reporting**
|
|
26
|
+
- **Email performance tracking** (opens, clicks, bounces)
|
|
27
|
+
- **Delivery reports** and bounce analysis
|
|
28
|
+
- **Provider performance metrics**
|
|
29
|
+
- **Historical data** and trend analysis
|
|
30
|
+
|
|
31
|
+
### ⏰ **Scheduling System**
|
|
32
|
+
- **Queue-based scheduling** with precise timing
|
|
33
|
+
- **Retry logic** for failed deliveries
|
|
34
|
+
- **Schedule management** (cancel, modify)
|
|
35
|
+
- **Background processing** with automatic cleanup
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @bernierllc/email-manager
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Dependencies
|
|
44
|
+
|
|
45
|
+
This package requires the following BernierLLC core packages:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install @bernierllc/email-sender @bernierllc/template-engine @bernierllc/magic-link
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
```typescript
|
|
54
|
+
import { EmailManager, EmailManagerConfig } from '@bernierllc/email-manager';
|
|
55
|
+
|
|
56
|
+
// Configure providers
|
|
57
|
+
const config: EmailManagerConfig = {
|
|
58
|
+
providers: [
|
|
59
|
+
{
|
|
60
|
+
id: 'sendgrid',
|
|
61
|
+
name: 'SendGrid',
|
|
62
|
+
type: 'sendgrid',
|
|
63
|
+
config: { apiKey: process.env.SENDGRID_API_KEY },
|
|
64
|
+
isActive: true,
|
|
65
|
+
priority: 1
|
|
66
|
+
}
|
|
67
|
+
],
|
|
68
|
+
analytics: { enabled: true },
|
|
69
|
+
scheduling: { enabled: true }
|
|
70
|
+
};
|
|
71
|
+
|
|
72
|
+
// Initialize manager
|
|
73
|
+
const emailManager = new EmailManager(config);
|
|
74
|
+
|
|
75
|
+
// Send email
|
|
76
|
+
const result = await emailManager.sendEmail({
|
|
77
|
+
to: 'user@example.com',
|
|
78
|
+
subject: 'Hello World',
|
|
79
|
+
html: '<h1>Hello!</h1><p>This is a test email.</p>',
|
|
80
|
+
text: 'Hello! This is a test email.'
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
console.log('Email sent:', result.success);
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Core API
|
|
87
|
+
|
|
88
|
+
### Email Operations
|
|
89
|
+
|
|
90
|
+
#### Send Email
|
|
91
|
+
```typescript
|
|
92
|
+
const result = await emailManager.sendEmail({
|
|
93
|
+
to: ['user1@example.com', 'user2@example.com'],
|
|
94
|
+
cc: ['manager@example.com'],
|
|
95
|
+
subject: 'Important Update',
|
|
96
|
+
html: '<h1>Update</h1><p>Important information...</p>',
|
|
97
|
+
text: 'Update: Important information...',
|
|
98
|
+
priority: 'high',
|
|
99
|
+
metadata: { campaign: 'newsletter' }
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
#### Send Templated Email
|
|
104
|
+
```typescript
|
|
105
|
+
const result = await emailManager.sendTemplatedEmail(
|
|
106
|
+
'welcome-email',
|
|
107
|
+
{
|
|
108
|
+
user: { name: 'John Doe' },
|
|
109
|
+
company: 'MyApp',
|
|
110
|
+
confirmUrl: 'https://myapp.com/confirm?token=abc123'
|
|
111
|
+
},
|
|
112
|
+
['newuser@example.com']
|
|
113
|
+
);
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
#### Schedule Email
|
|
117
|
+
```typescript
|
|
118
|
+
const scheduleTime = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
|
|
119
|
+
const result = await emailManager.scheduleEmail({
|
|
120
|
+
to: 'user@example.com',
|
|
121
|
+
subject: 'Reminder',
|
|
122
|
+
html: '<p>This is your scheduled reminder</p>'
|
|
123
|
+
}, scheduleTime);
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Template Management
|
|
127
|
+
|
|
128
|
+
#### Create Template
|
|
129
|
+
```typescript
|
|
130
|
+
const template = await emailManager.createTemplate({
|
|
131
|
+
id: 'welcome-email',
|
|
132
|
+
name: 'Welcome Email',
|
|
133
|
+
subject: 'Welcome {{ user.name }}!',
|
|
134
|
+
htmlTemplate: '<h1>Welcome {{ user.name }}!</h1><p>Thanks for joining {{ company }}!</p>',
|
|
135
|
+
textTemplate: 'Welcome {{ user.name }}! Thanks for joining {{ company }}!',
|
|
136
|
+
variables: [
|
|
137
|
+
{ name: 'user.name', type: 'string', required: true },
|
|
138
|
+
{ name: 'company', type: 'string', required: true }
|
|
139
|
+
],
|
|
140
|
+
category: 'onboarding',
|
|
141
|
+
version: '1.0.0',
|
|
142
|
+
isActive: true
|
|
143
|
+
});
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
#### List Templates
|
|
147
|
+
```typescript
|
|
148
|
+
const templates = await emailManager.listTemplates({
|
|
149
|
+
page: 1,
|
|
150
|
+
pageSize: 20,
|
|
151
|
+
category: 'onboarding',
|
|
152
|
+
active: true,
|
|
153
|
+
search: 'welcome'
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
#### Update Template
|
|
158
|
+
```typescript
|
|
159
|
+
const result = await emailManager.updateTemplate('welcome-email', {
|
|
160
|
+
subject: 'Welcome to our platform, {{ user.name }}!',
|
|
161
|
+
isActive: false
|
|
162
|
+
});
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Provider Management
|
|
166
|
+
|
|
167
|
+
#### Add Provider
|
|
168
|
+
```typescript
|
|
169
|
+
const result = await emailManager.addProvider({
|
|
170
|
+
id: 'mailgun-backup',
|
|
171
|
+
name: 'Mailgun Backup',
|
|
172
|
+
type: 'mailgun',
|
|
173
|
+
config: {
|
|
174
|
+
apiKey: process.env.MAILGUN_API_KEY,
|
|
175
|
+
domain: process.env.MAILGUN_DOMAIN
|
|
176
|
+
},
|
|
177
|
+
isActive: true,
|
|
178
|
+
priority: 2,
|
|
179
|
+
rateLimit: {
|
|
180
|
+
maxPerMinute: 60,
|
|
181
|
+
maxPerHour: 1000,
|
|
182
|
+
maxPerDay: 10000
|
|
183
|
+
}
|
|
184
|
+
});
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
#### Get Provider Status
|
|
188
|
+
```typescript
|
|
189
|
+
const status = await emailManager.getProviderStatus('sendgrid');
|
|
190
|
+
console.log('Provider health:', status.isHealthy);
|
|
191
|
+
console.log('Current usage:', status.currentUsage);
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
#### Test Provider Connection
|
|
195
|
+
```typescript
|
|
196
|
+
const testResult = await emailManager.testConnection('sendgrid');
|
|
197
|
+
console.log('Connection test:', testResult.success, testResult.message);
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Analytics & Reporting
|
|
201
|
+
|
|
202
|
+
#### Get Email Statistics
|
|
203
|
+
```typescript
|
|
204
|
+
const stats = await emailManager.getEmailStats('email-message-id');
|
|
205
|
+
console.log('Delivery rate:', stats.deliveryRate);
|
|
206
|
+
console.log('Open rate:', stats.openRate);
|
|
207
|
+
console.log('Click rate:', stats.clickRate);
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
#### Get Delivery Report
|
|
211
|
+
```typescript
|
|
212
|
+
const report = await emailManager.getDeliveryReport({
|
|
213
|
+
startDate: new Date('2024-01-01'),
|
|
214
|
+
endDate: new Date('2024-01-31'),
|
|
215
|
+
provider: 'sendgrid'
|
|
216
|
+
});
|
|
217
|
+
console.log('Total sent:', report.totalSent);
|
|
218
|
+
console.log('Delivery rate:', report.deliveryRate);
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
#### Get Analytics Summary
|
|
222
|
+
```typescript
|
|
223
|
+
const summary = await emailManager.getAnalyticsSummary(30); // Last 30 days
|
|
224
|
+
console.log('Overview:', summary.overview);
|
|
225
|
+
console.log('Top providers:', summary.topProviders);
|
|
226
|
+
console.log('Daily stats:', summary.dailyStats);
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Scheduling Management
|
|
230
|
+
|
|
231
|
+
#### Cancel Scheduled Email
|
|
232
|
+
```typescript
|
|
233
|
+
const result = await emailManager.cancelScheduledEmail('schedule-id');
|
|
234
|
+
console.log('Cancelled:', result.success);
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Configuration
|
|
238
|
+
|
|
239
|
+
### EmailManagerConfig
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
interface EmailManagerConfig {
|
|
243
|
+
providers: EmailProvider[]; // Email provider configurations
|
|
244
|
+
templates?: EmailTemplate[]; // Pre-loaded templates
|
|
245
|
+
scheduling?: SchedulingConfig; // Scheduler settings
|
|
246
|
+
analytics?: AnalyticsConfig; // Analytics settings
|
|
247
|
+
retry?: RetryConfig; // Retry policy settings
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Provider Configuration
|
|
252
|
+
|
|
253
|
+
```typescript
|
|
254
|
+
interface EmailProvider {
|
|
255
|
+
id: string; // Unique provider ID
|
|
256
|
+
name: string; // Display name
|
|
257
|
+
type: 'sendgrid' | 'mailgun' | 'ses' | 'smtp' | 'postmark';
|
|
258
|
+
config: ProviderConfig; // Provider-specific config
|
|
259
|
+
isActive: boolean; // Enable/disable provider
|
|
260
|
+
priority: number; // Provider priority (lower = higher priority)
|
|
261
|
+
rateLimit?: RateLimit; // Rate limiting settings
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Template Configuration
|
|
266
|
+
|
|
267
|
+
```typescript
|
|
268
|
+
interface EmailTemplate {
|
|
269
|
+
id: string; // Unique template ID
|
|
270
|
+
name: string; // Display name
|
|
271
|
+
subject: string; // Email subject (supports variables)
|
|
272
|
+
htmlTemplate: string; // HTML template content
|
|
273
|
+
textTemplate?: string; // Plain text template content
|
|
274
|
+
variables: TemplateVariable[]; // Template variables
|
|
275
|
+
category?: string; // Template category
|
|
276
|
+
version: string; // Template version
|
|
277
|
+
isActive: boolean; // Enable/disable template
|
|
278
|
+
}
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
## Provider Types
|
|
282
|
+
|
|
283
|
+
### SendGrid
|
|
284
|
+
```typescript
|
|
285
|
+
{
|
|
286
|
+
type: 'sendgrid',
|
|
287
|
+
config: {
|
|
288
|
+
apiKey: 'your-sendgrid-api-key'
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Mailgun
|
|
294
|
+
```typescript
|
|
295
|
+
{
|
|
296
|
+
type: 'mailgun',
|
|
297
|
+
config: {
|
|
298
|
+
apiKey: 'your-mailgun-api-key',
|
|
299
|
+
domain: 'your-domain.mailgun.org'
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
### AWS SES
|
|
305
|
+
```typescript
|
|
306
|
+
{
|
|
307
|
+
type: 'ses',
|
|
308
|
+
config: {
|
|
309
|
+
accessKeyId: 'your-access-key',
|
|
310
|
+
secretAccessKey: 'your-secret-key',
|
|
311
|
+
region: 'us-east-1'
|
|
312
|
+
}
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### SMTP
|
|
317
|
+
```typescript
|
|
318
|
+
{
|
|
319
|
+
type: 'smtp',
|
|
320
|
+
config: {
|
|
321
|
+
host: 'smtp.gmail.com',
|
|
322
|
+
port: 587,
|
|
323
|
+
secure: false,
|
|
324
|
+
auth: {
|
|
325
|
+
user: 'your-email@gmail.com',
|
|
326
|
+
pass: 'your-password'
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
### Postmark
|
|
333
|
+
```typescript
|
|
334
|
+
{
|
|
335
|
+
type: 'postmark',
|
|
336
|
+
config: {
|
|
337
|
+
serverToken: 'your-postmark-server-token'
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
## Template Variables
|
|
343
|
+
|
|
344
|
+
Templates support dynamic content through variables:
|
|
345
|
+
|
|
346
|
+
```html
|
|
347
|
+
<!-- HTML Template -->
|
|
348
|
+
<h1>Welcome {{ user.name }}!</h1>
|
|
349
|
+
<p>Your account with {{ company }} is ready.</p>
|
|
350
|
+
<a href="{{ confirmUrl }}">Confirm Email</a>
|
|
351
|
+
|
|
352
|
+
<!-- Text Template -->
|
|
353
|
+
Welcome {{ user.name }}!
|
|
354
|
+
Your account with {{ company }} is ready.
|
|
355
|
+
Confirm your email: {{ confirmUrl }}
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
Variables are defined in the template configuration:
|
|
359
|
+
|
|
360
|
+
```typescript
|
|
361
|
+
variables: [
|
|
362
|
+
{ name: 'user.name', type: 'string', required: true },
|
|
363
|
+
{ name: 'company', type: 'string', required: true },
|
|
364
|
+
{ name: 'confirmUrl', type: 'string', required: true }
|
|
365
|
+
]
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
## Error Handling
|
|
369
|
+
|
|
370
|
+
The email manager provides comprehensive error handling:
|
|
371
|
+
|
|
372
|
+
```typescript
|
|
373
|
+
const result = await emailManager.sendEmail(emailData);
|
|
374
|
+
|
|
375
|
+
if (!result.success) {
|
|
376
|
+
console.error('Failed to send email:');
|
|
377
|
+
result.errors?.forEach(error => {
|
|
378
|
+
console.error(`${error.code}: ${error.message}`);
|
|
379
|
+
if (error.recipient) {
|
|
380
|
+
console.error(`Recipient: ${error.recipient}`);
|
|
381
|
+
}
|
|
382
|
+
});
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
## Event Tracking
|
|
387
|
+
|
|
388
|
+
Track email events for analytics:
|
|
389
|
+
|
|
390
|
+
```typescript
|
|
391
|
+
// Track email opened (typically from email tracking pixel)
|
|
392
|
+
emailManager.trackEmailEvent('opened', 'email-id', 'recipient@example.com');
|
|
393
|
+
|
|
394
|
+
// Track email clicked (typically from link tracking)
|
|
395
|
+
emailManager.trackEmailEvent('clicked', 'email-id', 'recipient@example.com', {
|
|
396
|
+
url: 'https://example.com/clicked-link'
|
|
397
|
+
});
|
|
398
|
+
|
|
399
|
+
// Track email bounced (typically from webhook)
|
|
400
|
+
emailManager.trackEmailEvent('bounced', 'email-id', 'recipient@example.com', {
|
|
401
|
+
reason: 'Invalid email address'
|
|
402
|
+
});
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
## Webhook Integration
|
|
406
|
+
|
|
407
|
+
Set up webhooks with your email providers to track events:
|
|
408
|
+
|
|
409
|
+
```typescript
|
|
410
|
+
// Express.js webhook endpoint example
|
|
411
|
+
app.post('/webhook/sendgrid', (req, res) => {
|
|
412
|
+
const events = req.body;
|
|
413
|
+
|
|
414
|
+
events.forEach(event => {
|
|
415
|
+
const { event: eventType, email, sg_message_id } = event;
|
|
416
|
+
|
|
417
|
+
switch (eventType) {
|
|
418
|
+
case 'delivered':
|
|
419
|
+
emailManager.trackEmailEvent('delivered', sg_message_id, email);
|
|
420
|
+
break;
|
|
421
|
+
case 'open':
|
|
422
|
+
emailManager.trackEmailEvent('opened', sg_message_id, email);
|
|
423
|
+
break;
|
|
424
|
+
case 'click':
|
|
425
|
+
emailManager.trackEmailEvent('clicked', sg_message_id, email, { url: event.url });
|
|
426
|
+
break;
|
|
427
|
+
case 'bounce':
|
|
428
|
+
emailManager.trackEmailEvent('bounced', sg_message_id, email, { reason: event.reason });
|
|
429
|
+
break;
|
|
430
|
+
}
|
|
431
|
+
});
|
|
432
|
+
|
|
433
|
+
res.status(200).send('OK');
|
|
434
|
+
});
|
|
435
|
+
```
|
|
436
|
+
|
|
437
|
+
## Magic Link Integration
|
|
438
|
+
|
|
439
|
+
Generate secure authentication links:
|
|
440
|
+
|
|
441
|
+
```typescript
|
|
442
|
+
// Generate magic link
|
|
443
|
+
const magicLink = await emailManager.generateMagicLink(
|
|
444
|
+
'user@example.com',
|
|
445
|
+
'login',
|
|
446
|
+
{ userId: '123', redirectUrl: '/dashboard' }
|
|
447
|
+
);
|
|
448
|
+
|
|
449
|
+
// Send magic link email
|
|
450
|
+
await emailManager.sendTemplatedEmail('magic-link-email', {
|
|
451
|
+
magicLink: magicLink.url,
|
|
452
|
+
user: { email: 'user@example.com' }
|
|
453
|
+
}, ['user@example.com']);
|
|
454
|
+
|
|
455
|
+
// Verify magic link (in your authentication endpoint)
|
|
456
|
+
const verification = await emailManager.verifyMagicLink(token);
|
|
457
|
+
if (verification.valid) {
|
|
458
|
+
// Log user in
|
|
459
|
+
console.log('User authenticated:', verification.payload);
|
|
460
|
+
}
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
## Performance Optimization
|
|
464
|
+
|
|
465
|
+
### Template Caching
|
|
466
|
+
Templates are cached after compilation for better performance.
|
|
467
|
+
|
|
468
|
+
### Provider Pooling
|
|
469
|
+
Email providers reuse connections where possible.
|
|
470
|
+
|
|
471
|
+
### Batch Processing
|
|
472
|
+
Process multiple emails efficiently:
|
|
473
|
+
|
|
474
|
+
```typescript
|
|
475
|
+
const emails = [
|
|
476
|
+
{ to: 'user1@example.com', subject: 'Email 1', html: '<p>Content 1</p>' },
|
|
477
|
+
{ to: 'user2@example.com', subject: 'Email 2', html: '<p>Content 2</p>' },
|
|
478
|
+
// ... more emails
|
|
479
|
+
];
|
|
480
|
+
|
|
481
|
+
const results = await Promise.all(
|
|
482
|
+
emails.map(email => emailManager.sendEmail(email))
|
|
483
|
+
);
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
### Rate Limiting
|
|
487
|
+
Configure rate limits per provider to respect API limits:
|
|
488
|
+
|
|
489
|
+
```typescript
|
|
490
|
+
{
|
|
491
|
+
rateLimit: {
|
|
492
|
+
maxPerMinute: 100,
|
|
493
|
+
maxPerHour: 1000,
|
|
494
|
+
maxPerDay: 10000
|
|
495
|
+
}
|
|
496
|
+
}
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
## System Status
|
|
500
|
+
|
|
501
|
+
Get comprehensive system statistics:
|
|
502
|
+
|
|
503
|
+
```typescript
|
|
504
|
+
const stats = emailManager.getSystemStats();
|
|
505
|
+
|
|
506
|
+
console.log('Templates:', stats.templates);
|
|
507
|
+
// { total: 5, active: 4, inactive: 1, byCategory: { onboarding: 2, marketing: 3 } }
|
|
508
|
+
|
|
509
|
+
console.log('Providers:', stats.providers);
|
|
510
|
+
// { total: 2, active: 2, inactive: 0, byType: { sendgrid: 1, mailgun: 1 } }
|
|
511
|
+
|
|
512
|
+
console.log('Scheduler:', stats.scheduler);
|
|
513
|
+
// { isRunning: true, totalInQueue: 3, scheduled: 3, overdue: 0 }
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
## Shutdown
|
|
517
|
+
|
|
518
|
+
Always properly shutdown the email manager:
|
|
519
|
+
|
|
520
|
+
```typescript
|
|
521
|
+
emailManager.shutdown();
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
This stops the scheduler and cleans up resources.
|
|
525
|
+
|
|
526
|
+
## License
|
|
527
|
+
|
|
528
|
+
Copyright (c) 2025 Bernier LLC. All rights reserved.
|
|
529
|
+
|
|
530
|
+
## See Also
|
|
531
|
+
|
|
532
|
+
- [@bernierllc/email-sender](../email-sender) - Core email sending functionality
|
|
533
|
+
- [@bernierllc/template-engine](../template-engine) - Template rendering engine
|
|
534
|
+
- [@bernierllc/magic-link](../magic-link) - Secure token generation
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
import { EmailManagerConfig, EmailData, EmailTemplate, EmailProvider, SendResult, ScheduleResult, TemplateResult, RenderedTemplate, TemplateContext, DeleteResult, TemplateList, ProviderList, ListOptions, EmailStats, DeliveryReport, BounceReport, ReportOptions, ProviderStatus, TestResult, CancelResult } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* EmailManager - Main orchestration service for email operations
|
|
4
|
+
*
|
|
5
|
+
* This service orchestrates email-sender, template-engine, and magic-link packages
|
|
6
|
+
* to provide comprehensive email management with templates, scheduling, and analytics.
|
|
7
|
+
*/
|
|
8
|
+
export declare class EmailManager {
|
|
9
|
+
private templateManager;
|
|
10
|
+
private providerManager;
|
|
11
|
+
private scheduler;
|
|
12
|
+
private analytics;
|
|
13
|
+
private emailSender;
|
|
14
|
+
private templateEngine;
|
|
15
|
+
private config;
|
|
16
|
+
constructor(config: EmailManagerConfig);
|
|
17
|
+
/**
|
|
18
|
+
* Send an email immediately
|
|
19
|
+
*/
|
|
20
|
+
sendEmail(email: EmailData): Promise<SendResult>;
|
|
21
|
+
/**
|
|
22
|
+
* Send a templated email
|
|
23
|
+
*/
|
|
24
|
+
sendTemplatedEmail(templateId: string, context: TemplateContext, recipients: string[]): Promise<SendResult>;
|
|
25
|
+
/**
|
|
26
|
+
* Schedule an email for future delivery
|
|
27
|
+
*/
|
|
28
|
+
scheduleEmail(email: EmailData, scheduleTime: Date): Promise<ScheduleResult>;
|
|
29
|
+
/**
|
|
30
|
+
* Cancel a scheduled email
|
|
31
|
+
*/
|
|
32
|
+
cancelScheduledEmail(scheduleId: string): Promise<CancelResult>;
|
|
33
|
+
/**
|
|
34
|
+
* Create a new email template
|
|
35
|
+
*/
|
|
36
|
+
createTemplate(template: Omit<EmailTemplate, 'createdAt' | 'updatedAt'>): Promise<TemplateResult>;
|
|
37
|
+
/**
|
|
38
|
+
* Update an existing template
|
|
39
|
+
*/
|
|
40
|
+
updateTemplate(templateId: string, template: Partial<EmailTemplate>): Promise<TemplateResult>;
|
|
41
|
+
/**
|
|
42
|
+
* Delete a template
|
|
43
|
+
*/
|
|
44
|
+
deleteTemplate(templateId: string): Promise<DeleteResult>;
|
|
45
|
+
/**
|
|
46
|
+
* Get a template by ID
|
|
47
|
+
*/
|
|
48
|
+
getTemplate(templateId: string): Promise<EmailTemplate | null>;
|
|
49
|
+
/**
|
|
50
|
+
* List templates with filtering and pagination
|
|
51
|
+
*/
|
|
52
|
+
listTemplates(options?: ListOptions): Promise<TemplateList>;
|
|
53
|
+
/**
|
|
54
|
+
* Render a template with context (without sending)
|
|
55
|
+
*/
|
|
56
|
+
renderTemplate(templateId: string, context: TemplateContext): Promise<RenderedTemplate>;
|
|
57
|
+
/**
|
|
58
|
+
* Add an email provider
|
|
59
|
+
*/
|
|
60
|
+
addProvider(provider: EmailProvider): Promise<any>;
|
|
61
|
+
/**
|
|
62
|
+
* Remove an email provider
|
|
63
|
+
*/
|
|
64
|
+
removeProvider(providerId: string): Promise<DeleteResult>;
|
|
65
|
+
/**
|
|
66
|
+
* Get a provider by ID
|
|
67
|
+
*/
|
|
68
|
+
getProvider(providerId: string): Promise<EmailProvider | null>;
|
|
69
|
+
/**
|
|
70
|
+
* List all providers
|
|
71
|
+
*/
|
|
72
|
+
listProviders(): Promise<ProviderList>;
|
|
73
|
+
/**
|
|
74
|
+
* Get provider status and health
|
|
75
|
+
*/
|
|
76
|
+
getProviderStatus(providerId: string): Promise<ProviderStatus | null>;
|
|
77
|
+
/**
|
|
78
|
+
* Test provider connection
|
|
79
|
+
*/
|
|
80
|
+
testConnection(providerId: string): Promise<TestResult>;
|
|
81
|
+
/**
|
|
82
|
+
* Get email statistics for a specific email
|
|
83
|
+
*/
|
|
84
|
+
getEmailStats(emailId: string): Promise<EmailStats>;
|
|
85
|
+
/**
|
|
86
|
+
* Get delivery report for a time period
|
|
87
|
+
*/
|
|
88
|
+
getDeliveryReport(options?: ReportOptions): Promise<DeliveryReport>;
|
|
89
|
+
/**
|
|
90
|
+
* Get bounce report for a time period
|
|
91
|
+
*/
|
|
92
|
+
getBounceReport(options?: ReportOptions): Promise<BounceReport>;
|
|
93
|
+
/**
|
|
94
|
+
* Get analytics summary
|
|
95
|
+
*/
|
|
96
|
+
getAnalyticsSummary(days?: number): Promise<any>;
|
|
97
|
+
/**
|
|
98
|
+
* Track email events (for webhook integration)
|
|
99
|
+
*/
|
|
100
|
+
trackEmailEvent(eventType: 'opened' | 'clicked' | 'bounced', emailId: string, recipient: string, metadata?: any): void;
|
|
101
|
+
/**
|
|
102
|
+
* Validate an email address
|
|
103
|
+
*/
|
|
104
|
+
validateEmail(email: string): boolean;
|
|
105
|
+
/**
|
|
106
|
+
* Generate a magic link for email authentication
|
|
107
|
+
*/
|
|
108
|
+
generateMagicLink(email: string, purpose: string, metadata?: any): Promise<any>;
|
|
109
|
+
/**
|
|
110
|
+
* Verify a magic link
|
|
111
|
+
*/
|
|
112
|
+
verifyMagicLink(token: string): Promise<any>;
|
|
113
|
+
/**
|
|
114
|
+
* Get overall system statistics
|
|
115
|
+
*/
|
|
116
|
+
getSystemStats(): any;
|
|
117
|
+
/**
|
|
118
|
+
* Shutdown the email manager (cleanup resources)
|
|
119
|
+
*/
|
|
120
|
+
shutdown(): void;
|
|
121
|
+
/**
|
|
122
|
+
* Initialize managers with configuration data
|
|
123
|
+
*/
|
|
124
|
+
private initializeFromConfig;
|
|
125
|
+
/**
|
|
126
|
+
* Get configuration
|
|
127
|
+
*/
|
|
128
|
+
getConfig(): EmailManagerConfig;
|
|
129
|
+
/**
|
|
130
|
+
* Update configuration
|
|
131
|
+
*/
|
|
132
|
+
updateConfig(updates: Partial<EmailManagerConfig>): void;
|
|
133
|
+
}
|
|
134
|
+
//# sourceMappingURL=email-manager.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"email-manager.d.ts","sourceRoot":"","sources":["../src/email-manager.ts"],"names":[],"mappings":"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"}
|