@bernierllc/email-webhook-events 1.0.0

package/__tests__/analytics/AnalyticsEngine.test.ts

@@ -0,0 +1,244 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { AnalyticsEngine } from '../../src/analytics/AnalyticsEngine';
+import { EmailEvent, EmailEventType, EmailProvider } from '../../src/types';
+
+describe('AnalyticsEngine', () => {
+  let engine: AnalyticsEngine;
+
+  beforeEach(() => {
+    engine = new AnalyticsEngine({
+      realTimeEnabled: true,
+      aggregationInterval: 5000,
+      retentionDays: 90
+    });
+  });
+
+  const createEvent = (type: EmailEventType, overrides: Partial<EmailEvent> = {}): EmailEvent => ({
+    id: `event-${Math.random()}`,
+    emailId: 'email-123',
+    messageId: 'msg-123',
+    type,
+    recipient: 'user@example.com',
+    timestamp: new Date(),
+    provider: EmailProvider.SENDGRID,
+    metadata: {},
+    ...overrides
+  });
+
+  it('should record events', async () => {
+    const event = createEvent(EmailEventType.DELIVERED);
+    await engine.recordEvent(event);
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.totalDelivered).toBe(1);
+  });
+
+  it('should calculate delivery rate correctly', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.BOUNCED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.totalSent).toBe(3);
+    expect(analytics.totalDelivered).toBe(2);
+    expect(analytics.deliveryRate).toBeCloseTo(2 / 3, 2);
+  });
+
+  it('should calculate open rate correctly', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.OPENED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.totalDelivered).toBe(2);
+    expect(analytics.totalOpened).toBe(1);
+    expect(analytics.openRate).toBe(0.5);
+  });
+
+  it('should calculate click-to-open rate correctly', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.OPENED));
+    await engine.recordEvent(createEvent(EmailEventType.OPENED));
+    await engine.recordEvent(createEvent(EmailEventType.CLICKED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.totalOpened).toBe(2);
+    expect(analytics.totalClicked).toBe(1);
+    expect(analytics.clickToOpenRate).toBe(0.5);
+  });
+
+  it('should handle zero denominators gracefully', async () => {
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.deliveryRate).toBe(0);
+    expect(analytics.openRate).toBe(0);
+    expect(analytics.clickRate).toBe(0);
+  });
+
+  it('should calculate bounce rate correctly', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.BOUNCED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.bounceRate).toBe(0.5);
+  });
+
+  it('should break down by provider', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.SENDGRID }));
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.MAILGUN }));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.byProvider[EmailProvider.SENDGRID].delivered).toBe(1);
+    expect(analytics.byProvider[EmailProvider.MAILGUN].delivered).toBe(1);
+  });
+
+  it('should break down by event type', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.OPENED));
+    await engine.recordEvent(createEvent(EmailEventType.CLICKED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.byEventType[EmailEventType.DELIVERED]).toBe(1);
+    expect(analytics.byEventType[EmailEventType.OPENED]).toBe(1);
+    expect(analytics.byEventType[EmailEventType.CLICKED]).toBe(1);
+  });
+
+  it('should break down bounces by type', async () => {
+    await engine.recordEvent(
+      createEvent(EmailEventType.BOUNCED, {
+        metadata: { bounceType: 'hard' }
+      })
+    );
+    await engine.recordEvent(
+      createEvent(EmailEventType.BOUNCED, {
+        metadata: { bounceType: 'soft' }
+      })
+    );
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.byBounceType).toBeDefined();
+    expect(analytics.byBounceType!.hard).toBe(1);
+    expect(analytics.byBounceType!.soft).toBe(1);
+  });
+
+  it('should calculate top links', async () => {
+    await engine.recordEvent(
+      createEvent(EmailEventType.CLICKED, {
+        metadata: { url: 'https://example.com/link1' },
+        recipient: 'user1@example.com'
+      })
+    );
+    await engine.recordEvent(
+      createEvent(EmailEventType.CLICKED, {
+        metadata: { url: 'https://example.com/link1' },
+        recipient: 'user2@example.com'
+      })
+    );
+    await engine.recordEvent(
+      createEvent(EmailEventType.CLICKED, {
+        metadata: { url: 'https://example.com/link2' },
+        recipient: 'user1@example.com'
+      })
+    );
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.topLinks).toBeDefined();
+    expect(analytics.topLinks![0].url).toBe('https://example.com/link1');
+    expect(analytics.topLinks![0].clicks).toBe(2);
+    expect(analytics.topLinks![0].uniqueClicks).toBe(2);
+  });
+
+  it('should break down by device type', async () => {
+    await engine.recordEvent(
+      createEvent(EmailEventType.OPENED, {
+        metadata: { deviceType: 'desktop' }
+      })
+    );
+    await engine.recordEvent(
+      createEvent(EmailEventType.OPENED, {
+        metadata: { deviceType: 'mobile' }
+      })
+    );
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31')
+    );
+
+    expect(analytics.byDevice).toBeDefined();
+    expect(analytics.byDevice!.desktop).toBe(1);
+    expect(analytics.byDevice!.mobile).toBe(1);
+  });
+
+  it('should filter analytics by provider', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.SENDGRID }));
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED, { provider: EmailProvider.MAILGUN }));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31'),
+      { provider: EmailProvider.SENDGRID }
+    );
+
+    expect(analytics.totalDelivered).toBe(1);
+  });
+
+  it('should filter analytics by event type', async () => {
+    await engine.recordEvent(createEvent(EmailEventType.DELIVERED));
+    await engine.recordEvent(createEvent(EmailEventType.OPENED));
+
+    const analytics = await engine.getAnalytics(
+      new Date('2025-01-01'),
+      new Date('2025-12-31'),
+      { eventTypes: [EmailEventType.DELIVERED] }
+    );
+
+    expect(analytics.totalDelivered).toBe(1);
+    expect(analytics.totalOpened).toBe(0);
+  });
+});

