email.js

Go to the documentation of this file.

/**
 * @file Email Service - Multi-Provider Email Delivery
 * @module services/email
 * @description
 * Unified email sending service supporting multiple providers (SMTP, Mailgun). Provides
 * automatic fallback to console logging when no transport is configured (development mode).
 * Supports per-tenant email configuration and environment variable defaults.
 *
 * **Supported Providers:**
 * - **SMTP**: Universal email protocol via nodemailer (default)
 * - **Mailgun**: Transactional email API for high deliverability
 *
 * **Configuration Priority:**
 * 1. Runtime settings parameter (tenant-specific)
 * 2. Environment variables (global defaults)
 * 3. Console fallback (no configuration)
 *
 * **SMTP Environment Variables:**
 * - `SMTP_HOST` - SMTP server hostname
 * - `SMTP_PORT` - SMTP server port (25, 465, 587)
 * - `SMTP_USER` - SMTP authentication username
 * - `SMTP_PASS` - SMTP authentication password
 * - `SMTP_SECURE` - Use TLS (true for port 465)
 * - `FROM_EMAIL` - Default sender address
 *
 * **Mailgun Configuration:**
 * - `settings.mailgun.apiKey` - Mailgun API key
 * - `settings.mailgun.domain` - Mailgun domain
 *
 * **Use Cases:**
 * - Password reset emails
 * - User verification
 * - Alert notifications
 * - Invoice delivery
 * - Ticket notifications
 * @example
 * // Send email using SMTP (env vars)
 * const { sendEmail } = require('./services/email');
 * await sendEmail({
 *   to: 'user@example.com',
 *   subject: 'Welcome to RMM',
 *   html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',
 *   text: 'Welcome! Thanks for signing up.'
 * });
 * @example
 * // Send via Mailgun with custom settings
 * await sendEmail({
 *   to: 'customer@example.com',
 *   subject: 'Invoice #12345',
 *   html: invoiceHtml,
 *   provider: 'mailgun',
 *   settings: {
 *     mailgun: {
 *       apiKey: 'key-abc123',
 *       domain: 'mg.example.com'
 *     },
 *     from: 'billing@example.com'
 *   }
 * });
 * @example
 * // Development fallback (no SMTP configured)
 * // Logs email to console instead of sending
 * await sendEmail({
 *   to: 'test@test.com',
 *   subject: 'Test',
 *   text: 'Testing'
 * });
 * // Output:
 * // [Email:FALLBACK] To: test@test.com
 * // [Email:FALLBACK] Subject: Test
 * // [Email:FALLBACK] Text: Testing
 * @requires nodemailer - SMTP email client
 * @requires @mailgun-js/mailgun.js - Mailgun API client
 * @requires form-data - Multipart form data for Mailgun
 */
 
const nodemailer = require('nodemailer');
const formData = require('form-data');
const Mailgun = require('@mailgun-js/mailgun.js');
const pool = require('./db');
const crypto = require('crypto');
 
 
/**
 * Check if email configuration is valid for a tenant
 * @description Validates that tenant has complete email configuration (SMTP or Mailgun)
 * before attempting to send. Prevents connection errors and logs issues.
 * @param {number} tenantId - Tenant ID to check configuration for
 * @param {object} [settings] - Runtime settings to validate (optional, checks DB if not provided)
 * @returns {Promise<object>} {isConfigured: boolean, provider: string, error: string}
 */
