Add token compensation support for disconnected clients

API_DOCUMENTATION.md

@@ -699,6 +699,58 @@ The token must still belong to the authenticated tenant, still be valid, and sti
 
 ---
 
+### POST `/api/sessions/paid-disconnected/:tokenId/compensate`
+Add free compensation time to an affected paid client by extending the original purchased token.
+
+This is a goodwill extension only:
+- no new payment is created
+- revenue, balance, payouts, and ledgers are unchanged
+- the original token code stays the same
+- an audit record is written server-side
+
+The token must belong to the authenticated tenant and still be attached to a device in `offline`, `pending`, or `adopting`.
+
+**Auth:** Required
+
+**Body:**
+```json
+{
+  "minutes": 120,
+  "reason": "ISP outage compensation"
+}
+```
+
+**Validation:**
+- `minutes` must be a positive integer
+- max `minutes` is `10080` (7 days)
+- `reason` optional, max 255 characters
+
+**Response `200`:**
+```json
+{
+  "success": true,
+  "token_id": 88,
+  "token_code": "ABCD-1234",
+  "device_id": 3,
+  "device_name": "Main Building",
+  "status": "active",
+  "granted_minutes": 120,
+  "granted_seconds": 7200,
+  "old_expires_at": "2026-05-10T17:35:00.000Z",
+  "new_expires_at": "2026-05-10T19:35:00.000Z",
+  "remaining_seconds": 7200,
+  "reason": "ISP outage compensation",
+  "message": "Compensation time added successfully"
+}
+```
+
+**Notes:**
+- Use this from the Sessions page for outage support.
+- After success, refresh `GET /api/sessions/paid-disconnected`.
+- If the device is still offline, the row will remain in the list with a longer time left.
+
+---
+
 ### GET `/api/sessions`
 Session history (active and ended).
 

src/routes/sessions.routes.js

@@ -5,6 +5,10 @@ const { requireAuth } = require('../middleware/auth');
 
 router.use(requireAuth);
 
