@bernierllc/email-service 2.0.1

package/README.md

@@ -0,0 +1,578 @@
+# @bernierllc/email-service
+
+Comprehensive email service orchestrating template management, multi-provider delivery, tracking, and subscriber management.
+
+## Features
+
+- **Multi-Provider Support** - SendGrid, Mailgun, AWS SES, and SMTP
+- **Template Management** - Create, update, and render email templates with variable substitution
+- **Delivery Tracking** - Track email delivery, opens, clicks, and bounces
+- **Subscriber Management** - Manage subscribers, lists, and preferences
+- **Queue Integration** - Schedule and send emails in background
+- **Webhook Handling** - Process provider webhooks for delivery events
+- **Database Persistence** - Store templates, delivery records, and subscribers
+- **Analytics** - Comprehensive delivery statistics and reporting
+
+## Installation
+
+```bash
+npm install @bernierllc/email-service
+```
+
+### Peer Dependencies
+
+Install email provider(s) you need:
+
+```bash
+# SendGrid
+npm install @sendgrid/mail
+
+# SMTP (included)
+npm install nodemailer
+```
+
+## Usage
+
+### Quick Start
+
+```typescript
+import { EmailService } from '@bernierllc/email-service';
+
+const service = new EmailService({
+  providers: [
+    {
+      type: 'smtp',
+      smtp: {
+        host: 'smtp.gmail.com',
+        port: 587,
+        secure: false,
+        auth: { user: 'you@gmail.com', pass: 'password' }
+      }
+    }
+  ],
+  defaultProvider: 'smtp',
+  database: {
+    type: 'sqlite',
+    database: './data/email.db'
+  },
+  templates: {
+    cacheEnabled: true,
+    cacheTTL: 3600
+  },
+  tracking: {
+    enabled: true,
+    domain: 'yourdomain.com'
+  }
+});
+
+await service.initialize();
+
+// Send an email
+const result = await service.send({
+  from: 'noreply@yourdomain.com',
+  to: ['user@example.com'],
+  subject: 'Welcome!',
+  html: '<h1>Hello!</h1><p>Welcome to our service.</p>'
+});
+
+console.log(`Email sent: ${result.messageId}`);
+```
+
+## Core Concepts
+
+### 1. Multi-Provider Email Sending
+
+```typescript
+// Configure multiple providers
+const service = new EmailService({
+  providers: [
+    {
+      type: 'sendgrid',
+      apiKey: process.env.SENDGRID_API_KEY
+    },
+    {
+      type: 'mailgun',
+      apiKey: process.env.MAILGUN_API_KEY,
+      domain: 'mg.yourdomain.com'
+    },
+    {
+      type: 'ses',
+      region: 'us-east-1',
+      apiKey: process.env.AWS_ACCESS_KEY,
+      secretKey: process.env.AWS_SECRET_KEY
+    },
+    {
+      type: 'smtp',
+      smtp: {
+        host: 'smtp.gmail.com',
+        port: 587,
+        secure: false,
+        auth: {
+          user: process.env.SMTP_USER,
+          pass: process.env.SMTP_PASS
+        }
+      }
+    }
+  ],
+  defaultProvider: 'sendgrid',
+  database: { type: 'sqlite', database: './email.db' }
+});
+
+// Send via specific provider
+await service.send({
+  from: 'noreply@yourdomain.com',
+  to: ['user@example.com'],
+  subject: 'Test',
+  html: '<p>Test</p>',
+  provider: 'mailgun' // Override default
+});
+```
+
+### 2. Template Management
+
+```typescript
+// Create template
+const template = await service.createTemplate({
+  name: 'welcome-email',
+  subject: 'Welcome {{name}}!',
+  html: `
+    <h1>Hello {{name}}</h1>
+    <p>Welcome to {{company}}!</p>
+    <p>Your account email is: {{email}}</p>
+  `,
+  text: 'Hello {{name}}, welcome to {{company}}!'
+});
+
+// Send using template
+await service.send({
+  from: 'noreply@yourdomain.com',
+  to: ['user@example.com'],
+  templateId: template.id,
+  templateData: {
+    name: 'John Doe',
+    company: 'Acme Corp',
+    email: 'john@example.com'
+  }
+});
+
+// Update template
+await service.updateTemplate(template.id, {
+  subject: 'Welcome to {{company}}, {{name}}!',
+  html: '<h1>Welcome {{name}}!</h1>'
+});
+
+// Get template
+const retrieved = await service.getTemplate(template.id);
+console.log(retrieved.variables); // ['name', 'company', 'email']
+
+// Delete template
+await service.deleteTemplate(template.id);
+```
+
+### 3. Delivery Tracking
+
+```typescript
+// Send email
+const result = await service.send({
+  from: 'noreply@yourdomain.com',
+  to: ['user@example.com'],
+  subject: 'Order Confirmation',
+  html: '<h1>Thanks for your order!</h1>'
+});
+
+// Get delivery record
+const delivery = await service.getDelivery(result.deliveryId);
+console.log(delivery.status); // 'sent', 'delivered', 'opened', 'clicked', etc.
+
+// Track opens
+await service.trackOpen(result.deliveryId);
+
+// Track clicks
+await service.trackClick(result.deliveryId);
+
+// Get statistics
+const stats = await service.getDeliveryStats();
+console.log(`Open rate: ${stats.openRate}%`);
+console.log(`Click rate: ${stats.clickRate}%`);
+console.log(`Bounce rate: ${stats.bounceRate}%`);
+
+// Get statistics for date range
+const monthStats = await service.getDeliveryStats(
+  new Date('2025-01-01'),
+  new Date('2025-01-31')
+);
+```
+
+### 4. Subscriber Management
+
+```typescript
+// Create subscriber
+const subscriber = await service.createSubscriber({
+  email: 'user@example.com',
+  name: 'John Doe',
+  lists: ['newsletter', 'updates'],
+  tags: ['premium', 'early-adopter'],
+  metadata: {
+    source: 'website',
+    signupDate: new Date()
+  }
+});
+
+// Get subscriber
+const found = await service.getSubscriber(subscriber.id);
+
+// Update subscriber
+await service.updateSubscriber(subscriber.id, {
+  name: 'John Smith',
+  tags: ['premium', 'verified']
+});
+
+// Unsubscribe
+await service.unsubscribe('user@example.com');
+
+// Create subscriber list
+const list = await service.createList(
+  'Monthly Newsletter',
+  'Our monthly product updates and news'
+);
+```
+
+### 5. Scheduled Emails
+
+```typescript
+// Configure queue
+const service = new EmailService({
+  providers: [/* ... */],
+  database: { type: 'sqlite', database: './email.db' },
+  queue: {
+    backend: new MemoryBackend(),
+    concurrency: 5,
+    retryPolicy: {
+      maxAttempts: 3,
+      backoff: { type: 'exponential', delay: 1000 }
+    }
+  }
+});
+
+// Schedule for later
+await service.send({
+  from: 'noreply@yourdomain.com',
+  to: ['user@example.com'],
+  subject: 'Reminder',
+  html: '<p>This is your reminder</p>',
+  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000) // 24 hours
+});
+
+// Send with priority
+await service.send({
+  from: 'alerts@yourdomain.com',
+  to: ['admin@yourdomain.com'],
+  subject: 'URGENT: System Alert',
+  html: '<p>Critical alert</p>',
+  priority: 'high' // high, normal, low
+});
+```
+
+### 6. Bulk Sending
+
+```typescript
+const results = await service.sendBulk([
+  {
+    from: 'noreply@yourdomain.com',
+    to: ['user1@example.com'],
+    subject: 'Personalized for User 1',
+    html: '<p>Hello User 1</p>'
+  },
+  {
+    from: 'noreply@yourdomain.com',
+    to: ['user2@example.com'],
+    subject: 'Personalized for User 2',
+    html: '<p>Hello User 2</p>'
+  }
+]);
+
+results.forEach((result, index) => {
+  console.log(`Email ${index + 1}: ${result.success ? 'sent' : 'failed'}`);
+});
+```
+
+### 7. Webhook Handling
+
+```typescript
+// Register webhook handler
+service.registerWebhookHandler('delivered', async (event) => {
+  console.log(`Email ${event.messageId} was delivered`);
+  // Update your database, trigger workflows, etc.
+});
+
+service.registerWebhookHandler('opened', async (event) => {
+  console.log(`Email ${event.messageId} was opened`);
+  // Track user engagement
+});
+
+service.registerWebhookHandler('clicked', async (event) => {
+  console.log(`Link clicked in ${event.messageId}`);
+  // Track click-through rates
+});
+
+service.registerWebhookHandler('bounced', async (event) => {
+  console.log(`Email ${event.messageId} bounced`);
+  // Update subscriber status
+  await service.unsubscribe(event.data.email);
+});
+
+// Process webhook from provider
+await service.handleWebhook({
+  provider: 'sendgrid',
+  event: 'delivered',
+  messageId: 'msg_123',
+  timestamp: new Date(),
+  data: { /* provider-specific data */ }
+});
+```
+
+## API Reference
+
+### EmailService
+
+#### Constructor
+
+```typescript
+new EmailService(config: EmailServiceConfig)
+```
+
+**Configuration:**
+
+```typescript
+interface EmailServiceConfig {
+  providers: ProviderConfig[];
+  defaultProvider?: EmailProvider;
+  database: DatabaseConfig;
+  queue?: QueueOptions;
+  templates?: {
+    cacheEnabled?: boolean;
+    cacheTTL?: number;
+  };
+  tracking?: {
+    enabled?: boolean;
+    domain?: string;
+  };
+  compliance?: {
+    unsubscribeLink?: boolean;
+    footerRequired?: boolean;
+  };
+}
+
+interface ProviderConfig {
+  type: 'sendgrid' | 'mailgun' | 'ses' | 'smtp';
+  apiKey?: string;
+  domain?: string;
+  region?: string;
+  smtp?: SMTPConfig;
+  rateLimit?: RateLimitConfig;
+}
+```
+
+#### Methods
+
+##### Email Sending
+
+- `send(request: EmailRequest): Promise<SendEmailResult>` - Send email
+- `sendBulk(requests: EmailRequest[]): Promise<SendEmailResult[]>` - Send multiple emails
+
+##### Template Management
+
+- `createTemplate(request: TemplateCreateRequest): Promise<EmailTemplate>` - Create template
+- `getTemplate(id: string): Promise<EmailTemplate | null>` - Get template
+- `updateTemplate(id: string, update: TemplateUpdateRequest): Promise<EmailTemplate>` - Update template
+- `deleteTemplate(id: string): Promise<boolean>` - Delete template
+
+##### Delivery Tracking
+
+- `getDelivery(id: string): Promise<DeliveryRecord | null>` - Get delivery record
+- `trackOpen(deliveryId: string): Promise<void>` - Track email open
+- `trackClick(deliveryId: string): Promise<void>` - Track link click
+- `getDeliveryStats(startDate?: Date, endDate?: Date): Promise<DeliveryStats>` - Get statistics
+
+##### Subscriber Management
+
+- `createSubscriber(request: SubscriberCreateRequest): Promise<Subscriber>` - Create subscriber
+- `getSubscriber(id: string): Promise<Subscriber | null>` - Get subscriber
+- `updateSubscriber(id: string, update: SubscriberUpdateRequest): Promise<Subscriber>` - Update subscriber
+- `unsubscribe(email: string): Promise<boolean>` - Unsubscribe email
+- `createList(name: string, description?: string): Promise<SubscriberList>` - Create list
+
+##### Webhook Handling
+
+- `registerWebhookHandler(event: string, handler: WebhookHandler): void` - Register handler
+- `handleWebhook(event: WebhookEvent): Promise<void>` - Process webhook
+
+##### Lifecycle
+
+- `initialize(): Promise<void>` - Initialize service
+- `shutdown(): Promise<void>` - Cleanup and shutdown
+
+## Type Definitions
+
+```typescript
+interface EmailRequest {
+  from: EmailAddress | string;
+  to: EmailAddress[] | string[];
+  cc?: EmailAddress[] | string[];
+  bcc?: EmailAddress[] | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  templateId?: string;
+  templateData?: TemplateContext;
+  attachments?: EmailAttachment[];
+  headers?: Record<string, string>;
+  tags?: string[];
+  metadata?: Record<string, any>;
+  priority?: 'high' | 'normal' | 'low';
+  scheduledAt?: Date;
+  provider?: EmailProvider;
+}
+
+interface SendEmailResult {
+  success: boolean;
+  messageId?: string;
+  deliveryId?: string;
+  provider?: EmailProvider;
+  error?: string;
+  timestamp: Date;
+  queuedForLater?: boolean;
+}
+
+interface DeliveryStats {
+  total: number;
+  sent: number;
+  delivered: number;
+  opened: number;
+  clicked: number;
+  bounced: number;
+  failed: number;
+  openRate: number;
+  clickRate: number;
+  bounceRate: number;
+}
+
+enum DeliveryStatus {
+  QUEUED = 'queued',
+  SENDING = 'sending',
+  SENT = 'sent',
+  DELIVERED = 'delivered',
+  OPENED = 'opened',
+  CLICKED = 'clicked',
+  BOUNCED = 'bounced',
+  FAILED = 'failed',
+  UNSUBSCRIBED = 'unsubscribed'
+}
+```
+
+## Best Practices
+
+### Error Handling
+
+```typescript
+try {
+  await service.send(emailRequest);
+} catch (error) {
+  if (error instanceof ProviderError) {
+    // Switch to backup provider
+    console.error('Provider failed:', error.provider);
+  } else if (error instanceof TemplateError) {
+    // Template rendering failed
+    console.error('Template error:', error.message);
+  } else if (error instanceof DeliveryError) {
+    // Delivery failed
+    console.error('Delivery error:', error.message);
+  }
+}
+```
+
+### Template Variables
+
+```typescript
+// Always validate template data matches template variables
+const template = await service.getTemplate(templateId);
+const missingVars = template.variables.filter(
+  v => !(v in templateData)
+);
+if (missingVars.length > 0) {
+  throw new Error(`Missing template variables: ${missingVars.join(', ')}`);
+}
+```
+
+### Rate Limiting
+
+```typescript
+// Configure per-provider rate limits
+const service = new EmailService({
+  providers: [
+    {
+      type: 'sendgrid',
+      apiKey: process.env.SENDGRID_API_KEY,
+      rateLimit: {
+        maxPerSecond: 100,
+        maxPerMinute: 5000,
+        maxPerHour: 100000
+      }
+    }
+  ],
+  // ...
+});
+```
+
+### Monitoring
+
+```typescript
+// Regular health monitoring
+setInterval(async () => {
+  const stats = await service.getDeliveryStats();
+
+  if (stats.bounceRate > 5) {
+    console.warn('High bounce rate detected:', stats.bounceRate);
+  }
+
+  if (stats.failed > 100) {
+    console.error('High failure count:', stats.failed);
+  }
+}, 60000); // Every minute
+```
+
+## Dependencies
+
+This package orchestrates:
+
+- [@bernierllc/email-sender](../../core/email-sender) - Multi-provider email delivery
+- [@bernierllc/email-parser](../../core/email-parser) - Email content parsing
+- [@bernierllc/template-engine](../../core/template-engine) - Template rendering
+- [@bernierllc/queue-manager](../../core/queue-manager) - Background job processing
+- [@bernierllc/webhook-validator](../../core/webhook-validator) - Webhook verification
+- [@bernierllc/database-adapter](../../core/database-adapter) - Data persistence
+- [@bernierllc/logger](../../core/logger) - Structured logging
+- [@bernierllc/config-manager](../../core/config-manager) - Configuration management
+
+## Integration Status
+
+- **Logger**: Integrated - Uses @bernierllc/logger for structured logging
+- **Docs-Suite**: Ready - Markdown documentation available
+- **NeverHub integration**: Planned - Service discovery and event bus integration with @bernierllc/neverhub-adapter
+
+## Examples
+
+See the [examples directory](./examples) for complete working examples:
+
+- `basic-smtp.ts` - Basic SMTP email sending
+- `templates.ts` - Template management and rendering
+- `tracking.ts` - Delivery tracking and analytics
+- `subscribers.ts` - Subscriber management
+- `webhooks.ts` - Webhook handling
+- `multi-provider.ts` - Multi-provider configuration
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+This package is proprietary software licensed for use only within the scope of the project it was delivered for.

