@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.
Files changed (52) hide show
  1. package/dist/EmailWebhookEventsService.js +4 -0
  2. package/dist/EmailWebhookEventsService.js.map +1 -1
  3. package/dist/analytics/AnalyticsEngine.js +2 -1
  4. package/dist/analytics/AnalyticsEngine.js.map +1 -1
  5. package/dist/errors.d.ts +12 -0
  6. package/dist/errors.d.ts.map +1 -0
  7. package/dist/errors.js +25 -0
  8. package/dist/errors.js.map +1 -0
  9. package/dist/index.d.ts +1 -0
  10. package/dist/index.d.ts.map +1 -1
  11. package/dist/index.js +3 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/persistence/InMemoryPersistenceAdapter.js +2 -4
  14. package/dist/persistence/InMemoryPersistenceAdapter.js.map +1 -1
  15. package/package.json +6 -2
  16. package/.eslintrc.cjs +0 -30
  17. package/CHANGELOG.md +0 -131
  18. package/__tests__/EmailWebhookEventsService.test.ts +0 -251
  19. package/__tests__/WebhookEventCallbacks.test.ts +0 -343
  20. package/__tests__/analytics/AnalyticsEngine.test.ts +0 -250
  21. package/__tests__/fixtures/sendgrid-webhooks/.gitkeep +0 -0
  22. package/__tests__/fixtures/sendgrid-webhooks/README.md +0 -63
  23. package/__tests__/fixtures/sendgrid-webhooks/deferred.json +0 -31
  24. package/__tests__/fixtures/sendgrid-webhooks/delivered.json +0 -83
  25. package/__tests__/fixtures/sendgrid-webhooks/open.json +0 -83
  26. package/__tests__/integration/ngrok-tunnel-manager.ts +0 -88
  27. package/__tests__/integration/sendgrid-webhook-integration.test.ts +0 -272
  28. package/__tests__/integration/webhook-server.ts +0 -188
  29. package/__tests__/mocks/README.md +0 -172
  30. package/__tests__/mocks/index.ts +0 -94
  31. package/__tests__/mocks/sendgrid-api-responses.ts +0 -391
  32. package/__tests__/mocks/sendgrid-webhook-payloads.ts +0 -463
  33. package/__tests__/normalizers/MailgunNormalizer.test.ts +0 -149
  34. package/__tests__/normalizers/PostmarkNormalizer.test.ts +0 -112
  35. package/__tests__/normalizers/SESNormalizer.test.ts +0 -168
  36. package/__tests__/normalizers/SMTP2GONormalizer.test.ts +0 -83
  37. package/__tests__/normalizers/SendGridNormalizer.test.ts +0 -181
  38. package/__tests__/persistence/PersistenceAdapter.test.ts +0 -103
  39. package/jest.config.cjs +0 -38
  40. package/src/EmailWebhookEventsService.ts +0 -290
  41. package/src/analytics/AnalyticsEngine.ts +0 -230
  42. package/src/index.ts +0 -40
  43. package/src/normalizers/EventNormalizer.ts +0 -13
  44. package/src/normalizers/MailgunNormalizer.ts +0 -72
  45. package/src/normalizers/PostmarkNormalizer.ts +0 -72
  46. package/src/normalizers/SESNormalizer.ts +0 -117
  47. package/src/normalizers/SMTP2GONormalizer.ts +0 -54
  48. package/src/normalizers/SendGridNormalizer.ts +0 -63
  49. package/src/persistence/InMemoryPersistenceAdapter.ts +0 -68
  50. package/src/persistence/PersistenceAdapter.ts +0 -15
  51. package/src/types.ts +0 -261
  52. 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
- ]