notifications.js

Go to the documentation of this file.

/**
 * @file routes/notifications.js
 * @module routes/notifications
 * @description Notification management API for in-app and Slack notifications. Handles user-specific
 * and global notifications with multi-tenant isolation. Supports Slack webhook integration for
 * real-time team alerts.
 * 
 * **Notification Types:**
 * - User-specific (user_id set): Targeted to individual user
 * - Global (user_id NULL): Visible to all users in tenant
 * - System-wide (root MSP only): Visible across all tenants
 * 
 * **Common Notification Types:**
 * - stock: Low stock alerts (product inventory)
 * - ticket: Ticket updates and assignments
 * - invoice: Invoice generation and payment alerts
 * - system: System maintenance and updates
 * - alert: Critical system alerts
 * - info: Informational messages
 * 
 * **Multi-Tenant Behavior:**
 * - Root MSP: Sees all notifications (system + their user-specific)
 * - Regular tenants: See only notifications for their tenant (global + user-specific)
 * - User-specific notifications filtered by user_id from JWT
 * 
 * **Slack Integration:**
 * - Automatic webhook notification when Slack integration active
 * - Configured per tenant in integrations table
 * - Non-blocking (failures don't prevent notification creation)
 * - Message format: Bold title + plain text message
 * - Optional channel targeting via Slack config
 * 
 * **Use Cases:**
 * - Low stock alerts (from invoices.js stock management)
 * - Ticket assignment notifications
 * - System maintenance announcements
 * - Invoice generation alerts
 * - Agent heartbeat failures
 * - Critical system alerts
 * 
 * **Related Models:**
 * - notifications table (notification_id, user_id, customer_id, tenant_id, title, message, type, is_read)
 * - integrations table (Slack webhook configuration)
 * - users table (notification recipients)
 * @requires express
 * @requires ../services/db
 * @requires ../middleware/auth
 * @requires ../middleware/tenant
 * @author IBG MSP Development Team
 * @date 2024-03-11
 * @since 1.0.0
 * @see {@link module:routes/integrations} for Slack integration configuration
 * @see {@link module:routes/users} for user management
 */
 
const express = require('express');
const router = express.Router();
const pool = require('../services/db');
const authenticateToken = require('../middleware/auth');
 
const { getTenantFilter } = require('../middleware/tenant');
 
/**
 * @api {get} /notifications List Notifications
 * @apiName GetNotifications
 * @apiGroup Notifications
 * @apiDescription Retrieves notifications for authenticated user. Returns user-specific notifications
 * plus global notifications visible to entire tenant. Root MSP users see system-wide notifications.
 * Ordered by creation date (newest first), limited to 100 most recent.
 * 
 * **Notification Visibility:**
 * - User-specific (user_id = current user): Always visible
 * - Global (user_id NULL, tenant_id = user's tenant): Visible to all in tenant
 * - System-wide (user_id NULL, tenant_id NULL): Root MSP only
 * 
 * **Root MSP Behavior:**
 * Root MSP tenant sees:
 * - All their personal notifications (user_id = current user)
 * - All system-wide global notifications (user_id NULL)
 * 
 * **Regular Tenant Behavior:**
 * Regular tenants see:
 * - Their personal notifications (user_id = current user)
 * - Tenant-wide global notifications (user_id NULL AND tenant_id = user's tenant)
 * 
 * **Ordering & Limits:**
 * - Sorted by created_at DESC (newest first)
 * - Maximum 100 notifications returned
 * - Use is_read flag for client-side filtering of unread
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiSuccess {object[]} notifications Array of notification objects (max 100)
 * @apiSuccess {number} notifications.notification_id Unique notification ID
 * @apiSuccess {number} notifications.user_id Target user ID (NULL for global)
 * @apiSuccess {number} notifications.customer_id Associated customer ID (if applicable)
 * @apiSuccess {number} notifications.tenant_id Associated tenant ID (NULL for system-wide)
 * @apiSuccess {string} notifications.title Notification title/subject
 * @apiSuccess {string} notifications.message Notification body/details
 * @apiSuccess {string} notifications.type Notification type (stock, ticket, invoice, system, alert, info)
 * @apiSuccess {boolean} notifications.is_read Whether user has read notification
 * @apiSuccess {string} notifications.created_at Creation timestamp
 * @apiError {number} 500 Server error during notification retrieval
 * @apiExample {curl} Example Request:
 *   curl -X GET \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/notifications"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   [
 *     {
 *       "notification_id": 42,
 *       "user_id": 12,
 *       "customer_id": null,
 *       "tenant_id": 5,
 *       "title": "Ticket Assigned",
 *       "message": "Ticket #892 has been assigned to you",
 *       "type": "ticket",
 *       "is_read": false,
 *       "created_at": "2024-03-11T17:45:00.000Z"
 *     },
 *     {
 *       "notification_id": 38,
 *       "user_id": null,
 *       "customer_id": null,
 *       "tenant_id": 5,
 *       "title": "Low stock: Dell Latitude 5420 Laptop",
 *       "message": "Stock for product Dell Latitude 5420 Laptop is low (8 < 10)",
 *       "type": "stock",
 *       "is_read": false,
 *       "created_at": "2024-03-11T16:30:00.000Z"
 *     }
 *   ]
 * @since 1.0.0
 * @see {@link module:routes/notifications.createNotification} for creating notifications
 * @see {@link module:routes/notifications.markNotificationRead} for marking as read
 */
