@bernierllc/email-webhook-events 1.4.0 → 1.6.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/dist/EmailWebhookEventsService.js +4 -0
- package/dist/EmailWebhookEventsService.js.map +1 -1
- package/dist/analytics/AnalyticsEngine.js +2 -1
- package/dist/analytics/AnalyticsEngine.js.map +1 -1
- package/dist/errors.d.ts +12 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +25 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/persistence/InMemoryPersistenceAdapter.js +2 -4
- package/dist/persistence/InMemoryPersistenceAdapter.js.map +1 -1
- package/package.json +6 -2
- package/.eslintrc.cjs +0 -30
- package/CHANGELOG.md +0 -131
- package/__tests__/EmailWebhookEventsService.test.ts +0 -251
- package/__tests__/WebhookEventCallbacks.test.ts +0 -343
- package/__tests__/analytics/AnalyticsEngine.test.ts +0 -250
- package/__tests__/fixtures/sendgrid-webhooks/.gitkeep +0 -0
- package/__tests__/fixtures/sendgrid-webhooks/README.md +0 -63
- package/__tests__/fixtures/sendgrid-webhooks/deferred.json +0 -31
- package/__tests__/fixtures/sendgrid-webhooks/delivered.json +0 -83
- package/__tests__/fixtures/sendgrid-webhooks/open.json +0 -83
- package/__tests__/integration/ngrok-tunnel-manager.ts +0 -88
- package/__tests__/integration/sendgrid-webhook-integration.test.ts +0 -272
- package/__tests__/integration/webhook-server.ts +0 -188
- package/__tests__/mocks/README.md +0 -172
- package/__tests__/mocks/index.ts +0 -94
- package/__tests__/mocks/sendgrid-api-responses.ts +0 -391
- package/__tests__/mocks/sendgrid-webhook-payloads.ts +0 -463
- package/__tests__/normalizers/MailgunNormalizer.test.ts +0 -149
- package/__tests__/normalizers/PostmarkNormalizer.test.ts +0 -112
- package/__tests__/normalizers/SESNormalizer.test.ts +0 -168
- package/__tests__/normalizers/SMTP2GONormalizer.test.ts +0 -83
- package/__tests__/normalizers/SendGridNormalizer.test.ts +0 -181
- package/__tests__/persistence/PersistenceAdapter.test.ts +0 -103
- package/jest.config.cjs +0 -38
- package/src/EmailWebhookEventsService.ts +0 -290
- package/src/analytics/AnalyticsEngine.ts +0 -230
- package/src/index.ts +0 -40
- package/src/normalizers/EventNormalizer.ts +0 -13
- package/src/normalizers/MailgunNormalizer.ts +0 -72
- package/src/normalizers/PostmarkNormalizer.ts +0 -72
- package/src/normalizers/SESNormalizer.ts +0 -117
- package/src/normalizers/SMTP2GONormalizer.ts +0 -54
- package/src/normalizers/SendGridNormalizer.ts +0 -63
- package/src/persistence/InMemoryPersistenceAdapter.ts +0 -68
- package/src/persistence/PersistenceAdapter.ts +0 -15
- package/src/types.ts +0 -261
- package/tsconfig.json +0 -31
|
@@ -1,343 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright (c) 2025 Bernier LLC
|
|
3
|
-
|
|
4
|
-
This file is licensed to the client under a limited-use license.
|
|
5
|
-
The client may use and modify this code *only within the scope of the project it was delivered for*.
|
|
6
|
-
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
|
|
7
|
-
*/
|
|
8
|
-
|
|
9
|
-
import { EmailWebhookEventsService } from '../src/EmailWebhookEventsService';
|
|
10
|
-
import {
|
|
11
|
-
EmailEventType,
|
|
12
|
-
EmailProvider,
|
|
13
|
-
WebhookPayload,
|
|
14
|
-
EmailEvent,
|
|
15
|
-
WebhookEventCallbacks,
|
|
16
|
-
EmailWebhookEventsConfig
|
|
17
|
-
} from '../src/types';
|
|
18
|
-
|
|
19
|
-
describe('WebhookEventCallbacks', () => {
|
|
20
|
-
const createWebhook = (eventType: string, overrides: Partial<WebhookPayload> = {}): WebhookPayload => ({
|
|
21
|
-
provider: EmailProvider.SENDGRID,
|
|
22
|
-
signature: 'test-signature',
|
|
23
|
-
payload: {
|
|
24
|
-
event: eventType,
|
|
25
|
-
email: 'user@example.com',
|
|
26
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
27
|
-
sg_message_id: 'msg-123',
|
|
28
|
-
email_id: 'email-456'
|
|
29
|
-
},
|
|
30
|
-
headers: {},
|
|
31
|
-
...overrides
|
|
32
|
-
});
|
|
33
|
-
|
|
34
|
-
const createService = async (callbacks: WebhookEventCallbacks): Promise<EmailWebhookEventsService> => {
|
|
35
|
-
const config: EmailWebhookEventsConfig = {
|
|
36
|
-
providers: [{
|
|
37
|
-
provider: EmailProvider.SENDGRID,
|
|
38
|
-
enabled: true,
|
|
39
|
-
webhookUrl: '/webhooks/sendgrid',
|
|
40
|
-
secretKey: 'test-secret',
|
|
41
|
-
signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
|
|
42
|
-
signatureAlgorithm: 'sha256'
|
|
43
|
-
}],
|
|
44
|
-
persistence: {
|
|
45
|
-
enabled: true,
|
|
46
|
-
adapter: 'memory'
|
|
47
|
-
},
|
|
48
|
-
analytics: {
|
|
49
|
-
realTimeEnabled: true,
|
|
50
|
-
aggregationInterval: 5000,
|
|
51
|
-
retentionDays: 90
|
|
52
|
-
},
|
|
53
|
-
callbacks
|
|
54
|
-
};
|
|
55
|
-
|
|
56
|
-
const service = new EmailWebhookEventsService(config);
|
|
57
|
-
await service.initialize();
|
|
58
|
-
return service;
|
|
59
|
-
};
|
|
60
|
-
|
|
61
|
-
it('should invoke onBounce callback for bounce events', async () => {
|
|
62
|
-
const onBounce = jest.fn();
|
|
63
|
-
const service = await createService({ onBounce });
|
|
64
|
-
|
|
65
|
-
const webhook = createWebhook('bounce', {
|
|
66
|
-
payload: {
|
|
67
|
-
event: 'bounce',
|
|
68
|
-
email: 'user@example.com',
|
|
69
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
70
|
-
sg_message_id: 'msg-123',
|
|
71
|
-
status: '5.1.1',
|
|
72
|
-
reason: 'User unknown'
|
|
73
|
-
}
|
|
74
|
-
});
|
|
75
|
-
|
|
76
|
-
const result = await service.processWebhook(webhook);
|
|
77
|
-
|
|
78
|
-
expect(result.success).toBe(true);
|
|
79
|
-
expect(onBounce).toHaveBeenCalledTimes(1);
|
|
80
|
-
expect(onBounce).toHaveBeenCalledWith(
|
|
81
|
-
expect.objectContaining({
|
|
82
|
-
type: EmailEventType.BOUNCED,
|
|
83
|
-
recipient: 'user@example.com'
|
|
84
|
-
})
|
|
85
|
-
);
|
|
86
|
-
});
|
|
87
|
-
|
|
88
|
-
it('should invoke onComplaint callback for complaint events', async () => {
|
|
89
|
-
const onComplaint = jest.fn();
|
|
90
|
-
const service = await createService({ onComplaint });
|
|
91
|
-
|
|
92
|
-
const webhook = createWebhook('spamreport', {
|
|
93
|
-
payload: {
|
|
94
|
-
event: 'spamreport',
|
|
95
|
-
email: 'user@example.com',
|
|
96
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
97
|
-
sg_message_id: 'msg-123'
|
|
98
|
-
}
|
|
99
|
-
});
|
|
100
|
-
|
|
101
|
-
const result = await service.processWebhook(webhook);
|
|
102
|
-
|
|
103
|
-
expect(result.success).toBe(true);
|
|
104
|
-
expect(onComplaint).toHaveBeenCalledTimes(1);
|
|
105
|
-
expect(onComplaint).toHaveBeenCalledWith(
|
|
106
|
-
expect.objectContaining({
|
|
107
|
-
type: EmailEventType.COMPLAINED,
|
|
108
|
-
recipient: 'user@example.com'
|
|
109
|
-
})
|
|
110
|
-
);
|
|
111
|
-
});
|
|
112
|
-
|
|
113
|
-
it('should invoke onUnsubscribe callback for unsubscribe events', async () => {
|
|
114
|
-
const onUnsubscribe = jest.fn();
|
|
115
|
-
const service = await createService({ onUnsubscribe });
|
|
116
|
-
|
|
117
|
-
const webhook = createWebhook('unsubscribe', {
|
|
118
|
-
payload: {
|
|
119
|
-
event: 'unsubscribe',
|
|
120
|
-
email: 'user@example.com',
|
|
121
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
122
|
-
sg_message_id: 'msg-123'
|
|
123
|
-
}
|
|
124
|
-
});
|
|
125
|
-
|
|
126
|
-
const result = await service.processWebhook(webhook);
|
|
127
|
-
|
|
128
|
-
expect(result.success).toBe(true);
|
|
129
|
-
expect(onUnsubscribe).toHaveBeenCalledTimes(1);
|
|
130
|
-
expect(onUnsubscribe).toHaveBeenCalledWith(
|
|
131
|
-
expect.objectContaining({
|
|
132
|
-
type: EmailEventType.UNSUBSCRIBED,
|
|
133
|
-
recipient: 'user@example.com'
|
|
134
|
-
})
|
|
135
|
-
);
|
|
136
|
-
});
|
|
137
|
-
|
|
138
|
-
it('should invoke onDelivery callback for delivery events', async () => {
|
|
139
|
-
const onDelivery = jest.fn();
|
|
140
|
-
const service = await createService({ onDelivery });
|
|
141
|
-
|
|
142
|
-
const webhook = createWebhook('delivered');
|
|
143
|
-
const result = await service.processWebhook(webhook);
|
|
144
|
-
|
|
145
|
-
expect(result.success).toBe(true);
|
|
146
|
-
expect(onDelivery).toHaveBeenCalledTimes(1);
|
|
147
|
-
expect(onDelivery).toHaveBeenCalledWith(
|
|
148
|
-
expect.objectContaining({
|
|
149
|
-
type: EmailEventType.DELIVERED,
|
|
150
|
-
recipient: 'user@example.com'
|
|
151
|
-
})
|
|
152
|
-
);
|
|
153
|
-
});
|
|
154
|
-
|
|
155
|
-
it('should invoke onOpen callback for open events', async () => {
|
|
156
|
-
const onOpen = jest.fn();
|
|
157
|
-
const service = await createService({ onOpen });
|
|
158
|
-
|
|
159
|
-
const webhook = createWebhook('open');
|
|
160
|
-
const result = await service.processWebhook(webhook);
|
|
161
|
-
|
|
162
|
-
expect(result.success).toBe(true);
|
|
163
|
-
expect(onOpen).toHaveBeenCalledTimes(1);
|
|
164
|
-
expect(onOpen).toHaveBeenCalledWith(
|
|
165
|
-
expect.objectContaining({
|
|
166
|
-
type: EmailEventType.OPENED
|
|
167
|
-
})
|
|
168
|
-
);
|
|
169
|
-
});
|
|
170
|
-
|
|
171
|
-
it('should invoke onClick callback for click events', async () => {
|
|
172
|
-
const onClick = jest.fn();
|
|
173
|
-
const service = await createService({ onClick });
|
|
174
|
-
|
|
175
|
-
const webhook = createWebhook('click', {
|
|
176
|
-
payload: {
|
|
177
|
-
event: 'click',
|
|
178
|
-
email: 'user@example.com',
|
|
179
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
180
|
-
sg_message_id: 'msg-123',
|
|
181
|
-
url: 'https://example.com/link'
|
|
182
|
-
}
|
|
183
|
-
});
|
|
184
|
-
|
|
185
|
-
const result = await service.processWebhook(webhook);
|
|
186
|
-
|
|
187
|
-
expect(result.success).toBe(true);
|
|
188
|
-
expect(onClick).toHaveBeenCalledTimes(1);
|
|
189
|
-
expect(onClick).toHaveBeenCalledWith(
|
|
190
|
-
expect.objectContaining({
|
|
191
|
-
type: EmailEventType.CLICKED,
|
|
192
|
-
metadata: expect.objectContaining({
|
|
193
|
-
url: 'https://example.com/link'
|
|
194
|
-
})
|
|
195
|
-
})
|
|
196
|
-
);
|
|
197
|
-
});
|
|
198
|
-
|
|
199
|
-
it('should invoke onFailure callback for failed events', async () => {
|
|
200
|
-
const onFailure = jest.fn();
|
|
201
|
-
const service = await createService({ onFailure });
|
|
202
|
-
|
|
203
|
-
// An unmapped SendGrid event type falls through to EmailEventType.FAILED
|
|
204
|
-
const webhook = createWebhook('unknown_failure_event', {
|
|
205
|
-
payload: {
|
|
206
|
-
event: 'unknown_failure_event',
|
|
207
|
-
email: 'user@example.com',
|
|
208
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
209
|
-
sg_message_id: 'msg-123',
|
|
210
|
-
reason: 'Invalid email'
|
|
211
|
-
}
|
|
212
|
-
});
|
|
213
|
-
|
|
214
|
-
const result = await service.processWebhook(webhook);
|
|
215
|
-
|
|
216
|
-
expect(result.success).toBe(true);
|
|
217
|
-
expect(onFailure).toHaveBeenCalledTimes(1);
|
|
218
|
-
expect(onFailure).toHaveBeenCalledWith(
|
|
219
|
-
expect.objectContaining({
|
|
220
|
-
type: EmailEventType.FAILED
|
|
221
|
-
})
|
|
222
|
-
);
|
|
223
|
-
});
|
|
224
|
-
|
|
225
|
-
it('should not fail webhook processing if callback throws', async () => {
|
|
226
|
-
const onDelivery = jest.fn().mockRejectedValue(new Error('Callback exploded'));
|
|
227
|
-
const service = await createService({ onDelivery });
|
|
228
|
-
|
|
229
|
-
const webhook = createWebhook('delivered');
|
|
230
|
-
const result = await service.processWebhook(webhook);
|
|
231
|
-
|
|
232
|
-
expect(result.success).toBe(true);
|
|
233
|
-
expect(result.event).toBeDefined();
|
|
234
|
-
expect(onDelivery).toHaveBeenCalledTimes(1);
|
|
235
|
-
});
|
|
236
|
-
|
|
237
|
-
it('should not fail webhook processing if sync callback throws', async () => {
|
|
238
|
-
const onDelivery = jest.fn().mockImplementation(() => {
|
|
239
|
-
throw new Error('Sync callback exploded');
|
|
240
|
-
});
|
|
241
|
-
const service = await createService({ onDelivery });
|
|
242
|
-
|
|
243
|
-
const webhook = createWebhook('delivered');
|
|
244
|
-
const result = await service.processWebhook(webhook);
|
|
245
|
-
|
|
246
|
-
expect(result.success).toBe(true);
|
|
247
|
-
expect(result.event).toBeDefined();
|
|
248
|
-
expect(onDelivery).toHaveBeenCalledTimes(1);
|
|
249
|
-
});
|
|
250
|
-
|
|
251
|
-
it('should handle async callbacks', async () => {
|
|
252
|
-
let resolvedValue: string | undefined;
|
|
253
|
-
const onDelivery = jest.fn().mockImplementation(async (event: EmailEvent) => {
|
|
254
|
-
await new Promise(resolve => setTimeout(resolve, 10));
|
|
255
|
-
resolvedValue = event.recipient;
|
|
256
|
-
});
|
|
257
|
-
const service = await createService({ onDelivery });
|
|
258
|
-
|
|
259
|
-
const webhook = createWebhook('delivered');
|
|
260
|
-
const result = await service.processWebhook(webhook);
|
|
261
|
-
|
|
262
|
-
expect(result.success).toBe(true);
|
|
263
|
-
expect(onDelivery).toHaveBeenCalledTimes(1);
|
|
264
|
-
expect(resolvedValue).toBe('user@example.com');
|
|
265
|
-
});
|
|
266
|
-
|
|
267
|
-
it('should work when no callbacks configured', async () => {
|
|
268
|
-
const config: EmailWebhookEventsConfig = {
|
|
269
|
-
providers: [{
|
|
270
|
-
provider: EmailProvider.SENDGRID,
|
|
271
|
-
enabled: true,
|
|
272
|
-
webhookUrl: '/webhooks/sendgrid',
|
|
273
|
-
secretKey: 'test-secret',
|
|
274
|
-
signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
|
|
275
|
-
signatureAlgorithm: 'sha256'
|
|
276
|
-
}],
|
|
277
|
-
persistence: {
|
|
278
|
-
enabled: true,
|
|
279
|
-
adapter: 'memory'
|
|
280
|
-
},
|
|
281
|
-
analytics: {
|
|
282
|
-
realTimeEnabled: true,
|
|
283
|
-
aggregationInterval: 5000,
|
|
284
|
-
retentionDays: 90
|
|
285
|
-
}
|
|
286
|
-
// No callbacks property
|
|
287
|
-
};
|
|
288
|
-
|
|
289
|
-
const service = new EmailWebhookEventsService(config);
|
|
290
|
-
await service.initialize();
|
|
291
|
-
|
|
292
|
-
const webhook = createWebhook('delivered');
|
|
293
|
-
const result = await service.processWebhook(webhook);
|
|
294
|
-
|
|
295
|
-
expect(result.success).toBe(true);
|
|
296
|
-
expect(result.event).toBeDefined();
|
|
297
|
-
});
|
|
298
|
-
|
|
299
|
-
it('should work with empty callbacks object', async () => {
|
|
300
|
-
const service = await createService({});
|
|
301
|
-
|
|
302
|
-
const webhook = createWebhook('delivered');
|
|
303
|
-
const result = await service.processWebhook(webhook);
|
|
304
|
-
|
|
305
|
-
expect(result.success).toBe(true);
|
|
306
|
-
expect(result.event).toBeDefined();
|
|
307
|
-
});
|
|
308
|
-
|
|
309
|
-
it('should invoke multiple different callbacks for different events', async () => {
|
|
310
|
-
const onDelivery = jest.fn();
|
|
311
|
-
const onBounce = jest.fn();
|
|
312
|
-
const onOpen = jest.fn();
|
|
313
|
-
const service = await createService({ onDelivery, onBounce, onOpen });
|
|
314
|
-
|
|
315
|
-
await service.processWebhook(createWebhook('delivered'));
|
|
316
|
-
await service.processWebhook(createWebhook('bounce', {
|
|
317
|
-
payload: {
|
|
318
|
-
event: 'bounce',
|
|
319
|
-
email: 'user@example.com',
|
|
320
|
-
timestamp: Math.floor(Date.now() / 1000),
|
|
321
|
-
sg_message_id: 'msg-123',
|
|
322
|
-
status: '5.1.1',
|
|
323
|
-
reason: 'Unknown user'
|
|
324
|
-
}
|
|
325
|
-
}));
|
|
326
|
-
await service.processWebhook(createWebhook('open'));
|
|
327
|
-
|
|
328
|
-
expect(onDelivery).toHaveBeenCalledTimes(1);
|
|
329
|
-
expect(onBounce).toHaveBeenCalledTimes(1);
|
|
330
|
-
expect(onOpen).toHaveBeenCalledTimes(1);
|
|
331
|
-
});
|
|
332
|
-
|
|
333
|
-
it('should not invoke unrelated callbacks', async () => {
|
|
334
|
-
const onBounce = jest.fn();
|
|
335
|
-
const onComplaint = jest.fn();
|
|
336
|
-
const service = await createService({ onBounce, onComplaint });
|
|
337
|
-
|
|
338
|
-
await service.processWebhook(createWebhook('delivered'));
|
|
339
|
-
|
|
340
|
-
expect(onBounce).not.toHaveBeenCalled();
|
|
341
|
-
expect(onComplaint).not.toHaveBeenCalled();
|
|
342
|
-
});
|
|
343
|
-
});
|
|
@@ -1,250 +0,0 @@
|
|
|
1
|
-
/*
|
|
2
|
-
Copyright (c) 2025 Bernier LLC
|
|
3
|
-
|
|
4
|
-
This file is licensed to the client under a limited-use license.
|
|
5
|
-
The client may use and modify this code *only within the scope of the project it was delivered for*.
|
|
6
|
-
Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
|
|
7
|
-
*/
|
|
8
|
-
|
|
9
|
-
import { AnalyticsEngine } from '../../src/analytics/AnalyticsEngine';
|
|
10
|
-
import { EmailEvent, EmailEventType, EmailProvider } from '../../src/types';
|
|
11
|
-
|
|
12
|
-
describe('AnalyticsEngine', () => {
|
|
13
|
-
let engine: AnalyticsEngine;
|
|
14
|
-
let rangeStart: Date;
|
|
15
|
-
let rangeEnd: Date;
|
|
16
|
-
|
|
17
|
-
beforeEach(() => {
|
|
18
|
-
engine = new AnalyticsEngine({
|
|
19
|
-
realTimeEnabled: true,
|
|
20
|
-
aggregationInterval: 5000,
|
|
21
|
-
retentionDays: 90
|
|
22
|
-
});
|
|
23
|
-
|
|
24
|
-
// Use dynamic date range that always encompasses "now"
|
|
25
|
-
rangeStart = new Date(Date.now() - 24 * 60 * 60 * 1000); // 1 day ago
|
|
26
|
-
rangeEnd = new Date(Date.now() + 24 * 60 * 60 * 1000); // 1 day from now
|
|
27
|
-
});
|
|
28
|
-
|
|
29
|
-
const createEvent = (type: EmailEventType, overrides: Partial<EmailEvent> = {}): EmailEvent => ({
|
|
30
|
-
id: `event-${Math.random()}`,
|
|
31
|
-
emailId: 'email-123',
|
|
32
|
-
messageId: 'msg-123',
|
|
33
|
-
type,
|
|
34
|
-
recipient: 'user@example.com',
|
|
35
|
-
timestamp: new Date(),
|
|
36
|
-
provider: EmailProvider.SENDGRID,
|
|
37
|
-
metadata: {},
|
|
38
|
-
...overrides
|
|
39
|
-
});
|
|
40
|
-
|
|
41
|
-
it('should record events', async () => {
|
|
42
|
-
const event = createEvent(EmailEventType.DELIVERED);
|
|
43
|
-
await engine.recordEvent(event);
|
|
44
|
-
|
|
45
|
-
const analytics = await engine.getAnalytics(
|
|
46
|
-
rangeStart,
|
|
47
|
-
rangeEnd
|
|
48
|
-
);
|
|
49
|
-
|
|
50
|
-
expect(analytics.totalDelivered).toBe(1);
|
|
51
|
-
});
|
|
52
|
-
|
|
53
|
-
it('should calculate delivery rate correctly', async () => {
|
|
54
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
55
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
56
|
-
await engine.recordEvent(createEvent(EmailEventType.BOUNCED));
|
|
57
|
-
|
|
58
|
-
const analytics = await engine.getAnalytics(
|
|
59
|
-
rangeStart,
|
|
60
|
-
rangeEnd
|
|
61
|
-
);
|
|
62
|
-
|
|
63
|
-
expect(analytics.totalSent).toBe(3);
|
|
64
|
-
expect(analytics.totalDelivered).toBe(2);
|
|
65
|
-
expect(analytics.deliveryRate).toBeCloseTo(2 / 3, 2);
|
|
66
|
-
});
|
|
67
|
-
|
|
68
|
-
it('should calculate open rate correctly', async () => {
|
|
69
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
70
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
71
|
-
await engine.recordEvent(createEvent(EmailEventType.OPENED));
|
|
72
|
-
|
|
73
|
-
const analytics = await engine.getAnalytics(
|
|
74
|
-
rangeStart,
|
|
75
|
-
rangeEnd
|
|
76
|
-
);
|
|
77
|
-
|
|
78
|
-
expect(analytics.totalDelivered).toBe(2);
|
|
79
|
-
expect(analytics.totalOpened).toBe(1);
|
|
80
|
-
expect(analytics.openRate).toBe(0.5);
|
|
81
|
-
});
|
|
82
|
-
|
|
83
|
-
it('should calculate click-to-open rate correctly', async () => {
|
|
84
|
-
await engine.recordEvent(createEvent(EmailEventType.OPENED));
|
|
85
|
-
await engine.recordEvent(createEvent(EmailEventType.OPENED));
|
|
86
|
-
await engine.recordEvent(createEvent(EmailEventType.CLICKED));
|
|
87
|
-
|
|
88
|
-
const analytics = await engine.getAnalytics(
|
|
89
|
-
rangeStart,
|
|
90
|
-
rangeEnd
|
|
91
|
-
);
|
|
92
|
-
|
|
93
|
-
expect(analytics.totalOpened).toBe(2);
|
|
94
|
-
expect(analytics.totalClicked).toBe(1);
|
|
95
|
-
expect(analytics.clickToOpenRate).toBe(0.5);
|
|
96
|
-
});
|
|
97
|
-
|
|
98
|
-
it('should handle zero denominators gracefully', async () => {
|
|
99
|
-
const analytics = await engine.getAnalytics(
|
|
100
|
-
rangeStart,
|
|
101
|
-
rangeEnd
|
|
102
|
-
);
|
|
103
|
-
|
|
104
|
-
expect(analytics.deliveryRate).toBe(0);
|
|
105
|
-
expect(analytics.openRate).toBe(0);
|
|
106
|
-
expect(analytics.clickRate).toBe(0);
|
|
107
|
-
});
|
|
108
|
-
|
|
109
|
-
it('should calculate bounce rate correctly', async () => {
|
|
110
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
111
|
-
await engine.recordEvent(createEvent(EmailEventType.BOUNCED));
|
|
112
|
-
|
|
113
|
-
const analytics = await engine.getAnalytics(
|
|
114
|
-
rangeStart,
|
|
115
|
-
rangeEnd
|
|
116
|
-
);
|
|
117
|
-
|
|
118
|
-
expect(analytics.bounceRate).toBe(0.5);
|
|
119
|
-
});
|
|
120
|
-
|
|
121
|
-
it('should break down by provider', async () => {
|
|
122
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.SENDGRID }));
|
|
123
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.MAILGUN }));
|
|
124
|
-
|
|
125
|
-
const analytics = await engine.getAnalytics(
|
|
126
|
-
rangeStart,
|
|
127
|
-
rangeEnd
|
|
128
|
-
);
|
|
129
|
-
|
|
130
|
-
expect(analytics.byProvider[EmailProvider.SENDGRID].delivered).toBe(1);
|
|
131
|
-
expect(analytics.byProvider[EmailProvider.MAILGUN].delivered).toBe(1);
|
|
132
|
-
});
|
|
133
|
-
|
|
134
|
-
it('should break down by event type', async () => {
|
|
135
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
136
|
-
await engine.recordEvent(createEvent(EmailEventType.OPENED));
|
|
137
|
-
await engine.recordEvent(createEvent(EmailEventType.CLICKED));
|
|
138
|
-
|
|
139
|
-
const analytics = await engine.getAnalytics(
|
|
140
|
-
rangeStart,
|
|
141
|
-
rangeEnd
|
|
142
|
-
);
|
|
143
|
-
|
|
144
|
-
expect(analytics.byEventType[EmailEventType.DELIVERED]).toBe(1);
|
|
145
|
-
expect(analytics.byEventType[EmailEventType.OPENED]).toBe(1);
|
|
146
|
-
expect(analytics.byEventType[EmailEventType.CLICKED]).toBe(1);
|
|
147
|
-
});
|
|
148
|
-
|
|
149
|
-
it('should break down bounces by type', async () => {
|
|
150
|
-
await engine.recordEvent(
|
|
151
|
-
createEvent(EmailEventType.BOUNCED, {
|
|
152
|
-
metadata: { bounceType: 'hard' }
|
|
153
|
-
})
|
|
154
|
-
);
|
|
155
|
-
await engine.recordEvent(
|
|
156
|
-
createEvent(EmailEventType.BOUNCED, {
|
|
157
|
-
metadata: { bounceType: 'soft' }
|
|
158
|
-
})
|
|
159
|
-
);
|
|
160
|
-
|
|
161
|
-
const analytics = await engine.getAnalytics(
|
|
162
|
-
rangeStart,
|
|
163
|
-
rangeEnd
|
|
164
|
-
);
|
|
165
|
-
|
|
166
|
-
expect(analytics.byBounceType).toBeDefined();
|
|
167
|
-
expect(analytics.byBounceType!.hard).toBe(1);
|
|
168
|
-
expect(analytics.byBounceType!.soft).toBe(1);
|
|
169
|
-
});
|
|
170
|
-
|
|
171
|
-
it('should calculate top links', async () => {
|
|
172
|
-
await engine.recordEvent(
|
|
173
|
-
createEvent(EmailEventType.CLICKED, {
|
|
174
|
-
metadata: { url: 'https://example.com/link1' },
|
|
175
|
-
recipient: 'user1@example.com'
|
|
176
|
-
})
|
|
177
|
-
);
|
|
178
|
-
await engine.recordEvent(
|
|
179
|
-
createEvent(EmailEventType.CLICKED, {
|
|
180
|
-
metadata: { url: 'https://example.com/link1' },
|
|
181
|
-
recipient: 'user2@example.com'
|
|
182
|
-
})
|
|
183
|
-
);
|
|
184
|
-
await engine.recordEvent(
|
|
185
|
-
createEvent(EmailEventType.CLICKED, {
|
|
186
|
-
metadata: { url: 'https://example.com/link2' },
|
|
187
|
-
recipient: 'user1@example.com'
|
|
188
|
-
})
|
|
189
|
-
);
|
|
190
|
-
|
|
191
|
-
const analytics = await engine.getAnalytics(
|
|
192
|
-
rangeStart,
|
|
193
|
-
rangeEnd
|
|
194
|
-
);
|
|
195
|
-
|
|
196
|
-
expect(analytics.topLinks).toBeDefined();
|
|
197
|
-
expect(analytics.topLinks![0].url).toBe('https://example.com/link1');
|
|
198
|
-
expect(analytics.topLinks![0].clicks).toBe(2);
|
|
199
|
-
expect(analytics.topLinks![0].uniqueClicks).toBe(2);
|
|
200
|
-
});
|
|
201
|
-
|
|
202
|
-
it('should break down by device type', async () => {
|
|
203
|
-
await engine.recordEvent(
|
|
204
|
-
createEvent(EmailEventType.OPENED, {
|
|
205
|
-
metadata: { deviceType: 'desktop' }
|
|
206
|
-
})
|
|
207
|
-
);
|
|
208
|
-
await engine.recordEvent(
|
|
209
|
-
createEvent(EmailEventType.OPENED, {
|
|
210
|
-
metadata: { deviceType: 'mobile' }
|
|
211
|
-
})
|
|
212
|
-
);
|
|
213
|
-
|
|
214
|
-
const analytics = await engine.getAnalytics(
|
|
215
|
-
rangeStart,
|
|
216
|
-
rangeEnd
|
|
217
|
-
);
|
|
218
|
-
|
|
219
|
-
expect(analytics.byDevice).toBeDefined();
|
|
220
|
-
expect(analytics.byDevice!.desktop).toBe(1);
|
|
221
|
-
expect(analytics.byDevice!.mobile).toBe(1);
|
|
222
|
-
});
|
|
223
|
-
|
|
224
|
-
it('should filter analytics by provider', async () => {
|
|
225
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.SENDGRID }));
|
|
226
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.MAILGUN }));
|
|
227
|
-
|
|
228
|
-
const analytics = await engine.getAnalytics(
|
|
229
|
-
rangeStart,
|
|
230
|
-
rangeEnd,
|
|
231
|
-
{ provider: EmailProvider.SENDGRID }
|
|
232
|
-
);
|
|
233
|
-
|
|
234
|
-
expect(analytics.totalDelivered).toBe(1);
|
|
235
|
-
});
|
|
236
|
-
|
|
237
|
-
it('should filter analytics by event type', async () => {
|
|
238
|
-
await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
|
|
239
|
-
await engine.recordEvent(createEvent(EmailEventType.OPENED));
|
|
240
|
-
|
|
241
|
-
const analytics = await engine.getAnalytics(
|
|
242
|
-
rangeStart,
|
|
243
|
-
rangeEnd,
|
|
244
|
-
{ eventTypes: [EmailEventType.DELIVERED] }
|
|
245
|
-
);
|
|
246
|
-
|
|
247
|
-
expect(analytics.totalDelivered).toBe(1);
|
|
248
|
-
expect(analytics.totalOpened).toBe(0);
|
|
249
|
-
});
|
|
250
|
-
});
|
|
File without changes
|
|
@@ -1,63 +0,0 @@
|
|
|
1
|
-
# SendGrid Webhook Fixtures
|
|
2
|
-
|
|
3
|
-
This directory contains webhook payloads based on REAL SendGrid webhook structures captured during integration testing.
|
|
4
|
-
|
|
5
|
-
> ⚠️ **SANITIZED DATA**: All email addresses, IPs, message IDs, signatures, and other identifiable data have been replaced with fake test values. The **structure** matches real SendGrid payloads but all values are safe for version control.
|
|
6
|
-
|
|
7
|
-
## Structure
|
|
8
|
-
|
|
9
|
-
Each event type has its own JSON file containing an array of captured webhook payloads:
|
|
10
|
-
|
|
11
|
-
- `delivered.json` - Email delivered events
|
|
12
|
-
- `open.json` - Email opened events
|
|
13
|
-
- `click.json` - Link clicked events
|
|
14
|
-
- `bounce.json` - Email bounced events
|
|
15
|
-
- `spamreport.json` - Spam complaint events
|
|
16
|
-
- `unsubscribe.json` - Unsubscribe events
|
|
17
|
-
- `deferred.json` - Email delivery deferred events
|
|
18
|
-
- `dropped.json` - Email dropped events
|
|
19
|
-
|
|
20
|
-
## File Format
|
|
21
|
-
|
|
22
|
-
Each file contains an array of captured webhook objects:
|
|
23
|
-
|
|
24
|
-
```json
|
|
25
|
-
[
|
|
26
|
-
{
|
|
27
|
-
"headers": {
|
|
28
|
-
"x-twilio-email-event-webhook-signature": "...",
|
|
29
|
-
"content-type": "application/json",
|
|
30
|
-
...
|
|
31
|
-
},
|
|
32
|
-
"body": {
|
|
33
|
-
"event": "delivered",
|
|
34
|
-
"email": "user@example.com",
|
|
35
|
-
"timestamp": 1234567890,
|
|
36
|
-
"sg_message_id": "...",
|
|
37
|
-
...
|
|
38
|
-
},
|
|
39
|
-
"timestamp": "2025-01-27T12:00:00.000Z",
|
|
40
|
-
"eventType": "delivered"
|
|
41
|
-
}
|
|
42
|
-
]
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## Usage
|
|
46
|
-
|
|
47
|
-
These fixtures are automatically generated during integration tests and can be used to:
|
|
48
|
-
|
|
49
|
-
1. Generate accurate mocks for unit tests
|
|
50
|
-
2. Validate webhook payload structure
|
|
51
|
-
3. Test normalizer implementations with real data
|
|
52
|
-
4. Debug webhook processing issues
|
|
53
|
-
|
|
54
|
-
## Generation
|
|
55
|
-
|
|
56
|
-
Fixtures are automatically captured when running integration tests:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
npm test -- sendgrid-webhook-integration
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
The webhook server automatically saves all received webhooks to the appropriate fixture files.
|
|
63
|
-
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
[
|
|
2
|
-
{
|
|
3
|
-
"headers": {
|
|
4
|
-
"host": "example-webhook.ngrok.app",
|
|
5
|
-
"user-agent": "SendGrid Event API",
|
|
6
|
-
"content-length": "498",
|
|
7
|
-
"accept-encoding": "gzip",
|
|
8
|
-
"content-type": "application/json;charset=utf-8",
|
|
9
|
-
"x-forwarded-for": "192.0.2.30",
|
|
10
|
-
"x-forwarded-host": "example-webhook.ngrok.app",
|
|
11
|
-
"x-forwarded-proto": "https",
|
|
12
|
-
"x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEQCIG5UlgMJ_DO_NOT_USE_IN_PRODUCTION=",
|
|
13
|
-
"x-twilio-email-event-webhook-timestamp": "1700000300"
|
|
14
|
-
},
|
|
15
|
-
"body": {
|
|
16
|
-
"attempt": "2",
|
|
17
|
-
"domain": "example.com",
|
|
18
|
-
"email": "deferred-recipient@example.com",
|
|
19
|
-
"event": "deferred",
|
|
20
|
-
"from": "Test Sender <sender@example.com>",
|
|
21
|
-
"response": "temporarily unable to deliver - server busy, please retry later",
|
|
22
|
-
"sg_event_id": "FAKE_DEFERRED_EVENT_001",
|
|
23
|
-
"sg_message_id": "FAKE_MSG_DEFERRED_001.recvd-1234567890-pqrst-1-1234567B-14.0",
|
|
24
|
-
"smtp-id": "<FAKE_MSG_DEFERRED_001@geopod-ismtpd-test>",
|
|
25
|
-
"timestamp": 1700000300,
|
|
26
|
-
"tls": 0
|
|
27
|
-
},
|
|
28
|
-
"timestamp": "2025-01-01T12:05:00.000Z",
|
|
29
|
-
"eventType": "deferred"
|
|
30
|
-
}
|
|
31
|
-
]
|