async function checkEmailConfig(tenantId, settings = null) {
  try {
    // If settings provided, validate them
    if (settings) {
      if (settings.provider === 'mailgun') {
        const valid = settings.mailgun?.apiKey && settings.mailgun?.domain;
        return {
          isConfigured: valid,
          provider: 'mailgun',
          error: valid ? null : 'Missing Mailgun API key or domain'
        };
      }
      // SMTP validation
      const smtp = settings.smtp || {};
      const host = smtp.host || process.env.SMTP_HOST;
      const port = smtp.port || process.env.SMTP_PORT;
      const user = smtp.user || process.env.SMTP_USER;
      const pass = smtp.pass || process.env.SMTP_PASS;
      
      if (!host || !port) {
        return {
          isConfigured: false,
          provider: 'smtp',
          error: 'Missing SMTP host or port'
        };
      }
      
      return { isConfigured: true, provider: 'smtp', error: null };
    }
    
    // Check database for tenant config
    const result = await pool.query(
      'SELECT provider, is_configured, smtp_host, smtp_port, mailgun_api_key, mailgun_domain FROM tenant_email_config WHERE tenant_id = $1',
      [tenantId]
    );
    
    if (!result.rows.length) {
      // No tenant config, check global env vars
      const hasGlobalSMTP = process.env.SMTP_HOST && process.env.SMTP_PORT;
      return {
        isConfigured: hasGlobalSMTP,
        provider: 'smtp',
        error: hasGlobalSMTP ? null : 'No email configuration found (tenant or global)'
      };
    }
    
    const config = result.rows[0];
    return {
      isConfigured: config.is_configured,
      provider: config.provider,
      error: config.is_configured ? null : 'Email configuration incomplete or not tested'
    };
  } catch (error) {
    console.error('[Email] Config check error:', error);
    return { isConfigured: false, provider: 'unknown', error: error.message };
  }
}
 
 
/**
 * Create email tracking record in database
 * @description Generates tracking pixel ID and stores email metadata for open tracking
 * @param {object} params - Tracking parameters
 * @param {number} params.tenantId - Tenant ID
 * @param {string} params.to - Recipient email
 * @param {string} params.subject - Email subject
 * @param {string} [params.emailType] - Email type (invoice, ticket, notification, etc.)
 * @param {string} [params.referenceType] - Reference type (invoice, ticket, user, etc.)
 * @param {number} [params.referenceId] - Reference ID
 * @param {string} [params.provider] - Email provider (smtp, mailgun)
 * @returns {Promise<string>} Tracking ID (UUID)
 */
async function createEmailTracking({ tenantId, to, subject, emailType, referenceType, referenceId, provider = 'smtp' }) {
  try {
    const result = await pool.query(
      `INSERT INTO email_tracking 
       (tenant_id, recipient_email, subject, email_type, reference_type, reference_id, provider) 
       VALUES ($1, $2, $3, $4, $5, $6, $7) 
       RETURNING tracking_id`,
      [tenantId, to, subject, emailType, referenceType, referenceId, provider]
    );
    return result.rows[0].tracking_id;
  } catch (error) {
    console.error('[Email] Failed to create tracking record:', error);
    return null; // Non-fatal, email can still send without tracking
  }
}
 
 
/**
 * Inject tracking pixel into HTML email
 * @description Adds 1x1 transparent tracking pixel at end of HTML body for open tracking
 * @param {string} html - HTML email content
 * @param {string} trackingId - Tracking UUID to embed in pixel URL
 * @param {string} [backendUrl] - Backend URL (defaults to env var or relative)
 * @returns {string} HTML with tracking pixel injected
 */
