@bernierllc/email-webhook-events 1.0.0

package/src/analytics/AnalyticsEngine.ts

@@ -0,0 +1,230 @@
+/*
+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 {
+  EmailEvent,
+  EmailAnalytics,
+  EmailEventType,
+  EmailProvider,
+  ProviderAnalytics,
+  AnalyticsFilters
+} from '../types';
+
+export class AnalyticsEngine {
+  private events: EmailEvent[] = [];
+  private config?: {
+    realTimeEnabled: boolean;
+    aggregationInterval: number;
+    retentionDays: number;
+  };
+
+  constructor(config?: { realTimeEnabled: boolean; aggregationInterval: number; retentionDays: number }) {
+    this.config = config;
+  }
+
+  async recordEvent(event: EmailEvent): Promise<void> {
+    this.events.push(event);
+
+    // Cleanup old events based on retention policy
+    if (this.config?.retentionDays) {
+      const cutoffDate = new Date();
+      cutoffDate.setDate(cutoffDate.getDate() - this.config.retentionDays);
+      this.events = this.events.filter(e => e.timestamp >= cutoffDate);
+    }
+  }
+
+  async getAnalytics(
+    startDate: Date,
+    endDate: Date,
+    filters?: AnalyticsFilters
+  ): Promise<EmailAnalytics> {
+    // Filter events by date range and filters
+    let filteredEvents = this.events.filter(
+      e => e.timestamp >= startDate && e.timestamp <= endDate
+    );
+
+    if (filters?.provider) {
+      filteredEvents = filteredEvents.filter(e => e.provider === filters.provider);
+    }
+
+    if (filters?.emailId) {
+      filteredEvents = filteredEvents.filter(e => e.emailId === filters.emailId);
+    }
+
+    if (filters?.recipient) {
+      filteredEvents = filteredEvents.filter(e => e.recipient === filters.recipient);
+    }
+
+    if (filters?.eventTypes && filters.eventTypes.length > 0) {
+      filteredEvents = filteredEvents.filter(e => filters.eventTypes!.includes(e.type));
+    }
+
+    // Calculate counts
+    const counts = this.calculateCounts(filteredEvents);
+
+    // Calculate rates
+    const rates = this.calculateRates(counts);
+
+    // Calculate breakdowns
+    const byProvider = this.calculateProviderBreakdown(filteredEvents);
+    const byEventType = this.calculateEventTypeBreakdown(filteredEvents);
+    const byBounceType = this.calculateBounceTypeBreakdown(filteredEvents);
+    const topLinks = this.calculateTopLinks(filteredEvents);
+    const byDevice = this.calculateDeviceBreakdown(filteredEvents);
+
+    return {
+      startDate,
+      endDate,
+      ...counts,
+      ...rates,
+      byProvider,
+      byEventType,
+      byBounceType,
+      topLinks,
+      byDevice
+    };
+  }
+
+  private calculateCounts(events: EmailEvent[]): {
+    totalSent: number;
+    totalDelivered: number;
+    totalOpened: number;
+    totalClicked: number;
+    totalBounced: number;
+    totalComplained: number;
+    totalUnsubscribed: number;
+    totalFailed: number;
+  } {
+    return {
+      totalSent: events.length, // Simplified - in real implementation, would track sent separately
+      totalDelivered: events.filter(e => e.type === EmailEventType.DELIVERED).length,
+      totalOpened: events.filter(e => e.type === EmailEventType.OPENED).length,
+      totalClicked: events.filter(e => e.type === EmailEventType.CLICKED).length,
+      totalBounced: events.filter(e => e.type === EmailEventType.BOUNCED).length,
+      totalComplained: events.filter(e => e.type === EmailEventType.COMPLAINED).length,
+      totalUnsubscribed: events.filter(e => e.type === EmailEventType.UNSUBSCRIBED).length,
+      totalFailed: events.filter(e => e.type === EmailEventType.FAILED).length
+    };
+  }
+
+  private calculateRates(counts: {
+    totalSent: number;
+    totalDelivered: number;
+    totalOpened: number;
+    totalClicked: number;
+    totalBounced: number;
+    totalComplained: number;
+    totalUnsubscribed: number;
+  }): {
+    deliveryRate: number;
+    openRate: number;
+    clickRate: number;
+    clickToOpenRate: number;
+    bounceRate: number;
+    complaintRate: number;
+    unsubscribeRate: number;
+  } {
+    const safeDiv = (num: number, denom: number): number => (denom === 0 ? 0 : num / denom);
+
+    return {
+      deliveryRate: safeDiv(counts.totalDelivered, counts.totalSent),
+      openRate: safeDiv(counts.totalOpened, counts.totalDelivered),
+      clickRate: safeDiv(counts.totalClicked, counts.totalDelivered),
+      clickToOpenRate: safeDiv(counts.totalClicked, counts.totalOpened),
+      bounceRate: safeDiv(counts.totalBounced, counts.totalSent),
+      complaintRate: safeDiv(counts.totalComplained, counts.totalSent),
+      unsubscribeRate: safeDiv(counts.totalUnsubscribed, counts.totalDelivered)
+    };
+  }
+
+  private calculateProviderBreakdown(events: EmailEvent[]): Record<EmailProvider, ProviderAnalytics> {
+    const providers = Object.values(EmailProvider);
+    const breakdown = {} as Record<EmailProvider, ProviderAnalytics>;
+
+    for (const provider of providers) {
+      const providerEvents = events.filter(e => e.provider === provider);
+      const counts = this.calculateCounts(providerEvents);
+      const rates = this.calculateRates(counts);
+
+      breakdown[provider] = {
+        sent: counts.totalSent,
+        delivered: counts.totalDelivered,
+        opened: counts.totalOpened,
+        clicked: counts.totalClicked,
+        bounced: counts.totalBounced,
+        complained: counts.totalComplained,
+        failed: counts.totalFailed,
+        deliveryRate: rates.deliveryRate,
+        openRate: rates.openRate,
+        clickRate: rates.clickRate
+      };
+    }
+
+    return breakdown;
+  }
+
+  private calculateEventTypeBreakdown(events: EmailEvent[]): Record<EmailEventType, number> {
+    const eventTypes = Object.values(EmailEventType);
+    const breakdown = {} as Record<EmailEventType, number>;
+
+    for (const eventType of eventTypes) {
+      breakdown[eventType] = events.filter(e => e.type === eventType).length;
+    }
+
+    return breakdown;
+  }
+
+  private calculateBounceTypeBreakdown(events: EmailEvent[]): { hard: number; soft: number } | undefined {
+    const bounceEvents = events.filter(e => e.type === EmailEventType.BOUNCED);
+    if (bounceEvents.length === 0) return undefined;
+
+    return {
+      hard: bounceEvents.filter(e => e.metadata.bounceType === 'hard').length,
+      soft: bounceEvents.filter(e => e.metadata.bounceType === 'soft').length
+    };
+  }
+
+  private calculateTopLinks(events: EmailEvent[]): Array<{ url: string; clicks: number; uniqueClicks: number }> | undefined {
+    const clickEvents = events.filter(e => e.type === EmailEventType.CLICKED && e.metadata.url);
+    if (clickEvents.length === 0) return undefined;
+
+    const linkStats = new Map<string, { clicks: number; recipients: Set<string> }>();
+
+    for (const event of clickEvents) {
+      const url = event.metadata.url!;
+      const existing = linkStats.get(url) || { clicks: 0, recipients: new Set<string>() };
+      existing.clicks++;
+      existing.recipients.add(event.recipient);
+      linkStats.set(url, existing);
+    }
+
+    return Array.from(linkStats.entries())
+      .map(([url, stats]) => ({
+        url,
+        clicks: stats.clicks,
+        uniqueClicks: stats.recipients.size
+      }))
+      .sort((a, b) => b.clicks - a.clicks)
+      .slice(0, 10);
+  }
+
+  private calculateDeviceBreakdown(events: EmailEvent[]): { desktop: number; mobile: number; tablet: number; unknown: number } | undefined {
+    const interactionEvents = events.filter(
+      e => (e.type === EmailEventType.OPENED || e.type === EmailEventType.CLICKED) && e.metadata.deviceType
+    );
+
+    if (interactionEvents.length === 0) return undefined;
+
+    return {
+      desktop: interactionEvents.filter(e => e.metadata.deviceType === 'desktop').length,
+      mobile: interactionEvents.filter(e => e.metadata.deviceType === 'mobile').length,
+      tablet: interactionEvents.filter(e => e.metadata.deviceType === 'tablet').length,
+      unknown: interactionEvents.filter(e => e.metadata.deviceType === 'unknown').length
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+/*
+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.
+*/
+
+export { EmailWebhookEventsService } from './EmailWebhookEventsService';
+
+export {
+  EmailEvent,
+  EmailEventType,
+  EmailProvider,
+  EmailEventMetadata,
+  EmailAnalytics,
+  ProviderAnalytics,
+  EmailWebhookEventsConfig,
+  ProviderWebhookConfig,
+  NotificationChannel,
+  EmailWebhookResult,
+  WebhookPayload,
+  AnalyticsFilters,
+  EventQuery,
+  EmailWebhookError,
+  EmailWebhookErrorCode
+} from './types';
+
+export { EventNormalizer } from './normalizers/EventNormalizer';
+export { SendGridNormalizer } from './normalizers/SendGridNormalizer';
+export { MailgunNormalizer } from './normalizers/MailgunNormalizer';
+export { SESNormalizer } from './normalizers/SESNormalizer';
+export { PostmarkNormalizer } from './normalizers/PostmarkNormalizer';
+export { SMTP2GONormalizer } from './normalizers/SMTP2GONormalizer';
+
+export { AnalyticsEngine } from './analytics/AnalyticsEngine';
+
+export { PersistenceAdapter } from './persistence/PersistenceAdapter';
+export { InMemoryPersistenceAdapter } from './persistence/InMemoryPersistenceAdapter';

