@bernierllc/email-service 2.0.1

package/dist/email-service.js

@@ -0,0 +1,531 @@
+/*
+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 { DatabaseManager } from '@bernierllc/database-adapter';
+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 { EmailServiceError, ProviderError, TemplateError, DeliveryError, DeliveryStatus } from './types.js';
+export class EmailService {
+    constructor(config) {
+        this.config = config;
+        this.db = new DatabaseManager(config.database);
+        this.logger = new Logger({ level: LogLevel.INFO, transports: [], context: { service: 'email-service' } });
+        this.templateEngine = new TemplateEngine({});
+        this.emailSenders = new Map();
+        this.webhookHandlers = new Map();
+        this.templateCache = new Map();
+        // Initialize providers
+        this.initializeProviders(config.providers);
+        // Initialize queue if configured
+        if (config.queue) {
+            this.queue = new QueueManager('email-service', config.queue);
+        }
+    }
+    initializeProviders(providers) {
+        for (const providerConfig of providers) {
+            try {
+                const sender = new EmailSender({
+                    provider: providerConfig.type,
+                    apiKey: providerConfig.apiKey,
+                    domain: providerConfig.domain,
+                    region: providerConfig.region,
+                    fromEmail: 'noreply@example.com',
+                    host: providerConfig.smtp?.host,
+                    port: providerConfig.smtp?.port,
+                    secure: providerConfig.smtp?.secure,
+                    username: providerConfig.smtp?.auth.user,
+                    password: providerConfig.smtp?.auth.pass
+                });
+                this.emailSenders.set(providerConfig.type, sender);
+                this.logger.info(`Initialized ${providerConfig.type} provider`);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.error(`Failed to initialize ${providerConfig.type} provider`, err);
+                throw new ProviderError(`Failed to initialize ${providerConfig.type}`, providerConfig.type, err);
+            }
+        }
+    }
+    async initialize() {
+        try {
+            await this.db.connect();
+            await this.createTables();
+            this.logger.info('Email service initialized successfully');
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Failed to initialize email service', err);
+            throw new EmailServiceError('Initialization failed', 'INIT_ERROR', undefined, err);
+        }
+    }
+    async createTables() {
+        // Templates table
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS email_templates (
+        id TEXT PRIMARY KEY,
+        name TEXT UNIQUE NOT NULL,
+        subject TEXT NOT NULL,
+        html TEXT NOT NULL,
+        text TEXT,
+        variables TEXT NOT NULL,
+        version INTEGER DEFAULT 1,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+        // Delivery records table
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS email_deliveries (
+        id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL,
+        to_address TEXT NOT NULL,
+        from_address TEXT NOT NULL,
+        subject TEXT NOT NULL,
+        provider TEXT NOT NULL,
+        status TEXT NOT NULL,
+        template_id TEXT,
+        metadata TEXT,
+        sent_at TEXT,
+        delivered_at TEXT,
+        opened_at TEXT,
+        clicked_at TEXT,
+        bounced_at TEXT,
+        error TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+        // Subscribers table
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS subscribers (
+        id TEXT PRIMARY KEY,
+        email TEXT UNIQUE NOT NULL,
+        name TEXT,
+        status TEXT NOT NULL,
+        lists TEXT NOT NULL,
+        tags TEXT,
+        metadata TEXT,
+        subscribed_at TEXT NOT NULL,
+        unsubscribed_at TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+        // Subscriber lists table
+        await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS subscriber_lists (
+        id TEXT PRIMARY KEY,
+        name TEXT UNIQUE NOT NULL,
+        description TEXT,
+        subscriber_count INTEGER DEFAULT 0,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+        this.logger.info('Database tables created successfully');
+    }
+    // ===== Email Sending =====
+    async send(request) {
+        try {
+            // Handle scheduled emails
+            if (request.scheduledAt && request.scheduledAt > new Date()) {
+                return await this.scheduleEmail(request);
+            }
+            // Process template if specified
+            let html = request.html;
+            let text = request.text;
+            let subject = request.subject;
+            if (request.templateId) {
+                const rendered = await this.renderTemplate(request.templateId, request.templateData || {});
+                html = rendered.html;
+                text = rendered.text;
+                subject = rendered.subject;
+            }
+            // Select provider
+            const provider = request.provider || this.config.defaultProvider || this.config.providers[0].type;
+            const sender = this.emailSenders.get(provider);
+            if (!sender) {
+                throw new ProviderError(`Provider ${provider} not configured`, provider);
+            }
+            // Create delivery record
+            const deliveryId = this.generateId();
+            const deliveryRecord = {
+                id: deliveryId,
+                to: Array.isArray(request.to) ? request.to[0].toString() : request.to,
+                from: typeof request.from === 'string' ? request.from : request.from.email,
+                subject,
+                provider,
+                status: DeliveryStatus.SENDING,
+                templateId: request.templateId,
+                metadata: request.metadata,
+                createdAt: new Date(),
+                updatedAt: new Date()
+            };
+            await this.db.insert('email_deliveries', deliveryRecord);
+            // Send email
+            const toEmail = Array.isArray(request.to)
+                ? (typeof request.to[0] === 'string' ? request.to[0] : request.to[0].email)
+                : request.to;
+            const fromEmail = typeof request.from === 'string' ? request.from : request.from.email;
+            const fromName = typeof request.from === 'string' ? undefined : request.from.name;
+            const emailMessage = {
+                toEmail,
+                fromEmail,
+                fromName,
+                subject,
+                htmlContent: html,
+                textContent: text,
+                headers: request.headers,
+                metadata: request.metadata
+            };
+            const result = await sender.sendEmail(emailMessage);
+            // Update delivery record
+            await this.db.update('email_deliveries', deliveryId, {
+                messageId: result.messageId,
+                status: result.success ? DeliveryStatus.SENT : DeliveryStatus.FAILED,
+                sentAt: result.success ? new Date() : undefined,
+                error: result.errorMessage,
+                updatedAt: new Date()
+            });
+            this.logger.info(`Email sent via ${provider}`, { deliveryId, messageId: result.messageId });
+            return {
+                success: result.success,
+                messageId: result.messageId,
+                deliveryId,
+                provider,
+                error: result.errorMessage,
+                timestamp: new Date()
+            };
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Failed to send email', err);
+            throw new DeliveryError(err.message, request.provider, err);
+        }
+    }
+    async scheduleEmail(request) {
+        if (!this.queue) {
+            throw new EmailServiceError('Queue not configured for scheduled emails', 'QUEUE_NOT_CONFIGURED');
+        }
+        const delay = request.scheduledAt.getTime() - Date.now();
+        const priority = request.priority === 'high' ? JobPriority.HIGH :
+            request.priority === 'low' ? JobPriority.LOW :
+                JobPriority.NORMAL;
+        await this.queue.add('send-email', request, {
+            priority,
+            delay
+        });
+        this.logger.info('Email scheduled for delivery', { scheduledAt: request.scheduledAt });
+        return {
+            success: true,
+            queuedForLater: true,
+            timestamp: new Date()
+        };
+    }
+    async sendBulk(requests) {
+        const results = [];
+        for (const request of requests) {
+            try {
+                const result = await this.send(request);
+                results.push(result);
+            }
+            catch (error) {
+                results.push({
+                    success: false,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                    timestamp: new Date()
+                });
+            }
+        }
+        return results;
+    }
+    // ===== Template Management =====
+    async createTemplate(request) {
+        try {
+            const id = this.generateId();
+            const now = new Date();
+            // Extract variables from template
+            const variables = this.extractVariables(request.html);
+            const template = {
+                id,
+                name: request.name,
+                subject: request.subject,
+                html: request.html,
+                text: request.text,
+                variables,
+                version: 1,
+                createdAt: now,
+                updatedAt: now
+            };
+            await this.db.insert('email_templates', {
+                ...template,
+                variables: JSON.stringify(variables)
+            });
+            if (this.config.templates?.cacheEnabled) {
+                this.templateCache.set(id, template);
+            }
+            this.logger.info(`Template created: ${request.name}`, { id });
+            return template;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Failed to create template', err);
+            throw new TemplateError(err.message, err);
+        }
+    }
+    async getTemplate(id) {
+        // Check cache first
+        if (this.config.templates?.cacheEnabled && this.templateCache.has(id)) {
+            return this.templateCache.get(id);
+        }
+        const template = await this.db.findById('email_templates', id);
+        if (!template) {
+            return null;
+        }
+        const parsed = {
+            ...template,
+            variables: JSON.parse(template.variables),
+            createdAt: new Date(template.created_at),
+            updatedAt: new Date(template.updated_at)
+        };
+        if (this.config.templates?.cacheEnabled) {
+            this.templateCache.set(id, parsed);
+        }
+        return parsed;
+    }
+    async updateTemplate(id, update) {
+        const existing = await this.getTemplate(id);
+        if (!existing) {
+            throw new TemplateError(`Template ${id} not found`);
+        }
+        const html = update.html || existing.html;
+        const variables = this.extractVariables(html);
+        const updated = await this.db.update('email_templates', id, {
+            subject: update.subject || existing.subject,
+            html,
+            text: update.text || existing.text,
+            variables: JSON.stringify(variables),
+            version: existing.version + 1,
+            updatedAt: new Date()
+        });
+        // Invalidate cache
+        this.templateCache.delete(id);
+        const result = {
+            id: updated.id,
+            name: updated.name,
+            subject: updated.subject,
+            html: updated.html,
+            text: updated.text,
+            variables: JSON.parse(updated.variables),
+            version: updated.version,
+            createdAt: new Date(updated.created_at),
+            updatedAt: new Date(updated.updated_at)
+        };
+        return result;
+    }
+    async deleteTemplate(id) {
+        const deleted = await this.db.delete('email_templates', id);
+        this.templateCache.delete(id);
+        return deleted;
+    }
+    async renderTemplate(templateId, data) {
+        const template = await this.getTemplate(templateId);
+        if (!template) {
+            throw new TemplateError(`Template ${templateId} not found`);
+        }
+        const html = await this.templateEngine.render(template.html, data);
+        const text = template.text ? await this.templateEngine.render(template.text, data) : undefined;
+        const subject = await this.templateEngine.render(template.subject, data);
+        return { html, text, subject };
+    }
+    extractVariables(template) {
+        const regex = /\{\{([^}]+)\}\}/g;
+        const variables = new Set();
+        let match;
+        while ((match = regex.exec(template)) !== null) {
+            variables.add(match[1].trim());
+        }
+        return Array.from(variables);
+    }
+    // ===== Delivery Tracking =====
+    async getDelivery(id) {
+        const record = await this.db.findById('email_deliveries', id);
+        if (!record) {
+            return null;
+        }
+        return this.parseDeliveryRecord(record);
+    }
+    async trackOpen(deliveryId) {
+        await this.db.update('email_deliveries', deliveryId, {
+            status: DeliveryStatus.OPENED,
+            openedAt: new Date(),
+            updatedAt: new Date()
+        });
+    }
+    async trackClick(deliveryId) {
+        await this.db.update('email_deliveries', deliveryId, {
+            status: DeliveryStatus.CLICKED,
+            clickedAt: new Date(),
+            updatedAt: new Date()
+        });
+    }
+    async getDeliveryStats(startDate, endDate) {
+        const records = await this.db.findMany('email_deliveries');
+        let filtered = records;
+        if (startDate || endDate) {
+            filtered = records.filter(r => {
+                const date = new Date(r.created_at);
+                if (startDate && date < startDate)
+                    return false;
+                if (endDate && date > endDate)
+                    return false;
+                return true;
+            });
+        }
+        const total = filtered.length;
+        const sent = filtered.filter(r => r.status !== DeliveryStatus.QUEUED && r.status !== DeliveryStatus.SENDING).length;
+        const delivered = filtered.filter(r => r.status === DeliveryStatus.DELIVERED).length;
+        const opened = filtered.filter(r => r.opened_at).length;
+        const clicked = filtered.filter(r => r.clicked_at).length;
+        const bounced = filtered.filter(r => r.status === DeliveryStatus.BOUNCED).length;
+        const failed = filtered.filter(r => r.status === DeliveryStatus.FAILED).length;
+        return {
+            total,
+            sent,
+            delivered,
+            opened,
+            clicked,
+            bounced,
+            failed,
+            openRate: sent > 0 ? (opened / sent) * 100 : 0,
+            clickRate: sent > 0 ? (clicked / sent) * 100 : 0,
+            bounceRate: sent > 0 ? (bounced / sent) * 100 : 0
+        };
+    }
+    parseDeliveryRecord(record) {
+        return {
+            ...record,
+            metadata: record.metadata ? JSON.parse(record.metadata) : undefined,
+            createdAt: new Date(record.created_at),
+            updatedAt: new Date(record.updated_at),
+            sentAt: record.sent_at ? new Date(record.sent_at) : undefined,
+            deliveredAt: record.delivered_at ? new Date(record.delivered_at) : undefined,
+            openedAt: record.opened_at ? new Date(record.opened_at) : undefined,
+            clickedAt: record.clicked_at ? new Date(record.clicked_at) : undefined,
+            bouncedAt: record.bounced_at ? new Date(record.bounced_at) : undefined
+        };
+    }
+    // ===== Subscriber Management =====
+    async createSubscriber(request) {
+        const id = this.generateId();
+        const now = new Date();
+        const subscriber = await this.db.insert('subscribers', {
+            id,
+            email: request.email,
+            name: request.name,
+            status: 'active',
+            lists: JSON.stringify(request.lists || []),
+            tags: request.tags ? JSON.stringify(request.tags) : null,
+            metadata: request.metadata ? JSON.stringify(request.metadata) : null,
+            subscribedAt: now,
+            createdAt: now,
+            updatedAt: now
+        });
+        this.logger.info(`Subscriber created: ${request.email}`, { id });
+        return this.parseSubscriber(subscriber);
+    }
+    async getSubscriber(id) {
+        const subscriber = await this.db.findById('subscribers', id);
+        return subscriber ? this.parseSubscriber(subscriber) : null;
+    }
+    async updateSubscriber(id, update) {
+        const updateData = {
+            updatedAt: new Date()
+        };
+        if (update.name !== undefined)
+            updateData.name = update.name;
+        if (update.status !== undefined)
+            updateData.status = update.status;
+        if (update.lists !== undefined)
+            updateData.lists = JSON.stringify(update.lists);
+        if (update.tags !== undefined)
+            updateData.tags = JSON.stringify(update.tags);
+        if (update.metadata !== undefined)
+            updateData.metadata = JSON.stringify(update.metadata);
+        const updated = await this.db.update('subscribers', id, updateData);
+        return this.parseSubscriber(updated);
+    }
+    async unsubscribe(email) {
+        const subscriber = await this.db.findOne('subscribers', { email });
+        if (!subscriber) {
+            return false;
+        }
+        await this.db.update('subscribers', subscriber.id, {
+            status: 'unsubscribed',
+            unsubscribedAt: new Date(),
+            updatedAt: new Date()
+        });
+        this.logger.info(`Subscriber unsubscribed: ${email}`);
+        return true;
+    }
+    parseSubscriber(record) {
+        return {
+            ...record,
+            lists: JSON.parse(record.lists),
+            tags: record.tags ? JSON.parse(record.tags) : undefined,
+            metadata: record.metadata ? JSON.parse(record.metadata) : undefined,
+            subscribedAt: new Date(record.subscribed_at || record.subscribedAt),
+            unsubscribedAt: record.unsubscribed_at ? new Date(record.unsubscribed_at) : undefined,
+            createdAt: new Date(record.created_at || record.createdAt),
+            updatedAt: new Date(record.updated_at || record.updatedAt)
+        };
+    }
+    async createList(name, description) {
+        const id = this.generateId();
+        const now = new Date();
+        return await this.db.insert('subscriber_lists', {
+            id,
+            name,
+            description,
+            subscriberCount: 0,
+            createdAt: now,
+            updatedAt: now
+        });
+    }
+    // ===== Webhooks =====
+    registerWebhookHandler(event, handler) {
+        if (!this.webhookHandlers.has(event)) {
+            this.webhookHandlers.set(event, []);
+        }
+        this.webhookHandlers.get(event).push(handler);
+    }
+    async handleWebhook(event) {
+        const handlers = this.webhookHandlers.get(event.event) || [];
+        for (const handler of handlers) {
+            try {
+                await handler(event);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.logger.error(`Webhook handler error for ${event.event}`, err);
+            }
+        }
+    }
+    // ===== Lifecycle =====
+    async shutdown() {
+        if (this.queue) {
+            await this.queue.close();
+        }
+        await this.db.disconnect();
+        this.logger.info('Email service shutdown complete');
+    }
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +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 { DeliveryStatus, SubscriberStatus, EmailServiceError, ProviderError, TemplateError, DeliveryError } from './types.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/*
+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 { EmailService } from './email-service.js';
+export { DeliveryStatus, SubscriberStatus, EmailServiceError, ProviderError, TemplateError, DeliveryError } from './types.js';