@bernierllc/email-tracking 1.0.0

package/__tests__/integration.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 { EmailTracking } from '../src/EmailTracking';
+import { EmailDeliveryStatus } from '../src/types';
+
+describe('Integration', () => {
+  let tracking: EmailTracking;
+
+  beforeEach(async () => {
+    tracking = new EmailTracking();
+    await tracking.initialize();
+  });
+
+  afterEach(async () => {
+    await tracking.clearDatabase();
+  });
+
+  it('should handle complete email lifecycle', async () => {
+    // Send email
+    const sendResult = await tracking.recordEmailSent({
+      messageId: 'integration_msg',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: ['recipient@example.com'],
+      subject: 'Integration Test',
+      campaignId: 'integration_campaign'
+    });
+
+    expect(sendResult.success).toBe(true);
+    expect(sendResult.data?.currentStatus).toBe(EmailDeliveryStatus.SENT);
+
+    // Delivered
+    await tracking.processWebhookEvent({
+      messageId: 'integration_msg',
+      eventType: 'delivered',
+      timestamp: new Date().toISOString()
+    });
+
+    // Opened
+    await tracking.processWebhookEvent({
+      messageId: 'integration_msg',
+      eventType: 'open',
+      timestamp: new Date().toISOString()
+    });
+
+    // Clicked
+    await tracking.processWebhookEvent({
+      messageId: 'integration_msg',
+      eventType: 'click',
+      timestamp: new Date().toISOString()
+    });
+
+    // Check timeline
+    const timeline = await tracking.getTimeline(sendResult.data!.id);
+    expect(timeline.success).toBe(true);
+    expect(timeline.data?.events).toHaveLength(4);
+    expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.CLICKED);
+
+    // Check recipient history
+    const history = await tracking.getRecipientHistory('recipient@example.com');
+    expect(history.success).toBe(true);
+    expect(history.data?.totalSent).toBe(1);
+    expect(history.data?.totalClicked).toBe(1);
+
+    // Check campaign stats
+    const stats = await tracking.getCampaignStats('integration_campaign');
+    expect(stats.success).toBe(true);
+    expect(stats.data?.totalSent).toBe(1);
+    expect(stats.data?.totalClicked).toBe(1);
+  });
+
+  it('should work without NeverHub', async () => {
+    // Tests already run with NeverHub mocked to return false
+    const trackingNoHub = new EmailTracking();
+    await trackingNoHub.initialize();
+
+    const result = await trackingNoHub.recordEmailSent({
+      messageId: 'no_hub_msg',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: ['test@example.com'],
+      subject: 'No Hub Test'
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.data?.id).toBeDefined();
+  });
+
+  it('should handle edge cases', async () => {
+    // Empty campaign stats
+    const emptyStats = await tracking.getCampaignStats('nonexistent_campaign');
+    expect(emptyStats.success).toBe(true);
+    expect(emptyStats.data?.totalSent).toBe(0);
+
+    // Unknown timeline
+    const unknownTimeline = await tracking.getTimeline('unknown_id');
+    expect(unknownTimeline.success).toBe(false);
+
+    // Unknown recipient
+    const unknownHistory = await tracking.getRecipientHistory('unknown@example.com');
+    expect(unknownHistory.success).toBe(true);
+    expect(unknownHistory.data?.totalSent).toBe(0);
+  });
+
+  it('should handle multiple initialization calls', async () => {
+    const tracker = new EmailTracking();
+    await tracker.initialize();
+    await tracker.initialize(); // Should not throw
+
+    const result = await tracker.recordEmailSent({
+      messageId: 'multi_init_msg',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: ['test@example.com'],
+      subject: 'Multi Init Test'
+    });
+
+    expect(result.success).toBe(true);
+  });
+
+  it('should handle all provider types', async () => {
+    const providers = ['sendgrid', 'mailgun', 'ses', 'postmark'];
+
+    for (const provider of providers) {
+      const result = await tracking.recordEmailSent({
+        messageId: `${provider}_msg`,
+        provider,
+        from: 'sender@example.com',
+        to: ['test@example.com'],
+        subject: `${provider} Test`
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.data?.provider).toBe(provider);
+    }
+  });
+
+  it('should handle different event type formats', async () => {
+    // Send email
+    await tracking.recordEmailSent({
+      messageId: 'format_test',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: ['test@example.com'],
+      subject: 'Format Test'
+    });
+
+    // Test case-insensitive event types
+    const eventTypes = ['Delivered', 'BOUNCE', 'Open', 'CLICK'];
+
+    for (const eventType of eventTypes) {
+      await tracking.processWebhookEvent({
+        messageId: 'format_test',
+        eventType,
+        timestamp: new Date().toISOString()
+      });
+    }
+
+    // Should handle all events without error
+    // Process should not throw even with unknown message IDs
+  });
+
+  it('should calculate reputation scores correctly', async () => {
+    const recipient = 'reputation@example.com';
+
+    // Send and deliver
+    await tracking.recordEmailSent({
+      messageId: 'rep_1',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Rep Test 1'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'rep_1',
+      eventType: 'delivered',
+      timestamp: new Date().toISOString()
+    });
+
+    let history = await tracking.getRecipientHistory(recipient);
+    expect(history.data?.reputationScore).toBe(100);
+
+    // Bounce - reduces by 10
+    await tracking.recordEmailSent({
+      messageId: 'rep_2',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Rep Test 2'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'rep_2',
+      eventType: 'bounce',
+      timestamp: new Date().toISOString()
+    });
+
+    history = await tracking.getRecipientHistory(recipient);
+    expect(history.data?.reputationScore).toBe(90);
+
+    // Spam complaint - reduces by 25
+    await tracking.recordEmailSent({
+      messageId: 'rep_3',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Rep Test 3'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'rep_3',
+      eventType: 'spamreport',
+      timestamp: new Date().toISOString()
+    });
+
+    history = await tracking.getRecipientHistory(recipient);
+    expect(history.data?.reputationScore).toBe(65);
+
+    // Unsubscribe - reduces by 5
+    await tracking.recordEmailSent({
+      messageId: 'rep_4',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Rep Test 4'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'rep_4',
+      eventType: 'unsubscribe',
+      timestamp: new Date().toISOString()
+    });
+
+    history = await tracking.getRecipientHistory(recipient);
+    expect(history.data?.reputationScore).toBe(60);
+  });
+});

package/__tests__/recipient-history.test.ts

@@ -0,0 +1,210 @@
+/*
+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 { EmailTracking } from '../src/EmailTracking';
+
+describe('RecipientHistory', () => {
+  let tracking: EmailTracking;
+
+  beforeEach(async () => {
+    tracking = new EmailTracking({ aggregateStats: true });
+    await tracking.initialize();
+  });
+
+  afterEach(async () => {
+    await tracking.clearDatabase();
+  });
+
+  it('should track recipient history across multiple emails', async () => {
+    const recipient = 'frequent@example.com';
+
+    // Send multiple emails
+    for (let i = 0; i < 5; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [recipient],
+        subject: `Test Email ${i}`
+      });
+
+      // Simulate delivery
+      await tracking.processWebhookEvent({
+        messageId: `msg_${i}`,
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + i * 1000).toISOString()
+      });
+
+      // Simulate opens (3 out of 5)
+      if (i < 3) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_${i}`,
+          eventType: 'open',
+          timestamp: new Date(Date.now() + (i + 1) * 1000).toISOString()
+        });
+      }
+    }
+
+    const history = await tracking.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalSent).toBe(5);
+    expect(history.data?.totalDelivered).toBe(5);
+    expect(history.data?.totalOpened).toBe(3);
+    expect(history.data?.emailAddress).toBe(recipient);
+  });
+
+  it('should track bounces and reduce reputation score', async () => {
+    const recipient = 'bouncy@example.com';
+
+    // Send email
+    await tracking.recordEmailSent({
+      messageId: 'msg_bounce',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Bounce Test'
+    });
+
+    // Simulate bounce
+    await tracking.processWebhookEvent({
+      messageId: 'msg_bounce',
+      eventType: 'bounce',
+      timestamp: new Date().toISOString()
+    });
+
+    const history = await tracking.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalBounced).toBe(1);
+    expect(history.data?.reputationScore).toBeLessThan(100);
+    expect(history.data?.lastBouncedAt).toBeDefined();
+  });
+
+  it('should track spam complaints and severely reduce reputation', async () => {
+    const recipient = 'complainer@example.com';
+
+    await tracking.recordEmailSent({
+      messageId: 'msg_spam',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Spam Test'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'msg_spam',
+      eventType: 'spamreport',
+      timestamp: new Date().toISOString()
+    });
+
+    const history = await tracking.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalComplained).toBe(1);
+    expect(history.data?.reputationScore).toBeLessThan(80); // -25 penalty
+  });
+
+  it('should track clicks separately', async () => {
+    const recipient = 'clicker@example.com';
+
+    for (let i = 0; i < 3; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_click_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [recipient],
+        subject: `Click Test ${i}`
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: `msg_click_${i}`,
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + i * 1000).toISOString()
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: `msg_click_${i}`,
+        eventType: 'click',
+        timestamp: new Date(Date.now() + (i + 1) * 1000).toISOString()
+      });
+    }
+
+    const history = await tracking.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalSent).toBe(3);
+    expect(history.data?.totalClicked).toBe(3);
+    expect(history.data?.lastClickedAt).toBeDefined();
+  });
+
+  it('should return default history for unknown recipient', async () => {
+    const history = await tracking.getRecipientHistory('unknown@example.com');
+    expect(history.success).toBe(true);
+    expect(history.data?.totalSent).toBe(0);
+    expect(history.data?.totalDelivered).toBe(0);
+    expect(history.data?.reputationScore).toBe(100);
+  });
+
+  it('should track unsubscribes', async () => {
+    const recipient = 'unsubscribe@example.com';
+
+    await tracking.recordEmailSent({
+      messageId: 'msg_unsub',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'Unsubscribe Test'
+    });
+
+    await tracking.processWebhookEvent({
+      messageId: 'msg_unsub',
+      eventType: 'unsubscribe',
+      timestamp: new Date().toISOString()
+    });
+
+    const history = await tracking.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalUnsubscribed).toBe(1);
+    expect(history.data?.reputationScore).toBeLessThan(100); // -5 penalty
+  });
+
+  it('should handle multiple recipients in single email', async () => {
+    const recipients = ['user1@example.com', 'user2@example.com', 'user3@example.com'];
+
+    await tracking.recordEmailSent({
+      messageId: 'msg_multi',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: recipients,
+      subject: 'Multi Recipient Test'
+    });
+
+    // Check all recipients have updated history
+    for (const recipient of recipients) {
+      const history = await tracking.getRecipientHistory(recipient);
+      expect(history.success).toBe(true);
+      expect(history.data?.totalSent).toBe(1);
+    }
+  });
+
+  it('should not aggregate stats when disabled', async () => {
+    const trackingNoStats = new EmailTracking({ aggregateStats: false });
+    await trackingNoStats.initialize();
+
+    const recipient = 'nostats@example.com';
+
+    await trackingNoStats.recordEmailSent({
+      messageId: 'msg_nostats',
+      provider: 'sendgrid',
+      from: 'sender@example.com',
+      to: [recipient],
+      subject: 'No Stats Test'
+    });
+
+    const history = await trackingNoStats.getRecipientHistory(recipient);
+    expect(history.success).toBe(true);
+    expect(history.data?.totalSent).toBe(0); // No stats aggregated
+  });
+});

package/__tests__/status-calculator.test.ts

@@ -0,0 +1,141 @@
+/*
+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 { calculateNewStatus, mapWebhookEventType } from '../src/status-calculator';
+import { EmailDeliveryStatus } from '../src/types';
+
+describe('StatusCalculator', () => {
+  describe('calculateNewStatus', () => {
+    it('should upgrade from sent to delivered', () => {
+      const newStatus = calculateNewStatus(
+        EmailDeliveryStatus.SENT,
+        EmailDeliveryStatus.DELIVERED
+      );
+      expect(newStatus).toBe(EmailDeliveryStatus.DELIVERED);
+    });
+
+    it('should upgrade from delivered to opened', () => {
+      const newStatus = calculateNewStatus(
+        EmailDeliveryStatus.DELIVERED,
+        EmailDeliveryStatus.OPENED
+      );
+      expect(newStatus).toBe(EmailDeliveryStatus.OPENED);
+    });
+
+    it('should upgrade from opened to clicked', () => {
+      const newStatus = calculateNewStatus(
+        EmailDeliveryStatus.OPENED,
+        EmailDeliveryStatus.CLICKED
+      );
+      expect(newStatus).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should not downgrade from clicked to delivered', () => {
+      const newStatus = calculateNewStatus(
+        EmailDeliveryStatus.CLICKED,
+        EmailDeliveryStatus.DELIVERED
+      );
+      expect(newStatus).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should not downgrade from opened to delivered', () => {
+      const newStatus = calculateNewStatus(
+        EmailDeliveryStatus.OPENED,
+        EmailDeliveryStatus.DELIVERED
+      );
+      expect(newStatus).toBe(EmailDeliveryStatus.OPENED);
+    });
+
+    it('should upgrade to bounced from any lower status', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.SENT, EmailDeliveryStatus.BOUNCED))
+        .toBe(EmailDeliveryStatus.BOUNCED);
+      expect(calculateNewStatus(EmailDeliveryStatus.DELIVERED, EmailDeliveryStatus.BOUNCED))
+        .toBe(EmailDeliveryStatus.BOUNCED);
+      expect(calculateNewStatus(EmailDeliveryStatus.OPENED, EmailDeliveryStatus.BOUNCED))
+        .toBe(EmailDeliveryStatus.BOUNCED);
+    });
+
+    it('should upgrade to complained from any lower status', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.SENT, EmailDeliveryStatus.COMPLAINED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+      expect(calculateNewStatus(EmailDeliveryStatus.CLICKED, EmailDeliveryStatus.COMPLAINED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+      expect(calculateNewStatus(EmailDeliveryStatus.BOUNCED, EmailDeliveryStatus.COMPLAINED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should not downgrade from complained', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.COMPLAINED, EmailDeliveryStatus.CLICKED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+      expect(calculateNewStatus(EmailDeliveryStatus.COMPLAINED, EmailDeliveryStatus.BOUNCED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should upgrade to unsubscribed from lower statuses', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.SENT, EmailDeliveryStatus.UNSUBSCRIBED))
+        .toBe(EmailDeliveryStatus.UNSUBSCRIBED);
+      expect(calculateNewStatus(EmailDeliveryStatus.CLICKED, EmailDeliveryStatus.UNSUBSCRIBED))
+        .toBe(EmailDeliveryStatus.UNSUBSCRIBED);
+    });
+
+    it('should not downgrade from unsubscribed except to complained', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.UNSUBSCRIBED, EmailDeliveryStatus.CLICKED))
+        .toBe(EmailDeliveryStatus.UNSUBSCRIBED);
+      expect(calculateNewStatus(EmailDeliveryStatus.UNSUBSCRIBED, EmailDeliveryStatus.COMPLAINED))
+        .toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should handle failed status', () => {
+      expect(calculateNewStatus(EmailDeliveryStatus.SENT, EmailDeliveryStatus.FAILED))
+        .toBe(EmailDeliveryStatus.FAILED);
+      expect(calculateNewStatus(EmailDeliveryStatus.FAILED, EmailDeliveryStatus.BOUNCED))
+        .toBe(EmailDeliveryStatus.BOUNCED);
+    });
+  });
+
+  describe('mapWebhookEventType', () => {
+    it('should map delivered event', () => {
+      expect(mapWebhookEventType('delivered')).toBe(EmailDeliveryStatus.DELIVERED);
+    });
+
+    it('should map bounce event', () => {
+      expect(mapWebhookEventType('bounce')).toBe(EmailDeliveryStatus.BOUNCED);
+    });
+
+    it('should map open event', () => {
+      expect(mapWebhookEventType('open')).toBe(EmailDeliveryStatus.OPENED);
+    });
+
+    it('should map click event', () => {
+      expect(mapWebhookEventType('click')).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should map spamreport event', () => {
+      expect(mapWebhookEventType('spamreport')).toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should map unsubscribe event', () => {
+      expect(mapWebhookEventType('unsubscribe')).toBe(EmailDeliveryStatus.UNSUBSCRIBED);
+    });
+
+    it('should map failed event', () => {
+      expect(mapWebhookEventType('failed')).toBe(EmailDeliveryStatus.FAILED);
+    });
+
+    it('should handle case-insensitive mapping', () => {
+      expect(mapWebhookEventType('DELIVERED')).toBe(EmailDeliveryStatus.DELIVERED);
+      expect(mapWebhookEventType('Bounce')).toBe(EmailDeliveryStatus.BOUNCED);
+      expect(mapWebhookEventType('SpamReport')).toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should default to SENT for unknown event types', () => {
+      expect(mapWebhookEventType('unknown')).toBe(EmailDeliveryStatus.SENT);
+      expect(mapWebhookEventType('invalid_event')).toBe(EmailDeliveryStatus.SENT);
+    });
+  });
+});