Add captive portal free promo claims

public/engine.js

@@ -48,6 +48,7 @@
   // ── State ─────────────────────────────────────────────────────────────────
   let selectedPlanId    = null;
   let selectedPlanPrice = null;
+  let selectedPlanIsPromo = false;
   let pollTimer         = null;
   let currentReference  = null;
   let purchaseInFlight  = false;
@@ -64,7 +65,9 @@
   function updatePayBtn() {
     if (!payBtn) return;
     if (selectedPlanId && isPhoneValid()) {
-      payBtn.textContent = `Pay ${parseInt(selectedPlanPrice).toLocaleString()} TZS & Connect`;
+      payBtn.textContent = selectedPlanIsPromo
+        ? 'Claim promo'
+        : `Pay ${parseInt(selectedPlanPrice).toLocaleString()} TZS & Connect`;
       payBtn.disabled = false;
     } else if (selectedPlanId) {
       payBtn.textContent = 'Enter your phone number';
@@ -79,6 +82,7 @@
     radio.addEventListener('change', () => {
       selectedPlanId    = radio.dataset.planId;
       selectedPlanPrice = radio.dataset.planPrice;
+      selectedPlanIsPromo = radio.dataset.planPromo === '1' || Number(selectedPlanPrice) === 0;
       updatePayBtn();
     });
   });
@@ -106,24 +110,38 @@
       if (!phone || phone.replace(/\D/g, '').length < 9) {
         return showError('select-error', 'Enter a valid phone number.');
       }