router.get('/', authenticateToken, async (req, res) => {
  const userId = req.user && req.user.user_id;
  const tenantId = req.user?.tenantId || req.user?.tenant_id;
  const isRootTenant = req.tenant?.isMsp || req.user?.is_msp;
  
  const { clause: tenantClause, params: tenantParams } = getTenantFilter(req, 'n');
  try {
    let query;
    let params;
    
    if (isRootTenant) {
      // Root tenant sees all notifications (system + user-specific)
      query = `SELECT * FROM notifications n WHERE (user_id IS NULL OR user_id = $1)`;
      params = [userId];
    } else {
      // Regular tenants only see notifications for their tenant
      query = `SELECT * FROM notifications n WHERE (user_id = $1 OR (user_id IS NULL AND tenant_id = $2))`;
      params = [userId, tenantId];
    }
    
    if (tenantClause && !isRootTenant) {
      query += ` AND ${tenantClause}`;
      params = [...params, ...tenantParams];
    }
    
    query += ' ORDER BY created_at DESC LIMIT 100';
    const result = await pool.query(query, params);
    res.json(result.rows);
  } catch (err) {
    console.error('Error fetching notifications:', err);
    res.status(500).send('Server error');
  }
});
 
/**
 * @api {post} /notifications Create Notification
 * @apiName CreateNotification
 * @apiGroup Notifications
 * @apiDescription Creates a new notification with optional Slack webhook integration. Supports
 * user-specific and global notifications. Automatically sends to Slack if integration active
 * for tenant.
 * 
 * **Notification Targeting:**
 * - User-specific: Set user_id (notification visible only to that user)
 * - Global: Omit user_id or set NULL (notification visible to all users in tenant)
 * - Customer-related: Set customer_id to associate with customer record
 * 
 * **Tenant Context:**
 * - Application determines tenant_id from req.tenant context (JWT)
 * - Can override with explicit tenant_id parameter (for impersonation)
 * - Falls back to req.tenant.id if not provided
 * 
 * **Slack Integration:**
 * If Slack integration configured and active for tenant:
 * 1. Query integrations table for tenant's Slack config
 * 2. Extract webhookUrl and optional channel from config JSON
 * 3. POST to Slack webhook with formatted message
 * 4. Message format: Bold title + plain text message
 * 5. Failure non-blocking (notification still created)
 * 
 * **Type Best Practices:**
 * - stock: Inventory/reorder alerts
 * - ticket: Ticket assignments, updates, closures
 * - invoice: Invoice generation, payment, overdue
 * - system: Maintenance, updates, configuration changes
 * - alert: Critical issues requiring immediate attention
 * - info: General informational messages
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiHeader {string} Content-Type application/json
 * @apiParam {number} [user_id] Target user ID (NULL for global notification)
 * @apiParam {number} [customer_id] Related customer ID (optional)
 * @apiParam {string} title Notification title/subject (required)
 * @apiParam {string} message Notification body/details (required)
 * @apiParam {string} type Notification type (stock, ticket, invoice, system, alert, info)
 * @apiParam {number} [tenant_id] Override tenant ID (for impersonation, defaults to req.tenant.id)
 * @apiSuccess {number} notification_id Generated notification ID
 * @apiSuccess {number} user_id Target user ID
 * @apiSuccess {number} customer_id Associated customer ID
 * @apiSuccess {number} tenant_id Associated tenant ID
 * @apiSuccess {string} title Notification title
 * @apiSuccess {string} message Notification message
 * @apiSuccess {string} type Notification type
 * @apiSuccess {boolean} is_read Always false for new notifications
 * @apiSuccess {string} created_at Creation timestamp
 * 
 * @apiError {Number} 500 Failed to create notification
 * 
 * @apiExample {curl} Example Request (User-Specific):
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "user_id": 12,
 *          "title": "Ticket Assigned",
 *          "message": "Ticket #892 has been assigned to you",
 *          "type": "ticket"
 *        }' \
 *        "https://api.everydaytech.au/notifications"
 * 
 * @apiExample {curl} Example Request (Global):
 *   curl -X POST \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        -H "Content-Type: application/json" \
 *        -d '{
 *          "title": "System Maintenance",
 *          "message": "Platform maintenance scheduled for March 15, 2024 at 2:00 AM UTC",
 *          "type": "system"
 *        }' \
 *        "https://api.everydaytech.au/notifications"
 * 
 * @apiExample {json} Success Response:
 *   HTTP/1.1 201 Created
 *   {
 *     "notification_id": 42,
 *     "user_id": 12,
 *     "customer_id": null,
 *     "tenant_id": 5,
 *     "title": "Ticket Assigned",
 *     "message": "Ticket #892 has been assigned to you",
 *     "type": "ticket",
 *     "is_read": false,
 *     "created_at": "2024-03-11T17:45:00.000Z"
 *   }
 * 
 * @since 1.0.0
 * @see {@link module:routes/notifications.getNotifications} for retrieving notifications
 * @see {@link module:routes/integrations} for Slack integration setup
 */