package/dist/email-service.d.ts

@@ -0,0 +1,39 @@
+import type { EmailServiceConfig, EmailRequest, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler } from './types.js';
+export declare class EmailService {
+    private db;
+    private queue?;
+    private templateEngine;
+    private emailSenders;
+    private logger;
+    private config;
+    private webhookHandlers;
+    private templateCache;
+    constructor(config: EmailServiceConfig);
+    private initializeProviders;
+    initialize(): Promise<void>;
+    private createTables;
+    send(request: EmailRequest): Promise<SendEmailResult>;
+    private scheduleEmail;
+    sendBulk(requests: EmailRequest[]): Promise<SendEmailResult[]>;
+    createTemplate(request: TemplateCreateRequest): Promise<EmailTemplate>;
+    getTemplate(id: string): Promise<EmailTemplate | null>;
+    updateTemplate(id: string, update: TemplateUpdateRequest): Promise<EmailTemplate>;
+    deleteTemplate(id: string): Promise<boolean>;
+    private renderTemplate;
+    private extractVariables;
+    getDelivery(id: string): Promise<DeliveryRecord | null>;
+    trackOpen(deliveryId: string): Promise<void>;
+    trackClick(deliveryId: string): Promise<void>;
+    getDeliveryStats(startDate?: Date, endDate?: Date): Promise<DeliveryStats>;
+    private parseDeliveryRecord;
+    createSubscriber(request: SubscriberCreateRequest): Promise<Subscriber>;
+    getSubscriber(id: string): Promise<Subscriber | null>;
+    updateSubscriber(id: string, update: SubscriberUpdateRequest): Promise<Subscriber>;
+    unsubscribe(email: string): Promise<boolean>;
+    private parseSubscriber;
+    createList(name: string, description?: string): Promise<SubscriberList>;
+    registerWebhookHandler(event: string, handler: WebhookHandler): void;
+    handleWebhook(event: WebhookEvent): Promise<void>;
+    shutdown(): Promise<void>;
+    private generateId;
+}