emailAutomation.js

Go to the documentation of this file.

/**
 * @file emailAutomation.js
 * @module routes/emailAutomation
 * @description Email-to-ticket automation endpoints with Microsoft Graph OAuth integration.
 * Handles inbound email processing, tenant email settings, OAuth flow for Office 365,
 * and outbound email sending via Graph API, SMTP, or Mailgun.
 * @requires express
 * @requires pushEmailToRedis
 * @requires uuid
 * @requires @azure/msal-node
 * @requires services/db
 * @requires services/email
 * @author RMM-PSA Development Team
 * @copyright 2026 RMM-PSA Platform
 * @license Proprietary
 */
 
/**
 * @apiDefine EmailAutomation Email Automation
 * Email-to-ticket automation and Microsoft Graph integration
 */
 
const express = require('express');
const router = express.Router();
const { pushEmail } = require('../pushEmailToRedis');
const { v4: uuidv4 } = require('uuid');
const msal = require('@azure/msal-node');
 
/**
 * @api {post} /api/email/inbound Process inbound email
 * @apiName ProcessInboundEmail
 * @apiGroup EmailAutomation
 * @apiDescription Receive inbound emails and queue for AI parsing to create tickets.
 * Generates unique email ID, pushes to Redis queue for async processing by AI worker.
 * No authentication required (called by email webhook/IMAP forwarder).
 * @apiParam {string} from Sender email address
 * @apiParam {string} [to] Recipient email address
 * @apiParam {string} subject Email subject
 * @apiParam {string} [text] Plain text email body
 * @apiParam {string} [html] HTML email body (used if text not provided)
 * @apiSuccess {string} status="queued" Email queued for processing
 * @apiSuccess {string} emailId Generated UUID for email tracking
 * @apiError (400) {String} error="Missing required fields" From, subject, or body missing
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/email/inbound \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "from": "customer@example.com",
 *       "to": "support@msp.com",
 *       "subject": "Printer not working",
 *       "text": "My printer has stopped working since this morning."
 *     }'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "status": "queued",
 *     "emailId": "550e8400-e29b-41d4-a716-446655440000"
 *   }
 */
router.post('/inbound', async (req, res) => {
  const { from, to, subject, text, html } = req.body;
  if (!from || !subject || !(text || html)) {
    return res.status(400).json({ error: 'Missing required fields' });
  }
  // Generate a unique email ID
  const emailId = uuidv4();
  // Push to Redis for AI parsing
  pushEmail({ id: emailId, from, to, subject, text: text || html });
  res.json({ status: 'queued', emailId });
});
 
/**
 * @api {get} /api/email/settings/:tenant_id Get email settings
 * @apiName GetEmailSettings
 * @apiGroup EmailAutomation
 * @apiDescription Retrieve tenant email automation settings from database.
 * Returns email configuration (provider, credentials, OAuth tokens).
 * @apiParam {number} tenant_id Tenant ID
 * @apiSuccess {string} [provider] Email provider ("smtp", "mailgun", "office365")
 * @apiSuccess {string} [username] Email username/address
 * @apiSuccess {object} [graph] Microsoft Graph OAuth tokens (if using Office 365)
 * @apiSuccess {object} [smtp] SMTP server configuration
 * @apiSuccess {object} [mailgun] Mailgun API configuration
 * @apiError (404) {String} error="Tenant not found" Tenant ID not in database
 * @apiError (500) {String} error="Server error" Database query failed
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/email/settings/2
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "provider": "office365",
 *     "username": "support@acme.com",
 *     "graph": {
 *       "accessToken": "eyJ0eXAiOi...",
 *       "refreshToken": "M.R3_BAY..."
 *     }
 *   }
 */
