@flusys/nestjs-email 1.1.0-beta

package/fesm/providers/email-factory.service.js

@@ -0,0 +1,109 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import * as crypto from 'crypto';
+import { EmailConfigService } from '../config/email-config.service';
+import { EmailProviderRegistry } from './email-provider.registry';
+export class EmailFactoryService {
+    /**
+   * Generate a unique cache key for a provider configuration
+   */ generateCacheKey(config) {
+        const configString = JSON.stringify(config.config, Object.keys(config.config || {}).sort());
+        const configHash = crypto.createHash('sha256').update(configString).digest('hex').substring(0, 16);
+        return `${config.provider}-${configHash}`;
+    }
+    /**
+   * Create or retrieve a cached email provider instance
+   */ async createProvider(config) {
+        const providerKey = this.generateCacheKey(config);
+        // Return cached provider if exists
+        if (this.providerCache.has(providerKey)) {
+            return this.providerCache.get(providerKey);
+        }
+        // Get provider class from registry
+        const ProviderClass = EmailProviderRegistry.get(config.provider);
+        if (!ProviderClass) {
+            throw new NotFoundException(`Email provider '${config.provider}' is not registered. ` + `Available providers: ${EmailProviderRegistry.getAll().join(', ')}`);
+        }
+        try {
+            // Create new instance
+            const instance = new ProviderClass();
+            // Initialize if provider has initialize method
+            if ('initialize' in instance && typeof instance.initialize === 'function') {
+                await instance.initialize(config.config);
+            }
+            // Cache the instance
+            this.providerCache.set(providerKey, instance);
+            this.logger.log(`Created email provider: ${config.provider} (key: ${providerKey})`);
+            return instance;
+        } catch (error) {
+            this.logger.error(`Failed to create provider ${config.provider}:`, error);
+            throw new Error(`Failed to initialize email provider '${config.provider}': ${error?.message || 'Unknown error'}`);
+        }
+    }
+    /**
+   * Check if a provider is available (registered)
+   */ isProviderAvailable(providerName) {
+        return EmailProviderRegistry.has(providerName);
+    }
+    /**
+   * Get list of available providers
+   */ getAvailableProviders() {
+        return EmailProviderRegistry.getAll();
+    }
+    /**
+   * Cleanup on module destroy
+   */ async onModuleDestroy() {
+        this.logger.log('Cleaning up email provider connections...');
+        const closePromises = [];
+        for (const [key, provider] of this.providerCache.entries()){
+            if ('close' in provider && typeof provider.close === 'function') {
+                closePromises.push(provider.close().then(()=>this.logger.debug(`Closed provider: ${key}`)).catch((err)=>this.logger.warn(`Failed to close provider ${key}: ${err.message}`)));
+            }
+        }
+        await Promise.allSettled(closePromises);
+        this.providerCache.clear();
+        this.logger.log('Email provider cleanup complete');
+    }
+    constructor(emailConfigService){
+        _define_property(this, "emailConfigService", void 0);
+        _define_property(this, "logger", void 0);
+        _define_property(this, "providerCache", void 0);
+        this.emailConfigService = emailConfigService;
+        this.logger = new Logger(EmailFactoryService.name);
+        this.providerCache = new Map();
+    }
+}
+EmailFactoryService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(EmailConfigService)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof EmailConfigService === "undefined" ? Object : EmailConfigService
+    ])
+], EmailFactoryService);

package/fesm/providers/email-provider.registry.js

@@ -0,0 +1,44 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Registry for email providers
+ * Allows dynamic registration of providers at runtime
+ */ export class EmailProviderRegistry {
+    /**
+   * Register an email provider
+   */ static register(providerName, providerClass) {
+        this.providers.set(providerName.toLowerCase(), providerClass);
+    }
+    /**
+   * Get a registered provider class
+   */ static get(providerName) {
+        return this.providers.get(providerName.toLowerCase());
+    }
+    /**
+   * Check if a provider is registered
+   */ static has(providerName) {
+        return this.providers.has(providerName.toLowerCase());
+    }
+    /**
+   * Get all registered provider names
+   */ static getAll() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+   * Clear all providers (useful for testing)
+   */ static clear() {
+        this.providers.clear();
+    }
+}
+_define_property(EmailProviderRegistry, "providers", new Map());

package/fesm/providers/index.js

