@bernierllc/email-webhook-events 1.0.0

package/__tests__/normalizers/SMTP2GONormalizer.test.ts

@@ -0,0 +1,83 @@
+/*
+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 { SMTP2GONormalizer } from '../../src/normalizers/SMTP2GONormalizer';
+import { EmailEventType, EmailProvider, WebhookPayload } from '../../src/types';
+
+describe('SMTP2GONormalizer', () => {
+  let normalizer: SMTP2GONormalizer;
+
+  beforeEach(() => {
+    normalizer = new SMTP2GONormalizer();
+  });
+
+  it('should normalize delivered event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SMTP2GO,
+      signature: 'test-signature',
+      payload: {
+        event: 'delivered',
+        message_id: 'msg-123',
+        email_id: 'email-456',
+        rcpt_to: 'user@example.com',
+        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.SMTP2GO);
+    expect(result.messageId).toBe('msg-123');
+    expect(result.emailId).toBe('email-456');
+  });
+
+  it('should normalize bounce event with hard bounce', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SMTP2GO,
+      signature: 'test-signature',
+      payload: {
+        event: 'bounce',
+        message_id: 'msg-123',
+        rcpt_to: 'user@example.com',
+        timestamp: '2025-01-01T00:00:00.000Z',
+        bounce_type: 'hard bounce',
+        reason: '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 failed event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SMTP2GO,
+      signature: 'test-signature',
+      payload: {
+        event: 'failed',
+        message_id: 'msg-123',
+        rcpt_to: 'user@example.com',
+        timestamp: '2025-01-01T00:00:00.000Z',
+        reason: 'SMTP error'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.FAILED);
+    expect(result.metadata.failureReason).toBe('SMTP error');
+  });
+});

package/__tests__/normalizers/SendGridNormalizer.test.ts

@@ -0,0 +1,181 @@
+/*
+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 { SendGridNormalizer } from '../../src/normalizers/SendGridNormalizer';
+import { EmailEventType, EmailProvider, WebhookPayload } from '../../src/types';
+
+describe('SendGridNormalizer', () => {
+  let normalizer: SendGridNormalizer;
+
+  beforeEach(() => {
+    normalizer = new SendGridNormalizer();
+  });
+
+  it('should normalize delivered event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'delivered',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        email_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.SENDGRID);
+    expect(result.messageId).toBe('msg-123');
+    expect(result.emailId).toBe('email-456');
+    expect(result.timestamp).toEqual(new Date(1234567890000));
+  });
+
+  it('should normalize open event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'open',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        useragent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) mobile'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.OPENED);
+    expect(result.metadata.deviceType).toBe('mobile');
+  });
+
+  it('should normalize click event with URL', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'click',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        url: 'https://example.com/link'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.CLICKED);
+    expect(result.metadata.url).toBe('https://example.com/link');
+  });
+
+  it('should normalize bounce event with hard bounce', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'bounce',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        status: '5.1.1',
+        reason: '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 bounce event with soft bounce', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'bounce',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        status: '4.2.2',
+        reason: 'Mailbox full'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.BOUNCED);
+    expect(result.metadata.bounceType).toBe('soft');
+  });
+
+  it('should normalize spam complaint event', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'spamreport',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.type).toBe(EmailEventType.COMPLAINED);
+  });
+
+  it('should detect tablet device type', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'open',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        useragent: 'Mozilla/5.0 (iPad; CPU OS 14_0 like Mac OS X)'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.metadata.deviceType).toBe('tablet');
+  });
+
+  it('should detect desktop device type', () => {
+    const webhook: WebhookPayload = {
+      provider: EmailProvider.SENDGRID,
+      signature: 'test-signature',
+      payload: {
+        event: 'open',
+        email: 'user@example.com',
+        timestamp: 1234567890,
+        sg_message_id: 'msg-123',
+        useragent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+      },
+      headers: {}
+    };
+
+    const result = normalizer.normalize(webhook);
+
+    expect(result.metadata.deviceType).toBe('desktop');
+  });
+});

package/__tests__/persistence/PersistenceAdapter.test.ts

@@ -0,0 +1,103 @@
+/*
+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 { InMemoryPersistenceAdapter } from '../../src/persistence/InMemoryPersistenceAdapter';
+import { EmailEvent, EmailEventType, EmailProvider } from '../../src/types';
+
+describe('InMemoryPersistenceAdapter', () => {
+  let adapter: InMemoryPersistenceAdapter;
+
+  beforeEach(() => {
+    adapter = new InMemoryPersistenceAdapter();
+  });
+
+  const createEvent = (overrides: Partial<EmailEvent> = {}): EmailEvent => ({
+    id: `event-${Math.random()}`,
+    emailId: 'email-123',
+    messageId: 'msg-123',
+    type: EmailEventType.DELIVERED,
+    recipient: 'user@example.com',
+    timestamp: new Date(),
+    provider: EmailProvider.SENDGRID,
+    metadata: {},
+    ...overrides
+  });
+
+  it('should save and retrieve events', async () => {
+    const event = createEvent();
+    await adapter.saveEvent(event);
+
+    const results = await adapter.queryEvents({});
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe(event.id);
+  });
+
+  it('should query events by email ID', async () => {
+    await adapter.saveEvent(createEvent({ emailId: 'email-1' }));
+    await adapter.saveEvent(createEvent({ emailId: 'email-2' }));
+
+    const results = await adapter.queryEvents({ emailId: 'email-1' });
+    expect(results).toHaveLength(1);
+    expect(results[0].emailId).toBe('email-1');
+  });
+
+  it('should query events by recipient', async () => {
+    await adapter.saveEvent(createEvent({ recipient: 'user1@example.com' }));
+    await adapter.saveEvent(createEvent({ recipient: 'user2@example.com' }));
+
+    const results = await adapter.queryEvents({ recipient: 'user1@example.com' });
+    expect(results).toHaveLength(1);
+    expect(results[0].recipient).toBe('user1@example.com');
+  });
+
+  it('should query events by event types', async () => {
+    await adapter.saveEvent(createEvent({ type: EmailEventType.DELIVERED }));
+    await adapter.saveEvent(createEvent({ type: EmailEventType.OPENED }));
+
+    const results = await adapter.queryEvents({
+      eventTypes: [EmailEventType.DELIVERED]
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0].type).toBe(EmailEventType.DELIVERED);
+  });
+
+  it('should query events by date range', async () => {
+    await adapter.saveEvent(createEvent({ timestamp: new Date('2025-01-01') }));
+    await adapter.saveEvent(createEvent({ timestamp: new Date('2025-06-01') }));
+    await adapter.saveEvent(createEvent({ timestamp: new Date('2025-12-01') }));
+
+    const results = await adapter.queryEvents({
+      startDate: new Date('2025-05-01'),
+      endDate: new Date('2025-07-01')
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0].timestamp).toEqual(new Date('2025-06-01'));
+  });
+
+  it('should apply limit and offset', async () => {
+    await adapter.saveEvent(createEvent());
+    await adapter.saveEvent(createEvent());
+    await adapter.saveEvent(createEvent());
+    await adapter.saveEvent(createEvent());
+
+    const results = await adapter.queryEvents({ limit: 2, offset: 1 });
+    expect(results).toHaveLength(2);
+  });
+
+  it('should clear all events', async () => {
+    await adapter.saveEvent(createEvent());
+    await adapter.saveEvent(createEvent());
+
+    expect(adapter.getEventCount()).toBe(2);
+
+    adapter.clearEvents();
+    expect(adapter.getEventCount()).toBe(0);
+  });
+});