package/src/normalizers/EventNormalizer.ts

@@ -0,0 +1,13 @@
+/*
+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 { EmailEvent, WebhookPayload } from '../types';
+
+export interface EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent;
+}

package/src/normalizers/MailgunNormalizer.ts

@@ -0,0 +1,72 @@
+/*
+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 { EventNormalizer } from './EventNormalizer';
+import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
+
+export class MailgunNormalizer implements EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent {
+    const payload = webhook.payload as Record<string, unknown>;
+    const event = payload['event-data'] as Record<string, unknown>;
+    const message = (event.message as Record<string, unknown>) || {};
+    const headers = (message.headers as Record<string, string>) || {};
+    const deliveryStatus = event['delivery-status'] as Record<string, unknown> | undefined;
+    const clientInfo = event['client-info'] as Record<string, unknown> | undefined;
+    const geolocation = event.geolocation as Record<string, string> | undefined;
+
+    return {
+      id: this.generateEventId(event),
+      emailId: headers['message-id'] || '',
+      messageId: (event.id as string) || '',
+      type: this.mapEventType(event.event as string),
+      recipient: (event.recipient as string) || '',
+      timestamp: new Date((event.timestamp as number) * 1000),
+      provider: EmailProvider.MAILGUN,
+      metadata: {
+        url: event.url as string | undefined,
+        bounceType: (event.severity as string) === 'permanent' ? 'hard' : 'soft',
+        bounceReason: deliveryStatus?.message as string | undefined,
+        bounceCode: deliveryStatus?.code?.toString(),
+        ipAddress: clientInfo?.['client-ip'] as string | undefined,
+        userAgent: clientInfo?.['user-agent'] as string | undefined,
+        deviceType: this.detectDeviceType(clientInfo?.['user-agent'] as string | undefined),
+        location: {
+          country: geolocation?.country,
+          region: geolocation?.region,
+          city: geolocation?.city
+        }
+      },
+      rawEvent: event
+    };
+  }
+
+  private mapEventType(mailgunEvent: string): EmailEventType {
+    const mapping: Record<string, EmailEventType> = {
+      'delivered': EmailEventType.DELIVERED,
+      'opened': EmailEventType.OPENED,
+      'clicked': EmailEventType.CLICKED,
+      'bounced': EmailEventType.BOUNCED,
+      'complained': EmailEventType.COMPLAINED,
+      'unsubscribed': EmailEventType.UNSUBSCRIBED,
+      'failed': EmailEventType.FAILED
+    };
+    return mapping[mailgunEvent] || EmailEventType.FAILED;
+  }
+
+  private generateEventId(event: Record<string, unknown>): string {
+    return `mailgun-${event.id as string}`;
+  }
+
+  private detectDeviceType(userAgent?: string): 'desktop' | 'mobile' | 'tablet' | 'unknown' {
+    if (!userAgent) return 'unknown';
+    const ua = userAgent.toLowerCase();
+    if (ua.includes('mobile')) return 'mobile';
+    if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
+    return 'desktop';
+  }
+}

package/src/normalizers/PostmarkNormalizer.ts

@@ -0,0 +1,72 @@
+/*
+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 { EventNormalizer } from './EventNormalizer';
+import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
+
+export class PostmarkNormalizer implements EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent {
+    const event = webhook.payload as Record<string, unknown>;
+
+    return {
+      id: this.generateEventId(event),
+      emailId: (event.MessageID as string) || '',
+      messageId: (event.MessageID as string) || '',
+      type: this.mapEventType(event.RecordType as string),
+      recipient: (event.Recipient as string) || '',
+      timestamp: new Date(event.ReceivedAt as string),
+      provider: EmailProvider.POSTMARK,
+      metadata: {
+        url: event.OriginalLink as string | undefined,
+        bounceType: this.mapBounceType(event.Type as string | undefined),
+        bounceReason: event.Description as string | undefined,
+        bounceCode: event.TypeCode?.toString(),
+        complaintFeedbackType: event.Type as string | undefined,
+        userAgent: event.UserAgent as string | undefined,
+        deviceType: this.detectDeviceType(event.UserAgent as string | undefined),
+        location: {
+          country: (event.Geo as Record<string, string> | undefined)?.Country,
+          region: (event.Geo as Record<string, string> | undefined)?.Region,
+          city: (event.Geo as Record<string, string> | undefined)?.City
+        }
+      },
+      rawEvent: event
+    };
+  }
+
+  private mapEventType(postmarkEvent: string): EmailEventType {
+    const mapping: Record<string, EmailEventType> = {
+      'Delivery': EmailEventType.DELIVERED,
+      'Open': EmailEventType.OPENED,
+      'Click': EmailEventType.CLICKED,
+      'Bounce': EmailEventType.BOUNCED,
+      'SpamComplaint': EmailEventType.COMPLAINED,
+      'SubscriptionChange': EmailEventType.UNSUBSCRIBED
+    };
+    return mapping[postmarkEvent] || EmailEventType.FAILED;
+  }
+
+  private mapBounceType(bounceType?: string): 'hard' | 'soft' | undefined {
+    if (!bounceType) return undefined;
+    if (bounceType.includes('Hard')) return 'hard';
+    if (bounceType.includes('Soft')) return 'soft';
+    return undefined;
+  }
+
+  private generateEventId(event: Record<string, unknown>): string {
+    return `postmark-${(event.MessageID as string) || ''}-${Date.now()}`;
+  }
+
+  private detectDeviceType(userAgent?: string): 'desktop' | 'mobile' | 'tablet' | 'unknown' {
+    if (!userAgent) return 'unknown';
+    const ua = userAgent.toLowerCase();
+    if (ua.includes('mobile')) return 'mobile';
+    if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
+    return 'desktop';
+  }
+}

package/src/normalizers/SESNormalizer.ts

@@ -0,0 +1,117 @@
+/*
+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 { EventNormalizer } from './EventNormalizer';
+import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
+
+export class SESNormalizer implements EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent {
+    const payload = webhook.payload as Record<string, unknown>;
+    const message = JSON.parse(payload.Message as string) as Record<string, unknown>;
+    const eventType = message.eventType as string;
+
+    return {
+      id: this.generateEventId(message),
+      emailId: this.extractMessageId(message),
+      messageId: this.extractMessageId(message),
+      type: this.mapEventType(eventType),
+      recipient: this.extractRecipient(message),
+      timestamp: new Date((message.mail as Record<string, unknown>).timestamp as string),
+      provider: EmailProvider.AWS_SES,
+      metadata: {
+        bounceType: this.extractBounceType(message),
+        bounceReason: this.extractBounceReason(message),
+        complaintFeedbackType: this.extractComplaintType(message),
+        url: this.extractClickUrl(message),
+        ipAddress: this.extractIpAddress(message),
+        userAgent: this.extractUserAgent(message)
+      },
+      rawEvent: message
+    };
+  }
+
+  private mapEventType(sesEvent: string): EmailEventType {
+    const mapping: Record<string, EmailEventType> = {
+      'Delivery': EmailEventType.DELIVERED,
+      'Open': EmailEventType.OPENED,
+      'Click': EmailEventType.CLICKED,
+      'Bounce': EmailEventType.BOUNCED,
+      'Complaint': EmailEventType.COMPLAINED,
+      'Reject': EmailEventType.FAILED
+    };
+    return mapping[sesEvent] || EmailEventType.FAILED;
+  }
+
+  private extractMessageId(message: Record<string, unknown>): string {
+    const mail = message.mail as Record<string, unknown>;
+    return (mail?.messageId as string) || '';
+  }
+
+  private extractRecipient(message: Record<string, unknown>): string {
+    const bounce = message.bounce as Record<string, unknown> | undefined;
+    const complaint = message.complaint as Record<string, unknown> | undefined;
+    const mail = message.mail as Record<string, unknown>;
+
+    if (bounce) {
+      const bouncedRecipients = bounce.bouncedRecipients as Array<Record<string, string>> | undefined;
+      if (bouncedRecipients?.[0]?.emailAddress) {
+        return bouncedRecipients[0].emailAddress;
+      }
+    }
+
+    if (complaint) {
+      const complainedRecipients = complaint.complainedRecipients as Array<Record<string, string>> | undefined;
+      if (complainedRecipients?.[0]?.emailAddress) {
+        return complainedRecipients[0].emailAddress;
+      }
+    }
+
+    const destination = mail.destination as string[] | undefined;
+    return destination?.[0] || '';
+  }
+
+  private extractBounceType(message: Record<string, unknown>): 'hard' | 'soft' | undefined {
+    const bounce = message.bounce as Record<string, unknown> | undefined;
+    if (!bounce) return undefined;
+    return (bounce.bounceType as string)?.toLowerCase() as 'hard' | 'soft' | undefined;
+  }
+
+  private extractBounceReason(message: Record<string, unknown>): string | undefined {
+    const bounce = message.bounce as Record<string, unknown> | undefined;
+    if (!bounce) return undefined;
+    const bouncedRecipients = bounce.bouncedRecipients as Array<Record<string, string>> | undefined;
+    return bouncedRecipients?.[0]?.diagnosticCode;
+  }
+
+  private extractComplaintType(message: Record<string, unknown>): string | undefined {
+    const complaint = message.complaint as Record<string, unknown> | undefined;
+    return complaint?.complaintFeedbackType as string | undefined;
+  }
+
+  private extractClickUrl(message: Record<string, unknown>): string | undefined {
+    const click = message.click as Record<string, unknown> | undefined;
+    return click?.link as string | undefined;
+  }
+
+  private extractIpAddress(message: Record<string, unknown>): string | undefined {
+    const open = message.open as Record<string, unknown> | undefined;
+    const click = message.click as Record<string, unknown> | undefined;
+    return (open?.ipAddress as string) || (click?.ipAddress as string) || undefined;
+  }
+
+  private extractUserAgent(message: Record<string, unknown>): string | undefined {
+    const open = message.open as Record<string, unknown> | undefined;
+    const click = message.click as Record<string, unknown> | undefined;
+    return (open?.userAgent as string) || (click?.userAgent as string) || undefined;
+  }
+
+  private generateEventId(message: Record<string, unknown>): string {
+    const mail = message.mail as Record<string, unknown>;
+    return `ses-${(mail?.messageId as string) || ''}-${Date.now()}`;
+  }
+}

package/src/normalizers/SMTP2GONormalizer.ts

@@ -0,0 +1,54 @@
+/*
+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 { EventNormalizer } from './EventNormalizer';
+import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
+
+export class SMTP2GONormalizer implements EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent {
+    const event = webhook.payload as Record<string, unknown>;
+
+    return {
+      id: this.generateEventId(event),
+      emailId: (event.email_id as string) || (event.message_id as string) || '',
+      messageId: (event.message_id as string) || '',
+      type: this.mapEventType(event.event as string),
+      recipient: (event.rcpt_to as string) || '',
+      timestamp: new Date(event.timestamp as string),
+      provider: EmailProvider.SMTP2GO,
+      metadata: {
+        bounceType: this.mapBounceType(event.bounce_type as string | undefined),
+        bounceReason: event.reason as string | undefined,
+        failureReason: event.reason as string | undefined
+      },
+      rawEvent: event
+    };
+  }
+
+  private mapEventType(smtp2goEvent: string): EmailEventType {
+    const mapping: Record<string, EmailEventType> = {
+      'delivered': EmailEventType.DELIVERED,
+      'open': EmailEventType.OPENED,
+      'click': EmailEventType.CLICKED,
+      'bounce': EmailEventType.BOUNCED,
+      'failed': EmailEventType.FAILED
+    };
+    return mapping[smtp2goEvent] || EmailEventType.FAILED;
+  }
+
+  private mapBounceType(bounceType?: string): 'hard' | 'soft' | undefined {
+    if (!bounceType) return undefined;
+    if (bounceType.toLowerCase().includes('hard')) return 'hard';
+    if (bounceType.toLowerCase().includes('soft')) return 'soft';
+    return undefined;
+  }
+
+  private generateEventId(event: Record<string, unknown>): string {
+    return `smtp2go-${(event.message_id as string) || ''}-${Date.now()}`;
+  }
+}

package/src/normalizers/SendGridNormalizer.ts

@@ -0,0 +1,63 @@
+/*
+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 { EventNormalizer } from './EventNormalizer';
+import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
+
+export class SendGridNormalizer implements EventNormalizer {
+  normalize(webhook: WebhookPayload): EmailEvent {
+    const event = webhook.payload as Record<string, unknown>;
+
+    return {
+      id: this.generateEventId(event),
+      emailId: (event.email_id as string) || (event.sg_message_id as string) || '',
+      messageId: (event.sg_message_id as string) || '',
+      type: this.mapEventType(event.event as string),
+      recipient: (event.email as string) || '',
+      timestamp: new Date((event.timestamp as number) * 1000),
+      provider: EmailProvider.SENDGRID,
+      metadata: {
+        url: event.url as string | undefined,
+        bounceType: event.event === 'bounce'
+          ? ((event.status as string)?.startsWith('5') ? 'hard' : 'soft')
+          : undefined,
+        bounceReason: event.reason as string | undefined,
+        userAgent: event.useragent as string | undefined,
+        ipAddress: event.ip as string | undefined,
+        deviceType: this.detectDeviceType(event.useragent as string | undefined)
+      },
+      rawEvent: event
+    };
+  }
+
+  private mapEventType(sendgridEvent: string): EmailEventType {
+    const mapping: Record<string, EmailEventType> = {
+      'delivered': EmailEventType.DELIVERED,
+      'open': EmailEventType.OPENED,
+      'click': EmailEventType.CLICKED,
+      'bounce': EmailEventType.BOUNCED,
+      'dropped': EmailEventType.DROPPED,
+      'spamreport': EmailEventType.COMPLAINED,
+      'unsubscribe': EmailEventType.UNSUBSCRIBED,
+      'deferred': EmailEventType.DEFERRED
+    };
+    return mapping[sendgridEvent] || EmailEventType.FAILED;
+  }
+
+  private generateEventId(event: Record<string, unknown>): string {
+    return `sendgrid-${(event.sg_event_id as string) || Date.now()}`;
+  }
+
+  private detectDeviceType(userAgent?: string): 'desktop' | 'mobile' | 'tablet' | 'unknown' {
+    if (!userAgent) return 'unknown';
+    const ua = userAgent.toLowerCase();
+    if (ua.includes('mobile')) return 'mobile';
+    if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
+    return 'desktop';
+  }
+}