unifi/readme.hints.md

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:

{
  "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