2026-02-02 14:53:43 +00:00
|
|
|
# Project Readme Hints
|
|
|
|
|
|
feat(unifi): implement comprehensive UniFi API client with controllers, protect, access, account, managers, resources, HTTP client, interfaces, logging, plugins, and tests
2026-02-02 15:46:41 +00:00
|
|
|
## Architecture Overview
|
|
|
|
|
|
|
|
|
|
This package implements a comprehensive UniFi API client supporting four different UniFi applications:
|
|
|
|
|
|
|
|
|
|
### Entry Points
|
|
|
|
|
|
|
|
|
|
1. **UnifiAccount** - Site Manager (cloud) API
|
|
|
|
|
- Uses API key authentication via `X-API-Key` header
|
|
|
|
|
- Base URL: `https://api.ui.com/v1`
|
|
|
|
|
- Managers: SiteManager, HostManager
|
|
|
|
|
|
|
|
|
|
2. **UnifiController** - Network Controller API (local)
|
|
|
|
|
- Uses session cookie authentication
|
|
|
|
|
- Supports multiple controller types: `unifi-os`, `udm-pro`, `standalone`
|
|
|
|
|
- Managers: DeviceManager, ClientManager
|
|
|
|
|
|
|
|
|
|
3. **UnifiProtect** - Protect NVR API (local)
|
|
|
|
|
- Uses session cookie + CSRF token authentication
|
|
|
|
|
- Fetches bootstrap on login for camera/NVR info
|
|
|
|
|
- Manager: CameraManager
|
|
|
|
|
|
|
|
|
|
4. **UnifiAccess** - Access Controller API (local)
|
|
|
|
|
- Uses bearer token authentication
|
|
|
|
|
- Default port: 12445
|
|
|
|
|
- Manager: DoorManager
|
|
|
|
|
|
|
|
|
|
### Key Files
|
|
|
|
|
|
|
|
|
|
- `ts/classes.unifihttp.ts` - Base HTTP client with SSL handling
|
|
|
|
|
- `ts/interfaces/*.ts` - All TypeScript interfaces
|
|
|
|
|
- `ts/unifi.logger.ts` - Logging utility
|
|
|
|
|
|
|
|
|
|
### Authentication Notes
|
|
|
|
|
|
|
|
|
|
- **UniFi OS consoles** (UDM, UDM Pro, Cloud Key Gen2+) authenticate at console level (`/api/auth/login`) then access Network API via `/proxy/network`
|
|
|
|
|
- **Standalone controllers** authenticate directly at `/api/login`
|
|
|
|
|
- **Protect API** is behind `/proxy/protect/api`
|
|
|
|
|
- **Access API** uses port 12445 with bearer token
|
|
|
|
|
|
|
|
|
|
### SSL/TLS
|
|
|
|
|
|
|
|
|
|
All local APIs default to `verifySsl: false` to support self-signed certificates common on UniFi devices.
|
|
|
|
|
|
|
|
|
|
### Testing Environment Variables
|
|
|
|
|
|
|
|
|
|
Required in `.nogit/env.json`:
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"UNIFI_CONSOLE_IP": "192.168.x.x",
|
|
|
|
|
"UNIFI_NETWORK_DEV_KEY": "xxx",
|
|
|
|
|
"UNIFI_PROTECT_DEV_KEY": "xxx"
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Test Files
|
|
|
|
|
|
|
|
|
|
- `test/test.ts` - Unit tests (no credentials needed)
|
|
|
|
|
- `test/test.network.ts` - Network Controller integration tests
|
|
|
|
|
- `test/test.protect.ts` - Protect API integration tests (defensive - handles missing NVR/camera data gracefully)
|
|
|
|
|
|
|
|
|
|
### API Notes
|
|
|
|
|
|
|
|
|
|
- **Network API** works perfectly with local console API keys
|
|
|
|
|
- **Protect API** bootstrap structure may vary - NVR info may not be available with API key auth
|
|
|
|
|
- **Events endpoint** may return array or `{data: [...]}` format - CameraManager handles both
|
|
|
|
|
- **Site Manager cloud API** (`api.ui.com`) requires different keys (from ui.com portal), not local console keys
|
|
|
|
|
|
|
|
|
|
### Documentation Sources
|
|
|
|
|
|
|
|
|
|
- Local docs in `.nogit/docs/` contain OpenAPI specs from console
|
|
|
|
|
- Network API: `/unifi-api/network` on console
|
|
|
|
|
- Protect API: `/unifi-api/protect` on console
|