package/__tests__/normalizers/MailgunNormalizer.test.ts

@@ -0,0 +1,149 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { MailgunNormalizer } from '../../src/normalizers/MailgunNormalizer';
+import { EmailEventType, EmailProvider, WebhookPayload } from '../../src/types';
+
+describe('MailgunNormalizer', () => {
+  let normalizer: MailgunNormalizer;
+
+  beforeEach(() => {
+    normalizer = new MailgunNormalizer();
+  });
+
+  it('should normalize delivered event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.MAILGUN,
+      signature: 'test-signature',
+      payload: {
+        'event-data': {
+          event: 'delivered',
+          recipient: 'user@example.com',
+          timestamp: 1234567890,
+          id: 'msg-123',
+          message: {
+            headers: {
+              'message-id': 'email-456'
+            }
+          }
+        }
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.DELIVERED);
+    expect(result.recipient).toBe('user@example.com');
+    expect(result.provider).toBe(EmailProvider.MAILGUN);
+    expect(result.messageId).toBe('msg-123');
+    expect(result.emailId).toBe('email-456');
+  });
+
+  it('should normalize bounce event with geolocation', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.MAILGUN,
+      signature: 'test-signature',
+      payload: {
+        'event-data': {
+          event: 'bounced',
+          recipient: 'user@example.com',
+          timestamp: 1234567890,
+          id: 'msg-123',
+          severity: 'permanent',
+          'delivery-status': {
+            message: 'User unknown',
+            code: 550
+          },
+          message: {
+            headers: {
+              'message-id': 'email-456'
+            }
+          },
+          geolocation: {
+            country: 'US',
+            region: 'CA',
+            city: 'San Francisco'
+          }
+        }
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.BOUNCED);
+    expect(result.metadata.bounceType).toBe('hard');
+    expect(result.metadata.bounceReason).toBe('User unknown');
+    expect(result.metadata.bounceCode).toBe('550');
+    expect(result.metadata.location).toEqual({
+      country: 'US',
+      region: 'CA',
+      city: 'San Francisco'
+    });
+  });
+
+  it('should normalize soft bounce', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.MAILGUN,
+      signature: 'test-signature',
+      payload: {
+        'event-data': {
+          event: 'bounced',
+          recipient: 'user@example.com',
+          timestamp: 1234567890,
+          id: 'msg-123',
+          severity: 'temporary',
+          message: {
+            headers: {
+              'message-id': 'email-456'
+            }
+          }
+        }
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.metadata.bounceType).toBe('soft');
+  });
+
+  it('should normalize click event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.MAILGUN,
+      signature: 'test-signature',
+      payload: {
+        'event-data': {
+          event: 'clicked',
+          recipient: 'user@example.com',
+          timestamp: 1234567890,
+          id: 'msg-123',
+          url: 'https://example.com/link',
+          'client-info': {
+            'client-ip': '192.168.1.1',
+            'user-agent': 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) mobile'
+          },
+          message: {
+            headers: {
+              'message-id': 'email-456'
+            }
+          }
+        }
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.CLICKED);
+    expect(result.metadata.url).toBe('https://example.com/link');
+    expect(result.metadata.ipAddress).toBe('192.168.1.1');
+    expect(result.metadata.deviceType).toBe('mobile');
+  });
+});

