Add UI agent briefing with params and code snippets for all endpoints

UI_AGENT_BRIEFING.md

@@ -0,0 +1,673 @@
+# UI Agent Briefing — WiFi Platform Frontend
+
+> Read `API_DOCUMENTATION.md` and `FRONTEND_DESIGN_SYSTEM.md` in full before writing any code.  
+> This document is a focused briefing of what to build, with params and code snippets for every feature.
+
+---
+
+## Stack Assumptions
+
+- Framework: React (or Vue/Svelte — adapt snippets accordingly)
+- HTTP: `fetch` or `axios`
+- Icons: Lucide only (`lucide-react` / `lucide-vue`)
+- No emojis anywhere — ever
+- All auth requests send `Authorization: Bearer <token>` header
+
+```js
+// api/client.js — base helper used in all snippets below
+const BASE = import.meta.env.VITE_API_URL || '';
+
+export async function api(path, options = {}) {
+  const token = localStorage.getItem('token');
+  const res = await fetch(`${BASE}${path}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      ...options.headers,
+    },
+  });
+  const data = await res.json();
+  if (!res.ok) throw Object.assign(new Error(data.error || 'Request failed'), { status: res.status });
+  return data;
+}
+```
+
+---
+
+## 1. Authentication
+
+### POST `/api/auth/register`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `business_name` | string | yes |
+| `contact_name` | string | yes |
+| `email` | string | yes |
+| `phone` | string | yes |
+| `password` | string min 8 | yes |
+
+```js
+const { token, client } = await api('/api/auth/register', {
+  method: 'POST',
+  body: JSON.stringify({ business_name, contact_name, email, phone, password }),
+});
+localStorage.setItem('token', token);
+```
+
+---
+
+### POST `/api/auth/login`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `email` | string | yes |
+| `password` | string | yes |
+
+```js
+const { token, client } = await api('/api/auth/login', {
+  method: 'POST',
+  body: JSON.stringify({ email, password }),
+});
+localStorage.setItem('token', token);
+```
+
+---
+
+### POST `/api/auth/forgot-password`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `phone` | string | yes |
+
+```js
+await api('/api/auth/forgot-password', {
+  method: 'POST',
+  body: JSON.stringify({ phone }),
+});
+// Always returns 200 — don't reveal whether phone is registered
+```
+
+---
+
+### POST `/api/auth/reset-password`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `phone` | string | yes |
+| `otp` | string 6-digit | yes |
+| `new_password` | string min 8 | yes |
+
+```js
+await api('/api/auth/reset-password', {
+  method: 'POST',
+  body: JSON.stringify({ phone, otp, new_password }),
+});
+```
+
+---
+
+### GET `/api/auth/me`
+
+No params. Returns the authenticated tenant's full profile. Use this to seed the sidebar business name and profile page.
+
+```js
+const client = await api('/api/auth/me');
+// { id, business_name, contact_name, email, phone,
+//   balance, total_earned, total_withdrawn, created_at }
+```
+
+---
+
+### PATCH `/api/auth/profile`
+
+Send only the fields you want to change.
+
+**Params (body — all optional, send at least one):**
+| Field | Type |
+|---|---|
+| `contact_name` | string |
+| `business_name` | string |
+| `email` | string |
+
+```js
+const updated = await api('/api/auth/profile', {
+  method: 'PATCH',
+  body: JSON.stringify({ contact_name, business_name, email }),
+});
+// Returns updated client object (same shape as /me)
+```
+
+---
+
+### POST `/api/auth/change-password`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `current_password` | string | yes |
+| `new_password` | string min 8 | yes |
+
+```js
+await api('/api/auth/change-password', {
+  method: 'POST',
+  body: JSON.stringify({ current_password, new_password }),
+});
+// 401 if current_password is wrong
+```
+
+---
+
+### POST `/api/auth/phone/request`
+
+Sends OTP to the new phone number. Rate limited — 3 requests per 30 min.
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `new_phone` | string | yes |
+
+```js
+await api('/api/auth/phone/request', {
+  method: 'POST',
+  body: JSON.stringify({ new_phone }),
+});
+// Show OTP input after this succeeds
+```
+
+---
+
+### POST `/api/auth/phone/confirm`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `new_phone` | string | yes |
+| `otp` | string 6-digit | yes |
+
+```js
+await api('/api/auth/phone/confirm', {
+  method: 'POST',
+  body: JSON.stringify({ new_phone, otp }),
+});
+// On success, refresh /me to show updated phone
+```
+
+---
+
+## 2. Devices
+
+### GET `/api/devices`
+
+No params. Returns array of tenant's devices.
+
+```js
+const devices = await api('/api/devices');
+// [{ id, name, location, mac, model, ip, status, billing_status,
+//    billing_expires_at, monthly_fee, guest_count, last_seen_at, ... }]
+```
+
+Show a warning chip on rows where `billing_expires_at` is within 3 days.
+
+---
+
+### POST `/api/devices`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `name` | string | yes |
+| `mac` | string AA-BB-CC-DD-EE-FF | yes |
+| `location` | string | no |
+| `device_username` | string | no |
+| `device_password` | string | no |
+
+```js
+const { device, message } = await api('/api/devices', {
+  method: 'POST',
+  body: JSON.stringify({ name, mac, location, device_username, device_password }),
+});
+```
+
+---
+
+### GET `/api/devices/:id`
+
+```js
+const device = await api(`/api/devices/${id}`);
+// Includes active_sessions array, sales_today, earned_today
+```
+
+---
+
+### DELETE `/api/devices/:id`
+
+Pauses the device (reversible). Show confirmation modal: "This will kick all connected guests and suspend WiFi."
+
+```js
+await api(`/api/devices/${id}`, { method: 'DELETE' });
+```
+
+---
+
+### POST `/api/devices/:id/renew`
+
+Initiates M-Pesa renewal payment to tenant's phone.
+
+```js
+const { reference, amount } = await api(`/api/devices/${id}/renew`, { method: 'POST' });
+// Show: "Check your phone for M-Pesa prompt"
+// Poll GET /api/devices/:id until billing_status = 'active'
+```
+
+---
+
+### GET `/api/devices/:id/portal`
+
+```js
+const settings = await api(`/api/devices/${id}/portal`);
+// { device_id, display_name, welcome_text, logo_url,
+//   support_phone, primary_color, bg_color }
+```
+
+---
+
+### PATCH `/api/devices/:id/portal`
+
+All fields optional — send only what changed.
+
+**Params (body):**
+| Field | Type | Validation |
+|---|---|---|
+| `display_name` | string | — |
+| `welcome_text` | string | — |
+| `logo_url` | string | — |
+| `support_phone` | string | — |
+| `primary_color` | string | must be `#RRGGBB` |
+| `bg_color` | string | must be `#RRGGBB` |
+
+```js
+const updated = await api(`/api/devices/${id}/portal`, {
+  method: 'PATCH',
+  body: JSON.stringify({ display_name, welcome_text, logo_url, support_phone, primary_color, bg_color }),
+});
+```
+
+Show a live preview panel next to this form. Render a scaled-down version of the portal card using the form values as CSS variables `--primary` and `--bg`.
+
+---
+
+## 3. WiFi Plans
+
+### GET `/api/plans?deviceId=:id`
+
+**Params (query):**
+| Param | Required |
+|---|---|
+| `deviceId` | yes |
+
+```js
+const plans = await api(`/api/plans?deviceId=${deviceId}`);
+// [{ id, name, duration_seconds, price, down_limit, down_unit,
+//    up_limit, up_unit, is_active, display_order }]
+```
+
+---
+
+### POST `/api/plans`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `device_id` | number | yes |
+| `name` | string | yes |
+| `duration_seconds` | number | yes |
+| `price` | number TZS | yes |
+| `down_limit` | number | yes |
+| `down_unit` | 1=Kbps / 2=Mbps | yes |
+| `up_limit` | number | yes |
+| `up_unit` | 1=Kbps / 2=Mbps | yes |
+| `display_order` | number | no |
+
+```js
+const plan = await api('/api/plans', {
+  method: 'POST',
+  body: JSON.stringify({ device_id, name, duration_seconds, price,
+                         down_limit, down_unit, up_limit, up_unit, display_order }),
+});
+```
+
+Show a duration field with a unit selector (minutes / hours / days) and convert to `duration_seconds` before submitting:
+```js
+const duration_seconds = value * { minutes: 60, hours: 3600, days: 86400 }[unit];
+```
+
+---
+
+### PUT `/api/plans/:id`
+
+Same body as POST, all fields optional.
+
+```js
+await api(`/api/plans/${id}`, {
+  method: 'PUT',
+  body: JSON.stringify({ name, price, is_active }),
+});
+```
+
+---
+
+### DELETE `/api/plans/:id`
+
+```js
+await api(`/api/plans/${id}`, { method: 'DELETE' });
+```
+
+---
+
+## 4. Dashboard
+
+### GET `/api/dashboard/summary`
+
+```js
+const summary = await api('/api/dashboard/summary');
+// { device_count, active_sessions, revenue_today,
+//   revenue_month, balance, alert_count }
+```
+
+Show alert warning banner if `alert_count > 0`.
+
+---
+
+### GET `/api/dashboard/revenue/weekly`
+
+```js
+const weekly = await api('/api/dashboard/revenue/weekly');
+// [{ day: 'Mon', revenue: 45000 }, ...]
+```
+
+Feed into a bar chart. X-axis = day label, Y-axis = TZS (format with `.toLocaleString()`). Fill missing days with 0.
+
+---
+
+## 5. Sessions
+
+### GET `/api/sessions`
+
+**Params (query — all optional):**
+| Param | Type | Description |
+|---|---|---|
+| `deviceId` | number | Filter by device |
+| `active` | boolean | `true` for active only |
+| `page` | number | Pagination |
+| `limit` | number | Default 50 |
+
+```js
+const sessions = await api(`/api/sessions?deviceId=${id}&active=true`);
+// [{ id, client_mac, started_at, ended_at, bytes_down, bytes_up,
+//    is_active, plan_name, expires_at }]
+```
+
+Format bytes:
+```js
+function formatBytes(bytes) {
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  if (bytes < 1024 ** 3) return (bytes / 1024 ** 2).toFixed(1) + ' MB';
+  return (bytes / 1024 ** 3).toFixed(2) + ' GB';
+}
+```
+
+---
+
+## 6. Payouts
+
+### GET `/api/payouts`
+
+```js
+const payouts = await api('/api/payouts');
+// [{ id, amount, payout_fee, net_amount, status,
+//    destination_phone, created_at, completed_at }]
+```
+
+---
+
+### POST `/api/payouts`
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `amount` | number TZS | yes |
+
+```js
+const payout = await api('/api/payouts', {
+  method: 'POST',
+  body: JSON.stringify({ amount }),
+});
+```
+
+Show `net_amount` preview before confirming:
+```js
+const SNIPPE_FEE_RATE = 0.005;
+const net = amount * (1 - SNIPPE_FEE_RATE);
+// "You will receive X TZS after fees"
+```
+
+Disable submit if `balance === 0`.
+
+---
+
+## 7. Alerts
+
+### GET `/api/alerts/unresolved`
+
+```js
+const alerts = await api('/api/alerts/unresolved');
+// [{ id, severity, message, device_name, created_at }]
+```
+
+`severity` values: `info`, `warning`, `critical` — map to `--color-info`, `--color-warning`, `--color-error`.
+
+---
+
+### PATCH `/api/alerts/:id/resolve`
+
+```js
+await api(`/api/alerts/${id}/resolve`, { method: 'PATCH' });
+// Remove row with fade-out animation
+```
+
+---
+
+## 8. Super Admin
+
+All admin endpoints require `Authorization: Bearer <ADMIN_TOKEN>` (static token, not a JWT).
+
+```js
+function adminApi(path, options = {}) {
+  return api(path, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${import.meta.env.VITE_ADMIN_TOKEN}`,
+      ...options.headers,
+    },
+  });
+}
+```
+
+---
+
+### GET `/api/admin/overview`
+
+```js
+const stats = await adminApi('/api/admin/overview');
+// { tenants, devices_online, devices_offline, devices_suspended,
+//   guests_online, sales_today, gross_today, commission_today,
+//   pending_payouts, pending_payout_total }
+```
+
+---
+
+### GET `/api/admin/tenants`
+
+```js
+const tenants = await adminApi('/api/admin/tenants');
+// [{ id, business_name, contact_name, phone, balance,
+//    device_count, devices_online, created_at }]
+```
+
+---
+
+### GET `/api/admin/devices`
+
+```js
+const devices = await adminApi('/api/admin/devices');
+// [{ id, name, location, status, billing_status,
+//    billing_expires_at, monthly_fee, business_name, client_phone }]
+```
+
+---
+
+### POST `/api/admin/devices/:id/activate`
+
+Cash payment activation. Opens a "Record Cash Payment" modal with device name, tenant name, fee amount, and an optional note field.
+
+**Params (body):**
+| Field | Type | Required |
+|---|---|---|
+| `note` | string | no |
+
+```js
+const result = await adminApi(`/api/admin/devices/${id}/activate`, {
+  method: 'POST',
+  body: JSON.stringify({ note }),
+});
+// { message, billing_expires_at }
+// On success: toast "Device activated — tenant notified by SMS"
+// Update row billing_status to 'active' optimistically
+```
+
+---
+
+### POST `/api/admin/devices/:id/reboot`
+
+```js
+await adminApi(`/api/admin/devices/${id}/reboot`, { method: 'POST' });
+```
+
+---
+
+### GET `/api/admin/payouts/pending`
+
+```js
+const payouts = await adminApi('/api/admin/payouts/pending');
+// [{ id, amount, net_amount, destination_phone,
+//    business_name, contact_name, created_at }]
+```
+
+---
+
+### POST `/api/admin/payouts/:id/approve`
+
+```js
+await adminApi(`/api/admin/payouts/${id}/approve`, { method: 'POST' });
+```
+
+---
+
+### POST `/api/admin/payouts/:id/reject`
+
+```js
+await adminApi(`/api/admin/payouts/${id}/reject`, { method: 'POST' });
+```
+
+---
+
+### GET `/api/admin/revenue/daily`
+
+**Params (query):**
+| Param | Type | Default |
+|---|---|---|
+| `days` | number | 30 |
+
+```js
+const revenue = await adminApi('/api/admin/revenue/daily?days=30');
+// [{ day: '2026-04-15', sales: 12, gross: 180000, commission: 9000 }]
+```
+
+Render as a line chart. Days selector: 7 / 14 / 30 / 90.
+
+---
+
+## 9. Shared UX Patterns
+
+### Status badge mapping
+
+```js
+const STATUS_BADGE = {
+  active:    { bg: 'var(--color-success-bg)', text: 'var(--color-success)' },
+  online:    { bg: 'var(--color-success-bg)', text: 'var(--color-success)' },
+  trial:     { bg: 'var(--color-info-bg)',    text: 'var(--color-info)' },
+  suspended: { bg: 'var(--color-warning-bg)', text: 'var(--color-warning)' },
+  offline:   { bg: 'var(--color-bg)',         text: 'var(--color-text-disabled)' },
+  pending:   { bg: 'var(--color-warning-bg)', text: 'var(--color-warning)' },
+  failed:    { bg: 'var(--color-error-bg)',   text: 'var(--color-error)' },
+  completed: { bg: 'var(--color-success-bg)', text: 'var(--color-success)' },
+};
+```
+
+### Duration formatting
+
+```js
+function formatDuration(seconds) {
+  if (seconds >= 86400) {
+    const d = Math.floor(seconds / 86400);
+    return `${d} Day${d !== 1 ? 's' : ''}`;
+  }
+  const h = Math.floor(seconds / 3600);
+  return `${h} Hour${h !== 1 ? 's' : ''}`;
+}
+```
+
+### Speed formatting
+
+```js
+function formatSpeed(limit, unit) {
+  return `${limit}${unit === 2 ? 'Mbps' : 'Kbps'}`;
+}
+```
+
+### Currency formatting
+
+```js
+function formatTZS(amount) {
+  return `${parseInt(amount).toLocaleString()} TZS`;
+}
+```
+
+### Time remaining
+
+```js
+function formatTimeLeft(expiresAt) {
+  const secs = Math.floor((new Date(expiresAt) - Date.now()) / 1000);
+  if (secs <= 0) return 'Expired';
+  if (secs < 3600) return `${Math.ceil(secs / 60)}min`;
+  if (secs < 86400) return `${Math.ceil(secs / 3600)}h`;
+  return `${Math.ceil(secs / 86400)}d`;
+}
+```
+
+### Error handling
+
+```js
+try {
+  await someApiCall();
+} catch (err) {
+  if (err.status === 401) { /* redirect to login */ }
+  if (err.status === 409) { /* show field-level error */ }
+  showToast('error', err.message);
+}
+```