# Project Readme Hints

## 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