@@ -0,0 +1,5 @@
+export * from './email-provider.registry';
+export * from './email-factory.service';
+export * from './smtp-provider';
+export * from './sendgrid-provider';
+export * from './mailgun-provider';

package/fesm/providers/mailgun-provider.js

@@ -0,0 +1,119 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { Logger } from '@nestjs/common';
+/**
+ * Mailgun Email Provider
+ * Uses mailgun.js package for sending emails
+ * Install: npm install mailgun.js form-data
+ */ export class MailgunProvider {
+    /**
+   * Initialize the Mailgun provider with configuration
+   */ async initialize(config) {
+        this.config = config;
+        try {
+            // Dynamic import mailgun.js and form-data - use eval to bypass TypeScript module resolution
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const Mailgun = (await new Function('return import("mailgun.js")')()).default;
+            const FormData = (await new Function('return import("form-data")')()).default;
+            const mailgun = new Mailgun(FormData);
+            // Determine API URL based on region
+            const url = config.region === 'eu' ? 'https://api.eu.mailgun.net' : 'https://api.mailgun.net';
+            this.client = mailgun.client({
+                username: 'api',
+                key: config.apiKey,
+                url
+            });
+            this.logger.log(`Mailgun Provider initialized for domain: ${config.domain}`);
+        } catch (error) {
+            this.logger.error('Failed to initialize Mailgun:', error.message);
+            throw new Error('Mailgun initialization failed. Make sure mailgun.js and form-data are installed: npm install mailgun.js form-data');
+        }
+    }
+    /**
+   * Send a single email
+   */ async sendEmail(options) {
+        if (!this.client || !this.config) {
+            return {
+                success: false,
+                error: 'Mailgun provider not initialized'
+            };
+        }
+        try {
+            const to = Array.isArray(options.to) ? options.to.join(', ') : options.to;
+            const cc = options.cc ? Array.isArray(options.cc) ? options.cc.join(', ') : options.cc : undefined;
+            const bcc = options.bcc ? Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc : undefined;
+            const messageData = {
+                from: options.fromName ? `${options.fromName} <${options.from}>` : options.from,
+                to,
+                subject: options.subject
+            };
+            // Only include html/text if they have values (required for plain text templates)
+            if (options.html) messageData.html = options.html;
+            if (options.text) messageData.text = options.text;
+            // Optional fields
+            if (cc) messageData.cc = cc;
+            if (bcc) messageData.bcc = bcc;
+            if (options.replyTo) messageData['h:Reply-To'] = options.replyTo;
+            // Handle attachments
+            if (options.attachments && options.attachments.length > 0) {
+                messageData.attachment = options.attachments.map((a)=>({
+                        filename: a.filename,
+                        data: typeof a.content === 'string' ? Buffer.from(a.content, 'base64') : a.content,
+                        contentType: a.contentType
+                    }));
+            }
+            const result = await this.client.messages.create(this.config.domain, messageData);
+            this.logger.log(`Email sent via Mailgun: ${result.id}`);
+            return {
+                success: true,
+                messageId: result.id
+            };
+        } catch (error) {
+            this.logger.error('Mailgun send failed:', error);
+            return {
+                success: false,
+                error: error.message
+            };
+        }
+    }
+    /**
+   * Send multiple emails (batch)
+   */ async sendBulkEmails(options) {
+        // Mailgun supports batch sending with recipient variables
+        // For simplicity, we send individually here
+        return Promise.all(options.map((opt)=>this.sendEmail(opt)));
+    }
+    /**
+   * Health check for the provider
+   */ async healthCheck() {
+        if (!this.client || !this.config) return false;
+        try {
+            // Verify domain exists
+            await this.client.domains.get(this.config.domain);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    /**
+   * Cleanup
+   */ async close() {
+        this.client = null;
+    }
+    constructor(){
+        _define_property(this, "logger", new Logger(MailgunProvider.name));
+        _define_property(this, "client", null);
+        _define_property(this, "config", null);
+    }
+}

package/fesm/providers/sendgrid-provider.js

@@ -0,0 +1,150 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { Logger } from '@nestjs/common';
+/**
+ * SendGrid Email Provider
+ * Uses @sendgrid/mail package for sending emails
+ * Install: npm install @sendgrid/mail
+ */ export class SendGridProvider {
+    /**
+   * Initialize the SendGrid provider with configuration
+   */ async initialize(config) {
+        this.config = config;
+        try {
+            // Dynamic import @sendgrid/mail - use eval to bypass TypeScript module resolution
+            // eslint-disable-next-line @typescript-eslint/no-implied-eval
+            const sgMailModule = await new Function('return import("@sendgrid/mail")')();
+            this.sgMail = sgMailModule.default || sgMailModule;
+            this.sgMail.setApiKey(config.apiKey);
+            this.logger.log('SendGrid Provider initialized');
+        } catch (error) {
+            this.logger.error('Failed to initialize SendGrid:', error.message);
+            throw new Error('SendGrid initialization failed. Make sure @sendgrid/mail is installed: npm install @sendgrid/mail');
+        }
+    }
+    /**
+   * Send a single email
+   */ async sendEmail(options) {
+        if (!this.sgMail) {
+            return {
+                success: false,
+                error: 'SendGrid provider not initialized'
+            };
+        }
+        try {
+            const msg = {
+                to: Array.isArray(options.to) ? options.to : [
+                    options.to
+                ],
+                from: options.fromName ? {
+                    email: options.from,
+                    name: options.fromName
+                } : options.from,
+                subject: options.subject
+            };
+            // Only include html/text if they have values (required for plain text templates)
+            if (options.html) msg.html = options.html;
+            if (options.text) msg.text = options.text;
+            // Optional fields
+            if (options.cc) {
+                msg.cc = Array.isArray(options.cc) ? options.cc : [
+                    options.cc
+                ];
+            }
+            if (options.bcc) {
+                msg.bcc = Array.isArray(options.bcc) ? options.bcc : [
+                    options.bcc
+                ];
+            }
+            if (options.replyTo) msg.replyTo = options.replyTo;
+            if (options.attachments?.length) {
+                msg.attachments = options.attachments.map((a)=>({
+                        filename: a.filename,
+                        content: typeof a.content === 'string' ? a.content : a.content.toString('base64'),
+                        type: a.contentType,
+                        disposition: 'attachment'
+                    }));
+            }
+            const [response] = await this.sgMail.send(msg);
+            const messageId = response.headers['x-message-id'] || response.headers['X-Message-Id'];
+            this.logger.log(`Email sent via SendGrid: ${messageId}`);
+            return {
+                success: true,
+                messageId
+            };
+        } catch (error) {
+            this.logger.error('SendGrid send failed:', error);
+            const errorMessage = error.response?.body?.errors?.[0]?.message || error.message;
+            return {
+                success: false,
+                error: errorMessage
+            };
+        }
+    }
+    /**
+   * Send multiple emails (batch)
+   */ async sendBulkEmails(options) {
+        if (!this.sgMail) {
+            return options.map(()=>({
+                    success: false,
+                    error: 'SendGrid provider not initialized'
+                }));
+        }
+        // SendGrid supports batch sending with sendMultiple
+        const messages = options.map((opt)=>{
+            const msg = {
+                to: Array.isArray(opt.to) ? opt.to : [
+                    opt.to
+                ],
+                from: opt.fromName ? {
+                    email: opt.from,
+                    name: opt.fromName
+                } : opt.from,
+                subject: opt.subject
+            };
+            if (opt.html) msg.html = opt.html;
+            if (opt.text) msg.text = opt.text;
+            return msg;
+        });
+        try {
+            await this.sgMail.send(messages);
+            return options.map(()=>({
+                    success: true
+                }));
+        } catch (error) {
+            this.logger.error('SendGrid bulk send failed:', error);
+            return options.map(()=>({
+                    success: false,
+                    error: error.message
+                }));
+        }
+    }
+    /**
+   * Health check for the provider
+   */ async healthCheck() {
+        // SendGrid doesn't have a direct health check API
+        // We verify the API key format is valid
+        return !!(this.sgMail && this.config?.apiKey?.startsWith('SG.'));
+    }
+    /**
+   * Cleanup (no-op for SendGrid)
+   */ async close() {
+        this.sgMail = null;
+    }
+    constructor(){
+        _define_property(this, "logger", new Logger(SendGridProvider.name));
+        _define_property(this, "sgMail", null);
+        _define_property(this, "config", null);
+    }
+}

package/fesm/providers/smtp-provider.js

@@ -0,0 +1,137 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { Logger } from '@nestjs/common';
+/**
+ * SMTP Email Provider using nodemailer
+ * Default provider - always available
+ */ export class SmtpProvider {
+    /**
+   * Initialize the SMTP provider with configuration
+   */ async initialize(config) {
+        this.config = config;
+        this.logger.log(`Initializing SMTP: host=${config.host}, port=${config.port}, secure=${config.secure}, user=${config.auth?.user}`);
+        // Dynamic import nodemailer
+        const nodemailer = await import('nodemailer');
+        // Determine secure mode: port 465 = implicit TLS, port 587 = STARTTLS
+        const isSecure = config.secure ?? config.port === 465;
+        this.transporter = nodemailer.createTransport({
+            host: config.host,
+            port: config.port,
+            secure: isSecure,
+            auth: config.auth,
+            // Timeout settings to prevent hanging
+            connectionTimeout: 10000,
+            greetingTimeout: 10000,
+            socketTimeout: 30000,
+            // TLS options for better compatibility
+            tls: {
+                rejectUnauthorized: false,
+                minVersion: 'TLSv1.2'
+            }
+        });
+        this.logger.log(`SMTP transporter created with secure=${isSecure}`);
+        // Verify connection with timeout
+        try {
+            const verifyPromise = this.transporter.verify();
+            const timeoutPromise = new Promise((_, reject)=>setTimeout(()=>reject(new Error('SMTP verification timeout')), 10000));
+            await Promise.race([
+                verifyPromise,
+                timeoutPromise
+            ]);
+            this.logger.log(`SMTP Provider verified successfully: ${config.host}:${config.port}`);
+        } catch (error) {
+            this.logger.warn(`SMTP verification failed: ${error.message}`);
+        // Don't throw - allow initialization even if verification fails
+        // Connection will be retried on send
+        }
+    }
+    /**
+   * Send a single email
+   */ async sendEmail(options) {
+        if (!this.transporter) {
+            return {
+                success: false,
+                error: 'SMTP provider not initialized'
+            };
+        }
+        const toAddress = Array.isArray(options.to) ? options.to.join(', ') : options.to;
+        this.logger.log(`Sending email to: ${toAddress}, subject: ${options.subject}`);
+        try {
+            const mailOptions = {
+                from: options.fromName ? `"${options.fromName}" <${options.from}>` : options.from,
+                to: toAddress,
+                cc: options.cc ? Array.isArray(options.cc) ? options.cc.join(', ') : options.cc : undefined,
+                bcc: options.bcc ? Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc : undefined,
+                subject: options.subject,
+                text: options.text,
+                html: options.html,
+                replyTo: options.replyTo,
+                attachments: options.attachments?.map((a)=>({
+                        filename: a.filename,
+                        content: a.content,
+                        contentType: a.contentType,
+                        encoding: a.encoding
+                    }))
+            };
+            this.logger.log(`Mail options: from=${mailOptions.from}, to=${mailOptions.to}`);
+            // Send with timeout
+            const sendPromise = this.transporter.sendMail(mailOptions);
+            const timeoutPromise = new Promise((_, reject)=>setTimeout(()=>reject(new Error('SMTP send timeout after 30 seconds')), 30000));
+            const info = await Promise.race([
+                sendPromise,
+                timeoutPromise
+            ]);
+            this.logger.log(`Email sent via SMTP: ${info.messageId}`);
+            return {
+                success: true,
+                messageId: info.messageId
+            };
+        } catch (error) {
+            this.logger.error(`SMTP send failed: ${error.message}`, error.stack);
+            return {
+                success: false,
+                error: error.message
+            };
+        }
+    }
+    /**
+   * Send multiple emails (batch)
+   */ async sendBulkEmails(options) {
+        return Promise.all(options.map((opt)=>this.sendEmail(opt)));
+    }
+    /**
+   * Health check for the provider
+   */ async healthCheck() {
+        if (!this.transporter) return false;
+        try {
+            await this.transporter.verify();
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+    /**
+   * Close the transporter
+   */ async close() {
+        if (this.transporter) {
+            this.transporter.close();
+            this.transporter = null;
+        }
+    }
+    constructor(){
+        _define_property(this, "logger", new Logger(SmtpProvider.name));
+        _define_property(this, "transporter", null);
+        _define_property(this, "config", null);
+    }
+}