Initial: Splynx API integration, portal architecture, inventory snapshot

2026-07-25 15:16:08 -04:00
commit 1f3d55d89f
2 changed files with 161 additions and 0 deletions
@@ -0,0 +1,114 @@
+# Forefront Wireless Customer Portal
+
+> **Status:** Scoped & Documented — awaiting build
+> **Started:** July 25, 2026
+> **Domain:** my.forefrontwireless.com
+> **Companion project:** IntelSight (shared auth — same Super Search/deepseek infra)
+
+Self-service customer portal for Forefront Wireless, a WISP operating in Texas. Replaces or augments the existing Splynx customer portal with a modern, branded experience that directly consumes the Splynx API.
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌────────────────────────┐
+│  my.forefront    │────▶│  FastAPI backend  │────▶│  Splynx API v2.0       │
+│  wireless.com    │     │  (api subdomain)  │     │  portal.forefront...   │
+│  (React SPA)     │     │  Flask or FastAPI │     │  /api/2.0/             │
+└─────────────────┘     └──────────────────┘     └────────────────────────┘
+                                                        │
+                                              ┌─────────▼──────────┐
+                                              │  Splynx self-hosted │
+                                              │  v4.2               │
+                                              │  Forefront Wireless │
+                                              └────────────────────┘
+```
+
+**Stack:** React SPA → FastAPI → Splynx API v2.0  
+**Auth:** Signature-based HMAC-SHA256 (nonce + key, secret-driven)  
+**API Key:** `5a8dc490716424f435306f2c18b4fdcb` (full permissions)  
+**Hosting:** CloudPanel on app3 (same as other ITPP portals)
+
+---
+
+## Splynx API — Proven Endpoints
+
+### Authentication
+```
+POST /api/2.0/admin/auth/tokens
+Body: {"auth_type":"api_key","key":"...","nonce":<timestamp>,"signature":"..."}
+→ Returns access_token (30-min expiry) + refresh_token
+
+OR: Direct signature header (preferred for server-to-server)
+Authorization: Splynx-EA (key=K&nonce=N&signature=S)
+Nonce: round(microtime * 100) — hundredths of a second
+Signature: strtoupper(hash_hmac('sha256', nonce . key, secret))
+```
+
+### Working Endpoints
+
+| Method | Path | Description | Status |
+|--------|------|-------------|:---:|
+| GET | `/admin/customers/customer` | List all customers (43 total, 33 active) | ✓ |
+| GET | `/admin/customers/customer/{id}` | Single customer detail | ✓ |
+| GET | `/admin/customers/customer-internet-services/{customer_id}` | Services for customer | ✓ |
+| POST | `/admin/customers/customer-internet-services` | List with filters (needs `customer_id` in body) | ⚠ 405 on GET |
+| GET | `/admin/networking/routers` | All routers (5 CCR2004s) | ✓ |
+| GET | `/admin/tariffs/internet` | Internet plans (9 plans, $59.95–$299.95) | ✓ |
+| GET | `/admin/finance/invoices` | Invoice list | ✓ |
+| GET | `/admin/finance/payments` | Payment records | ⚠ untested |
+| GET | `/admin/finance/transactions` | Transaction history | ⚠ untested |
+| GET | `/admin/support/tickets` | Support tickets | ⚠ untested |
+
+### Inventory Snapshot (July 2026)
+
+| Resource | Count |
+|----------|:---:|
+| Total customers | 43 |
+| Active subscribers | 33 |
+| Disabled accounts | 9 |
+| Routers | 5 × MikroTik CCR2004 |
+| Internet tariffs | 9 plans |
+
+---
+
+## Portal Feature Ladder
+
+### V1 — Core Self-Service
+- [ ] Customer login (email + password, or magic link)
+- [ ] Dashboard: active services, current bill, data usage
+- [ ] View & pay invoices (Stripe integration)
+- [ ] Update contact info, phone, email
+- [ ] Change WiFi password (via MikroTik API → router)
+
+### V2 — Enhanced
+- [ ] Service upgrade/downgrade with proration
+- [ ] Support ticket submission & tracking
+- [ ] Outage notifications (SMS opt-in)
+- [ ] Referral program
+
+### V3 — Operational
+- [ ] Usage graphs (daily/weekly/monthly bandwidth)
+- [ ] Auto-pay setup
+- [ ] Seasonal hold / vacation pause
+- [ ] Equipment return workflow
+- [ ] Speed test integration
+
+---
+
+## Splynx Quirks (Lessons Learned)
+
+1. **Signature auth is required** — Basic auth returns 401 unless "Unsecure access" is enabled on the key. Signature uses HMAC-SHA256 with a microtime nonce.
+2. **Services need customer_id in URL** — `GET /admin/customers/customer-internet-services/{id}` works, but `GET /admin/customers/customer-internet-services?customer_id=2` returns 405.
+3. **Tariff names may need separate resolution** — The list endpoint may return tariff IDs only; names require a follow-up call to `/admin/tariffs/internet/{id}`.
+4. **Data shown is filtered** — Only what the API key has permission for. Current key has full permissions.
+
+---
+
+## Related
+
+- **Splynx v2 docs:** https://api-doc.splynx.com/
+- **Splynx v4.2 wiki:** https://wiki.splynx.com/4_2/
+- **Admin panel:** https://portal.forefrontwireless.com/admin/
+- **Git:** https://git.itpropartner.com/ippadmin/forefront-wireless-portal