# ShopDesk Admin Dashboard API Reference

## Dashboard overview

Cross-cutting KPIs (orders, revenue, customers, stock, commission, etc.), admin wallets, and distance from the configured store location (miles, km, meters).

---

## Wallet, adjust & geo APIs

### Wallet (admin ledger)

#### Self wallet balance
- `GET /api/admin/wallet/me`
- Auth: `Authorization: Bearer <token>`
- Notes: requires an **admin staff session**; if the admin wallet is not available, you get `403`.

#### Wallet transactions (ledger)
- `GET /api/admin/wallet/me/transactions`
- Access: any signed-in admin can view their own ledger
- Query: `limit` (optional; server enforces sensible caps)
- `GET /api/admin/wallet/:userId/transactions`
- Auth: `Authorization: Bearer <token>`
- Access:
  - `:userId = <staffId>` → requires `wallet.read` permission, or **Super Admin**
- Query: `limit` (optional; server enforces sensible caps)

#### View another admin wallet balance (summary)
- `GET /api/admin/wallet/:userId`
- Auth: `Authorization: Bearer <token>`
- Access: self or `wallet.read` / Super Admin (same permission logic as the ledger routes)

### Adjust (write)

#### Adjust admin wallet balance (creates a ledger row)
- `POST /api/admin/wallet/adjust`
- Auth: `Authorization: Bearer <token>`
- RBAC: **Super Admin only**
- JSON body:
  - `userId` (or `targetUserId`) — required, numeric admin staff id
  - `amountUSD` — required, non-zero number (positive or negative depending on your policy)
  - `note` — optional string

### Geo (store location + distance)

#### Public store origin
- `GET /api/geo/store`
- No auth
- Storage-backed by: `data/store-geo.json`

#### Store origin (admin full management)
- `GET /api/admin/store-geo`
  - Auth required
  - RBAC: `platform.read`
- `PUT /api/admin/store-geo`
  - Auth required
  - RBAC: **Super Admin only**
  - Persists to: `data/store-geo.json`

#### Distance
- `GET /api/geo/distance?lat=&lng=`
  - No auth
- `POST /api/geo/distance`
  - No auth
  - JSON body: `{ lat, lng }` (or `latitude`, `longitude`)

---

## Storage & files (geo)

- Persist file: `data/store-geo.json`
- Public read: `GET /api/geo/store`
- Save: `PUT /api/admin/store-geo` (Super Admin)