From 1f3d55d89f3b223bcbeb4417defc114474c83306 Mon Sep 17 00:00:00 2001 From: root Date: Sat, 25 Jul 2026 15:16:08 -0400 Subject: [PATCH] Initial: Splynx API integration, portal architecture, inventory snapshot --- CHANGELOG.md | 47 +++++++++++++++++++++ README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 161 insertions(+) create mode 100644 CHANGELOG.md create mode 100644 README.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b48118c --- /dev/null +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..2f40e47 --- /dev/null +++ b/README.md @@ -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":,"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