package/__tests__/normalizers/PostmarkNormalizer.test.ts

@@ -0,0 +1,112 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { PostmarkNormalizer } from '../../src/normalizers/PostmarkNormalizer';
+import { EmailEventType, EmailProvider, WebhookPayload } from '../../src/types';
+
+describe('PostmarkNormalizer', () => {
+  let normalizer: PostmarkNormalizer;
+
+  beforeEach(() => {
+    normalizer = new PostmarkNormalizer();
+  });
+
+  it('should normalize delivery event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.POSTMARK,
+      signature: 'test-signature',
+      payload: {
+        RecordType: 'Delivery',
+        MessageID: 'msg-123',
+        Recipient: 'user@example.com',
+        ReceivedAt: '2025-01-01T00:00:00.000Z'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.DELIVERED);
+    expect(result.recipient).toBe('user@example.com');
+    expect(result.provider).toBe(EmailProvider.POSTMARK);
+    expect(result.messageId).toBe('msg-123');
+  });
+
+  it('should normalize bounce event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.POSTMARK,
+      signature: 'test-signature',
+      payload: {
+        RecordType: 'Bounce',
+        MessageID: 'msg-123',
+        Recipient: 'user@example.com',
+        ReceivedAt: '2025-01-01T00:00:00.000Z',
+        Type: 'HardBounce',
+        TypeCode: 1,
+        Description: 'User unknown'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.BOUNCED);
+    expect(result.metadata.bounceType).toBe('hard');
+    expect(result.metadata.bounceReason).toBe('User unknown');
+  });
+
+  it('should normalize open event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.POSTMARK,
+      signature: 'test-signature',
+      payload: {
+        RecordType: 'Open',
+        MessageID: 'msg-123',
+        Recipient: 'user@example.com',
+        ReceivedAt: '2025-01-01T00:00:00.000Z',
+        UserAgent: 'Mozilla/5.0',
+        Geo: {
+          Country: 'US',
+          Region: 'CA',
+          City: 'San Francisco'
+        }
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.OPENED);
+    expect(result.metadata.location).toEqual({
+      country: 'US',
+      region: 'CA',
+      city: 'San Francisco'
+    });
+  });
+
+  it('should normalize click event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.POSTMARK,
+      signature: 'test-signature',
+      payload: {
+        RecordType: 'Click',
+        MessageID: 'msg-123',
+        Recipient: 'user@example.com',
+        ReceivedAt: '2025-01-01T00:00:00.000Z',
+        OriginalLink: 'https://example.com/link',
+        UserAgent: 'Mozilla/5.0'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.CLICKED);
+    expect(result.metadata.url).toBe('https://example.com/link');
+  });
+});

