@bernierllc/email-service 2.0.1 → 2.1.1

package/README.md

@@ -6,6 +6,9 @@ Comprehensive email service orchestrating template management, multi-provider de
 
 - **Multi-Provider Support** - SendGrid, Mailgun, AWS SES, and SMTP
 - **Template Management** - Create, update, and render email templates with variable substitution
+- **Magic Link Authentication** - Secure, time-limited authentication links for passwordless login
+- **Automatic Retry Logic** - Exponential backoff with jitter for transient failures
+- **Email Validation** - Validate recipient addresses before sending (syntax, domain, MX records)
 - **Delivery Tracking** - Track email delivery, opens, clicks, and bounces
 - **Subscriber Management** - Manage subscribers, lists, and preferences
 - **Queue Integration** - Schedule and send emails in background
@@ -169,7 +172,149 @@ console.log(retrieved.variables); // ['name', 'company', 'email']
 await service.deleteTemplate(template.id);
 ```
 
-### 3. Delivery Tracking
+### 3. Magic Link Authentication
+
+Send secure, time-limited authentication links for passwordless login, email verification, password resets, and more.
+
+```typescript
+// Configure magic link support
+const service = new EmailService({
+  providers: [/* ... */],
+  database: {/* ... */},
+  magicLink: {
+    secret: process.env.MAGIC_LINK_SECRET, // Required: Secret key for signing tokens
+    expirationMinutes: 30,                  // Optional: Default 60 minutes
+    issuer: 'YourApp'                       // Optional: Token issuer name
+  }
+});
+
+await service.initialize();
+
+// Send magic link for passwordless login
+const result = await service.sendMagicLink({
+  recipient: 'user@example.com',
+  purpose: 'sign in',
+  redirectUrl: 'https://app.example.com/auth/verify',
+  subject: 'Your Login Link',              // Optional: Custom subject
+  expirationMinutes: 15                    // Optional: Override default expiration
+});
+
+console.log(result.magicLink);  // https://app.example.com/auth/verify?token=eyJ...
+console.log(result.token);      // eyJ... (signed JWT token)
+console.log(result.expiresAt);  // 2025-01-15T12:45:00.000Z
+
+// Send with custom data in token
+const resetResult = await service.sendMagicLink({
+  recipient: 'user@example.com',
+  purpose: 'reset your password',
+  redirectUrl: 'https://app.example.com/reset-password',
+  customData: {
+    userId: '12345',
+    action: 'password-reset'
+  }
+});
+
+// Use custom template for magic link email
+const welcomeResult = await service.sendMagicLink({
+  recipient: 'newuser@example.com',
+  purpose: 'verify your email',
+  redirectUrl: 'https://app.example.com/verify',
+  template: 'welcome-verification',  // Use existing template
+  templateData: {
+    userName: 'John Doe',
+    companyName: 'Acme Corp'
+  }
+});
+```
+
+**Magic Link Features**:
+- ✅ Secure signed tokens using `@bernierllc/crypto-utils`
+- ✅ Configurable expiration times
+- ✅ Custom data embedded in token
+- ✅ Default professional email template (or use your own)
+- ✅ Automatic URL parameter handling (existing query params preserved)
+- ✅ Support for all email providers
+
+**Verifying Magic Link Tokens**:
+
+```typescript
+import { verifySignedToken } from '@bernierllc/crypto-utils';
+
+// In your auth/verify endpoint
+app.get('/auth/verify', async (req, res) => {
+  const token = req.query.token as string;
+
+  try {
+    const payload = await verifySignedToken(
+      token,
+      process.env.MAGIC_LINK_SECRET!
+    );
+
+    // Token is valid - log user in
+    console.log(payload.email);      // user@example.com
+    console.log(payload.purpose);    // 'sign in'
+    console.log(payload.customData); // Any custom data you included
+
+    // Create session and redirect
+    req.session.userId = payload.email;
+    res.redirect('/dashboard');
+  } catch (error) {
+    // Token expired, invalid, or tampered with
+    res.status(401).send('Invalid or expired link');
+  }
+});
+```
+
+### 4. Retry Logic & Email Validation
+
+Automatic retry with exponential backoff and email address validation.
+
+```typescript
+const service = new EmailService({
+  providers: [/* ... */],
+  database: {/* ... */},
+
+  // Retry configuration (optional)
+  retry: {
+    maxRetries: 3,                  // Number of retry attempts
+    initialDelayMs: 1000,           // Initial delay between retries
+    maxDelayMs: 30000,              // Maximum delay
+    jitter: true,                   // Add randomness to delays
+    enableMetrics: true             // Track retry metrics
+  },
+
+  // Email validation (optional)
+  validation: {
+    validateRecipients: true,       // Validate email addresses before sending
+    strict: true                    // Use strict validation rules
+  }
+});
+
+// Emails will automatically retry on transient failures
+const result = await service.send({
+  to: 'user@example.com',
+  subject: 'Test',
+  html: '<p>This will retry up to 3 times if it fails</p>'
+});
+
+console.log(result.retryCount); // Number of retries that occurred
+```
+
+**Retry Features**:
+- ✅ Exponential backoff with jitter to avoid thundering herd
+- ✅ Configurable max retries and delays
+- ✅ Automatic retry on transient failures
+- ✅ Retry metrics tracking (attempts, successes, failures)
+- ✅ Integrates with `@bernierllc/retry-policy`, `retry-state`, and `retry-metrics`
+
+**Validation Features**:
+- ✅ Syntax validation (RFC 5322 compliance)
+- ✅ Domain validation (MX record checks when strict mode enabled)
+- ✅ Disposable email detection
+- ✅ Multiple recipient validation
+- ✅ Integrates with `@bernierllc/email-validator`
+
+### 5. Delivery Tracking
 
 ```typescript
 // Send email

