@bernierllc/email-webhook-events 1.0.0

package/.eslintrc.cjs

@@ -0,0 +1,29 @@
+/*
+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.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json',
+  },
+  plugins: ['@typescript-eslint'],
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:@typescript-eslint/recommended-requiring-type-checking',
+  ],
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'warn',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/strict-boolean-expressions': 'off',
+  },
+  ignorePatterns: ['dist/', 'node_modules/', '*.cjs'],
+};

package/README.md

@@ -0,0 +1,349 @@
+# @bernierllc/email-webhook-events
+
+Email event tracking, normalization, and analytics service for processing webhooks from all email providers (SendGrid, Mailgun, AWS SES, Postmark, SMTP2GO). Provides unified event format, real-time notifications, and comprehensive analytics aggregation.
+
+## Installation
+
+```bash
+npm install @bernierllc/email-webhook-events
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { EmailWebhookEventsService, EmailProvider } from '@bernierllc/email-webhook-events';
+
+const service = new EmailWebhookEventsService({
+  providers: [
+    {
+      provider: EmailProvider.SENDGRID,
+      enabled: true,
+      webhookUrl: '/webhooks/sendgrid',
+      secretKey: process.env.SENDGRID_WEBHOOK_SECRET!,
+      signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
+      signatureAlgorithm: 'sha256'
+    },
+    {
+      provider: EmailProvider.MAILGUN,
+      enabled: true,
+      webhookUrl: '/webhooks/mailgun',
+      secretKey: process.env.MAILGUN_WEBHOOK_SECRET!,
+      signatureHeader: 'X-Mailgun-Signature',
+      signatureAlgorithm: 'sha256'
+    }
+  ],
+  persistence: {
+    enabled: true,
+    adapter: 'memory' // or 'supabase', 'postgresql', 'mongodb'
+  },
+  analytics: {
+    realTimeEnabled: true,
+    aggregationInterval: 5000,
+    retentionDays: 90
+  },
+  notifications: {
+    enabled: true,
+    criticalEvents: ['bounced', 'complained', 'failed'],
+    channels: [
+      { type: 'neverhub', config: {} }
+    ]
+  }
+});
+
+await service.initialize();
+```
+
+### Processing Webhooks
+
+```typescript
+// Express.js example
+app.post('/webhooks/sendgrid', async (req, res) => {
+  const webhook = {
+    provider: EmailProvider.SENDGRID,
+    signature: req.headers['x-twilio-email-event-webhook-signature'],
+    payload: req.body,
+    headers: req.headers
+  };
+
+  const result = await service.processWebhook(webhook);
+
+  if (result.success) {
+    res.status(200).json({ message: 'Event processed' });
+  } else {
+    res.status(400).json({ error: result.error });
+  }
+});
+```
+
+### Querying Analytics
+
+```typescript
+// Get analytics for the last 30 days
+const startDate = new Date();
+startDate.setDate(startDate.getDate() - 30);
+const endDate = new Date();
+
+const analytics = await service.getAnalytics(startDate, endDate);
+
+console.log(`Delivery rate: ${(analytics.deliveryRate * 100).toFixed(2)}%`);
+console.log(`Open rate: ${(analytics.openRate * 100).toFixed(2)}%`);
+console.log(`Click rate: ${(analytics.clickRate * 100).toFixed(2)}%`);
+console.log(`Bounce rate: ${(analytics.bounceRate * 100).toFixed(2)}%`);
+
+// Filter by provider
+const sendgridAnalytics = await service.getAnalytics(
+  startDate,
+  endDate,
+  { provider: EmailProvider.SENDGRID }
+);
+
+// Filter by event type
+const bounceAnalytics = await service.getAnalytics(
+  startDate,
+  endDate,
+  { eventTypes: ['bounced'] }
+);
+```
+
+### Querying Events
+
+```typescript
+// Get all events for a specific email
+const emailEvents = await service.getEventsForEmail('email-123');
+
+// Query events with filters
+const events = await service.queryEvents({
+  recipient: 'user@example.com',
+  eventTypes: ['opened', 'clicked'],
+  startDate: new Date('2025-01-01'),
+  endDate: new Date('2025-12-31'),
+  limit: 100
+});
+```
+
+## API Reference
+
+### EmailWebhookEventsService
+
+#### `constructor(config: EmailWebhookEventsConfig)`
+
+Creates a new EmailWebhookEventsService instance.
+
+**Parameters:**
+- `config.providers` - Array of provider configurations
+- `config.persistence` - Persistence settings (optional)
+- `config.analytics` - Analytics settings (optional)
+- `config.notifications` - Notification settings (optional)
+- `config.rateLimiting` - Rate limiting settings (optional)
+
+#### `async initialize(): Promise<void>`
+
+Initializes the service. Must be called before processing webhooks.
+
+#### `async processWebhook(webhook: WebhookPayload): Promise<EmailWebhookResult>`
+
+Processes an incoming webhook from an email provider.
+
+**Parameters:**
+- `webhook.provider` - Email provider (sendgrid, mailgun, aws_ses, etc.)
+- `webhook.signature` - Webhook signature for validation
+- `webhook.payload` - Raw webhook payload
+- `webhook.headers` - Request headers
+
+**Returns:** `EmailWebhookResult` with success status and normalized event
+
+#### `async getAnalytics(startDate: Date, endDate: Date, filters?: AnalyticsFilters): Promise<EmailAnalytics>`
+
+Retrieves analytics for the specified date range.
+
+**Parameters:**
+- `startDate` - Start of date range
+- `endDate` - End of date range
+- `filters` - Optional filters (provider, emailId, recipient, eventTypes)
+
+**Returns:** `EmailAnalytics` with counts, rates, and breakdowns
+
+#### `async queryEvents(query: EventQuery): Promise<EmailEvent[]>`
+
+Queries events with various filters.
+
+**Parameters:**
+- `query.emailId` - Filter by email ID
+- `query.recipient` - Filter by recipient
+- `query.eventTypes` - Filter by event types
+- `query.startDate` - Filter by start date
+- `query.endDate` - Filter by end date
+- `query.limit` - Maximum number of results
+- `query.offset` - Offset for pagination
+
+**Returns:** Array of `EmailEvent`
+
+#### `async getEventsForEmail(emailId: string): Promise<EmailEvent[]>`
+
+Gets all events for a specific email.
+
+**Parameters:**
+- `emailId` - Email identifier
+
+**Returns:** Array of `EmailEvent`
+
+## Supported Providers
+
+### SendGrid
+
+```typescript
+{
+  provider: EmailProvider.SENDGRID,
+  signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
+  signatureAlgorithm: 'sha256'
+}
+```
+
+**Supported Events:** delivered, open, click, bounce, spamreport, unsubscribe, deferred, dropped
+
+### Mailgun
+
+```typescript
+{
+  provider: EmailProvider.MAILGUN,
+  signatureHeader: 'X-Mailgun-Signature',
+  signatureAlgorithm: 'sha256'
+}
+```
+
+**Supported Events:** delivered, opened, clicked, bounced, complained, unsubscribed, failed
+
+### AWS SES
+
+```typescript
+{
+  provider: EmailProvider.AWS_SES,
+  signatureHeader: 'X-Amz-Sns-Message-Type',
+  signatureAlgorithm: 'sha256'
+}
+```
+
+**Supported Events:** Delivery, Open, Click, Bounce, Complaint, Reject
+
+### Postmark
+
+```typescript
+{
+  provider: EmailProvider.POSTMARK,
+  signatureHeader: 'X-Postmark-Signature',
+  signatureAlgorithm: 'sha256'
+}
+```
+
+**Supported Events:** Delivery, Open, Click, Bounce, SpamComplaint, SubscriptionChange
+
+### SMTP2GO
+
+```typescript
+{
+  provider: EmailProvider.SMTP2GO,
+  signatureHeader: 'X-Smtp2go-Signature',
+  signatureAlgorithm: 'sha256'
+}
+```
+
+**Supported Events:** delivered, open, click, bounce, failed
+
+## Event Types
+
+All provider events are normalized to these unified types:
+
+- `DELIVERED` - Email successfully delivered
+- `OPENED` - Email opened by recipient
+- `CLICKED` - Link clicked in email
+- `BOUNCED` - Email bounced (hard or soft)
+- `COMPLAINED` - Spam complaint received
+- `UNSUBSCRIBED` - Recipient unsubscribed
+- `FAILED` - Email delivery failed
+- `DEFERRED` - Email delivery deferred
+- `DROPPED` - Email dropped by provider
+
+## Analytics Metrics
+
+### Counts
+- `totalSent` - Total emails sent
+- `totalDelivered` - Total emails delivered
+- `totalOpened` - Total emails opened
+- `totalClicked` - Total links clicked
+- `totalBounced` - Total emails bounced
+- `totalComplained` - Total spam complaints
+- `totalUnsubscribed` - Total unsubscribes
+- `totalFailed` - Total delivery failures
+
+### Rates
+- `deliveryRate` - delivered / sent
+- `openRate` - opened / delivered
+- `clickRate` - clicked / delivered
+- `clickToOpenRate` - clicked / opened
+- `bounceRate` - bounced / sent
+- `complaintRate` - complained / sent
+- `unsubscribeRate` - unsubscribed / delivered
+
+### Breakdowns
+- `byProvider` - Analytics per provider
+- `byEventType` - Counts per event type
+- `byBounceType` - Hard vs soft bounces
+- `topLinks` - Most clicked links
+- `byDevice` - Desktop, mobile, tablet breakdown
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Provider webhook secrets
+EMAIL_WEBHOOK_SENDGRID_SECRET=your-sendgrid-webhook-secret
+EMAIL_WEBHOOK_MAILGUN_SECRET=your-mailgun-webhook-secret
+EMAIL_WEBHOOK_SES_SECRET=your-ses-sns-topic-subscription-secret
+EMAIL_WEBHOOK_POSTMARK_SECRET=your-postmark-webhook-secret
+
+# Persistence
+EMAIL_WEBHOOK_PERSISTENCE_ENABLED=true
+EMAIL_WEBHOOK_PERSISTENCE_ADAPTER=memory
+EMAIL_WEBHOOK_PERSISTENCE_RETENTION_DAYS=90
+
+# Analytics
+EMAIL_WEBHOOK_ANALYTICS_REALTIME=true
+EMAIL_WEBHOOK_ANALYTICS_INTERVAL=5000
+
+# Notifications
+EMAIL_WEBHOOK_NOTIFICATIONS_ENABLED=true
+
+# Rate limiting
+EMAIL_WEBHOOK_RATE_LIMIT_ENABLED=false
+EMAIL_WEBHOOK_RATE_LIMIT_MAX_PER_SECOND=100
+```
+
+## Integration Status
+
+- **Logger**: integrated - Uses MockLogger (pending @bernierllc/logger publication)
+- **Docs-Suite**: ready - TypeScript interfaces with JSDoc comments
+- **NeverHub**: required - Event publishing and service discovery (pending implementation)
+
+## Examples
+
+See the `examples/` directory for complete usage examples:
+
+- `setup-sendgrid.ts` - SendGrid webhook setup
+- `setup-mailgun.ts` - Mailgun webhook setup
+- `query-analytics.ts` - Analytics query examples
+- `critical-events.ts` - Critical event handling
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+This package 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.
+
+## See Also
+
+- [@bernierllc/webhook-processor](../webhook-processor) - Generic webhook processing (pending)
+- [@bernierllc/email-sender](../../core/email-sender) - Email sending service
+- [@bernierllc/email-campaign-management](./email-campaign-management) - Campaign management (pending)

package/__tests__/EmailWebhookEventsService.test.ts

@@ -0,0 +1,247 @@
+/*
+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 { EmailWebhookEventsService } from '../src/EmailWebhookEventsService';
+import {
+  EmailEventType,
+  EmailProvider,
+  WebhookPayload,
+  ProviderWebhookConfig
+} from '../src/types';
+
+describe('EmailWebhookEventsService', () => {
+  let service: EmailWebhookEventsService;
+
+  const createProviderConfig = (): ProviderWebhookConfig => ({
+    provider: EmailProvider.SENDGRID,
+    enabled: true,
+    webhookUrl: '/webhooks/sendgrid',
+    secretKey: 'test-secret',
+    signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
+    signatureAlgorithm: 'sha256'
+  });
+
+  beforeEach(async () => {
+    service = new EmailWebhookEventsService({
+      providers: [createProviderConfig()],
+      persistence: {
+        enabled: true,
+        adapter: 'memory'
+      },
+      analytics: {
+        realTimeEnabled: true,
+        aggregationInterval: 5000,
+        retentionDays: 90
+      },
+      notifications: {
+        enabled: true,
+        criticalEvents: [EmailEventType.BOUNCED, EmailEventType.COMPLAINED],
+        channels: []
+      }
+    });
+
+    await service.initialize();
+  });
+
+  const createWebhook = (eventType: string, overrides: Partial<WebhookPayload> = {}): WebhookPayload => ({
+    provider: EmailProvider.SENDGRID,
+    signature: 'test-signature',
+    payload: {
+      event: eventType,
+      email: 'user@example.com',
+      timestamp: Math.floor(Date.now() / 1000),
+      sg_message_id: 'msg-123',
+      email_id: 'email-456'
+    },
+    headers: {},
+    ...overrides
+  });
+
+  describe('processWebhook', () => {
+    it('should process delivered event successfully', async () => {
+      const webhook = createWebhook('delivered');
+      const result = await service.processWebhook(webhook);
+
+      expect(result.success).toBe(true);
+      expect(result.event).toBeDefined();
+      expect(result.event!.type).toBe(EmailEventType.DELIVERED);
+      expect(result.event!.recipient).toBe('user@example.com');
+    });
+
+    it('should process opened event successfully', async () => {
+      const webhook = createWebhook('open');
+      const result = await service.processWebhook(webhook);
+
+      expect(result.success).toBe(true);
+      expect(result.event!.type).toBe(EmailEventType.OPENED);
+    });
+
+    it('should process clicked event successfully', async () => {
+      const webhook = createWebhook('click', {
+        payload: {
+          event: 'click',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          url: 'https://example.com/link'
+        }
+      });
+
+      const result = await service.processWebhook(webhook);
+
+      expect(result.success).toBe(true);
+      expect(result.event!.type).toBe(EmailEventType.CLICKED);
+      expect(result.event!.metadata.url).toBe('https://example.com/link');
+    });
+
+    it('should process bounce event successfully', async () => {
+      const webhook = createWebhook('bounce', {
+        payload: {
+          event: 'bounce',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          status: '5.1.1',
+          reason: 'User unknown'
+        }
+      });
+
+      const result = await service.processWebhook(webhook);
+
+      expect(result.success).toBe(true);
+      expect(result.event!.type).toBe(EmailEventType.BOUNCED);
+      expect(result.event!.metadata.bounceType).toBe('hard');
+      expect(result.event!.metadata.bounceReason).toBe('User unknown');
+    });
+
+    it('should handle unsupported provider gracefully', async () => {
+      const webhook = createWebhook('delivered', {
+        provider: EmailProvider.GENERIC_SMTP
+      });
+
+      const result = await service.processWebhook(webhook);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Event normalization failed');
+    });
+  });
+
+  describe('getAnalytics', () => {
+    it('should return analytics for processed events', async () => {
+      // Process multiple events
+      await service.processWebhook(createWebhook('delivered'));
+      await service.processWebhook(createWebhook('delivered'));
+      await service.processWebhook(createWebhook('open'));
+      await service.processWebhook(createWebhook('click', {
+        payload: {
+          event: 'click',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          url: 'https://example.com/link'
+        }
+      }));
+
+      const analytics = await service.getAnalytics(
+        new Date('2025-01-01'),
+        new Date('2025-12-31')
+      );
+
+      expect(analytics.totalDelivered).toBe(2);
+      expect(analytics.totalOpened).toBe(1);
+      expect(analytics.totalClicked).toBe(1);
+      expect(analytics.openRate).toBe(0.5);
+      expect(analytics.clickRate).toBe(0.5);
+    });
+
+    it('should filter analytics by provider', async () => {
+      await service.processWebhook(createWebhook('delivered', {
+        provider: EmailProvider.SENDGRID
+      }));
+
+      const analytics = await service.getAnalytics(
+        new Date('2025-01-01'),
+        new Date('2025-12-31'),
+        { provider: EmailProvider.SENDGRID }
+      );
+
+      expect(analytics.totalDelivered).toBe(1);
+    });
+  });
+
+  describe('queryEvents', () => {
+    it('should query events by email ID', async () => {
+      await service.processWebhook(createWebhook('delivered', {
+        payload: {
+          event: 'delivered',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          email_id: 'email-123'
+        }
+      }));
+
+      await service.processWebhook(createWebhook('delivered', {
+        payload: {
+          event: 'delivered',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-456',
+          email_id: 'email-456'
+        }
+      }));
+
+      const events = await service.queryEvents({ emailId: 'email-123' });
+
+      expect(events).toHaveLength(1);
+      expect(events[0].emailId).toBe('email-123');
+    });
+
+    it('should query events by event type', async () => {
+      await service.processWebhook(createWebhook('delivered'));
+      await service.processWebhook(createWebhook('open'));
+
+      const events = await service.queryEvents({
+        eventTypes: [EmailEventType.DELIVERED]
+      });
+
+      expect(events).toHaveLength(1);
+      expect(events[0].type).toBe(EmailEventType.DELIVERED);
+    });
+  });
+
+  describe('getEventsForEmail', () => {
+    it('should return all events for a specific email', async () => {
+      await service.processWebhook(createWebhook('delivered', {
+        payload: {
+          event: 'delivered',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          email_id: 'email-123'
+        }
+      }));
+
+      await service.processWebhook(createWebhook('open', {
+        payload: {
+          event: 'open',
+          email: 'user@example.com',
+          timestamp: Math.floor(Date.now() / 1000),
+          sg_message_id: 'msg-123',
+          email_id: 'email-123'
+        }
+      }));
+
+      const events = await service.getEventsForEmail('email-123');
+
+      expect(events).toHaveLength(2);
+      expect(events[0].emailId).toBe('email-123');
+      expect(events[1].emailId).toBe('email-123');
+    });
+  });
+});