Alert tenants for token lifecycle events

src/jobs/pollSessions.job.js

@@ -1,6 +1,7 @@
 const db         = require('../config/db');
 const omada      = require('../services/omada');
 const { alertAdmin } = require('../utils/adminAlert');
+const { alertWifiClient } = require('../utils/tokenClientAlerts');
 
 function normalizeMac(mac) {
   return String(mac || '')
@@ -111,6 +112,8 @@ async function pollSessions() {
 
           if (!token) {
             console.log(`[pollSessions] Created manual Omada session for mac=${mac} device=${device.id} without token`);
+          } else {
+            alertWifiClient('token_started', token.id, { mac }).catch(() => {});
           }
         }
       } catch (err) {

src/routes/portal.routes.js

@@ -12,6 +12,7 @@ const { alertAdmin } = require('../utils/adminAlert');
 const { makePaymentAssetUrl } = require('../utils/portalPaymentStorage');
 const { snippeWebhookUrl } = require('../utils/webhookUrl');
 const { decryptSecret } = require('../utils/paymentSecrets');
+const { alertWifiClient } = require('../utils/tokenClientAlerts');
 
 const normalizeMac = mac => String(mac || '').toUpperCase().replace(/[:\-]/g, '');
 const normalizePortalMac = mac => String(mac || '').trim().toUpperCase().replace(/:/g, '-');
@@ -175,6 +176,7 @@ async function recordOmadaVoucherUse({ siteId, code, mac }) {
 
     const now = new Date();
     let expiresAt = token.expires_at ? new Date(token.expires_at) : null;
+    const shouldAlertStarted = token.status === 'unused' || !token.activated_at;
 
     if (token.status === 'revoked') {
       await conn.rollback();
@@ -245,6 +247,10 @@ async function recordOmadaVoucherUse({ siteId, code, mac }) {
 
     await conn.commit();
 
+    if (shouldAlertStarted) {
+      alertWifiClient('token_started', token.id, { mac }).catch(() => {});
+    }
+
     return {
       token: updatedRows[0] || { ...token, status: 'active', locked_mac: mac, expires_at: expiresAt },
       expiresAt,
@@ -882,6 +888,7 @@ router.post('/:siteId/auth', portalAuthLimiter, async (req, res) => {
 
     const now = new Date();
     let expiresAt = token.expires_at ? new Date(token.expires_at) : null;
+    let shouldAlertStarted = false;
     trace.step('expiry_window_prepared', { existingExpiresAt: token.expires_at });
 
     if (token.status === 'unused') {
@@ -897,6 +904,7 @@ router.post('/:siteId/auth', portalAuthLimiter, async (req, res) => {
         [mac, now, expiresAt, token.id]
       );
       trace.step('token_activated', { expiresAt: expiresAt.toISOString() });
+      shouldAlertStarted = true;
     } else if (!expiresAt) {
       expiresAt = new Date(now.getTime() + token.duration_seconds * 1000);
       await db.query(
@@ -929,6 +937,10 @@ router.post('/:siteId/auth', portalAuthLimiter, async (req, res) => {
       trace.step('session_created');
     }
 
+    if (shouldAlertStarted) {
+      alertWifiClient('token_started', token.id, { mac }).catch(() => {});
+    }
+
     const unitLabel = (v, u) => `${v}${u === 2 ? 'Mbps' : 'Kbps'}`;
     const secsLeft  = Math.floor((expiresAt - now) / 1000);
     trace.step('response_ready', { secsLeft, expiresAt: expiresAt.toISOString() });

src/routes/tokens.routes.js

@@ -2,6 +2,7 @@ const router = require('express').Router();
 const db = require('../config/db');
 const { requireAuth } = require('../middleware/auth');
 const omada = require('../services/omada');
+const { alertWifiClient } = require('../utils/tokenClientAlerts');
 
 router.use(requireAuth);
 
@@ -650,6 +651,10 @@ router.post('/:id/extend', async (req, res) => {
     await connection.commit();
 
     const updated = await loadTokenRow(token.token_id, req.client.id);
+    alertWifiClient('token_extended', token.token_id, {
+      minutes: Math.ceil(grantedSeconds / 60),
+      expiresAt: auditNewExpiresAt,
+    }).catch(() => {});
 
     res.json({
       success: true,
@@ -770,6 +775,12 @@ router.patch('/:id/duration', async (req, res) => {
     await connection.commit();
 
     const updated = await loadTokenRow(token.token_id, req.client.id);
+    if (deltaSeconds > 0) {
+      alertWifiClient('token_extended', token.token_id, {
+        minutes: Math.ceil(deltaSeconds / 60),
+        expiresAt: nextExpiresAt,
+      }).catch(() => {});
+    }
 
     res.json({
       success: true,
@@ -911,6 +922,13 @@ router.delete('/:id', async (req, res) => {
 
     await connection.commit();
 
+    if (action !== 'deleted') {
+      alertWifiClient('token_revoked', token.token_id, {
+        action,
+        mac: token.locked_mac,
+      }).catch(() => {});
+    }
+
     res.json({
       success: true,
       action,

src/utils/messages.js

@@ -18,6 +18,18 @@ module.exports = {
       ? `Your WiFi access for ${deviceName} (${planName}) has expired. Buy a new bundle to reconnect.`
       : `Your WiFi access for ${deviceName} has expired. Buy a new bundle to reconnect.`,
 
+  // Tenant receives this when a guest starts using a token
+  tokenStartedAlert: (code, deviceName, mac) =>
+    `Token ${code} started being used on ${deviceName}${mac ? ` by ${mac}` : ''}.`,
+
+  // Tenant receives this when a token extension is granted
+  tokenExtendedAlert: (code, deviceName, minutes, expiresAt = null) =>
+    `Token ${code} on ${deviceName} was extended by ${minutes} minute(s)${expiresAt ? `. New expiry: ${expiresAt}` : ''}.`,
+
+  // Tenant receives this when a token is revoked or voided
+  tokenRevokedAlert: (code, deviceName, action = 'revoked') =>
+    `Token ${code} on ${deviceName} was ${action}.`,
+
   // Tenant receives this after their device subscription renews
   deviceRenewal: (deviceName, expiryDate) =>
     `"${deviceName}" renewed until ${expiryDate}. Keep selling!`,

src/utils/tokenClientAlerts.js

@@ -0,0 +1,96 @@
+const db = require('../config/db');
+const sms = require('../services/sms');
+const messages = require('./messages');
+const { canSendTenantNotification } = require('./notificationPreferences');
+
+function formatDateTime(value) {
+  if (!value) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleString('en-TZ', {
+    timeZone: 'Africa/Dar_es_Salaam',
+    year: 'numeric',
+    month: 'short',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+  });
+}
+
+async function loadTokenContext(tokenId) {
+  return db.queryOne(
+    `SELECT t.id AS token_id, t.code AS token_code, t.locked_mac, t.expires_at,
+            d.id AS device_id, d.name AS device_name,
+            c.id AS client_id, c.phone AS client_phone
+     FROM access_tokens t
+     JOIN devices d ON d.id = t.device_id
+     JOIN clients c ON c.id = t.client_id
+     WHERE t.id = ?
+     LIMIT 1`,
+    [tokenId]
+  );
+}
+
+async function alertWifiClient(eventType, tokenId, options = {}) {
+  try {
+    const token = await loadTokenContext(tokenId);
+    if (!token?.client_id) return false;
+    if (!(await canSendTenantNotification(token.client_id, 'purchase_alerts'))) return false;
+
+    const mac = options.mac || token.locked_mac || null;
+    const minutes = options.minutes || null;
+    const action = options.action || 'revoked';
+    const expiresAt = formatDateTime(options.expiresAt || token.expires_at);
+
+    let alertKey = null;
+    let module = 'tokens';
+    let content = null;
+
+    if (eventType === 'token_started') {
+      alertKey = `token-started-${token.token_id}-${String(mac || 'unknown').replace(/[^A-Za-z0-9]/g, '')}`;
+      content = messages.tokenStartedAlert(token.token_code, token.device_name, mac);
+    } else if (eventType === 'token_extended') {
+      alertKey = `token-extended-${token.token_id}-${Date.now()}`;
+      content = messages.tokenExtendedAlert(token.token_code, token.device_name, minutes, expiresAt);
+    } else if (eventType === 'token_revoked') {
+      alertKey = `token-revoked-${token.token_id}-${Date.now()}`;
+      content = messages.tokenRevokedAlert(token.token_code, token.device_name, action);
+    } else {
+      return false;
+    }
+
+    const result = await db.query(
+      `INSERT IGNORE INTO omada_alerts
+         (client_id, device_id, omada_alert_id, alert_key, module, level, content, device_mac, alert_time)
+       VALUES (?, ?, ?, ?, ?, 'info', ?, ?, NOW())`,
+      [
+        token.client_id,
+        token.device_id,
+        alertKey,
+        eventType,
+        module,
+        content,
+        mac,
+      ]
+    );
+
+    if (Number(result?.affectedRows || 0) === 0) {
+      return false;
+    }
+
+    if (token.client_phone) {
+      sms.sendSMS(token.client_phone, content).catch(err => {
+        console.error('[token-alert] SMS failed:', err.message);
+      });
+    }
+
+    return true;
+  } catch (err) {
+    console.error('[token-alert] failed:', err.message, { eventType, tokenId });
+    return false;
+  }
+}
+
+module.exports = {
+  alertWifiClient,
+};