proxmox/unifi-api/README.md

# UniFi API Library

TypeScript library for interacting with Ubiquiti UniFi/UDM Pro Controller REST API.

## Features

- Type-safe API client with full TypeScript support
- Dual API mode support:
  - **Official Local API** (v1 endpoints) - API key authentication
  - **Private Controller API** (proxy/network endpoints) - Cookie-based session authentication
- Support for all UniFi devices (APs, switches, gateways)
- Complete device, client, network, and system management
- Built-in CLI tool for common operations

## Installation

```bash
pnpm install
pnpm build
```

## Usage

### Basic Setup

#### Official API Mode (API Key)

```typescript
import { UnifiClient, ApiMode } from 'unifi-api';

const client = new UnifiClient({
  baseUrl: 'https://192.168.1.1',
  apiMode: ApiMode.OFFICIAL,
  apiKey: 'your-api-key',
  siteId: 'default', // Optional
  verifySSL: false, // Set to true for production
});
```

#### Private API Mode (Username/Password)

```typescript
import { UnifiClient, ApiMode } from 'unifi-api';

const client = new UnifiClient({
  baseUrl: 'https://192.168.1.1',
  apiMode: ApiMode.PRIVATE,
  username: 'admin',
  password: 'password',
  siteId: 'default', // Optional
  verifySSL: false, // Set to true for production
});
```

### Device Management

```typescript
import { DevicesService } from 'unifi-api';

const devicesService = new DevicesService(client);

// List all devices
const devices = await devicesService.listDevices();

// Get device by MAC address
const device = await devicesService.getDevice('aa:bb:cc:dd:ee:ff');

// Get device statistics
const stats = await devicesService.getDeviceStats();
```

### Client Management

```typescript
import { ClientsService } from 'unifi-api';

const clientsService = new ClientsService(client);

// List active clients
const clients = await clientsService.listClients();

// Get client by ID or MAC
const client = await clientsService.getClient('client-id-or-mac');

// Authorize guest access (Official API only)
await clientsService.authorizeGuest('client-id', {
  action: 'AUTHORIZE_GUEST_ACCESS',
  timeLimit: 3600,
  dataLimit: 1073741824, // 1GB in bytes
});
```

### Network Management

```typescript
import { NetworksService } from 'unifi-api';

const networksService = new NetworksService(client);

// List all networks
const networks = await networksService.listNetworks();

// Get network by ID
const network = await networksService.getNetwork('network-id');
```

### Site Management

```typescript
import { SitesService } from 'unifi-api';

const sitesService = new SitesService(client);

// List all sites (Private API only)
const sites = await sitesService.listSites();

// Get site statistics
const stats = await sitesService.getSiteStats();
```

### WLAN Management

```typescript
import { WlansService } from 'unifi-api';

const wlansService = new WlansService(client);

// List all WLANs
const wlans = await wlansService.listWlans();

// Get WLAN by ID
const wlan = await wlansService.getWlan('wlan-id');
```

### Events & Alarms

```typescript
import { EventsService } from 'unifi-api';

const eventsService = new EventsService(client);

// List events
const events = await eventsService.listEvents(100);

// List alarms
const alarms = await eventsService.listAlarms(false);
```

### System Operations

```typescript
import { SystemService } from 'unifi-api';

const systemService = new SystemService(client);

// Get system information
const info = await systemService.getSystemInfo();

// Get health status
const health = await systemService.getHealth();

// Reboot system (requires Super Admin)
// await systemService.reboot();
```

## CLI Tool

The library includes a CLI tool for common operations:

```bash
# Set environment variables in ~/.env
UNIFI_UDM_URL=https://192.168.1.1
UNIFI_API_MODE=private
UNIFI_USERNAME=admin
UNIFI_PASSWORD=password
UNIFI_SITE_ID=default

# List sites
unifi-cli sites

# List devices
unifi-cli devices

# Get device by MAC
unifi-cli device aa:bb:cc:dd:ee:ff

# List clients
unifi-cli clients

# Get client by ID
unifi-cli client client-id-or-mac

# List networks
unifi-cli networks

# UDM Pro config (Private API)
unifi-cli system-info     # Controller / self info
unifi-cli health          # Site health status
unifi-cli sysinfo         # System stats
unifi-cli firewall-rules  # Firewall rules
unifi-cli port-forward    # Port forwarding rules
unifi-cli config          # Dump full config summary (sysinfo, health, networks, firewall, port-forward)
```

## API Modes

### Official Local API (v1 endpoints)

- **Authentication**: API key (Bearer token)
- **Endpoints**: `/v1/sites/{siteId}/...`
- **Documentation**: Available in UniFi Network app (Settings → Control Plane → Integrations)
- **API Key**: Generate from Integrations page in UniFi Network app

### Private Controller API (proxy/network endpoints)

- **Authentication**: Cookie-based session (username/password)
- **Endpoints**: `/proxy/network/api/s/{site}/...`
- **Documentation**: Reverse-engineered, may vary between versions
- **Login**: `POST /api/auth/login` with username/password

## Notes

- UDM Pro uses `/proxy/network` prefix for all Network API paths
- Official API endpoints are version-specific
- Private API endpoints are reverse-engineered and may change between releases
- SSL verification is disabled by default (set `verifySSL: true` for production)

## License

MIT