@push.rocks/smartmta 5.1.2 → 5.2.0

package/ts/mail/core/classes.emailvalidator.ts

@@ -0,0 +1,239 @@
+import * as plugins from '../../plugins.js';
+import { logger } from '../../logger.js';
+import { LRUCache } from 'lru-cache';
+
+export interface IEmailValidationResult {
+  isValid: boolean;
+  hasMx: boolean;
+  hasSpamMarkings: boolean;
+  score: number;
+  details?: {
+    formatValid?: boolean;
+    mxRecords?: string[];
+    disposable?: boolean;
+    role?: boolean;
+    spamIndicators?: string[];
+    errorMessage?: string;
+  };
+}
+
+/**
+ * Advanced email validator class using smartmail's capabilities
+ */
+export class EmailValidator {
+  private validator: plugins.smartmail.EmailAddressValidator;
+  private dnsCache: LRUCache<string, string[]>;
+  
+  constructor(options?: {
+    maxCacheSize?: number;
+    cacheTTL?: number;
+  }) {
+    this.validator = new plugins.smartmail.EmailAddressValidator();
+    
+    // Initialize LRU cache for DNS records
+    this.dnsCache = new LRUCache<string, string[]>({
+      // Default to 1000 entries (reasonable for most applications)
+      max: options?.maxCacheSize || 1000,
+      // Default TTL of 1 hour (DNS records don't change frequently)
+      ttl: options?.cacheTTL || 60 * 60 * 1000,
+      // Optional cache monitoring
+      allowStale: false,
+      updateAgeOnGet: true,
+      // Add logging for cache events in production environments
+      disposeAfter: (value, key) => {
+        logger.log('debug', `DNS cache entry expired for domain: ${key}`);
+      },
+    });
+  }
+  
+  /**
+   * Validates an email address using comprehensive checks
+   * @param email The email to validate
+   * @param options Validation options
+   * @returns Validation result with details
+   */
+  public async validate(
+    email: string,
+    options: {
+      checkMx?: boolean;
+      checkDisposable?: boolean;
+      checkRole?: boolean;
+      checkSyntaxOnly?: boolean;
+    } = {}
+  ): Promise<IEmailValidationResult> {
+    try {
+      const result: IEmailValidationResult = {
+        isValid: false,
+        hasMx: false,
+        hasSpamMarkings: false,
+        score: 0,
+        details: {
+          formatValid: false,
+          spamIndicators: []
+        }
+      };
+      
+      // Always check basic format
+      result.details.formatValid = this.validator.isValidEmailFormat(email);
+      if (!result.details.formatValid) {
+        result.details.errorMessage = 'Invalid email format';
+        return result;
+      }
+      
+      // If syntax-only check is requested, return early
+      if (options.checkSyntaxOnly) {
+        result.isValid = true;
+        result.score = 0.5;
+        return result;
+      }
+      
+      // Get domain for additional checks
+      const domain = email.split('@')[1];
+      
+      // Check MX records
+      if (options.checkMx !== false) {
+        try {
+          const mxRecords = await this.getMxRecords(domain);
+          result.details.mxRecords = mxRecords;
+          result.hasMx = mxRecords && mxRecords.length > 0;
+          
+          if (!result.hasMx) {
+            result.details.spamIndicators.push('No MX records');
+            result.details.errorMessage = 'Domain has no MX records';
+          }
+        } catch (error) {
+          logger.log('error', `Error checking MX records: ${error.message}`);
+          result.details.errorMessage = 'Unable to check MX records';
+        }
+      }
+      
+      // Check if domain is disposable
+      if (options.checkDisposable !== false) {
+        result.details.disposable = await this.validator.isDisposableEmail(email);
+        if (result.details.disposable) {
+          result.details.spamIndicators.push('Disposable email');
+        }
+      }
+      
+      // Check if email is a role account
+      if (options.checkRole !== false) {
+        result.details.role = this.validator.isRoleAccount(email);
+        if (result.details.role) {
+          result.details.spamIndicators.push('Role account');
+        }
+      }
+      
+      // Calculate spam score and final validity
+      result.hasSpamMarkings = result.details.spamIndicators.length > 0;
+      
+      // Calculate a score between 0-1 based on checks
+      let scoreFactors = 0;
+      let scoreTotal = 0;
+      
+      // Format check (highest weight)
+      scoreFactors += 0.4;
+      if (result.details.formatValid) scoreTotal += 0.4;
+      
+      // MX check (high weight)
+      if (options.checkMx !== false) {
+        scoreFactors += 0.3;
+        if (result.hasMx) scoreTotal += 0.3;
+      }
+      
+      // Disposable check (medium weight)
+      if (options.checkDisposable !== false) {
+        scoreFactors += 0.2;
+        if (!result.details.disposable) scoreTotal += 0.2;
+      }
+      
+      // Role account check (low weight)
+      if (options.checkRole !== false) {
+        scoreFactors += 0.1;
+        if (!result.details.role) scoreTotal += 0.1;
+      }
+      
+      // Normalize score based on factors actually checked
+      result.score = scoreFactors > 0 ? scoreTotal / scoreFactors : 0;
+      
+      // Email is valid if score is above 0.7 (configurable threshold)
+      result.isValid = result.score >= 0.7;
+      
+      return result;
+    } catch (error) {
+      logger.log('error', `Email validation error: ${error.message}`);
+      return {
+        isValid: false,
+        hasMx: false,
+        hasSpamMarkings: true,
+        score: 0,
+        details: {
+          formatValid: false,
+          errorMessage: `Validation error: ${error.message}`,
+          spamIndicators: ['Validation error']
+        }
+      };
+    }
+  }
+  
+  /**
+   * Gets MX records for a domain with caching
+   * @param domain Domain to check
+   * @returns Array of MX records
+   */
+  private async getMxRecords(domain: string): Promise<string[]> {
+    // Check cache first
+    const cachedRecords = this.dnsCache.get(domain);
+    if (cachedRecords) {
+      logger.log('debug', `Using cached MX records for domain: ${domain}`);
+      return cachedRecords;
+    }
+    
+    try {
+      // Use smartmail's getMxRecords method
+      const records = await this.validator.getMxRecords(domain);
+      
+      // Store in cache (TTL is handled by the LRU cache configuration)
+      this.dnsCache.set(domain, records);
+      logger.log('debug', `Cached MX records for domain: ${domain}`);
+      
+      return records;
+    } catch (error) {
+      logger.log('error', `Error fetching MX records for ${domain}: ${error.message}`);
+      return [];
+    }
+  }
+  
+  /**
+   * Validates multiple email addresses in batch
+   * @param emails Array of emails to validate
+   * @param options Validation options
+   * @returns Object with email addresses as keys and validation results as values
+   */
+  public async validateBatch(
+    emails: string[],
+    options: {
+      checkMx?: boolean;
+      checkDisposable?: boolean;
+      checkRole?: boolean;
+      checkSyntaxOnly?: boolean;
+    } = {}
+  ): Promise<Record<string, IEmailValidationResult>> {
+    const results: Record<string, IEmailValidationResult> = {};
+    
+    for (const email of emails) {
+      results[email] = await this.validate(email, options);
+    }
+    
+    return results;
+  }
+  
+  /**
+   * Quick check if an email format is valid (synchronous, no DNS checks)
+   * @param email Email to check
+   * @returns Boolean indicating if format is valid
+   */
+  public isValidFormat(email: string): boolean {
+    return this.validator.isValidEmailFormat(email);
+  }
+  
+}