+      if (selectedPlanIsPromo && !P.clientMac) {
+        return showError('select-error', 'Open this portal from the WiFi login page on the device you want to connect.');
+      }
 
       purchaseInFlight = true;
       payBtn.disabled = true;
       showScreen('waiting');
 
       try {
-        const res = await fetch(`/portal/${P.siteId}/purchase`, {
+        const endpoint = selectedPlanIsPromo ? 'promo' : 'purchase';
+        const payload = selectedPlanIsPromo
+          ? { planId: selectedPlanId, phone, clientMac: P.clientMac }
+          : { planId: selectedPlanId, phone };
+        const res = await fetch(`/portal/${P.siteId}/${endpoint}`, {
           method:  'POST',
           headers: { 'Content-Type': 'application/json' },
-          body:    JSON.stringify({ planId: selectedPlanId, phone }),
+          body:    JSON.stringify(payload),
         });
-        const data = await res.json();
+        const data = await readJsonSafe(res);
+
+        if (selectedPlanIsPromo && res.ok && data.code) {
+          purchaseInFlight = false;
+          payBtn.disabled = false;
+          showCodeEntry(data.code);
+          return;
+        }
 
         if (!res.ok || !data.reference) {
           showScreen('select');
           purchaseInFlight = false;
           payBtn.disabled = false;
-          return showError('select-error', data.error || 'Purchase failed. Try again.');
+          return showError('select-error', data.error || (selectedPlanIsPromo ? 'Could not issue promo code. Please ask the attendant.' : 'Purchase failed. Try again.'));
         }
 
         currentReference = data.reference;

src/routes/plans.routes.js

@@ -11,6 +11,12 @@ function formatVoucherSyncError(err) {
   return `${code}${err.message || 'Voucher group sync failed'}${detail}`.slice(0, 255);
 }
 
+function parsePlanNumber(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
 async function syncPlanVoucherGroup(plan) {
   const device = await db.queryOne(
     `SELECT id, omada_site_id FROM devices WHERE id = ? AND client_id = ? LIMIT 1`,
@@ -171,10 +177,18 @@ router.get('/', async (req, res) => {
 // POST /api/plans
 router.post('/', async (req, res) => {
   const { device_id, name, duration_seconds, price, down_limit, down_unit, up_limit, up_unit, display_order } = req.body;
+  const durationValue = parsePlanNumber(duration_seconds);
+  const priceValue = parsePlanNumber(price);
 
-  if (!device_id || !name || !duration_seconds || !price) {
+  if (!device_id || !name || durationValue === null || priceValue === null) {
     return res.status(400).json({ error: 'device_id, name, duration_seconds, price required' });
   }
+  if (durationValue <= 0) {
+    return res.status(400).json({ error: 'duration_seconds must be greater than 0' });
+  }
+  if (priceValue < 0) {
+    return res.status(400).json({ error: 'price cannot be negative' });
+  }
 
   try {
     const device = await db.query(
@@ -190,7 +204,7 @@ router.post('/', async (req, res) => {
        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
       [
         req.client.id, device_id, name,
-        parseInt(duration_seconds), parseFloat(price),
+        parseInt(durationValue, 10), priceValue,
         down_limit || 1, down_unit || 2,
         up_limit   || 5, up_unit   || 2,
         display_order || 0,
@@ -208,6 +222,15 @@ router.post('/', async (req, res) => {
 // PUT /api/plans/:id
 router.put('/:id', async (req, res) => {
   const { name, duration_seconds, price, down_limit, down_unit, up_limit, up_unit, display_order, is_active } = req.body;
+  const durationValue = parsePlanNumber(duration_seconds);
+  const priceValue = parsePlanNumber(price);
+
+  if (duration_seconds !== undefined && (durationValue === null || durationValue <= 0)) {
+    return res.status(400).json({ error: 'duration_seconds must be greater than 0' });
+  }
+  if (price !== undefined && (priceValue === null || priceValue < 0)) {
+    return res.status(400).json({ error: 'price cannot be negative' });
+  }
 
   try {
     const plan = await db.query(
@@ -229,7 +252,7 @@ router.put('/:id', async (req, res) => {
          is_active        = COALESCE(?, is_active)
        WHERE id = ?`,
       [
-        name ?? null, duration_seconds ?? null, price ?? null,
+        name ?? null, duration_seconds !== undefined ? parseInt(durationValue, 10) : null, price !== undefined ? priceValue : null,
         down_limit ?? null, down_unit ?? null,
         up_limit ?? null, up_unit ?? null,
         display_order !== undefined ? display_order : null,

src/routes/portal.routes.js

@@ -5,7 +5,8 @@ const db     = require('../config/db');
 const omada  = require('../services/omada');
 const snippe = require('../services/snippe');
 const sms    = require('../services/sms');
-const { generateCode } = require('../utils/generateCode');
+const messages = require('../utils/messages');
+const { createAccessTokenForPayment } = require('../utils/tokenSales');
 const { v4: uuidv4 } = require('uuid');
 const { purchaseLimiter, portalAuthLimiter } = require('../middleware/rateLimiter');
 const { alertAdmin } = require('../utils/adminAlert');
@@ -17,6 +18,27 @@ const { alertWifiClient } = require('../utils/tokenClientAlerts');
 const normalizeMac = mac => String(mac || '').toUpperCase().replace(/[:\-]/g, '');
 const normalizePortalMac = mac => String(mac || '').trim().toUpperCase().replace(/:/g, '-');
 
+function formatDuration(seconds) {
+  if (seconds >= 86400) {
+    const days = Math.round(seconds / 86400);
+    return `${days} day${days === 1 ? '' : 's'}`;
+  }
+  if (seconds >= 3600) {
+    const hours = Math.round(seconds / 3600);
+    return `${hours} hour${hours === 1 ? '' : 's'}`;
+  }
+  const mins = Math.round(seconds / 60);
+  return `${mins} min`;
+}
+
+function normalizePhoneForPromo(phone) {
+  const digits = String(phone || '').replace(/\D/g, '');
+  if (digits.length === 9) return `255${digits}`;
+  if (digits.length === 10 && digits.startsWith('0')) return `255${digits.slice(1)}`;
+  if (digits.length === 12 && digits.startsWith('255')) return digits;
+  return digits;
+}
+
 const omadaPortalErrorMap = {
   '-41501': 'Failed to authenticate.',
   '-41502': 'Voucher code is incorrect.',
@@ -190,13 +212,18 @@ async function recordOmadaVoucherUse({ siteId, code, mac }) {
     }
 
     if (token.locked_mac && token.locked_mac.toUpperCase() !== mac) {
-      console.warn('[portal/omada-auth-record] Omada accepted token for a different MAC; syncing DB lock to Omada result:', {
+      await conn.rollback();
+      console.warn('[portal/omada-auth-record] Omada accepted token for a different MAC; rejecting DB sync:', {
         siteId,
         code,
         tokenId: token.id,
-        previousMac: token.locked_mac,
+        lockedMac: token.locked_mac,
         acceptedMac: mac,
       });
+      const err = new Error('Code is locked to another device');
+      err.status = 403;
+      err.code = 'TOKEN_LOCKED_TO_ANOTHER_DEVICE';
+      throw err;
     }
 
     if (!expiresAt || expiresAt < now) {
@@ -601,6 +628,172 @@ router.post('/:siteId/purchase', purchaseLimiter, async (req, res) => {
 });
 
 // ── GET /portal/:siteId/check/:reference  — poll payment status ───────────────
+// POST /portal/:siteId/promo - claim a free promo voucher instantly
+router.post('/:siteId/promo', purchaseLimiter, async (req, res) => {
+  const { siteId } = req.params;
+  const { planId, phone, clientMac } = req.body;
+  const cleanPhone = normalizePhoneForPromo(phone);
+  const mac = normalizePortalMac(clientMac);
+
+  if (!planId || !cleanPhone || cleanPhone.length < 12 || !mac) {
+    return res.status(400).json({ error: 'planId, phone and clientMac required' });
+  }
+
+  const connection = await db.pool.getConnection();
+
+  try {
+    await connection.beginTransaction();
+
+    const [deviceRows] = await connection.execute(
+      `SELECT d.*, c.business_name, c.commission_rate
+       FROM devices d JOIN clients c ON c.id = d.client_id
+       WHERE d.omada_site_id = ? LIMIT 1`,
+      [siteId]
+    );
+    const device = deviceRows[0];
+
+    if (!device) {
+      await connection.rollback();
+      return res.status(404).json({ error: 'Device not found' });
+    }
+    if (!['trial', 'active'].includes(device.billing_status)) {
+      await connection.rollback();
+      return res.status(403).json({ error: 'WiFi service unavailable - billing suspended' });
+    }
+
+    const [planRows] = await connection.execute(
+      `SELECT *
+       FROM wifi_plans
+       WHERE id = ? AND device_id = ? AND is_active = 1 LIMIT 1
+       FOR UPDATE`,
+      [planId, device.id]
+    );
+    const plan = planRows[0];
+
+    if (!plan) {
+      await connection.rollback();
+      return res.status(404).json({ error: 'Promo is not available right now.' });
+    }
+    if (Number(plan.price) !== 0) {
+      await connection.rollback();
+      return res.status(400).json({ error: 'Selected plan is not a free promo.' });
+    }
+    if (!plan.omada_voucher_group_id) {
+      await connection.rollback();
+      return res.status(409).json({ error: 'Promo is not available yet. Please ask the attendant.' });
+    }
+
+    const [phoneClaimRows] = await connection.execute(
+      `SELECT p.id
+       FROM payments p
+       WHERE p.device_id = ?
+         AND p.plan_id = ?
+         AND p.phone = ?
+         AND p.status = 'completed'
+         AND p.gross_amount = 0
+       LIMIT 1`,
+      [device.id, plan.id, cleanPhone]
+    );
+    const [macClaimRows] = await connection.execute(
+      `SELECT t.id
+       FROM access_tokens t
+       JOIN payments p ON p.id = t.payment_id
+       WHERE t.device_id = ?
+         AND t.plan_id = ?
+         AND t.locked_mac = ?
+         AND p.status = 'completed'
+         AND p.gross_amount = 0
+       LIMIT 1`,
+      [device.id, plan.id, mac]
+    );
+
+    if (phoneClaimRows.length || macClaimRows.length) {
+      await connection.rollback();
+      return res.status(409).json({ error: 'This promo has already been claimed for this phone or device.' });
+    }
+
+    const [issuedRows] = await connection.execute(
+      `SELECT code, omada_voucher_id
+       FROM access_tokens
+       WHERE omada_voucher_group_id = ?`,
+      [plan.omada_voucher_group_id]
+    );
+    const voucher = await omada.issueVoucherFromGroup(device.omada_site_id, plan.omada_voucher_group_id, {
+      excludeCodes: issuedRows.map(row => row.code),
+      excludeVoucherIds: issuedRows.map(row => row.omada_voucher_id),
+    });
+
+    const reference = `PROMO-${uuidv4().replace(/-/g, '').slice(0, 18).toUpperCase()}`;
+    const [paymentResult] = await connection.execute(
+      `INSERT INTO payments
+         (reference, client_id, device_id, plan_id, phone, phone_provider,
+          payment_channel, provider_account_type, verification_source, counts_toward_balance,
+          confirmed_at, notes, gross_amount, snippe_fee, commission_rate,
+          commission_amount, client_credit, status, completed_at)
+       VALUES (?, ?, ?, ?, ?, 'other',
+               'tenant_direct_manual', 'platform', 'tenant_confirmed', 0,
+               NOW(), 'Captive portal free promo claim', 0.00, 0.00, ?,
+               0.00, 0.00, 'completed', NOW())`,
+      [
+        reference,
+        device.client_id,
+        device.id,
+        plan.id,
+        cleanPhone,
+        device.commission_rate,
+      ]
+    );
+
+    const { tokenId, code } = await createAccessTokenForPayment({
+      connection,
+      paymentId: paymentResult.insertId,
+      clientId: device.client_id,
+      deviceId: device.id,
+      planId: plan.id,
+      durationSeconds: plan.duration_seconds,
+      downLimit: plan.down_limit,
+      downUnit: plan.down_unit,
+      upLimit: plan.up_limit,
+      upUnit: plan.up_unit,
+      code: voucher.code,
+      omadaVoucherId: voucher.voucherId,
+      omadaVoucherGroupId: plan.omada_voucher_group_id,
+      requirePreferredCode: true,
+    });
+
+    await connection.execute(
+      `UPDATE access_tokens
+       SET locked_mac = ?
+       WHERE id = ?`,
+      [mac, tokenId]
+    );
+
+    await connection.commit();
+
+    const duration = formatDuration(plan.duration_seconds);
+    const smsSent = Boolean(await sms.sendSMS(
+      cleanPhone,
+      messages.promoWifiCode(code, plan.name, duration, device.name)
+    ).catch(() => false));
+
+    res.status(201).json({
+      reference,
+      token_id: tokenId,
+      code,
+      plan_name: plan.name,
+      duration_seconds: plan.duration_seconds,
+      sms_sent: smsSent,
+      message: smsSent ? 'Promo code sent successfully' : 'Promo code generated successfully',
+    });
+  } catch (err) {
+    await connection.rollback();
+    console.error('[portal/promo]', err.message);
+    res.status(500).json({ error: 'Could not issue promo code. Please ask the attendant.' });
+  } finally {
+    connection.release();
+  }
+});
+
 router.get('/:siteId/check/:reference', async (req, res) => {
   try {
     const payment = await db.query(
@@ -836,14 +1029,14 @@ router.post('/:siteId/auth', portalAuthLimiter, async (req, res) => {
       return res.status(410).json({ error: 'Code has expired' });
     }
 
+    if (token.locked_mac && token.locked_mac.toUpperCase() !== mac) {
+      trace.step('token_rejected_locked_mac', { lockedMac: token.locked_mac });
+      return res.status(403).json({ error: 'Code is locked to another device' });
+    }
+
     if (token.status === 'active') {
       trace.step('active_token_validation_start');
 
-      if (token.locked_mac && token.locked_mac.toUpperCase() !== mac) {
-        trace.step('token_rejected_locked_mac', { lockedMac: token.locked_mac });
-        return res.status(403).json({ error: 'Code is locked to another device' });
-      }
-
       if (token.expires_at && new Date(token.expires_at) < new Date()) {
         await db.query(`UPDATE access_tokens SET status = 'expired' WHERE id = ?`, [token.id]);
         trace.step('token_marked_expired');

src/utils/messages.js

@@ -12,6 +12,10 @@ module.exports = {
   manualWifiCode: (code, planName, duration, deviceName, expiryPreview) =>
     `WiFi Code: ${code}\nPlan: ${planName} (${duration})\nDevice: ${deviceName}\nValid for ${duration} after first connection. If used now, access ends around ${expiryPreview}.`,
 
+  // Guest receives this after claiming a free promo on the captive portal
+  promoWifiCode: (code, planName, duration, deviceName) =>
+    `Free WiFi promo code: ${code}\nPlan: ${planName} (${duration})\nDevice: ${deviceName}\nEnter this code on the WiFi login page. Valid for ${duration} after connecting.`,
+
   // Guest receives this when their WiFi token expires
   tokenExpired: (deviceName, planName = null) =>
     planName

src/views/screens/portal.ejs

@@ -777,6 +777,7 @@
 
       <!-- SCREEN 1: Plan selection & phone -->
       <div id="screen-select" class="screen active">
+        <% const hasPromoPlans = portal.plans.some(function(plan) { return Number(plan.price) === 0; }); %>
         <% if (portal.plans.length === 0) { %>
           <div class="empty-state">No plans available yet.<br>Check back soon.</div>
         <% } else { %>
@@ -786,16 +787,17 @@
               const hours = Math.floor(plan.duration_seconds / 3600);
               const days  = Math.floor(plan.duration_seconds / 86400);
               const dur   = days >= 1 ? days + (days === 1 ? ' Day' : ' Days') : hours + (hours === 1 ? ' Hr' : ' Hrs');
+              const isPromo = Number(plan.price) === 0;
             %>
               <div class="plan-item">
                 <input type="radio" name="plan" id="plan-<%= plan.id %>"
-                  data-plan-id="<%= plan.id %>" data-plan-price="<%= plan.price %>">
+                  data-plan-id="<%= plan.id %>" data-plan-price="<%= plan.price %>" data-plan-promo="<%= isPromo ? '1' : '0' %>">
                 <label class="plan-btn" for="plan-<%= plan.id %>">
                   <div class="plan-row">
                     <span class="plan-name"><%= plan.name %></span>
-                    <span class="plan-price"><%= parseInt(plan.price).toLocaleString() %> TZS</span>
+                    <span class="plan-price"><%= isPromo ? 'Free' : parseInt(plan.price).toLocaleString() + ' TZS' %></span>
                   </div>
-                  <div class="plan-meta"><%= dur %></div>
+                  <div class="plan-meta"><%= dur %><%= isPromo ? ' · Promo' : '' %></div>
                 </label>
               </div>
             <% }); %>
@@ -840,9 +842,9 @@
       <% } %>
 
       <div class="divider" <% if (!showOnlinePayment) { %>style="display:none;"<% } %>><span>Pay via Mobile Money</span></div>
-      <p class="payment-note" <% if (!showOnlinePayment) { %>style="display:none;"<% } %>>Prefer instant activation? Enter your own number below to pay online and receive an Omada voucher automatically.</p>
+      <p class="payment-note" <% if (!showOnlinePayment && !hasPromoPlans) { %>style="display:none;"<% } %>>Prefer instant activation? Enter your own number below to pay online or claim an available free promo.</p>
 
-      <div class="input-wrap" <% if (!showOnlinePayment) { %>style="display:none;"<% } %>>
+      <div class="input-wrap" <% if (!showOnlinePayment && !hasPromoPlans) { %>style="display:none;"<% } %>>
         <label class="field-label" for="phone-input">Phone Number</label>
         <div class="phone-group">
           <div class="phone-prefix">
@@ -856,7 +858,7 @@
       </div>
 
       <div class="error-msg" id="select-error"></div>
-      <button class="btn-primary" id="pay-btn" disabled <% if (!showOnlinePayment) { %>style="display:none;"<% } %>>Select a plan to continue</button>
+      <button class="btn-primary" id="pay-btn" disabled <% if (!showOnlinePayment && !hasPromoPlans) { %>style="display:none;"<% } %>>Select a plan to continue</button>
 
       <% if (!showOnlinePayment) { %>
         <div class="quick-access-note" style="margin-top:18px;">