@bernierllc/email-tracking 1.0.0

package/__tests__/EmailTracking.test.ts

@@ -0,0 +1,334 @@
+/*
+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('EmailTracking', () => {
+  let tracking: EmailTracking;
+
+  beforeEach(async () => {
+    tracking = new EmailTracking({
+      enableOpenTracking: true,
+      enableClickTracking: true,
+      eventRetentionDays: 90,
+      aggregateStats: true
+    });
+    await tracking.initialize();
+  });
+
+  afterEach(async () => {
+    await tracking.clearDatabase();
+  });
+
+  describe('recordEmailSent', () => {
+    it('should record email send and create tracking ID', async () => {
+      const result = await tracking.recordEmailSent({
+        messageId: 'msg_123',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.data?.id).toMatch(/^track_/);
+      expect(result.data?.currentStatus).toBe(EmailDeliveryStatus.SENT);
+      expect(result.data?.messageId).toBe('msg_123');
+      expect(result.data?.provider).toBe('sendgrid');
+      expect(result.data?.from).toBe('sender@example.com');
+      expect(result.data?.to).toEqual(['recipient@example.com']);
+      expect(result.data?.subject).toBe('Test Email');
+    });
+
+    it('should record email with CC and BCC', async () => {
+      const result = await tracking.recordEmailSent({
+        messageId: 'msg_456',
+        provider: 'mailgun',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        cc: ['cc@example.com'],
+        bcc: ['bcc@example.com'],
+        subject: 'Test Email with CC/BCC'
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.data?.cc).toEqual(['cc@example.com']);
+      expect(result.data?.bcc).toEqual(['bcc@example.com']);
+    });
+
+    it('should record email with campaign ID and metadata', async () => {
+      const result = await tracking.recordEmailSent({
+        messageId: 'msg_789',
+        provider: 'ses',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Campaign Email',
+        campaignId: 'campaign_123',
+        metadata: { source: 'marketing', segment: 'premium' }
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.data?.campaignId).toBe('campaign_123');
+      expect(result.data?.metadata).toEqual({ source: 'marketing', segment: 'premium' });
+    });
+
+    it('should handle errors gracefully', async () => {
+      // Force an error by using invalid provider
+      const result = await tracking.recordEmailSent({
+        messageId: '',
+        provider: '',
+        from: '',
+        to: [],
+        subject: ''
+      });
+
+      // Should still return a result (even if it's an empty tracking record)
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe('processWebhookEvent', () => {
+    it('should link webhook event to send record', async () => {
+      // Record send
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_123',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      // Process webhook event
+      const webhookResult = await tracking.processWebhookEvent({
+        messageId: 'msg_123',
+        eventType: 'delivered',
+        timestamp: new Date().toISOString(),
+        metadata: { smtpResponse: '250 OK' }
+      });
+
+      expect(webhookResult.success).toBe(true);
+
+      // Check timeline
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.success).toBe(true);
+      expect(timeline.data?.events).toHaveLength(2); // sent + delivered
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.DELIVERED);
+    });
+
+    it('should handle missing send record gracefully', async () => {
+      const result = await tracking.processWebhookEvent({
+        messageId: 'unknown_msg',
+        eventType: 'delivered',
+        timestamp: new Date().toISOString()
+      });
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Send record not found');
+    });
+
+    it('should map webhook event types correctly', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_456',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      // Test bounce event
+      await tracking.processWebhookEvent({
+        messageId: 'msg_456',
+        eventType: 'bounce',
+        timestamp: new Date().toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.BOUNCED);
+    });
+
+    it('should handle spam report event', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_789',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: 'msg_789',
+        eventType: 'spamreport',
+        timestamp: new Date().toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+
+    it('should handle unsubscribe event', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_101',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: 'msg_101',
+        eventType: 'unsubscribe',
+        timestamp: new Date().toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.UNSUBSCRIBED);
+    });
+  });
+
+  describe('status priority', () => {
+    it('should handle status priority correctly', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_456',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      // Delivered
+      await tracking.processWebhookEvent({
+        messageId: 'msg_456',
+        eventType: 'delivered',
+        timestamp: new Date().toISOString()
+      });
+
+      let timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.DELIVERED);
+
+      // Opened (higher priority than delivered)
+      await tracking.processWebhookEvent({
+        messageId: 'msg_456',
+        eventType: 'open',
+        timestamp: new Date(Date.now() + 1000).toISOString()
+      });
+
+      timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.OPENED);
+
+      // Clicked (higher priority than opened)
+      await tracking.processWebhookEvent({
+        messageId: 'msg_456',
+        eventType: 'click',
+        timestamp: new Date(Date.now() + 2000).toISOString()
+      });
+
+      timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should not downgrade status to lower priority', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_999',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      // Clicked (high priority)
+      await tracking.processWebhookEvent({
+        messageId: 'msg_999',
+        eventType: 'click',
+        timestamp: new Date().toISOString()
+      });
+
+      // Try to set to delivered (lower priority) - should not change
+      await tracking.processWebhookEvent({
+        messageId: 'msg_999',
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + 1000).toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should prioritize complained status highest', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_888',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Test Email'
+      });
+
+      // Clicked
+      await tracking.processWebhookEvent({
+        messageId: 'msg_888',
+        eventType: 'click',
+        timestamp: new Date().toISOString()
+      });
+
+      // Spam complaint (highest priority)
+      await tracking.processWebhookEvent({
+        messageId: 'msg_888',
+        eventType: 'spamreport',
+        timestamp: new Date(Date.now() + 1000).toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.data?.currentStatus).toBe(EmailDeliveryStatus.COMPLAINED);
+    });
+  });
+
+  describe('getTimeline', () => {
+    it('should retrieve complete event timeline', async () => {
+      const sendResult = await tracking.recordEmailSent({
+        messageId: 'msg_timeline',
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: ['recipient@example.com'],
+        subject: 'Timeline Test'
+      });
+
+      // Add multiple events
+      await tracking.processWebhookEvent({
+        messageId: 'msg_timeline',
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + 1000).toISOString()
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: 'msg_timeline',
+        eventType: 'open',
+        timestamp: new Date(Date.now() + 2000).toISOString()
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: 'msg_timeline',
+        eventType: 'click',
+        timestamp: new Date(Date.now() + 3000).toISOString()
+      });
+
+      const timeline = await tracking.getTimeline(sendResult.data!.id);
+      expect(timeline.success).toBe(true);
+      expect(timeline.data?.events).toHaveLength(4); // sent + delivered + open + click
+      expect(timeline.data?.events[0].eventType).toBe(EmailDeliveryStatus.SENT);
+      expect(timeline.data?.events[1].eventType).toBe(EmailDeliveryStatus.DELIVERED);
+      expect(timeline.data?.events[2].eventType).toBe(EmailDeliveryStatus.OPENED);
+      expect(timeline.data?.events[3].eventType).toBe(EmailDeliveryStatus.CLICKED);
+    });
+
+    it('should return error for unknown tracking ID', async () => {
+      const timeline = await tracking.getTimeline('unknown_id');
+      expect(timeline.success).toBe(false);
+      expect(timeline.error).toBe('Send record not found');
+    });
+  });
+});

package/__tests__/campaign-stats.test.ts

@@ -0,0 +1,224 @@
+/*
+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('CampaignStatistics', () => {
+  let tracking: EmailTracking;
+
+  beforeEach(async () => {
+    tracking = new EmailTracking();
+    await tracking.initialize();
+  });
+
+  afterEach(async () => {
+    await tracking.clearDatabase();
+  });
+
+  it('should calculate campaign statistics correctly', async () => {
+    const campaignId = 'campaign_123';
+
+    // Send 10 emails for campaign
+    for (let i = 0; i < 10; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_camp_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`recipient${i}@example.com`],
+        subject: 'Campaign Email',
+        campaignId
+      });
+
+      // 8 delivered
+      if (i < 8) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_camp_${i}`,
+          eventType: 'delivered',
+          timestamp: new Date(Date.now() + i * 1000).toISOString()
+        });
+      }
+
+      // 2 bounced
+      if (i >= 8) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_camp_${i}`,
+          eventType: 'bounce',
+          timestamp: new Date(Date.now() + i * 1000).toISOString()
+        });
+      }
+
+      // 5 opened
+      if (i < 5) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_camp_${i}`,
+          eventType: 'open',
+          timestamp: new Date(Date.now() + (i + 1) * 1000).toISOString()
+        });
+      }
+
+      // 2 clicked
+      if (i < 2) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_camp_${i}`,
+          eventType: 'click',
+          timestamp: new Date(Date.now() + (i + 2) * 1000).toISOString()
+        });
+      }
+    }
+
+    const stats = await tracking.getCampaignStats(campaignId);
+    expect(stats.success).toBe(true);
+    expect(stats.data?.campaignId).toBe(campaignId);
+    expect(stats.data?.totalSent).toBe(10);
+    expect(stats.data?.totalDelivered).toBe(8); // includes opened and clicked
+    expect(stats.data?.totalBounced).toBe(2);
+    expect(stats.data?.totalOpened).toBe(5); // includes clicked
+    expect(stats.data?.totalClicked).toBe(2);
+    expect(stats.data?.deliveryRate).toBe(80); // 8/10 * 100
+    expect(stats.data?.openRate).toBe(62.5); // 5/8 * 100
+    expect(stats.data?.clickRate).toBe(40); // 2/5 * 100
+  });
+
+  it('should handle campaign with no deliveries', async () => {
+    const campaignId = 'campaign_fail';
+
+    // All bounces
+    for (let i = 0; i < 5; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_fail_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`bad${i}@example.com`],
+        subject: 'Failed Campaign',
+        campaignId
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: `msg_fail_${i}`,
+        eventType: 'bounce',
+        timestamp: new Date(Date.now() + i * 1000).toISOString()
+      });
+    }
+
+    const stats = await tracking.getCampaignStats(campaignId);
+    expect(stats.success).toBe(true);
+    expect(stats.data?.totalSent).toBe(5);
+    expect(stats.data?.totalDelivered).toBe(0);
+    expect(stats.data?.totalBounced).toBe(5);
+    expect(stats.data?.deliveryRate).toBe(0);
+    expect(stats.data?.openRate).toBe(0);
+    expect(stats.data?.clickRate).toBe(0);
+  });
+
+  it('should handle empty campaign', async () => {
+    const stats = await tracking.getCampaignStats('empty_campaign');
+    expect(stats.success).toBe(true);
+    expect(stats.data?.totalSent).toBe(0);
+    expect(stats.data?.deliveryRate).toBe(0);
+  });
+
+  it('should track spam complaints in campaign', async () => {
+    const campaignId = 'campaign_spam';
+
+    for (let i = 0; i < 5; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_spam_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`user${i}@example.com`],
+        subject: 'Spam Test',
+        campaignId
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: `msg_spam_${i}`,
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + i * 1000).toISOString()
+      });
+
+      // 2 complaints
+      if (i < 2) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_spam_${i}`,
+          eventType: 'spamreport',
+          timestamp: new Date(Date.now() + (i + 1) * 1000).toISOString()
+        });
+      }
+    }
+
+    const stats = await tracking.getCampaignStats(campaignId);
+    expect(stats.success).toBe(true);
+    expect(stats.data?.totalComplained).toBe(2);
+  });
+
+  it('should track unsubscribes in campaign', async () => {
+    const campaignId = 'campaign_unsub';
+
+    for (let i = 0; i < 5; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_unsub_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`user${i}@example.com`],
+        subject: 'Unsubscribe Test',
+        campaignId
+      });
+
+      await tracking.processWebhookEvent({
+        messageId: `msg_unsub_${i}`,
+        eventType: 'delivered',
+        timestamp: new Date(Date.now() + i * 1000).toISOString()
+      });
+
+      // 1 unsubscribe
+      if (i === 0) {
+        await tracking.processWebhookEvent({
+          messageId: `msg_unsub_${i}`,
+          eventType: 'unsubscribe',
+          timestamp: new Date(Date.now() + (i + 1) * 1000).toISOString()
+        });
+      }
+    }
+
+    const stats = await tracking.getCampaignStats(campaignId);
+    expect(stats.success).toBe(true);
+    expect(stats.data?.totalUnsubscribed).toBe(1);
+  });
+
+  it('should only count emails for specified campaign', async () => {
+    // Campaign A
+    for (let i = 0; i < 3; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_a_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`user${i}@example.com`],
+        subject: 'Campaign A',
+        campaignId: 'campaign_a'
+      });
+    }
+
+    // Campaign B
+    for (let i = 0; i < 5; i++) {
+      await tracking.recordEmailSent({
+        messageId: `msg_b_${i}`,
+        provider: 'sendgrid',
+        from: 'sender@example.com',
+        to: [`user${i}@example.com`],
+        subject: 'Campaign B',
+        campaignId: 'campaign_b'
+      });
+    }
+
+    const statsA = await tracking.getCampaignStats('campaign_a');
+    const statsB = await tracking.getCampaignStats('campaign_b');
+
+    expect(statsA.data?.totalSent).toBe(3);
+    expect(statsB.data?.totalSent).toBe(5);
+  });
+});

package/__tests__/config.test.ts

@@ -0,0 +1,108 @@
+/*
+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 { loadConfig } from '../src/config';
+
+describe('Config', () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    jest.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it('should use default values when no config provided', () => {
+    const config = loadConfig();
+    expect(config.enableOpenTracking).toBe(true);
+    expect(config.enableClickTracking).toBe(true);
+    expect(config.eventRetentionDays).toBe(90);
+    expect(config.aggregateStats).toBe(true);
+  });
+
+  it('should use user config over defaults', () => {
+    const config = loadConfig({
+      enableOpenTracking: false,
+      enableClickTracking: false,
+      eventRetentionDays: 30,
+      aggregateStats: false
+    });
+
+    expect(config.enableOpenTracking).toBe(false);
+    expect(config.enableClickTracking).toBe(false);
+    expect(config.eventRetentionDays).toBe(30);
+    expect(config.aggregateStats).toBe(false);
+  });
+
+  it('should read from environment variables', () => {
+    process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING = 'false';
+    process.env.EMAIL_TRACKING_ENABLE_CLICK_TRACKING = 'false';
+    process.env.EMAIL_TRACKING_EVENT_RETENTION_DAYS = '60';
+    process.env.EMAIL_TRACKING_AGGREGATE_STATS = 'false';
+
+    const config = loadConfig();
+    expect(config.enableOpenTracking).toBe(false);
+    expect(config.enableClickTracking).toBe(false);
+    expect(config.eventRetentionDays).toBe(60);
+    expect(config.aggregateStats).toBe(false);
+  });
+
+  it('should prioritize user config over environment variables', () => {
+    process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING = 'false';
+    process.env.EMAIL_TRACKING_EVENT_RETENTION_DAYS = '30';
+
+    const config = loadConfig({
+      enableOpenTracking: true,
+      eventRetentionDays: 120
+    });
+
+    expect(config.enableOpenTracking).toBe(true);
+    expect(config.eventRetentionDays).toBe(120);
+  });
+
+  it('should handle partial user config', () => {
+    const config = loadConfig({
+      enableOpenTracking: false
+    });
+
+    expect(config.enableOpenTracking).toBe(false);
+    expect(config.enableClickTracking).toBe(true); // Default
+    expect(config.eventRetentionDays).toBe(90); // Default
+    expect(config.aggregateStats).toBe(true); // Default
+  });
+
+  it('should parse retention days as integer', () => {
+    process.env.EMAIL_TRACKING_EVENT_RETENTION_DAYS = '45';
+    const config = loadConfig();
+    expect(config.eventRetentionDays).toBe(45);
+    expect(typeof config.eventRetentionDays).toBe('number');
+  });
+
+  it('should handle invalid retention days gracefully', () => {
+    process.env.EMAIL_TRACKING_EVENT_RETENTION_DAYS = 'invalid';
+    const config = loadConfig();
+    expect(isNaN(config.eventRetentionDays)).toBe(true);
+  });
+
+  it('should handle boolean environment variables correctly', () => {
+    process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING = 'true';
+    const config1 = loadConfig();
+    expect(config1.enableOpenTracking).toBe(true);
+
+    process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING = 'false';
+    const config2 = loadConfig();
+    expect(config2.enableOpenTracking).toBe(false);
+
+    process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING = 'anything';
+    const config3 = loadConfig();
+    expect(config3.enableOpenTracking).toBe(false);
+  });
+});