@bernierllc/email-manager 0.4.0 → 0.4.2

package/README.md

@@ -529,6 +529,659 @@ emailManager.shutdown();
 
 This stops the scheduler and cleans up resources.
 
+---
+
+## Enhanced Features
+
+The `EnhancedEmailManager` extends the base `EmailManager` with calendar invites, batch sending, subscription management, unsubscribe flows, and more. All enhanced features are available through a single import:
+
+```typescript
+import { EnhancedEmailManager, EnhancedEmailManagerConfig } from '@bernierllc/email-manager';
+```
+
+### Calendar Invites
+
+Send calendar invitations (ICS) and cancellations as email attachments. The manager generates valid ICS content using the `@bernierllc/email-calendar` package and attaches it automatically.
+
+#### Send a Calendar Invite
+
+```typescript
+import { EnhancedEmailManager, CalendarEvent } from '@bernierllc/email-manager';
+
+const event: CalendarEvent = {
+  uid: 'meeting-2025-q2@example.com',
+  title: 'Q2 Business Review',
+  description: 'Quarterly review of business metrics.',
+  start: new Date('2025-07-15T14:00:00Z'),
+  end: new Date('2025-07-15T15:30:00Z'),
+  location: 'Conference Room A',
+  organizer: { email: 'organizer@example.com', name: 'Alice Johnson' },
+  attendees: [
+    { email: 'bob@example.com', name: 'Bob Smith', role: 'REQ-PARTICIPANT' },
+    { email: 'carol@example.com', name: 'Carol Lee', role: 'OPT-PARTICIPANT' },
+  ],
+};
+
+const result = await manager.sendCalendarInvite(
+  event,
+  ['bob@example.com', 'carol@example.com'],
+);
+
+console.log('Invite sent:', result.success);
+```
+
+You can customize the subject and body:
+
+```typescript
+const result = await manager.sendCalendarInvite(event, recipients, {
+  subject: 'You are invited: Q2 Business Review',
+  htmlBody: '<h2>Q2 Review</h2><p>Please join us for the quarterly review.</p>',
+  textBody: 'Please join us for the Q2 quarterly review.',
+  metadata: { campaign: 'internal-meetings' },
+});
+```
+
+#### Cancel a Calendar Event
+
+```typescript
+import { CalendarAttendee } from '@bernierllc/email-manager';
+
+const organizer: CalendarAttendee = { email: 'organizer@example.com', name: 'Alice' };
+const attendees: CalendarAttendee[] = [
+  { email: 'bob@example.com', name: 'Bob' },
+  { email: 'carol@example.com', name: 'Carol' },
+];
+
+const result = await manager.sendCalendarCancel(
+  'meeting-2025-q2@example.com', // UID of the original event
+  organizer,
+  attendees,
+  {
+    subject: 'Cancelled: Q2 Business Review',
+    htmlBody: '<p>The Q2 Business Review has been cancelled.</p>',
+  },
+);
+```
+
+> See [`examples/calendar-invites.ts`](examples/calendar-invites.ts) for a complete working example.
+
+---
+
+### Batch Sending
+
+Send large volumes of email with built-in concurrency control, rate limiting, retry logic, and progress tracking. Powered by `@bernierllc/email-batch-sender`.
+
+#### Basic Batch Send
+
+```typescript
+import { BatchEmailInput } from '@bernierllc/email-manager';
+
+const emails: BatchEmailInput[] = [
+  {
+    toEmail: 'alice@example.com',
+    subject: 'Newsletter - July',
+    htmlContent: '<h1>Newsletter</h1><p>Hello Alice...</p>',
+    textContent: 'Newsletter\n\nHello Alice...',
+  },
+  {
+    toEmail: 'bob@example.com',
+    subject: 'Newsletter - July',
+    htmlContent: '<h1>Newsletter</h1><p>Hello Bob...</p>',
+  },
+];
+
+const result = await manager.sendBatch(emails);
+console.log(`Sent: ${result.succeeded}/${result.total}, Failed: ${result.failed}`);
+```
+
+#### Batch Send with Rate Limiting and Retry
+
+```typescript
+import { BatchSenderOptions } from '@bernierllc/email-manager';
+
+const options: BatchSenderOptions = {
+  concurrency: 5,               // Up to 5 emails in parallel
+  rateLimit: {
+    maxPerSecond: 10,            // Respect provider rate limits
+  },
+  retry: {
+    maxRetries: 3,               // Retry failed sends
+    initialDelayMs: 1000,        // 1 second initial delay
+    backoffMultiplier: 2,        // Exponential backoff
+  },
+  failureStrategy: 'continue',  // Keep sending even if some fail
+};
+
+const result = await manager.sendBatch(emails, options);
+```
+
+#### Batch Send with Progress Tracking
+
+```typescript
+const result = await manager.sendBatch(emails, {
+  concurrency: 3,
+  onProgress: (progress) => {
+    const pct = ((progress.completed / progress.total) * 100).toFixed(0);
+    console.log(`Progress: ${pct}% - ${progress.succeeded} sent, ${progress.failed} failed`);
+  },
+});
+```
+
+#### Abort on Failure
+
+For critical emails where partial delivery is unacceptable:
+
+```typescript
+const result = await manager.sendBatch(criticalEmails, {
+  concurrency: 1,
+  failureStrategy: 'abort',  // Stop immediately on first failure
+  retry: { maxRetries: 5 },
+});
+
+if (result.aborted) {
+  console.error('Batch was aborted due to a failure');
+}
+```
+
+> See [`examples/batch-sending.ts`](examples/batch-sending.ts) for complete examples.
+
+---
+
+### Subscription Management
+
+Manage subscriber lists, add/remove subscribers, and handle bulk imports. The subscription system uses `@bernierllc/email-subscription` under the hood.
+
+#### Create Subscriber Lists
+
+```typescript
+const newsletter = await manager.createSubscriberList('Monthly Newsletter', {
+  description: 'Monthly product newsletter subscribers',
+  metadata: { category: 'marketing' },
+});
+
+console.log('List ID:', newsletter.id);
+```
+
+#### Add Subscribers
+
+```typescript
+// Individual subscriber
+await manager.addSubscriber(newsletter.id, {
+  email: 'alice@example.com',
+  name: 'Alice Johnson',
+});
+
+// Bulk add (skips duplicates and suppressed emails)
+const result = await manager.addSubscribers(newsletter.id, [
+  { email: 'user1@example.com', name: 'User One' },
+  { email: 'user2@example.com', name: 'User Two' },
+  { email: 'user3@example.com', name: 'User Three' },
+]);
+
+console.log(`Added: ${result.added}, Skipped: ${result.skipped}`);
+```
+
+#### Look Up and Remove Subscribers
+
+```typescript
+// Look up a subscriber
+const subscriber = await manager.getSubscriber(newsletter.id, 'alice@example.com');
+if (subscriber) {
+  console.log('Status:', subscriber.status);
+}
+
+// Remove a subscriber
+const removed = await manager.removeSubscriber(newsletter.id, 'alice@example.com');
+```
+
+#### Delete a List
+
+```typescript
+const deleted = await manager.deleteSubscriberList(newsletter.id);
+```
+
+---
+
+### Unsubscribe Flows
+
+Generate signed unsubscribe URLs and process unsubscribe requests. Requires the `subscription.unsubscribe` configuration.
+
+#### Configuration
+
+```typescript
+const config: EnhancedEmailManagerConfig = {
+  providers: [/* ... */],
+  subscription: {
+    enabled: true,
+    unsubscribe: {
+      baseUrl: 'https://example.com/unsubscribe',
+      secret: process.env.UNSUBSCRIBE_SECRET!,
+      expiresIn: 30 * 24 * 60 * 60, // 30 days
+    },
+  },
+};
+```
+
+#### Generate Unsubscribe URL
+
+```typescript
+const url = manager.generateUnsubscribeUrl('alice@example.com', listId);
+// Returns: https://example.com/unsubscribe?token=<signed-jwt>
+```
+
+#### Process Unsubscribe Request
+
+In your web server's unsubscribe endpoint:
+
+```typescript
+app.get('/unsubscribe', async (req, res) => {
+  const token = req.query.token as string;
+
+  try {
+    await manager.processUnsubscribe(token);
+    res.send('You have been unsubscribed successfully.');
+  } catch (error) {
+    res.status(400).send('Invalid or expired unsubscribe link.');
+  }
+});
+```
+
+#### Send Email with List-Unsubscribe Headers
+
+Automatically generate and attach RFC 2369 / RFC 8058 `List-Unsubscribe` headers:
+
+```typescript
+const result = await manager.sendWithUnsubscribe(
+  {
+    to: 'alice@example.com',
+    subject: 'Monthly Newsletter',
+    html: '<p>Newsletter content...</p>',
+  },
+  listId,                  // Subscriber list ID
+  'alice@example.com',     // Recipient for token generation
+  true,                    // Enable one-click unsubscribe (RFC 8058)
+);
+```
+
+> See [`examples/subscription-management.ts`](examples/subscription-management.ts) for the full lifecycle.
+
+---
+
+### Suppression
+
+Check if an email address is suppressed before sending. Emails become suppressed when a subscriber unsubscribes or when bounces/complaints are processed.
+
+```typescript
+// Check global suppression
+const isSuppressed = await manager.isSuppressed('alice@example.com');
+
+// Check list-specific suppression
+const isListSuppressed = await manager.isSuppressed('alice@example.com', listId);
+
+if (isSuppressed) {
+  console.log('Skipping send - email is suppressed');
+}
+```
+
+---
+
+### Custom Subscription Store
+
+By default, the manager uses an in-memory subscription store. For production, replace it with a database-backed implementation:
+
+```typescript
+import { SubscriptionStore } from '@bernierllc/email-manager';
+
+class DatabaseSubscriptionStore implements SubscriptionStore {
+  // Implement all SubscriptionStore methods using your database
+  // (createList, getList, addSubscriber, etc.)
+}
+
+const store = new DatabaseSubscriptionStore();
+manager.setSubscriptionStore(store);
+```
+
+---
+
+### Custom Headers
+
+Add custom email headers for threading, read receipts, and other purposes by including them in the `metadata.headers` field.
+
+#### Email Threading
+
+```typescript
+const result = await manager.sendEmail({
+  to: 'colleague@example.com',
+  subject: 'Re: Project Discussion',
+  html: '<p>I agree with the proposed approach.</p>',
+  metadata: {
+    headers: {
+      'In-Reply-To': '<original-message-id@example.com>',
+      'References': '<original-message-id@example.com>',
+    },
+  },
+});
+```
+
+#### List-Unsubscribe Headers (Standalone)
+
+Use the `createListUnsubscribeHeaders` utility directly:
+
+```typescript
+import { createListUnsubscribeHeaders } from '@bernierllc/email-manager';
+
+const headers = createListUnsubscribeHeaders(
+  'https://example.com/unsubscribe?id=123',   // HTTPS unsubscribe URL
+  'mailto:unsub@example.com?subject=unsub',    // Optional mailto fallback
+  true,                                         // One-click unsubscribe (RFC 8058)
+);
+
+const result = await manager.sendEmail({
+  to: 'subscriber@example.com',
+  subject: 'Weekly Digest',
+  html: '<p>Your digest...</p>',
+  metadata: { headers },
+});
+```
+
+#### MDN (Read Receipt) Request
+
+```typescript
+const result = await manager.sendEmail({
+  to: 'recipient@example.com',
+  subject: 'Contract for Review',
+  html: '<p>Please confirm receipt of the attached contract.</p>',
+  metadata: {
+    headers: {
+      'Disposition-Notification-To': 'sender@example.com',
+    },
+  },
+});
+```
+
+> See [`examples/attachments-and-headers.ts`](examples/attachments-and-headers.ts) for complete examples.
+
+---
+
+### Attachments
+
+Send emails with file attachments, inline images, or both.
+
+#### File Attachment
+
+```typescript
+const result = await manager.sendEmail({
+  to: 'recipient@example.com',
+  subject: 'Report Attached',
+  html: '<p>Please find the report attached.</p>',
+  attachments: [
+    {
+      filename: 'report.pdf',
+      content: fs.readFileSync('/path/to/report.pdf'),
+      contentType: 'application/pdf',
+    },
+  ],
+});
+```
+
+#### String Content Attachment
+
+```typescript
+const csvData = 'Name,Email\nAlice,alice@example.com\nBob,bob@example.com\n';
+
+const result = await manager.sendEmail({
+  to: 'manager@example.com',
+  subject: 'User Export',
+  html: '<p>User export attached.</p>',
+  attachments: [
+    {
+      filename: 'users.csv',
+      content: csvData,  // String content is also supported
+      contentType: 'text/csv',
+    },
+  ],
+});
+```
+
+#### Inline / Embedded Image
+
+Reference inline images using a Content-ID (CID):
+
+```typescript
+const result = await manager.sendEmail({
+  to: 'customer@example.com',
+  subject: 'Order Confirmation',
+  html: `
+    <img src="cid:company-logo" alt="Logo" />
+    <h2>Order Confirmed!</h2>
+  `,
+  attachments: [
+    {
+      filename: 'logo.png',
+      content: fs.readFileSync('/path/to/logo.png'),
+      contentType: 'image/png',
+      contentDisposition: 'inline',
+      cid: 'company-logo',  // Matches src="cid:company-logo" in HTML
+    },
+  ],
+});
+```
+
+#### Multiple Attachments
+
+```typescript
+const result = await manager.sendEmail({
+  to: 'team@example.com',
+  subject: 'Brand Kit Assets',
+  html: '<p>Attached are the brand assets.</p>',
+  attachments: [
+    {
+      filename: 'guidelines.pdf',
+      content: fs.readFileSync('/path/to/guidelines.pdf'),
+      contentType: 'application/pdf',
+    },
+    {
+      filename: 'logo.png',
+      content: fs.readFileSync('/path/to/logo.png'),
+      contentType: 'image/png',
+    },
+    {
+      filename: 'palette.json',
+      content: JSON.stringify({ primary: '#0066CC' }, null, 2),
+      contentType: 'application/json',
+    },
+  ],
+});
+```
+
+> See [`examples/attachments-and-headers.ts`](examples/attachments-and-headers.ts) for complete examples.
+
+---
+
+## Capability Matrix & Smart Routing
+
+The email manager includes a full capability matrix that maps every feature to every provider, enabling smart routing decisions and graceful degradation.
+
+### Capability Matrix
+
+Each feature is classified per provider with one of four source types:
+
+| Source | Meaning |
+|--------|---------|
+| `provider` | Natively supported by the email provider's API |
+| `platform` | Implemented by the platform (polyfilled locally) |
+| `enhanced` | Built on top of provider primitives with added value |
+| `unsupported` | Not available for this provider |
+
+#### Provider Feature Support
+
+| Feature | SendGrid | Mailgun | Postmark | SES | SMTP |
+|---------|----------|---------|----------|-----|------|
+| sendEmail | provider | provider | provider | provider | provider |
+| batchSend | provider | provider | provider | provider | platform |
+| providerTemplates | provider | provider | provider | provider | unsupported |
+| localTemplates | platform | platform | platform | platform | platform |
+| calendarInvites | platform | platform | platform | platform | platform |
+| calendarEventMgmt | platform | platform | platform | platform | platform |
+| webhooksReceive | provider | provider | provider | provider | unsupported |
+| webhookNormalization | enhanced | enhanced | enhanced | enhanced | unsupported |
+| deliveryTracking | provider | provider | provider | provider | unsupported |
+| inboundEmailParsing | enhanced | enhanced | enhanced | enhanced | unsupported |
+| subscriptionMgmt | enhanced | enhanced | platform | platform | platform |
+| suppressionLists | provider | provider | provider | provider | platform |
+| unsubscribeUrlGeneration | platform | platform | platform | platform | platform |
+| scheduledSend | provider | provider | platform | platform | platform |
+| openClickTracking | provider | provider | provider* | unsupported | unsupported |
+| emailContentParsing | platform | platform | platform | platform | platform |
+| emailHeaderMgmt | platform | platform | platform | platform | platform |
+| attachments | provider | provider | provider | provider | provider |
+| advancedAttachmentProcessing | platform | platform | platform | platform | platform |
+| dkimSpf | provider | provider | provider | provider | unsupported |
+| linkBranding | provider | provider | unsupported | unsupported | unsupported |
+| retryResilience | platform | platform | platform | platform | platform |
+| multiProviderFailover | platform | platform | platform | platform | platform |
+
+*Postmark supports open tracking only; click tracking is not available.
+
+Notable provider-specific limitations:
+- **SendGrid** `scheduledSend`: 72-hour maximum scheduling window
+- **Mailgun** `scheduledSend`: 3-day maximum scheduling window
+- **SES** `webhooksReceive` / `deliveryTracking`: Requires SNS topic configuration
+
+### Routing Configuration
+
+Capability-aware routing is opt-in. Enable it by adding a `routing` section to your config:
+
+```typescript
+import { EmailManager, EmailManagerConfig } from '@bernierllc/email-manager';
+
+const config: EmailManagerConfig = {
+  providers: [
+    { id: 'sg', name: 'SendGrid', type: 'sendgrid', config: { apiKey: '...' }, isActive: true, priority: 1 },
+    { id: 'mg', name: 'Mailgun', type: 'mailgun', config: { apiKey: '...', domain: '...' }, isActive: true, priority: 2 },
+  ],
+  routing: {
+    strategy: 'primary-failover',
+    featureOverrides: {
+      // Always use platform implementation for local templates
+      localTemplates: { behavior: 'platform-always' },
+      // Throw an error if no native provider supports the feature
+      openClickTracking: { behavior: 'error' },
+    },
+  },
+  degradation: {
+    logLevel: 'warn',
+    includeDocLinks: true,
+    docsBaseUrl: 'https://docs.example.com/email',
+  },
+};
+
+const manager = new EmailManager(config);
+```
+
+#### Feature Override Behaviors
+
+| Behavior | Description |
+|----------|-------------|
+| `native-first` | (Default) Prefer providers with native or enhanced support; fall back to platform if none found |
+| `platform-always` | Always use the platform implementation, even if the provider supports it natively |
+| `error` | Throw `FeatureUnsupportedError` if no provider has native or enhanced support |
+
+### Degradation Behavior
+
+When a feature is routed to a provider via platform polyfill (not native), the system records degradation information:
+
+- **`platform` source features** (e.g., SMTP `batchSend`): Emails are sent sequentially rather than in a true batch. The `SendResult.routing` field indicates `degraded: true` with a `degradationReason`.
+- **`unsupported` features** (e.g., SMTP `webhooksReceive`): The router skips the provider entirely and tries the next in priority order. If no provider supports the feature, a `FeatureUnsupportedError` is thrown.
+- **Degradation logging**: Controlled by `degradation.logLevel` (`'silent'` | `'info'` | `'warn'` | `'error'`). When `includeDocLinks` is `true`, log messages include links to degradation documentation.
+
+### Redis Resolver Setup
+
+By default, the capability matrix is resolved from an in-memory snapshot. For shared or dynamic capability data across multiple instances, use the Redis-backed resolver:
+
+```bash
+# Set the environment variable to enable Redis resolver auto-detection
+export EMAIL_MANAGER_REDIS_URL="redis://localhost:6379"
+```
+
+The factory (`createCapabilityResolver`) automatically detects the environment variable and creates a `SafeCapabilityResolver` that wraps a Redis resolver with an in-memory fallback. If `ioredis` is not installed or Redis is unavailable, it falls back to the in-memory resolver silently.
+
+#### Redis Resolver Options
+
+```typescript
+import { createCapabilityResolver } from '@bernierllc/email-manager';
+
+const resolver = await createCapabilityResolver({
+  namespace: 'myapp:capabilities', // Redis key namespace (default: 'email-manager:capabilities')
+  ttl: 3600,                       // Cache TTL in seconds (default: varies by implementation)
+});
+```
+
+You can also provide your own resolver implementation:
+
+```typescript
+const config: EmailManagerConfig = {
+  providers: [/* ... */],
+  routing: {
+    strategy: 'primary-failover',
+    capabilityResolver: myCustomResolver, // Must implement CapabilityResolver interface
+  },
+};
+```
+
+### RoutingMetadata in Responses
+
+When routing is active, `SendResult` includes a `routing` field:
+
+```typescript
+const result = await manager.sendEmail(emailData);
+
+if (result.routing) {
+  console.log('Provider used:', result.routing.provider);
+  console.log('Feature:', result.routing.feature);
+  console.log('Source:', result.routing.source);       // 'provider' | 'platform' | 'enhanced' | 'unsupported'
+  console.log('Degraded:', result.routing.degraded);   // true if platform polyfill was used
+  console.log('Reason:', result.routing.degradationReason);
+  console.log('Tried:', result.routing.attemptedProviders); // providers checked before selecting
+}
+```
+
+The `RoutingMetadata` interface:
+
+```typescript
+interface RoutingMetadata {
+  provider: string;
+  feature: string;
+  source: 'provider' | 'platform' | 'enhanced' | 'unsupported';
+  degraded: boolean;
+  degradationReason?: string;
+  attemptedProviders?: string[];
+}
+```
+
+### Migration Guide from v0.4.x
+
+The capability matrix and routing system is fully backward compatible. Existing code continues to work without changes:
+
+- **No routing config**: When `routing` is omitted from the config, the manager uses the same provider selection logic as before (priority-based failover).
+- **No degradation config**: When `degradation` is omitted, degradation events are not logged.
+- **Opt-in**: To enable capability-aware routing, add a `routing` section to your config. The `RoutingMetadata` field on `SendResult` only appears when routing is active.
+- **No new required dependencies**: The Redis resolver is optional and only activated when `EMAIL_MANAGER_REDIS_URL` is set and `ioredis` is installed.
+
+---
+
+## Re-exported Types
+
+For convenience, the email-manager re-exports types and utilities from its sub-packages so consumers do not need direct dependencies:
+
+| Package | Re-exported Items |
+|---------|-------------------|
+| `@bernierllc/email-calendar` | `CalendarEvent`, `CalendarAttendee`, `CalendarMethod`, `createCalendarInvite`, `createCalendarCancel`, `toCalendarAttachment` |
+| `@bernierllc/email-batch-sender` | `BatchSenderOptions`, `BatchResult`, `BatchEmailInput`, `BatchProgress`, `BatchSender`, `createBatchSender` |
+| `@bernierllc/email-subscription` | `SubscriberList`, `Subscriber`, `SubscriptionStore`, `AddSubscriberInput`, `CreateListOptions`, `BulkAddResult`, `UnsubscribeManager`, `SuppressionManager`, `InMemorySubscriptionStore` |
+| `@bernierllc/email-headers` | `EmailHeaders`, `ThreadingHeaders`, `ListUnsubscribeHeaders`, `createListUnsubscribeHeaders` |
+| `@bernierllc/email-attachments` | `AttachmentInput`, `AttachmentLimits`, `AttachmentValidationResult` |
+
 ## License
 
 Copyright (c) 2025 Bernier LLC. All rights reserved.