function injectTrackingPixel(html, trackingId, backendUrl = null) {
  if (!html || !trackingId) return html;
  
  const baseUrl = backendUrl || process.env.BACKEND_URL || 'https://rmm-psa-backend-t9f7k.ondigitalocean.app';
  const pixelUrl = `${baseUrl}/api/email/track/${trackingId}/pixel.gif`;
  
  // Inject pixel before closing body tag (or at end if no body tag)
  const pixel = `<img src="${pixelUrl}" width="1" height="1" alt="" style="display:block;width:1px;height:1px;border:0;" />`;
  
  if (html.toLowerCase().includes('</body>')) {
    return html.replace(/<\/body>/i, `${pixel}</body>`);
  } else {
    return html + pixel;
  }
}
 
 
/**
 * Build email transport client for SMTP or Mailgun
 * @description Creates nodemailer transport for SMTP or Mailgun client based on settings.
 * Returns null if SMTP not configured (triggers console fallback). Supports both
 * runtime settings and environment variable configuration.
 * @param {object} [settings] - Transport configuration object
 * @param {string} [settings.provider] - Transport provider: 'smtp' (default) or 'mailgun'
 * @param {object} [settings.smtp] - SMTP configuration
 * @param {string} [settings.smtp.host] - SMTP server hostname
 * @param {number} [settings.smtp.port] - SMTP server port (25, 465, 587)
 * @param {string} [settings.smtp.user] - SMTP authentication username
 * @param {string} [settings.smtp.pass] - SMTP authentication password
 * @param {boolean} [settings.smtp.secure] - Use TLS (true for port 465)
 * @param {object} [settings.mailgun] - Mailgun configuration
 * @param {string} [settings.mailgun.apiKey] - Mailgun API key
 * @param {string} [settings.mailgun.domain] - Mailgun sending domain
 * @returns {object|null} Nodemailer transport, Mailgun client, or null if unconfigured
 */
function buildTransport(settings) {
  // settings: { smtp: {...}, mailgun: {...}, provider: 'smtp'|'mailgun' }
  if (settings && settings.provider === 'mailgun' && settings.mailgun) {
    // Mailgun transport (new SDK)
    const mg = new Mailgun(formData);
    return mg.client({
      username: 'api',
      key: settings.mailgun.apiKey
    });
  }
  // Default to SMTP
  const smtp = settings && settings.smtp ? settings.smtp : {};
  const host = smtp.host || process.env.SMTP_HOST;
  const port = smtp.port || process.env.SMTP_PORT;
  const user = smtp.user || process.env.SMTP_USER;
  const pass = smtp.pass || process.env.SMTP_PASS;
  const secure = smtp.secure !== undefined ? smtp.secure : (process.env.SMTP_SECURE === 'true');
  if (!host || !port) {
    return null; // No SMTP configured; fallback to console
  }
  return nodemailer.createTransport({
    host,
    port: Number(port),
    secure,
    auth: user && pass ? { user, pass } : undefined,
  });
}
 
 
/**
 * Send email via SMTP or Mailgun with automatic fallback
 * @description Sends email using configured provider (SMTP by default). Falls back to
 * console logging in development if SMTP is not configured. Supports HTML and plain text
 * content with automatic multipart handling. Now includes tracking pixel injection and
 * configuration validation to prevent connection errors.
 * @param {object} param0 - Email sending options
 * @param {string} param0.to - Recipient email address
 * @param {string} param0.subject - Email subject line
 * @param {string} [param0.html] - HTML email content
 * @param {string} [param0.text] - Plain text email content
 * @param {string} [param0.provider] - Email provider: 'smtp' (default) or 'mailgun'
 * @param {object} [param0.settings] - Provider configuration with from/smtp/mailgun properties
 * @param {number} [param0.tenantId] - Tenant ID for tracking and config validation
 * @param {string} [param0.emailType] - Email type for tracking (invoice, ticket, notification, etc.)
 * @param {string} [param0.referenceType] - Reference type (invoice, ticket, user, etc.)
 * @param {number} [param0.referenceId] - Reference ID for tracking
 * @param {boolean} [param0.skipTracking] - Skip tracking pixel injection (default: false)
 * @returns {Promise<object>} Email send result with tracking info: {success, trackingId, messageId, fallback}
 * @throws {Error} Throws if email sending fails (network, auth, etc.) or if config is invalid
 */