+function formatDateTimeLocal(date) {
+  return new Date(date).toISOString().slice(0, 19) + 'Z';
+}
+
 // GET /api/sessions/active
 router.get('/active', async (req, res) => {
   try {
@@ -140,6 +144,108 @@ router.post('/paid-disconnected/:tokenId/message', async (req, res) => {
   }
 });
 
+// POST /api/sessions/paid-disconnected/:tokenId/compensate
+router.post('/paid-disconnected/:tokenId/compensate', async (req, res) => {
+  const minutes = parseInt(req.body.minutes, 10);
+  const reason = req.body.reason ? String(req.body.reason).trim() : null;
+
+  if (!Number.isInteger(minutes) || minutes <= 0) {
+    return res.status(400).json({ error: 'minutes must be a positive integer' });
+  }
+  if (minutes > 7 * 24 * 60) {
+    return res.status(400).json({ error: 'minutes too large (max 10080)' });
+  }
+  if (reason && reason.length > 255) {
+    return res.status(400).json({ error: 'reason too long (max 255 characters)' });
+  }
+
+  const grantedSeconds = minutes * 60;
+  const conn = await db.pool.getConnection();
+
+  try {
+    await conn.beginTransaction();
+
+    const [rows] = await conn.execute(
+      `SELECT t.id AS token_id, t.payment_id, t.client_id, t.device_id, t.code AS token_code,
+              t.status, t.expires_at, t.duration_seconds,
+              d.name AS device_name, d.status AS device_status, d.billing_status
+       FROM access_tokens t
+       JOIN devices d ON d.id = t.device_id
+       JOIN payments p ON p.id = t.payment_id AND p.status = 'completed'
+       WHERE t.id = ?
+         AND t.client_id = ?
+         AND t.payment_id IS NOT NULL
+         AND d.billing_status NOT IN ('suspended', 'cancelled')
+         AND d.status IN ('offline', 'pending', 'adopting')
+       LIMIT 1`,
+      [req.params.tokenId, req.client.id]
+    );
+
+    const token = rows[0];
+    if (!token) {
+      await conn.rollback();
+      return res.status(404).json({ error: 'Compensatable client token not found' });
+    }
+
+    const oldExpiry = token.expires_at ? new Date(token.expires_at) : new Date();
+    const baseExpiry = oldExpiry > new Date() ? oldExpiry : new Date();
+    const newExpiry = new Date(baseExpiry.getTime() + grantedSeconds * 1000);
+
+    const nextStatus = newExpiry > new Date() ? 'active' : token.status;
+    const oldDurationSeconds = Number(token.duration_seconds || 0);
+    const nextDurationSeconds = oldDurationSeconds + grantedSeconds;
+
+    await conn.execute(
+      `UPDATE access_tokens
+       SET expires_at = ?, duration_seconds = ?, status = ?
+       WHERE id = ?`,
+      [newExpiry, nextDurationSeconds, nextStatus, token.token_id]
+    );
+
+    await conn.execute(
+      `INSERT INTO token_compensations
+         (token_id, payment_id, client_id, device_id, actor_type, actor_client_id,
+          granted_seconds, old_expires_at, new_expires_at, reason)
+       VALUES (?, ?, ?, ?, 'tenant', ?, ?, ?, ?, ?)`,
+      [
+        token.token_id,
+        token.payment_id,
+        token.client_id,
+        token.device_id,
+        req.client.id,
+        grantedSeconds,
+        token.expires_at || null,
+        newExpiry,
+        reason,
+      ]
+    );
+
+    await conn.commit();
+
+    res.json({
+      success: true,
+      token_id: token.token_id,
+      token_code: token.token_code,
+      device_id: token.device_id,
+      device_name: token.device_name,
+      status: nextStatus,
+      granted_minutes: minutes,
+      granted_seconds: grantedSeconds,
+      old_expires_at: token.expires_at ? formatDateTimeLocal(token.expires_at) : null,
+      new_expires_at: formatDateTimeLocal(newExpiry),
+      remaining_seconds: Math.max(0, Math.floor((newExpiry.getTime() - Date.now()) / 1000)),
+      reason,
+      message: 'Compensation time added successfully',
+    });
+  } catch (err) {
+    await conn.rollback();
+    console.error('[sessions/paid-disconnected/compensate]', err.message);
+    res.status(500).json({ error: 'Failed to compensate client token' });
+  } finally {
+    conn.release();
+  }
+});
+
 // GET /api/sessions?deviceId=&limit=
 router.get('/', async (req, res) => {
   const { deviceId, limit = 50 } = req.query;

src/utils/migrate.js

@@ -35,6 +35,29 @@ const migrations = [
   // 005 — Fix any invalid payments.status values before modifying the ENUM
   `UPDATE payments SET status = 'pending' WHERE status NOT IN ('pending','completed','failed','refunded')`,
   `ALTER TABLE payments MODIFY COLUMN status ENUM('pending','completed','failed','refunded') NOT NULL DEFAULT 'pending'`,
+
+  // 006 — Audit trail for tenant/admin customer compensation extensions
+  `CREATE TABLE IF NOT EXISTS token_compensations (
+    id                BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
+    token_id          BIGINT UNSIGNED NOT NULL,
+    payment_id        BIGINT UNSIGNED NOT NULL,
+    client_id         INT UNSIGNED NOT NULL,
+    device_id         INT UNSIGNED NOT NULL,
+    actor_type        ENUM('tenant','admin') NOT NULL,
+    actor_client_id   INT UNSIGNED DEFAULT NULL,
+    granted_seconds   INT UNSIGNED NOT NULL,
+    old_expires_at    TIMESTAMP NULL DEFAULT NULL,
+    new_expires_at    TIMESTAMP NOT NULL,
+    reason            VARCHAR(255) DEFAULT NULL,
+    created_at        TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    KEY idx_token_comp_token (token_id),
+    KEY idx_token_comp_client (client_id),
+    KEY idx_token_comp_payment (payment_id),
+    CONSTRAINT fk_token_comp_token FOREIGN KEY (token_id) REFERENCES access_tokens(id) ON DELETE CASCADE,
+    CONSTRAINT fk_token_comp_payment FOREIGN KEY (payment_id) REFERENCES payments(id) ON DELETE CASCADE,
+    CONSTRAINT fk_token_comp_client FOREIGN KEY (client_id) REFERENCES clients(id) ON DELETE CASCADE,
+    CONSTRAINT fk_token_comp_device FOREIGN KEY (device_id) REFERENCES devices(id) ON DELETE CASCADE
+  ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`,
 ];
 
 async function runMigrations() {