@bernierllc/email-webhook-events 1.0.0

package/src/persistence/InMemoryPersistenceAdapter.ts

@@ -0,0 +1,68 @@
+/*
+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 { PersistenceAdapter } from './PersistenceAdapter';
+import { EmailEvent, EventQuery } from '../types';
+
+export class InMemoryPersistenceAdapter implements PersistenceAdapter {
+  private events: EmailEvent[] = [];
+  private sentEmails: unknown[] = [];
+
+  async saveEvent(event: EmailEvent): Promise<void> {
+    this.events.push(event);
+  }
+
+  async queryEvents(query: EventQuery): Promise<EmailEvent[]> {
+    let results = [...this.events];
+
+    if (query.emailId) {
+      results = results.filter(e => e.emailId === query.emailId);
+    }
+
+    if (query.recipient) {
+      results = results.filter(e => e.recipient === query.recipient);
+    }
+
+    if (query.eventTypes && query.eventTypes.length > 0) {
+      results = results.filter(e => query.eventTypes!.includes(e.type));
+    }
+
+    if (query.startDate) {
+      results = results.filter(e => e.timestamp >= query.startDate!);
+    }
+
+    if (query.endDate) {
+      results = results.filter(e => e.timestamp <= query.endDate!);
+    }
+
+    // Apply offset and limit
+    if (query.offset) {
+      results = results.slice(query.offset);
+    }
+
+    if (query.limit) {
+      results = results.slice(0, query.limit);
+    }
+
+    return results;
+  }
+
+  async saveSentEmail(emailData: unknown): Promise<void> {
+    this.sentEmails.push(emailData);
+  }
+
+  // Test helper methods
+  getEventCount(): number {
+    return this.events.length;
+  }
+
+  clearEvents(): void {
+    this.events = [];
+    this.sentEmails = [];
+  }
+}

package/src/persistence/PersistenceAdapter.ts

@@ -0,0 +1,15 @@
+/*
+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, EventQuery } from '../types';
+
+export interface PersistenceAdapter {
+  saveEvent(event: EmailEvent): Promise<void>;
+  queryEvents(query: EventQuery): Promise<EmailEvent[]>;
+  saveSentEmail?(emailData: unknown): Promise<void>;
+}

package/src/types.ts

@@ -0,0 +1,246 @@
+/*
+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.
+*/
+
+// Unified email event format
+export interface EmailEvent {
+  // Event identification
+  id: string;
+  emailId: string;
+  messageId: string;
+
+  // Event type
+  type: EmailEventType;
+
+  // Recipient information
+  recipient: string;
+
+  // Timestamp
+  timestamp: Date;
+
+  // Provider information
+  provider: EmailProvider;
+
+  // Event-specific data
+  metadata: EmailEventMetadata;
+
+  // Original webhook data (for debugging)
+  rawEvent?: unknown;
+}
+
+export enum EmailEventType {
+  DELIVERED = 'delivered',
+  OPENED = 'opened',
+  CLICKED = 'clicked',
+  BOUNCED = 'bounced',
+  COMPLAINED = 'complained',
+  UNSUBSCRIBED = 'unsubscribed',
+  FAILED = 'failed',
+  DEFERRED = 'deferred',
+  DROPPED = 'dropped'
+}
+
+export enum EmailProvider {
+  SENDGRID = 'sendgrid',
+  MAILGUN = 'mailgun',
+  AWS_SES = 'aws_ses',
+  POSTMARK = 'postmark',
+  SMTP2GO = 'smtp2go',
+  GENERIC_SMTP = 'generic_smtp'
+}
+
+export interface EmailEventMetadata {
+  // For clicked events
+  url?: string;
+  linkId?: string;
+
+  // For bounced events
+  bounceType?: 'hard' | 'soft';
+  bounceReason?: string;
+  bounceCode?: string;
+
+  // For complained events
+  complaintFeedbackType?: string;
+
+  // For failed events
+  failureReason?: string;
+  smtpResponse?: string;
+
+  // For deferred events
+  deferralReason?: string;
+  attemptNumber?: number;
+  nextAttempt?: Date;
+
+  // Common metadata
+  userAgent?: string;
+  ipAddress?: string;
+  deviceType?: 'desktop' | 'mobile' | 'tablet' | 'unknown';
+  location?: {
+    country?: string;
+    region?: string;
+    city?: string;
+  };
+}
+
+// Analytics aggregation
+export interface EmailAnalytics {
+  // Time range
+  startDate: Date;
+  endDate: Date;
+
+  // Counts
+  totalSent: number;
+  totalDelivered: number;
+  totalOpened: number;
+  totalClicked: number;
+  totalBounced: number;
+  totalComplained: number;
+  totalUnsubscribed: number;
+  totalFailed: number;
+
+  // Rates
+  deliveryRate: number;
+  openRate: number;
+  clickRate: number;
+  clickToOpenRate: number;
+  bounceRate: number;
+  complaintRate: number;
+  unsubscribeRate: number;
+
+  // Breakdowns
+  byProvider: Record<EmailProvider, ProviderAnalytics>;
+  byEventType: Record<EmailEventType, number>;
+  byBounceType?: {
+    hard: number;
+    soft: number;
+  };
+
+  // Top links (for clicked events)
+  topLinks?: Array<{
+    url: string;
+    clicks: number;
+    uniqueClicks: number;
+  }>;
+
+  // Device breakdown
+  byDevice?: {
+    desktop: number;
+    mobile: number;
+    tablet: number;
+    unknown: number;
+  };
+}
+
+export interface ProviderAnalytics {
+  sent: number;
+  delivered: number;
+  opened: number;
+  clicked: number;
+  bounced: number;
+  complained: number;
+  failed: number;
+  deliveryRate: number;
+  openRate: number;
+  clickRate: number;
+}
+
+// Configuration
+export interface EmailWebhookEventsConfig {
+  // Provider configurations
+  providers: ProviderWebhookConfig[];
+
+  // Event persistence
+  persistence?: {
+    enabled: boolean;
+    adapter: 'supabase' | 'postgresql' | 'mongodb' | 'memory';
+    config?: unknown;
+  };
+
+  // Analytics
+  analytics?: {
+    realTimeEnabled: boolean;
+    aggregationInterval: number;
+    retentionDays: number;
+  };
+
+  // Notifications
+  notifications?: {
+    enabled: boolean;
+    criticalEvents: EmailEventType[];
+    channels: NotificationChannel[];
+  };
+
+  // Rate limiting
+  rateLimiting?: {
+    enabled: boolean;
+    maxEventsPerSecond: number;
+  };
+}
+
+export interface ProviderWebhookConfig {
+  provider: EmailProvider;
+  enabled: boolean;
+  webhookUrl: string;
+  secretKey: string;
+  signatureHeader: string;
+  signatureAlgorithm: 'sha256' | 'sha1' | 'sha512';
+}
+
+export interface NotificationChannel {
+  type: 'neverhub' | 'webhook' | 'email';
+  config: {
+    url?: string;
+    recipients?: string[];
+    [key: string]: unknown;
+  };
+}
+
+export interface EmailWebhookResult {
+  success: boolean;
+  event?: EmailEvent;
+  error?: string;
+}
+
+export interface WebhookPayload {
+  provider: EmailProvider;
+  signature: string;
+  payload: unknown;
+  headers: Record<string, string>;
+}
+
+export interface AnalyticsFilters {
+  provider?: EmailProvider;
+  emailId?: string;
+  recipient?: string;
+  eventTypes?: EmailEventType[];
+}
+
+export interface EventQuery {
+  emailId?: string;
+  recipient?: string;
+  eventTypes?: EmailEventType[];
+  startDate?: Date;
+  endDate?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export interface EmailWebhookError {
+  code: EmailWebhookErrorCode;
+  message: string;
+  details?: unknown;
+  retryable: boolean;
+}
+
+export enum EmailWebhookErrorCode {
+  INVALID_SIGNATURE = 'INVALID_SIGNATURE',
+  UNSUPPORTED_PROVIDER = 'UNSUPPORTED_PROVIDER',
+  NORMALIZATION_FAILED = 'NORMALIZATION_FAILED',
+  PERSISTENCE_FAILED = 'PERSISTENCE_FAILED',
+  ANALYTICS_UPDATE_FAILED = 'ANALYTICS_UPDATE_FAILED',
+  NOTIFICATION_FAILED = 'NOTIFICATION_FAILED'
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "__tests__"]
+}