async function sendEmail({ 
  to, 
  subject, 
  html, 
  text, 
  provider = 'smtp', 
  settings = {}, 
  tenantId = null,
  emailType = null,
  referenceType = null,
  referenceId = null,
  skipTracking = false
}) {
  const from = (settings.from || process.env.FROM_EMAIL) || 'no-reply@ibg.local';
  
  // Validate email configuration before attempting to send
  if (tenantId) {
    const configCheck = await checkEmailConfig(tenantId, settings);
    if (!configCheck.isConfigured) {
      console.warn(`[Email] Tenant ${tenantId}: Email not configured - ${configCheck.error}`);
      console.log('[Email:FALLBACK] To:', to);
      console.log('[Email:FALLBACK] Subject:', subject);
      console.log('[Email:FALLBACK] Reason: Email not configured for tenant');
      return { 
        success: false, 
        fallback: true, 
        error: configCheck.error,
        message: 'Email configuration incomplete - email not sent'
      };
    }
  }
  
  // Create tracking record and inject pixel (if enabled)
  let trackingId = null;
  if (tenantId && !skipTracking) {
    trackingId = await createEmailTracking({
      tenantId,
      to,
      subject,
      emailType,
      referenceType,
      referenceId,
      provider
    });
    
    // Inject tracking pixel into HTML
    if (trackingId && html) {
      html = injectTrackingPixel(html, trackingId);
    }
  }
  
  // Send via provider
  if (provider === 'mailgun' && settings.mailgun) {
    // Use Mailgun
    const mg = buildTransport({ provider: 'mailgun', mailgun: settings.mailgun });
    const data = {
      from,
      to,
      subject,
      text: text || undefined,
      html: html || undefined
    };
    try {
      const result = await mg.messages.create(settings.mailgun.domain, data);
      console.log(`[Email:Mailgun] Sent to ${to} - Message ID: ${result.id}`);
      
      // Update tracking with provider message ID
      if (trackingId) {
        await pool.query(
          'UPDATE email_tracking SET provider_message_id = $1, delivery_status = $2 WHERE tracking_id = $3',
          [result.id, 'sent', trackingId]
        );
      }
      
      return { 
        success: true, 
        messageId: result.id, 
        trackingId,
        provider: 'mailgun'
      };
    } catch (error) {
      console.error('[Mailgun] Error:', error);
      
      // Update tracking with error
      if (trackingId) {
        await pool.query(
          'UPDATE email_tracking SET delivery_status = $1, delivery_error = $2 WHERE tracking_id = $3',
          ['failed', error.message, trackingId]
        );
      }
      
      throw error;
    }
  } else {
    // Use SMTP
    const transporter = buildTransport({ provider: 'smtp', smtp: settings.smtp });
    if (!transporter) {
      console.log('[Email:FALLBACK] To:', to);
      console.log('[Email:FALLBACK] Subject:', subject);
      console.log('[Email:FALLBACK] Text:', text || '');
      console.log('[Email:FALLBACK] HTML length:', html ? html.length : 0);
      console.log('[Email:FALLBACK] Reason: SMTP not configured (missing SMTP_HOST or SMTP_PORT)');
      return { 
        success: false, 
        fallback: true,
        trackingId: null,
        message: 'SMTP not configured - email logged to console only'
      };
    }
    
    try {
      const info = await transporter.sendMail({ from, to, subject, text, html });
      console.log(`[Email:SMTP] Sent to ${to} - Message ID: ${info.messageId}`);
      
      // Update tracking with provider message ID
      if (trackingId) {
        await pool.query(
          'UPDATE email_tracking SET provider_message_id = $1, delivery_status = $2 WHERE tracking_id = $3',
          [info.messageId, 'sent', trackingId]
        );
      }
      
      return { 
        success: true, 
        messageId: info.messageId, 
        trackingId,
        provider: 'smtp'
      };
    } catch (error) {
      console.error('[SMTP] Error:', error);
      
      // Update tracking with error
      if (trackingId) {
        await pool.query(
          'UPDATE email_tracking SET delivery_status = $1, delivery_error = $2 WHERE tracking_id = $3',
          ['failed', error.message, trackingId]
        );
      }
      
      throw error;
    }
  }
}
 
module.exports = { sendEmail, checkEmailConfig, createEmailTracking, injectTrackingPixel };