@bernierllc/email-tracking 1.0.0

package/src/EmailTracking.ts

@@ -0,0 +1,296 @@
+/*
+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 { NeverHubAdapter } from '@bernierllc/neverhub-adapter';
+import {
+  EmailSendRecord,
+  EmailEvent,
+  EmailTimeline,
+  RecipientHistory,
+  TrackingConfig,
+  EmailTrackingResult,
+  RecordEmailSentData,
+  WebhookEventData,
+  EmailDeliveryStatus,
+  EmailProvider,
+  CampaignStatistics
+} from './types.js';
+import { loadConfig } from './config.js';
+import { calculateNewStatus, mapWebhookEventType } from './status-calculator.js';
+import { Database } from './database.js';
+
+export class EmailTracking {
+  private neverhub?: NeverHubAdapter;
+  private logger?: Console;
+  private config: Required<TrackingConfig>;
+  private database: Database;
+  private initialized = false;
+
+  constructor(config: TrackingConfig = {}) {
+    this.config = loadConfig(config);
+    this.database = new Database();
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+
+    // Auto-detect NeverHub
+    if (await NeverHubAdapter.detect()) {
+      this.neverhub = new NeverHubAdapter();
+      await this.registerWithNeverHub();
+      await this.setupEventSubscriptions();
+    }
+
+    // Initialize logger
+    this.logger = this.neverhub
+      ? await this.neverhub.getService('logging')
+      : console;
+
+    await this.initializeCore();
+    this.initialized = true;
+  }
+
+  private async registerWithNeverHub(): Promise<void> {
+    if (!this.neverhub) return;
+
+    await this.neverhub.register({
+      type: 'email-tracking',
+      name: '@bernierllc/email-tracking',
+      version: '1.0.0',
+      dependencies: ['email-webhook-events', 'logging'],
+      capabilities: [
+        {
+          type: 'email',
+          name: 'delivery-tracking',
+          version: '1.0.0',
+          metadata: {
+            features: ['send-tracking', 'event-linking', 'timeline', 'recipient-history']
+          }
+        }
+      ],
+      discoveryEnabled: true,
+      discoverySubscriptions: [
+        {
+          pattern: 'capability.available',
+          handler: 'onCapabilityAvailable',
+          metadata: {
+            capabilityTypes: ['email', 'logging']
+          }
+        }
+      ]
+    });
+  }
+
+  private async setupEventSubscriptions(): Promise<void> {
+    if (!this.neverhub) return;
+
+    // Subscribe to email sent events
+    await this.neverhub.subscribe('email.sent', async (event: { data: RecordEmailSentData }) => {
+      await this.recordEmailSent(event.data);
+    });
+
+    // Subscribe to normalized webhook events
+    await this.neverhub.subscribe('email.webhook.*', async (event: { data: WebhookEventData }) => {
+      await this.processWebhookEvent(event.data);
+    });
+  }
+
+  async recordEmailSent(data: RecordEmailSentData): Promise<EmailTrackingResult<EmailSendRecord>> {
+    try {
+      const sendRecord: EmailSendRecord = {
+        id: this.generateTrackingId(),
+        messageId: data.messageId,
+        provider: data.provider as EmailProvider,
+        from: data.from,
+        to: data.to,
+        cc: data.cc,
+        bcc: data.bcc,
+        subject: data.subject,
+        campaignId: data.campaignId,
+        metadata: data.metadata,
+        sentAt: new Date(),
+        currentStatus: EmailDeliveryStatus.SENT,
+        updatedAt: new Date()
+      };
+
+      // Store send record
+      await this.database.storeSendRecord(sendRecord);
+
+      // Create initial "sent" event
+      const event: EmailEvent = {
+        id: this.generateEventId(),
+        sendRecordId: sendRecord.id,
+        eventType: EmailDeliveryStatus.SENT,
+        timestamp: sendRecord.sentAt,
+        metadata: { provider: data.provider }
+      };
+      await this.database.createEvent(event);
+
+      // Update recipient history
+      if (this.config.aggregateStats) {
+        await this.database.updateRecipientHistory(sendRecord.to, EmailDeliveryStatus.SENT);
+      }
+
+      this.logger?.log('Email send recorded', {
+        trackingId: sendRecord.id,
+        messageId: data.messageId,
+        recipients: data.to.length
+      });
+
+      return { success: true, data: sendRecord };
+    } catch (error) {
+      this.logger?.error('Failed to record email send', { error });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  async processWebhookEvent(webhookEvent: WebhookEventData): Promise<EmailTrackingResult> {
+    try {
+      // Find matching send record by messageId
+      const sendRecord = await this.database.findSendRecordByMessageId(webhookEvent.messageId);
+
+      if (!sendRecord) {
+        this.logger?.warn('No send record found for webhook event', {
+          messageId: webhookEvent.messageId,
+          eventType: webhookEvent.eventType
+        });
+        return { success: false, error: 'Send record not found' };
+      }
+
+      // Map webhook event type to our enum
+      const eventType = mapWebhookEventType(webhookEvent.eventType);
+
+      // Create event
+      const event: EmailEvent = {
+        id: this.generateEventId(),
+        sendRecordId: sendRecord.id,
+        eventType,
+        timestamp: new Date(webhookEvent.timestamp),
+        metadata: webhookEvent.metadata,
+        sourceEvent: webhookEvent
+      };
+
+      await this.database.createEvent(event);
+
+      // Update send record status
+      const newStatus = calculateNewStatus(sendRecord.currentStatus, eventType);
+
+      if (newStatus !== sendRecord.currentStatus) {
+        await this.database.updateSendRecordStatus(sendRecord.id, newStatus);
+
+        // Publish status change event
+        if (this.neverhub) {
+          await this.neverhub.publishEvent({
+            type: 'email.status_changed',
+            data: {
+              trackingId: sendRecord.id,
+              messageId: sendRecord.messageId,
+              oldStatus: sendRecord.currentStatus,
+              newStatus: newStatus,
+              eventType: eventType,
+              recipient: sendRecord.to[0],
+              timestamp: event.timestamp
+            }
+          });
+        }
+      }
+
+      // Update recipient history
+      if (this.config.aggregateStats) {
+        await this.database.updateRecipientHistory(sendRecord.to, eventType);
+      }
+
+      this.logger?.log('Webhook event processed', {
+        trackingId: sendRecord.id,
+        eventType: eventType,
+        newStatus: newStatus
+      });
+
+      return { success: true };
+    } catch (error) {
+      this.logger?.error('Failed to process webhook event', { error });
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  async getTimeline(trackingId: string): Promise<EmailTrackingResult<EmailTimeline>> {
+    try {
+      const sendRecord = await this.database.getSendRecord(trackingId);
+      if (!sendRecord) {
+        return { success: false, error: 'Send record not found' };
+      }
+
+      const events = await this.database.getEventsBySendRecord(trackingId);
+      const lastEvent = events[events.length - 1];
+
+      const timeline: EmailTimeline = {
+        sendRecord,
+        events,
+        currentStatus: sendRecord.currentStatus,
+        lastEventAt: lastEvent ? lastEvent.timestamp : sendRecord.sentAt
+      };
+
+      return { success: true, data: timeline };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  async getRecipientHistory(emailAddress: string): Promise<EmailTrackingResult<RecipientHistory>> {
+    try {
+      const history = await this.database.fetchRecipientHistory(emailAddress);
+      return { success: true, data: history };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  async getCampaignStats(campaignId: string): Promise<EmailTrackingResult<CampaignStatistics>> {
+    try {
+      const stats = await this.database.aggregateCampaignStats(campaignId);
+      return { success: true, data: stats };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  private generateTrackingId(): string {
+    return `track_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private generateEventId(): string {
+    return `event_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+
+  private async initializeCore(): Promise<void> {
+    // Core initialization (database connections, etc.)
+    // In production, this would set up real database connections
+  }
+
+  // Test helper to clear database
+  async clearDatabase(): Promise<void> {
+    await this.database.clear();
+  }
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+/*
+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 { TrackingConfig } from './types.js';
+
+export function loadConfig(userConfig: TrackingConfig = {}): Required<TrackingConfig> {
+  return {
+    enableOpenTracking: userConfig.enableOpenTracking !== undefined
+      ? userConfig.enableOpenTracking
+      : (process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING === 'true' || process.env.EMAIL_TRACKING_ENABLE_OPEN_TRACKING === undefined),
+    enableClickTracking: userConfig.enableClickTracking !== undefined
+      ? userConfig.enableClickTracking
+      : (process.env.EMAIL_TRACKING_ENABLE_CLICK_TRACKING === 'true' || process.env.EMAIL_TRACKING_ENABLE_CLICK_TRACKING === undefined),
+    eventRetentionDays: userConfig.eventRetentionDays !== undefined
+      ? userConfig.eventRetentionDays
+      : parseInt(process.env.EMAIL_TRACKING_EVENT_RETENTION_DAYS || '90', 10),
+    aggregateStats: userConfig.aggregateStats !== undefined
+      ? userConfig.aggregateStats
+      : (process.env.EMAIL_TRACKING_AGGREGATE_STATS === 'true' || process.env.EMAIL_TRACKING_AGGREGATE_STATS === undefined)
+  };
+}

package/src/database.ts

@@ -0,0 +1,179 @@
+/*
+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 {
+  EmailSendRecord,
+  EmailEvent,
+  RecipientHistory,
+  EmailDeliveryStatus,
+  CampaignStatistics
+} from './types.js';
+
+/**
+ * In-memory database implementation for email tracking.
+ * In production, this would be replaced with a real database (PostgreSQL, etc.)
+ */
+export class Database {
+  private sendRecords: Map<string, EmailSendRecord> = new Map();
+  private messageIdIndex: Map<string, string> = new Map(); // messageId -> trackingId
+  private events: Map<string, EmailEvent[]> = new Map(); // sendRecordId -> events[]
+  private recipientHistory: Map<string, RecipientHistory> = new Map();
+
+  async storeSendRecord(record: EmailSendRecord): Promise<void> {
+    this.sendRecords.set(record.id, record);
+    this.messageIdIndex.set(record.messageId, record.id);
+  }
+
+  async getSendRecord(trackingId: string): Promise<EmailSendRecord | null> {
+    return this.sendRecords.get(trackingId) || null;
+  }
+
+  async findSendRecordByMessageId(messageId: string): Promise<EmailSendRecord | null> {
+    const trackingId = this.messageIdIndex.get(messageId);
+    if (!trackingId) return null;
+    return this.getSendRecord(trackingId);
+  }
+
+  async updateSendRecordStatus(trackingId: string, status: EmailDeliveryStatus): Promise<void> {
+    const record = this.sendRecords.get(trackingId);
+    if (record) {
+      record.currentStatus = status;
+      record.updatedAt = new Date();
+      this.sendRecords.set(trackingId, record);
+    }
+  }
+
+  async createEvent(event: EmailEvent): Promise<void> {
+    const existingEvents = this.events.get(event.sendRecordId) || [];
+    existingEvents.push(event);
+    this.events.set(event.sendRecordId, existingEvents);
+  }
+
+  async getEventsBySendRecord(sendRecordId: string): Promise<EmailEvent[]> {
+    return this.events.get(sendRecordId) || [];
+  }
+
+  async updateRecipientHistory(recipients: string[], eventType: EmailDeliveryStatus): Promise<void> {
+    for (const recipient of recipients) {
+      let history = this.recipientHistory.get(recipient);
+
+      if (!history) {
+        history = {
+          emailAddress: recipient,
+          totalSent: 0,
+          totalDelivered: 0,
+          totalBounced: 0,
+          totalOpened: 0,
+          totalClicked: 0,
+          totalComplained: 0,
+          totalUnsubscribed: 0,
+          reputationScore: 100
+        };
+      }
+
+      const now = new Date();
+
+      switch (eventType) {
+        case EmailDeliveryStatus.SENT:
+          history.totalSent++;
+          history.lastSentAt = now;
+          break;
+        case EmailDeliveryStatus.DELIVERED:
+          history.totalDelivered++;
+          history.lastDeliveredAt = now;
+          break;
+        case EmailDeliveryStatus.BOUNCED:
+          history.totalBounced++;
+          history.lastBouncedAt = now;
+          history.reputationScore = Math.max(0, history.reputationScore - 10);
+          break;
+        case EmailDeliveryStatus.OPENED:
+          history.totalOpened++;
+          history.lastOpenedAt = now;
+          break;
+        case EmailDeliveryStatus.CLICKED:
+          history.totalClicked++;
+          history.lastClickedAt = now;
+          break;
+        case EmailDeliveryStatus.COMPLAINED:
+          history.totalComplained++;
+          history.reputationScore = Math.max(0, history.reputationScore - 25);
+          break;
+        case EmailDeliveryStatus.UNSUBSCRIBED:
+          history.totalUnsubscribed++;
+          history.reputationScore = Math.max(0, history.reputationScore - 5);
+          break;
+      }
+
+      this.recipientHistory.set(recipient, history);
+    }
+  }
+
+  async fetchRecipientHistory(emailAddress: string): Promise<RecipientHistory> {
+    const history = this.recipientHistory.get(emailAddress);
+
+    if (!history) {
+      return {
+        emailAddress,
+        totalSent: 0,
+        totalDelivered: 0,
+        totalBounced: 0,
+        totalOpened: 0,
+        totalClicked: 0,
+        totalComplained: 0,
+        totalUnsubscribed: 0,
+        reputationScore: 100
+      };
+    }
+
+    return history;
+  }
+
+  async aggregateCampaignStats(campaignId: string): Promise<CampaignStatistics> {
+    const campaignRecords = Array.from(this.sendRecords.values())
+      .filter(record => record.campaignId === campaignId);
+
+    const totalSent = campaignRecords.length;
+    const totalDelivered = campaignRecords.filter(r =>
+      [EmailDeliveryStatus.DELIVERED, EmailDeliveryStatus.OPENED, EmailDeliveryStatus.CLICKED]
+        .includes(r.currentStatus)
+    ).length;
+    const totalBounced = campaignRecords.filter(r => r.currentStatus === EmailDeliveryStatus.BOUNCED).length;
+    const totalOpened = campaignRecords.filter(r =>
+      [EmailDeliveryStatus.OPENED, EmailDeliveryStatus.CLICKED].includes(r.currentStatus)
+    ).length;
+    const totalClicked = campaignRecords.filter(r => r.currentStatus === EmailDeliveryStatus.CLICKED).length;
+    const totalComplained = campaignRecords.filter(r => r.currentStatus === EmailDeliveryStatus.COMPLAINED).length;
+    const totalUnsubscribed = campaignRecords.filter(r => r.currentStatus === EmailDeliveryStatus.UNSUBSCRIBED).length;
+
+    const deliveryRate = totalSent > 0 ? (totalDelivered / totalSent) * 100 : 0;
+    const openRate = totalDelivered > 0 ? (totalOpened / totalDelivered) * 100 : 0;
+    const clickRate = totalOpened > 0 ? (totalClicked / totalOpened) * 100 : 0;
+
+    return {
+      campaignId,
+      totalSent,
+      totalDelivered,
+      totalBounced,
+      totalOpened,
+      totalClicked,
+      totalComplained,
+      totalUnsubscribed,
+      deliveryRate: Math.round(deliveryRate * 100) / 100,
+      openRate: Math.round(openRate * 100) / 100,
+      clickRate: Math.round(clickRate * 100) / 100
+    };
+  }
+
+  async clear(): Promise<void> {
+    this.sendRecords.clear();
+    this.messageIdIndex.clear();
+    this.events.clear();
+    this.recipientHistory.clear();
+  }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/*
+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 { EmailTracking } from './EmailTracking.js';
+export * from './types.js';
+export { calculateNewStatus, mapWebhookEventType } from './status-calculator.js';
+export { loadConfig } from './config.js';

package/src/status-calculator.ts

@@ -0,0 +1,43 @@
+/*
+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 { EmailDeliveryStatus } from './types.js';
+
+const STATUS_PRIORITY: Record<EmailDeliveryStatus, number> = {
+  [EmailDeliveryStatus.COMPLAINED]: 7,
+  [EmailDeliveryStatus.UNSUBSCRIBED]: 6,
+  [EmailDeliveryStatus.BOUNCED]: 5,
+  [EmailDeliveryStatus.FAILED]: 4,
+  [EmailDeliveryStatus.CLICKED]: 3,
+  [EmailDeliveryStatus.OPENED]: 2,
+  [EmailDeliveryStatus.DELIVERED]: 1,
+  [EmailDeliveryStatus.SENT]: 0
+};
+
+export function calculateNewStatus(
+  currentStatus: EmailDeliveryStatus,
+  eventType: EmailDeliveryStatus
+): EmailDeliveryStatus {
+  return STATUS_PRIORITY[eventType] > STATUS_PRIORITY[currentStatus]
+    ? eventType
+    : currentStatus;
+}
+
+export function mapWebhookEventType(webhookEventType: string): EmailDeliveryStatus {
+  const mapping: Record<string, EmailDeliveryStatus> = {
+    delivered: EmailDeliveryStatus.DELIVERED,
+    bounce: EmailDeliveryStatus.BOUNCED,
+    open: EmailDeliveryStatus.OPENED,
+    click: EmailDeliveryStatus.CLICKED,
+    spamreport: EmailDeliveryStatus.COMPLAINED,
+    unsubscribe: EmailDeliveryStatus.UNSUBSCRIBED,
+    failed: EmailDeliveryStatus.FAILED
+  };
+
+  return mapping[webhookEventType.toLowerCase()] || EmailDeliveryStatus.SENT;
+}

package/src/types.ts

@@ -0,0 +1,115 @@
+/*
+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 enum EmailDeliveryStatus {
+  SENT = 'sent',
+  DELIVERED = 'delivered',
+  BOUNCED = 'bounced',
+  OPENED = 'opened',
+  CLICKED = 'clicked',
+  COMPLAINED = 'complained',
+  UNSUBSCRIBED = 'unsubscribed',
+  FAILED = 'failed'
+}
+
+export type EmailProvider = 'sendgrid' | 'mailgun' | 'ses' | 'postmark';
+
+export interface EmailSendRecord {
+  id: string;
+  messageId: string;
+  provider: EmailProvider;
+  from: string;
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  campaignId?: string;
+  metadata?: Record<string, unknown>;
+  sentAt: Date;
+  currentStatus: EmailDeliveryStatus;
+  updatedAt: Date;
+}
+
+export interface EmailEvent {
+  id: string;
+  sendRecordId: string;
+  eventType: EmailDeliveryStatus;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+  sourceEvent?: unknown;
+}
+
+export interface EmailTimeline {
+  sendRecord: EmailSendRecord;
+  events: EmailEvent[];
+  currentStatus: EmailDeliveryStatus;
+  lastEventAt: Date;
+}
+
+export interface RecipientHistory {
+  emailAddress: string;
+  totalSent: number;
+  totalDelivered: number;
+  totalBounced: number;
+  totalOpened: number;
+  totalClicked: number;
+  totalComplained: number;
+  totalUnsubscribed: number;
+  lastSentAt?: Date;
+  lastDeliveredAt?: Date;
+  lastBouncedAt?: Date;
+  lastOpenedAt?: Date;
+  lastClickedAt?: Date;
+  reputationScore: number;
+}
+
+export interface TrackingConfig {
+  enableOpenTracking?: boolean;
+  enableClickTracking?: boolean;
+  eventRetentionDays?: number;
+  aggregateStats?: boolean;
+}
+
+export interface EmailTrackingResult<T = unknown> {
+  success: boolean;
+  data?: T;
+  error?: string;
+}
+
+export interface RecordEmailSentData {
+  messageId: string;
+  provider: string;
+  from: string;
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  subject: string;
+  campaignId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WebhookEventData {
+  messageId: string;
+  eventType: string;
+  timestamp: string | Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CampaignStatistics {
+  campaignId: string;
+  totalSent: number;
+  totalDelivered: number;
+  totalBounced: number;
+  totalOpened: number;
+  totalClicked: number;
+  totalComplained: number;
+  totalUnsubscribed: number;
+  deliveryRate: number;
+  openRate: number;
+  clickRate: number;
+}

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__"]
+}