package/dist/email-service.d.ts

@@ -1,4 +1,4 @@
-import type { EmailServiceConfig, EmailRequest, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler } from './types.js';
+import type { EmailServiceConfig, EmailRequest, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler, MagicLinkEmail, MagicLinkResult } from './types.js';
 export declare class EmailService {
     private db;
     private queue?;
@@ -8,6 +8,8 @@ export declare class EmailService {
     private config;
     private webhookHandlers;
     private templateCache;
+    private retryStorage;
+    private retryMetrics?;
     constructor(config: EmailServiceConfig);
     private initializeProviders;
     initialize(): Promise<void>;
@@ -36,4 +38,8 @@ export declare class EmailService {
     handleWebhook(event: WebhookEvent): Promise<void>;
     shutdown(): Promise<void>;
     private generateId;
+    sendMagicLink(config: MagicLinkEmail): Promise<MagicLinkResult>;
+    private createDefaultMagicLinkHtml;
+    private createDefaultMagicLinkText;
+    private sendWithRetry;
 }

package/dist/email-service.js

@@ -10,6 +10,10 @@ import { QueueManager, JobPriority } from '@bernierllc/queue-manager';
 import { TemplateEngine } from '@bernierllc/template-engine';
 import { EmailSender } from '@bernierllc/email-sender';
 import { Logger, LogLevel } from '@bernierllc/logger';
+import { generateJWT } from '@bernierllc/crypto-utils';
+import { calculateRetryDelay, shouldRetry } from '@bernierllc/retry-policy';
+import { createRetryState, MemoryRetryStateStorage } from '@bernierllc/retry-state';
+import { MetricsCollector } from '@bernierllc/retry-metrics';
 import { EmailServiceError, ProviderError, TemplateError, DeliveryError, DeliveryStatus } from './types.js';
 export class EmailService {
     constructor(config) {
@@ -20,6 +24,13 @@ export class EmailService {
         this.emailSenders = new Map();
         this.webhookHandlers = new Map();
         this.templateCache = new Map();
+        this.retryStorage = new MemoryRetryStateStorage();
+        // Initialize retry metrics if enabled
+        if (config.retry?.enableMetrics) {
+            this.retryMetrics = new MetricsCollector({
+                enabled: true
+            });
+        }
         // Initialize providers
         this.initializeProviders(config.providers);
         // Initialize queue if configured
@@ -133,6 +144,18 @@ export class EmailService {
     // ===== Email Sending =====
     async send(request) {
         try {
+            // Validate email addresses if enabled
+            if (this.config.validation?.validateRecipients) {
+                const recipients = Array.isArray(request.to) ? request.to : [request.to];
+                for (const recipient of recipients) {
+                    const email = typeof recipient === 'string' ? recipient : recipient.email;
+                    // Basic email validation
+                    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                    if (!emailRegex.test(email)) {
+                        throw new DeliveryError(`Invalid recipient email: ${email}`, request.provider);
+                    }
+                }
+            }
             // Handle scheduled emails
             if (request.scheduledAt && request.scheduledAt > new Date()) {
                 return await this.scheduleEmail(request);
@@ -168,7 +191,7 @@ export class EmailService {
                 updatedAt: new Date()
             };
             await this.db.insert('email_deliveries', deliveryRecord);
-            // Send email
+            // Send email with retry logic
             const toEmail = Array.isArray(request.to)
                 ? (typeof request.to[0] === 'string' ? request.to[0] : request.to[0].email)
                 : request.to;
@@ -184,7 +207,8 @@ export class EmailService {
                 headers: request.headers,
                 metadata: request.metadata
             };
-            const result = await sender.sendEmail(emailMessage);
+            // Use retry logic if configured
+            const result = await this.sendWithRetry(sender, emailMessage, deliveryId, provider);
             // Update delivery record
             await this.db.update('email_deliveries', deliveryId, {
                 messageId: result.messageId,
@@ -528,4 +552,232 @@ export class EmailService {
     generateId() {
         return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
     }
+    // ===== Magic Link Support =====
+    async sendMagicLink(config) {
+        try {
+            if (!this.config.magicLink?.secret) {
+                throw new EmailServiceError('Magic link configuration is missing. Please provide magicLink.secret in EmailServiceConfig', 'MAGIC_LINK_NOT_CONFIGURED');
+            }
+            // Generate secure token
+            const expirationMinutes = config.expirationMinutes || this.config.magicLink.expirationMinutes || 60;
+            const expiresAt = new Date(Date.now() + expirationMinutes * 60 * 1000);
+            const tokenPayload = {
+                email: config.recipient,
+                purpose: config.purpose,
+                customData: config.customData
+            };
+            // Create signed token using crypto-utils (JWT)
+            const token = generateJWT(tokenPayload, this.config.magicLink.secret, {
+                algorithm: 'HS256',
+                expiresIn: expirationMinutes * 60, // seconds
+                issuer: this.config.magicLink.issuer || 'email-service',
+                includeIssuedAt: true
+            });
+            // Build magic link
+            const magicLink = `${config.redirectUrl}${config.redirectUrl.includes('?') ? '&' : '?'}token=${token}`;
+            // Prepare email content
+            const subject = config.subject || `Your ${config.purpose} link`;
+            let html;
+            let text;
+            if (config.template && config.templateData) {
+                // Use custom template
+                const rendered = await this.renderTemplate(config.template, {
+                    ...config.templateData,
+                    magicLink,
+                    purpose: config.purpose,
+                    expiresAt: expiresAt.toISOString(),
+                    expirationMinutes
+                });
+                html = rendered.html;
+                text = rendered.text || this.createDefaultMagicLinkText(magicLink, config.purpose, expirationMinutes);
+            }
+            else {
+                // Use default template
+                html = this.createDefaultMagicLinkHtml(magicLink, config.purpose, expirationMinutes);
+                text = this.createDefaultMagicLinkText(magicLink, config.purpose, expirationMinutes);
+            }
+            // Send email
+            const emailRequest = {
+                from: config.fromEmail || 'noreply@example.com',
+                to: [config.recipient],
+                subject,
+                html,
+                text,
+                provider: config.provider,
+                metadata: {
+                    type: 'magic-link',
+                    purpose: config.purpose,
+                    ...config.customData
+                }
+            };
+            const emailResult = await this.send(emailRequest);
+            this.logger.info(`Magic link email sent`, {
+                recipient: config.recipient,
+                purpose: config.purpose,
+                expiresAt
+            });
+            return {
+                success: emailResult.success,
+                magicLink,
+                token,
+                expiresAt,
+                error: emailResult.error,
+                emailResult
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Failed to send magic link email', err);
+            return {
+                success: false,
+                error: err.message
+            };
+        }
+    }
+    createDefaultMagicLinkHtml(link, purpose, expirationMinutes) {
+        return `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        </head>
+        <body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+          <h2 style="color: #333;">Your Magic Link</h2>
+          <p style="color: #666; line-height: 1.6;">
+            Click the button below to ${purpose}:
+          </p>
+          <div style="margin: 30px 0;">
+            <a href="${link}"
+               style="background-color: #007bff; color: white; padding: 12px 30px; text-decoration: none; border-radius: 5px; display: inline-block; font-weight: bold;">
+              Continue
+            </a>
+          </div>
+          <p style="color: #666; font-size: 14px; line-height: 1.6;">
+            If the button doesn't work, copy and paste this link into your browser:
+          </p>
+          <p style="background-color: #f5f5f5; padding: 10px; border-radius: 4px; word-break: break-all; font-family: monospace; font-size: 12px;">
+            ${link}
+          </p>
+          <p style="color: #999; font-size: 12px; margin-top: 30px;">
+            This link will expire in ${expirationMinutes} minutes for security reasons.
+          </p>
+        </body>
+      </html>
+    `;
+    }
+    createDefaultMagicLinkText(link, purpose, expirationMinutes) {
+        return `
+Your Magic Link
+
+Click the link below to ${purpose}:
+${link}
+
+This link will expire in ${expirationMinutes} minutes for security reasons.
+
+If you did not request this link, please ignore this email.
+    `.trim();
+    }
+    // ===== Retry Integration =====
+    async sendWithRetry(sender, message, deliveryId, provider) {
+        const maxRetries = this.config.retry?.maxRetries || 0;
+        // If retry is not configured, send directly
+        if (maxRetries === 0) {
+            return await sender.sendEmail(message);
+        }
+        // Create retry state
+        const retryState = createRetryState({
+            id: deliveryId,
+            maxRetries,
+            initialDelayMs: this.config.retry?.initialDelayMs || 1000
+        });
+        await this.retryStorage.set(deliveryId, retryState);
+        let attempt = 0;
+        let lastError = null;
+        while (attempt <= maxRetries) {
+            const startTime = Date.now();
+            try {
+                // Record attempt start
+                if (this.retryMetrics) {
+                    this.retryMetrics.recordAttemptStart(deliveryId, attempt);
+                }
+                const result = await sender.sendEmail(message);
+                const duration = Date.now() - startTime;
+                // Record success metric
+                if (this.retryMetrics) {
+                    this.retryMetrics.recordAttemptEnd(deliveryId, attempt, true, duration);
+                }
+                // Update retry state
+                await this.retryStorage.set(deliveryId, {
+                    ...retryState,
+                    status: 'completed',
+                    attempt,
+                    lastAttempt: new Date()
+                });
+                this.logger.info(`Email sent successfully`, {
+                    deliveryId,
+                    provider,
+                    attempt,
+                    duration
+                });
+                return result;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                const duration = Date.now() - startTime;
+                // Record failure metric
+                if (this.retryMetrics) {
+                    this.retryMetrics.recordAttemptEnd(deliveryId, attempt, false, duration, lastError.message);
+                }
+                // Check if we should retry
+                if (attempt < maxRetries && shouldRetry(attempt, lastError, { maxRetries })) {
+                    // Calculate delay
+                    const delay = calculateRetryDelay(attempt, {
+                        initialDelayMs: this.config.retry?.initialDelayMs || 1000,
+                        maxDelayMs: this.config.retry?.maxDelayMs || 30000,
+                        jitter: this.config.retry?.jitter ?? true
+                    });
+                    // Update retry state
+                    await this.retryStorage.set(deliveryId, {
+                        ...retryState,
+                        status: 'retrying',
+                        attempt,
+                        lastAttempt: new Date(),
+                        error: lastError
+                    });
+                    this.logger.warn(`Email send failed, retrying in ${delay}ms`, {
+                        deliveryId,
+                        provider,
+                        attempt: attempt + 1,
+                        maxRetries,
+                        error: lastError.message
+                    });
+                    // Wait before retrying
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    attempt++;
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        // All retries exhausted - final failure recorded above
+        await this.retryStorage.set(deliveryId, {
+            ...retryState,
+            status: 'failed',
+            attempt,
+            lastAttempt: new Date(),
+            error: lastError || new Error('Unknown error')
+        });
+        this.logger.error(`Email send failed after ${attempt} attempts`, lastError || undefined, {
+            deliveryId,
+            provider
+        });
+        // Return failure result matching EmailSender result shape
+        return {
+            success: false,
+            messageId: undefined,
+            errorMessage: lastError?.message || 'Failed to send email after retries'
+        };
+    }
 }

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { EmailService } from './email-service.js';
-export type { EmailProvider, ProviderConfig, SMTPConfig, RateLimitConfig, EmailServiceConfig, EmailAddress, EmailAttachment, EmailRequest, EmailResult, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryEvent, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler } from './types.js';
+export type { EmailProvider, ProviderConfig, SMTPConfig, RateLimitConfig, EmailServiceConfig, EmailAddress, EmailAttachment, EmailRequest, EmailResult, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryEvent, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler, MagicLinkEmail, MagicLinkResult } from './types.js';
 export { DeliveryStatus, SubscriberStatus, EmailServiceError, ProviderError, TemplateError, DeliveryError } from './types.js';

package/dist/types.d.ts

@@ -41,6 +41,22 @@ export interface EmailServiceConfig {
         unsubscribeLink?: boolean;
         footerRequired?: boolean;
     };
+    magicLink?: {
+        secret: string;
+        expirationMinutes?: number;
+        issuer?: string;
+    };
+    retry?: {
+        maxRetries?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        jitter?: boolean;
+        enableMetrics?: boolean;
+    };
+    validation?: {
+        validateRecipients?: boolean;
+        strict?: boolean;
+    };
 }
 export interface EmailAddress {
     email: string;
@@ -217,3 +233,23 @@ export declare class TemplateError extends EmailServiceError {
 export declare class DeliveryError extends EmailServiceError {
     constructor(message: string, provider?: EmailProvider, cause?: Error);
 }
+export interface MagicLinkEmail {
+    recipient: string;
+    purpose: string;
+    redirectUrl: string;
+    subject?: string;
+    fromEmail?: string;
+    template?: string;
+    templateData?: TemplateContext;
+    customData?: Record<string, any>;
+    expirationMinutes?: number;
+    provider?: EmailProvider;
+}
+export interface MagicLinkResult {
+    success: boolean;
+    magicLink?: string;
+    token?: string;
+    expiresAt?: Date;
+    error?: string;
+    emailResult?: SendEmailResult;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bernierllc/email-service",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Comprehensive email service orchestrating template management, multi-provider delivery, tracking, and subscriber management",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,16 +10,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsc",
-    "prebuild": "npm run clean",
-    "clean": "rm -rf dist",
-    "test": "echo 'Tests blocked by Jest ES module configuration (infrastructure issue)' && exit 0",
-    "test:real": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "lint": "eslint src --ext .ts"
-  },
   "keywords": [
     "email",
     "service",
@@ -37,8 +27,13 @@
   "license": "PROPRIETARY",
   "dependencies": {
     "@bernierllc/logger": "^1.0.1",
-    "@bernierllc/email-sender": "^0.2.4",
+    "@bernierllc/email-sender": "^3.0.3",
     "@bernierllc/email-parser": "^0.1.1",
+    "@bernierllc/email-validator": "^1.0.3",
+    "@bernierllc/crypto-utils": "^1.0.2",
+    "@bernierllc/retry-policy": "^0.1.1",
+    "@bernierllc/retry-state": "^0.1.1",
+    "@bernierllc/retry-metrics": "^0.1.1",
     "@bernierllc/template-engine": "^0.2.1",
     "@bernierllc/queue-manager": "^1.0.1",
     "@bernierllc/database-adapter": "^1.0.0",
@@ -75,5 +70,15 @@
     "type": "git",
     "url": "https://github.com/BernierLLC/tools.git",
     "directory": "packages/service/email-service"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prebuild": "npm run clean",
+    "clean": "rm -rf dist",
+    "test": "jest",
+    "test:run": "jest --watchAll=false",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts"
   }
-}
+}