router.post('/', authenticateToken, async (req, res) => {
  const { user_id, customer_id, title, message, type, tenant_id } = req.body;
  let targetTenantId = tenant_id;
  if (!targetTenantId && req.tenant && req.tenant.id) targetTenantId = req.tenant.id;
  try {
    const result = await pool.query(
      `INSERT INTO notifications (user_id, customer_id, title, message, type, tenant_id) VALUES ($1,$2,$3,$4,$5,$6) RETURNING *`,
      [user_id || null, customer_id || null, title, message, type, targetTenantId]
    );
    // Slack integration: send notification if enabled and configured
    try {
      const slackRes = await pool.query(
        `SELECT config FROM integrations WHERE tenant_id = $1 AND integration_type = 'slack' AND is_active = true LIMIT 1`,
        [targetTenantId]
      );
      if (slackRes.rows.length) {
        const slackCfg = slackRes.rows[0].config;
        const webhookUrl = slackCfg.webhookUrl;
        const channel = slackCfg.channel || '';
        if (webhookUrl) {
          const payload = {
            text: `*${title}*\n${message}`,
            channel: channel || undefined
          };
          await fetch(webhookUrl, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
          });
        }
      }
    } catch (e) {
      console.error('Slack notification error:', e);
    }
    res.status(201).json(result.rows[0]);
  } catch (err) {
    console.error('Error creating notification:', err);
    res.status(500).send('Failed to create notification');
  }
});
 
/**
 * @api {put} /notifications/:id/mark-read Mark Notification as Read
 * @apiName MarkNotificationRead
 * @apiGroup Notifications
 * @apiDescription Marks a notification as read by setting is_read flag to true. Used when user
 * views notification in UI. Idempotent operation - calling multiple times has same effect.
 * 
 * **UI Integration:**
 * - Call when user clicks/views notification
 * - Update notification badge counts in real-time
 * - Use for "mark all as read" features (call for each notification)
 * 
 * **No Ownership Validation:**
 * Current implementation does not validate notification belongs to authenticated user.
 * Consider adding WHERE user_id = $1 clause for security.
 * @apiHeader {string} Authorization Bearer JWT token
 * @apiParam {number} id Notification ID (in URL path)
 * @apiSuccess {number} notification_id Notification ID
 * @apiSuccess {boolean} is_read Always true after successful update
 * @apiSuccess {string} updated_at Update timestamp (if column exists)
 * @apiError {number} 500 Failed to update notification
 * @apiExample {curl} Example Request:
 *   curl -X PUT \
 *        -H "Authorization: Bearer eyJhbGc..." \
 *        "https://api.everydaytech.au/notifications/42/mark-read"
 * @apiExample {json} Success Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "notification_id": 42,
 *     "user_id": 12,
 *     "customer_id": null,
 *     "tenant_id": 5,
 *     "title": "Ticket Assigned",
 *     "message": "Ticket #892 has been assigned to you",
 *     "type": "ticket",
 *     "is_read": true,
 *     "created_at": "2024-03-11T17:45:00.000Z"
 *   }
 * @since 1.0.0
 * @see {@link module:routes/notifications.getNotifications} for retrieving notifications
 */
router.put('/:id/mark-read', authenticateToken, async (req, res) => {
  const id = req.params.id;
  try {
    const result = await pool.query('UPDATE notifications SET is_read = TRUE WHERE notification_id = $1 RETURNING *', [id]);
    res.json(result.rows[0]);
  } catch (err) {
    console.error('Error marking notification read:', err);
    res.status(500).send('Failed to update notification');
  }
});
 
module.exports = router;