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,47 @@
+# CHANGELOG — Forefront Wireless Customer Portal
+
+---
+
+## 2026-07-25 — Project Inception & API Connection
+
+**Context:** Germaine shared Splynx API credentials for Forefront Wireless, his WISP company. The self-hosted Splynx instance (v4.2) runs at `portal.forefrontwireless.com/admin/`. The goal is to build a branded customer portal at `my.forefrontwireless.com`.
+
+### Completed
+
+- **API connection established** — Splynx API v2.0 at `/api/2.0/` verified working
+- **Authentication cracked** — Signature-based auth (HMAC-SHA256) with microtime nonce. Three methods tested:
+  - ✅ Signature: `Splynx-EA (key=K&nonce=N&signature=S)` — works
+  - ✅ Access Token: POST `/admin/auth/tokens` — generates token with 30-min expiry
+  - ⚠️ Basic Auth: returns 403 unless "Unsecure access" is enabled on the API key
+- **API key configured** — Full permissions on all resources (customers, services, finance, networking, support, tariffs, scheduling, inventory)
+- **Endpoint reconnaissance** — Verified working:
+  - `GET /admin/customers/customer` — 43 customers (33 active, 9 disabled)
+  - `GET /admin/customers/customer-internet-services/{id}` — per-customer services
+  - `GET /admin/networking/routers` — 5 MikroTik CCR2004 routers
+  - `GET /admin/tariffs/internet` — 9 plans ($59.95-$299.95/mo)
+  - `GET /admin/finance/invoices` — billing records
+- **Splynx quirks documented** — 405 on query-param service endpoints, tariff name resolution, signature nonce format
+
+### Decisions
+
+- **Stack:** React SPA → FastAPI backend → Splynx API v2.0. Same pattern as IntelSight and VoIPSimplicity.
+- **Hosting:** CloudPanel on app3 (152.53.241.111) — keeps customer portals together
+- **Auth pattern:** Server-to-server signature auth (not per-user Access Tokens) — portal handles its own user auth, backend proxies to Splynx
+- **Domain:** my.forefrontwireless.com (follows ITPP product convention: my.*.com)
+- **Building after:** IntelSight + LaunchCheck (shared infrastructure, shared auth patterns, reusable Super Search engine)
+
+### Reference: API Credentials
+
+```
+Key:    5a8dc490716424f435306f2c18b4fdcb
+Secret: 5773f779e5ae5aac965845a66bd857a0
+Base:   https://portal.forefrontwireless.com/api/2.0/
+```
+
+### Next Steps (When Ready)
+
+1. Register `my.forefrontwireless.com` DNS
+2. Build FastAPI backend with Splynx proxy layer
+3. Build React dashboard
+4. Stripe integration for payments
+5. Deploy on app3 via CloudPanel
@@ -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