package/__tests__/normalizers/SESNormalizer.test.ts

@@ -0,0 +1,168 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { SESNormalizer } from '../../src/normalizers/SESNormalizer';
+import { EmailEventType, EmailProvider, WebhookPayload } from '../../src/types';
+
+describe('SESNormalizer', () => {
+  let normalizer: SESNormalizer;
+
+  beforeEach(() => {
+    normalizer = new SESNormalizer();
+  });
+
+  it('should normalize delivery event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.AWS_SES,
+      signature: 'test-signature',
+      payload: {
+        Message: JSON.stringify({
+          eventType: 'Delivery',
+          mail: {
+            messageId: 'msg-123',
+            timestamp: '2025-01-01T00:00:00.000Z',
+            destination: ['user@example.com']
+          },
+          delivery: {
+            timestamp: '2025-01-01T00:00:00.000Z'
+          }
+        })
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.DELIVERED);
+    expect(result.recipient).toBe('user@example.com');
+    expect(result.provider).toBe(EmailProvider.AWS_SES);
+    expect(result.messageId).toBe('msg-123');
+  });
+
+  it('should normalize bounce event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.AWS_SES,
+      signature: 'test-signature',
+      payload: {
+        Message: JSON.stringify({
+          eventType: 'Bounce',
+          mail: {
+            messageId: 'msg-123',
+            timestamp: '2025-01-01T00:00:00.000Z',
+            destination: ['user@example.com']
+          },
+          bounce: {
+            bounceType: 'Permanent',
+            bouncedRecipients: [
+              {
+                emailAddress: 'user@example.com',
+                diagnosticCode: 'smtp; 550 5.1.1 user unknown'
+              }
+            ]
+          }
+        })
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.BOUNCED);
+    expect(result.recipient).toBe('user@example.com');
+    expect(result.metadata.bounceType).toBe('permanent');
+    expect(result.metadata.bounceReason).toBe('smtp; 550 5.1.1 user unknown');
+  });
+
+  it('should normalize complaint event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.AWS_SES,
+      signature: 'test-signature',
+      payload: {
+        Message: JSON.stringify({
+          eventType: 'Complaint',
+          mail: {
+            messageId: 'msg-123',
+            timestamp: '2025-01-01T00:00:00.000Z',
+            destination: ['user@example.com']
+          },
+          complaint: {
+            complainedRecipients: [
+              {
+                emailAddress: 'user@example.com'
+              }
+            ],
+            complaintFeedbackType: 'abuse'
+          }
+        })
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.COMPLAINED);
+    expect(result.recipient).toBe('user@example.com');
+    expect(result.metadata.complaintFeedbackType).toBe('abuse');
+  });
+
+  it('should normalize open event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.AWS_SES,
+      signature: 'test-signature',
+      payload: {
+        Message: JSON.stringify({
+          eventType: 'Open',
+          mail: {
+            messageId: 'msg-123',
+            timestamp: '2025-01-01T00:00:00.000Z',
+            destination: ['user@example.com']
+          },
+          open: {
+            ipAddress: '192.168.1.1',
+            userAgent: 'Mozilla/5.0'
+          }
+        })
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.OPENED);
+    expect(result.metadata.ipAddress).toBe('192.168.1.1');
+    expect(result.metadata.userAgent).toBe('Mozilla/5.0');
+  });
+
+  it('should normalize click event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.AWS_SES,
+      signature: 'test-signature',
+      payload: {
+        Message: JSON.stringify({
+          eventType: 'Click',
+          mail: {
+            messageId: 'msg-123',
+            timestamp: '2025-01-01T00:00:00.000Z',
+            destination: ['user@example.com']
+          },
+          click: {
+            link: 'https://example.com/link',
+            ipAddress: '192.168.1.1',
+            userAgent: 'Mozilla/5.0'
+          }
+        })
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.CLICKED);
+    expect(result.metadata.url).toBe('https://example.com/link');
+  });
+});