package/ts/mail/core/classes.templatemanager.ts

@@ -0,0 +1,320 @@
+import * as plugins from '../../plugins.js';
+import * as paths from '../../paths.js';
+import { logger } from '../../logger.js';
+import { Email, type IEmailOptions, type IAttachment } from './classes.email.js';
+
+/**
+ * Email template type definition
+ */
+export interface IEmailTemplate<T = any> {
+  id: string;
+  name: string;
+  description: string;
+  from: string;
+  subject: string;
+  bodyHtml: string;
+  bodyText?: string;
+  category?: string;
+  sampleData?: T;
+  attachments?: Array<{
+    name: string;
+    path: string;
+    contentType?: string;
+  }>;
+}
+
+/**
+ * Email template context - data used to render the template
+ */
+export interface ITemplateContext {
+  [key: string]: any;
+}
+
+/**
+ * Template category definitions
+ */
+export enum TemplateCategory {
+  NOTIFICATION = 'notification',
+  TRANSACTIONAL = 'transactional',
+  MARKETING = 'marketing',
+  SYSTEM = 'system'
+}
+
+/**
+ * Enhanced template manager using Email class for template rendering
+ */
+export class TemplateManager {
+  private templates: Map<string, IEmailTemplate> = new Map();
+  private defaultConfig: {
+    from: string;
+    replyTo?: string;
+    footerHtml?: string;
+    footerText?: string;
+  };
+  
+  constructor(defaultConfig?: {
+    from?: string;
+    replyTo?: string;
+    footerHtml?: string;
+    footerText?: string;
+  }) {
+    // Set default configuration
+    this.defaultConfig = {
+      from: defaultConfig?.from || 'noreply@mail.lossless.com',
+      replyTo: defaultConfig?.replyTo,
+      footerHtml: defaultConfig?.footerHtml || '',
+      footerText: defaultConfig?.footerText || ''
+    };
+    
+    // Initialize with built-in templates
+    this.registerBuiltinTemplates();
+  }
+  
+  /**
+   * Register built-in email templates
+   */
+  private registerBuiltinTemplates(): void {
+    // Welcome email
+    this.registerTemplate<{
+      firstName: string;
+      accountUrl: string;
+    }>({
+      id: 'welcome',
+      name: 'Welcome Email',
+      description: 'Sent to users when they first sign up',
+      from: this.defaultConfig.from,
+      subject: 'Welcome to {{serviceName}}!',
+      category: TemplateCategory.TRANSACTIONAL,
+      bodyHtml: `
+        <h1>Welcome, {{firstName}}!</h1>
+        <p>Thank you for joining {{serviceName}}. We're excited to have you on board.</p>
+        <p>To get started, <a href="{{accountUrl}}">visit your account</a>.</p>
+      `,
+      bodyText: 
+        `Welcome, {{firstName}}!
+        
+        Thank you for joining {{serviceName}}. We're excited to have you on board.
+        
+        To get started, visit your account: {{accountUrl}}
+        `,
+      sampleData: {
+        firstName: 'John',
+        accountUrl: 'https://example.com/account'
+      }
+    });
+    
+    // Password reset
+    this.registerTemplate<{
+      resetUrl: string;
+      expiryHours: number;
+    }>({
+      id: 'password-reset',
+      name: 'Password Reset',
+      description: 'Sent when a user requests a password reset',
+      from: this.defaultConfig.from,
+      subject: 'Password Reset Request',
+      category: TemplateCategory.TRANSACTIONAL,
+      bodyHtml: `
+        <h2>Password Reset Request</h2>
+        <p>You recently requested to reset your password. Click the link below to reset it:</p>
+        <p><a href="{{resetUrl}}">Reset Password</a></p>
+        <p>This link will expire in {{expiryHours}} hours.</p>
+        <p>If you didn't request a password reset, please ignore this email.</p>
+      `,
+      sampleData: {
+        resetUrl: 'https://example.com/reset-password?token=abc123',
+        expiryHours: 24
+      }
+    });
+    
+    // System notification
+    this.registerTemplate({
+      id: 'system-notification',
+      name: 'System Notification',
+      description: 'General system notification template',
+      from: this.defaultConfig.from,
+      subject: '{{subject}}',
+      category: TemplateCategory.SYSTEM,
+      bodyHtml: `
+        <h2>{{title}}</h2>
+        <div>{{message}}</div>
+      `,
+      sampleData: {
+        subject: 'Important System Notification',
+        title: 'System Maintenance',
+        message: 'The system will be undergoing maintenance on Saturday from 2-4am UTC.'
+      }
+    });
+  }
+  
+  /**
+   * Register a new email template
+   * @param template The email template to register
+   */
+  public registerTemplate<T = any>(template: IEmailTemplate<T>): void {
+    if (this.templates.has(template.id)) {
+      logger.log('warn', `Template with ID '${template.id}' already exists and will be overwritten`);
+    }
+    
+    // Add footer to templates if configured
+    if (this.defaultConfig.footerHtml && template.bodyHtml) {
+      template.bodyHtml += this.defaultConfig.footerHtml;
+    }
+    
+    if (this.defaultConfig.footerText && template.bodyText) {
+      template.bodyText += this.defaultConfig.footerText;
+    }
+    
+    this.templates.set(template.id, template);
+    logger.log('info', `Registered email template: ${template.id}`);
+  }
+  
+  /**
+   * Get an email template by ID
+   * @param templateId The template ID
+   * @returns The template or undefined if not found
+   */
+  public getTemplate<T = any>(templateId: string): IEmailTemplate<T> | undefined {
+    return this.templates.get(templateId) as IEmailTemplate<T>;
+  }
+  
+  /**
+   * List all available templates
+   * @param category Optional category filter
+   * @returns Array of email templates
+   */
+  public listTemplates(category?: TemplateCategory): IEmailTemplate[] {
+    const templates = Array.from(this.templates.values());
+    if (category) {
+      return templates.filter(template => template.category === category);
+    }
+    return templates;
+  }
+  
+  /**
+   * Create an Email instance from a template
+   * @param templateId The template ID
+   * @param context The template context data
+   * @returns A configured Email instance
+   */
+  public async createEmail<T = any>(
+    templateId: string,
+    context?: ITemplateContext
+  ): Promise<Email> {
+    const template = this.getTemplate(templateId);
+    
+    if (!template) {
+      throw new Error(`Template with ID '${templateId}' not found`);
+    }
+    
+    // Build attachments array for Email
+    const attachments: IAttachment[] = [];
+    
+    if (template.attachments && template.attachments.length > 0) {
+      for (const attachment of template.attachments) {
+        try {
+          const attachmentPath = plugins.path.isAbsolute(attachment.path) 
+            ? attachment.path 
+            : plugins.path.join(paths.MtaAttachmentsDir, attachment.path);
+            
+          // Read the file
+          const fileBuffer = await plugins.fs.promises.readFile(attachmentPath);
+          
+          attachments.push({
+            filename: attachment.name,
+            content: fileBuffer,
+            contentType: attachment.contentType || 'application/octet-stream'
+          });
+        } catch (error) {
+          logger.log('error', `Failed to add attachment '${attachment.name}': ${error.message}`);
+        }
+      }
+    }
+    
+    // Create Email instance with template content
+    const emailOptions: IEmailOptions = {
+      from: template.from || this.defaultConfig.from,
+      subject: template.subject,
+      text: template.bodyText || '',
+      html: template.bodyHtml,
+      // Note: 'to' is intentionally omitted for templates
+      attachments,
+      variables: context || {}
+    };
+    
+    return new Email(emailOptions);
+  }
+  
+  /**
+   * Create and completely process an Email instance from a template
+   * @param templateId The template ID
+   * @param context The template context data
+   * @returns A complete, processed Email instance ready to send
+   */
+  public async prepareEmail<T = any>(
+    templateId: string,
+    context: ITemplateContext = {}
+  ): Promise<Email> {
+    const email = await this.createEmail<T>(templateId, context);
+    
+    // Email class processes variables when needed, no pre-compilation required
+    
+    return email;
+  }
+  
+  /**
+   * Create a MIME-formatted email from a template
+   * @param templateId The template ID
+   * @param context The template context data
+   * @returns A MIME-formatted email string
+   */
+  public async createMimeEmail(
+    templateId: string,
+    context: ITemplateContext = {}
+  ): Promise<string> {
+    const email = await this.prepareEmail(templateId, context);
+    return email.toRFC822String(context);
+  }
+  
+  
+  /**
+   * Load templates from a directory
+   * @param directory The directory containing template JSON files
+   */
+  public async loadTemplatesFromDirectory(directory: string): Promise<void> {
+    try {
+      // Ensure directory exists
+      if (!plugins.fs.existsSync(directory)) {
+        logger.log('error', `Template directory does not exist: ${directory}`);
+        return;
+      }
+      
+      // Get all JSON files
+      const files = plugins.fs.readdirSync(directory)
+        .filter(file => file.endsWith('.json'));
+      
+      for (const file of files) {
+        try {
+          const filePath = plugins.path.join(directory, file);
+          const content = plugins.fs.readFileSync(filePath, 'utf8');
+          const template = JSON.parse(content) as IEmailTemplate;
+          
+          // Validate template
+          if (!template.id || !template.subject || (!template.bodyHtml && !template.bodyText)) {
+            logger.log('warn', `Invalid template in ${file}: missing required fields`);
+            continue;
+          }
+          
+          this.registerTemplate(template);
+        } catch (error) {
+          logger.log('error', `Error loading template from ${file}: ${error.message}`);
+        }
+      }
+      
+      logger.log('info', `Loaded ${this.templates.size} email templates`);
+    } catch (error) {
+      logger.log('error', `Failed to load templates from directory: ${error.message}`);
+      throw error;
+    }
+  }
+}

package/ts/mail/core/index.ts

@@ -0,0 +1,5 @@
+// Core email components
+export * from './classes.email.js';
+export * from './classes.emailvalidator.js';
+export * from './classes.templatemanager.js';
+export * from './classes.bouncemanager.js';