router.get('/settings/:tenant_id', async (req, res) => {
  const { tenant_id } = req.params;
  try {
    const pool = require('../services/db');
    const result = await pool.query('SELECT email_automation FROM tenants WHERE tenant_id = $1', [tenant_id]);
    if (!result.rows.length) return res.status(404).json({ error: 'Tenant not found' });
    res.json(result.rows[0].email_automation || {});
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {post} /api/email/settings/:tenant_id Save email settings
 * @apiName SaveEmailSettings
 * @apiGroup EmailAutomation
 * @apiDescription Update tenant email automation settings in database.
 * Accepts full settings object (provider, credentials, tokens).
 * @apiParam {number} tenant_id Tenant ID
 * @apiParam {string} [provider] Email provider ("smtp", "mailgun", "office365")
 * @apiParam {string} [username] Email username/address
 * @apiParam {object} [smtp] SMTP server configuration
 * @apiParam {string} [smtp.host] SMTP server hostname
 * @apiParam {number} [smtp.port] SMTP port
 * @apiParam {string} [smtp.password] SMTP password
 * @apiParam {object} [mailgun] Mailgun API configuration
 * @apiParam {string} [mailgun.apiKey] Mailgun API key
 * @apiParam {string} [mailgun.domain] Mailgun domain
 * @apiSuccess {boolean} success=true Settings saved successfully
 * @apiError (500) {String} error="Server error" Database update failed
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/email/settings/2 \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "provider": "smtp",
 *       "username": "support@acme.com",
 *       "smtp": {
 *         "host": "mail.acme.com",
 *         "port": 587,
 *         "password": "secret123"
 *       }
 *     }'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.post('/settings/:tenant_id', async (req, res) => {
  const { tenant_id } = req.params;
  const settings = req.body;
  try {
    const pool = require('../services/db');
    await pool.query('UPDATE tenants SET email_automation = $1 WHERE tenant_id = $2', [JSON.stringify(settings), tenant_id]);
    res.json({ success: true });
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {post} /api/email/oauth/:tenant_id Trigger OAuth flow (stub)
 * @apiName TriggerEmailOAuth
 * @apiGroup EmailAutomation
 * @apiDescription Stub endpoint for triggering Microsoft Graph OAuth flow.
 * Currently not implemented - returns placeholder response.
 * Use GET /oauth/:tenant_id/start for actual OAuth initiation.
 * @apiParam {number} tenant_id Tenant ID
 * @apiSuccess {string} status="not_implemented"
 * @apiSuccess {string} message Placeholder message
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/email/oauth/2
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "status": "not_implemented",
 *     "message": "OAuth flow not yet implemented."
 *   }
 */
router.post('/oauth/:tenant_id', async (req, res) => {
  // TODO: Implement Microsoft Graph OAuth flow and store tokens in email_automation
  res.json({ status: 'not_implemented', message: 'OAuth flow not yet implemented.' });
});
 
/**
 * @api {get} /api/email/oauth/:tenant_id/start Start OAuth flow
 * @apiName StartEmailOAuth
 * @apiGroup EmailAutomation
 * @apiDescription Initiate Microsoft Graph OAuth2 flow for Office 365 email integration.
 * Generates authorization URL using MSAL. User redirects to Microsoft login.
 * Requires msalConfig with clientId, authority configured.
 * @apiParam {number} tenant_id Tenant ID (used in OAuth state parameter)
 * @apiSuccess {string} url Microsoft authorization URL for user redirect
 * @apiError (500) {String} error="Failed to generate auth URL" MSAL configuration error
 * @apiExample {curl} Example:
 *   curl -X GET http://localhost:3000/api/email/oauth/2/start
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=..."
 *   }
 */
router.get('/oauth/:tenant_id/start', async (req, res) => {
  const { tenant_id } = req.params;
  const msalClient = new msal.ConfidentialClientApplication(msalConfig);
  const authCodeUrlParameters = {
    scopes: ['offline_access', 'Mail.Read', 'Mail.Send'],
    redirectUri
  };
  try {
    const url = await msalClient.getAuthCodeUrl(authCodeUrlParameters);
    res.json({ url });
  } catch (err) {
    res.status(500).json({ error: 'Failed to generate auth URL' });
  }
});
 
/**
 * @api {get} /api/email/oauth/callback OAuth callback
 * @apiName EmailOAuthCallback
 * @apiGroup EmailAutomation
 * @apiDescription Handle Microsoft Graph OAuth callback after user authorization.
 * Exchanges authorization code for access/refresh tokens using MSAL.
 * Stores tokens in tenant email_automation settings.
 * @apiParam {string} code Authorization code (query parameter from Microsoft)
 * @apiParam {string} state Tenant ID passed as state parameter (query parameter)
 * @apiSuccess {boolean} success=true Tokens acquired and saved successfully
 * @apiError (400) {String} error="Missing code or tenant_id" Required parameters not provided
 * @apiError (500) {String} error="OAuth callback failed" Token exchange or database save failed
 * @apiExample {curl} Example:
 *   curl -X GET "http://localhost:3000/api/email/oauth/callback?code=M.R3_BAY...&state=2"
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.get('/oauth/callback', async (req, res) => {
  const code = req.query.code;
  const tenant_id = req.query.state; // Pass tenant_id in state param for security
  if (!code || !tenant_id) return res.status(400).json({ error: 'Missing code or tenant_id' });
  const msalClient = new msal.ConfidentialClientApplication(msalConfig);
  try {
    const tokenResponse = await msalClient.acquireTokenByCode({
      code,
      scopes: ['offline_access', 'Mail.Read', 'Mail.Send'],
      redirectUri
    });
    // Save tokens to tenant email_automation config
    await pool.query(
      "UPDATE tenants SET email_automation = jsonb_set(coalesce(email_automation, '{}'), '{graph}', $1::jsonb) WHERE tenant_id = $2",
      [JSON.stringify(tokenResponse), tenant_id]
    );
    res.json({ success: true });
  } catch (err) {
    res.status(500).json({ error: 'OAuth callback failed', details: err.message });
  }
});
 
/**
 * @api {post} /api/email/test/:tenant_id Test email connection
 * @apiName TestEmailConnection
 * @apiGroup EmailAutomation
 * @apiDescription Test tenant email connection settings (stub implementation).
 * Verifies email configuration exists. TODO: Implement actual connection test (IMAP/Graph API).
 * @apiParam {number} tenant_id Tenant ID
 * @apiSuccess {boolean} success=true Settings found (not actual connection test)
 * @apiSuccess {string} message Stub message
 * @apiError (404) {String} error="Tenant not found" Tenant ID not in database
 * @apiError (400) {String} error="No email settings found" Email automation not configured
 * @apiError (500) {String} error="Server error" Database query failed
 * @apiExample {curl} Example:
 *   curl -X POST http://localhost:3000/api/email/test/2
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true,
 *     "message": "Connection test stub (implement real test)"
 *   }
 */
router.post('/test/:tenant_id', async (req, res) => {
  const { tenant_id } = req.params;
  try {
    const pool = require('../services/db');
    const result = await pool.query('SELECT email_automation FROM tenants WHERE tenant_id = $1', [tenant_id]);
    if (!result.rows.length) return res.status(404).json({ error: 'Tenant not found' });
    const settings = result.rows[0].email_automation;
    // TODO: Actually test connection (IMAP/Graph API)
    if (!settings || !settings.username) return res.status(400).json({ error: 'No email settings found' });
    res.json({ success: true, message: 'Connection test stub (implement real test)' });
  } catch (err) {
    res.status(500).json({ error: 'Server error' });
  }
});
 
/**
 * @api {post} /api/email/send/:tenant_id Send email
 * @apiName SendEmail
 * @apiGroup EmailAutomation
 * @apiDescription Send email via Microsoft Graph, SMTP, or Mailgun.
 * Uses tenant email automation settings to determine provider and credentials.
 * Supports Office 365 Graph API, generic SMTP, or Mailgun.
 * @apiParam {number} tenant_id Tenant ID
 * @apiParam {string} to Recipient email address
 * @apiParam {string} subject Email subject
 * @apiParam {string} [body] Email body (HTML or text, deprecated - use html/text)
 * @apiParam {string} [html] HTML email body
 * @apiParam {string} [text] Plain text email body
 * @apiParam {string} [provider] Override provider ("office365", "smtp", "mailgun")
 * @apiSuccess {boolean} success=true Email sent successfully
 * @apiSuccess {Object} [result] Send result details (SMTP/Mailgun only)
 * @apiError (400) {String} error="Missing to, subject, or body/html/text" Required parameters missing
 * @apiError (404) {String} error="Tenant not found" Tenant ID not in database
 * @apiError (400) {String} error="No Graph access token found" Office 365 tokens not configured
 * @apiError (500) {String} error="Failed to send email" Send operation failed
 * @apiExample {curl} Example (Office 365):
 *   curl -X POST http://localhost:3000/api/email/send/2 \\
 *     -H "Content-Type: application/json" \\
 *     -d '{
 *       "to": "customer@example.com",
 *       "subject": "Ticket Update",
 *       "html": "<p>Your ticket has been resolved.</p>",
 *       "provider": "office365"
 *     }'
 * @apiSuccessExample {json} Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "success": true
 *   }
 */
router.post('/send/:tenant_id', async (req, res) => {
  const { tenant_id } = req.params;
  const { to, subject, body, html, text, provider } = req.body;
  if (!to || !subject || !(body || html || text)) return res.status(400).json({ error: 'Missing to, subject, or body/html/text' });
  try {
    const pool = require('../services/db');
    const { sendEmail } = require('../services/email');
    // Get tenant email settings
    const result = await pool.query('SELECT email_automation FROM tenants WHERE tenant_id = $1', [tenant_id]);
    if (!result.rows.length) return res.status(404).json({ error: 'Tenant not found' });
    const settings = result.rows[0].email_automation || {};
    // Determine provider: 'mailgun', 'smtp', or 'office365' (graph)
    let emailProvider = provider || settings.provider || 'smtp';
    // If office365/graph, use old logic
    if (emailProvider === 'office365' || emailProvider === 'graph') {
      const graph = settings.graph;
      if (!graph || !graph.accessToken) return res.status(400).json({ error: 'No Graph access token found' });
      const { Client } = require('@microsoft/microsoft-graph-client');
      require('isomorphic-fetch');
      // TODO: Refresh token if expired
      const client = Client.init({
        authProvider: (done) => { done(null, graph.accessToken); }
      });
      await client.api('/me/sendMail').post({
        message: {
          subject,
          body: { contentType: 'HTML', content: body || html },
          toRecipients: [{ emailAddress: { address: to } }]
        },
        saveToSentItems: true
      });
      return res.json({ success: true });
    }
    // Otherwise, use sendEmail (Mailgun/SMTP)
    const emailResult = await sendEmail({
      to,
      subject,
      html: html || body,
      text,
      provider: emailProvider,
      settings
    });
    res.json({ success: true, result: emailResult });
  } catch (err) {
    res.status(500).json({ error: 'Failed to send email', details: err.message });
  }
});
 
// This route can be called by your email parser (IMAP/SMTP webhook)
// The AI worker will process and create a ticket if needed
module.exports = router;