proxmox/site-manager-api/README.md

# Site Manager API Library

TypeScript library for interacting with Ubiquiti UniFi Site Manager Cloud API.

## Features

- Type-safe API client with full TypeScript support
- Cloud-based API for managing multiple UniFi deployments at scale
- Support for hosts, sites, devices, ISP metrics, and SD-WAN configurations
- Built-in CLI tool for common operations
- Rate limiting handling with automatic retry-after support
- Comprehensive error handling

## Installation

```bash
pnpm install
pnpm build
```

## Usage

### Basic Setup

```typescript
import { SiteManagerClient } from 'site-manager-api';

const client = new SiteManagerClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.ui.com/v1', // Optional, defaults to this
});
```

### Getting an API Key

1. Sign in to the UniFi Site Manager at [unifi.ui.com](https://unifi.ui.com)
2. Navigate to the API section from the left navigation bar
3. Select "Create API Key"
4. Copy the generated key and store it securely (shown only once)

### Host Management

```typescript
import { HostsService } from 'site-manager-api';

const hostsService = new HostsService(client);

// List all hosts
const hosts = await hostsService.listHosts();
```

### Site Management

```typescript
import { SitesService } from 'site-manager-api';

const sitesService = new SitesService(client);

// List all sites
const sites = await sitesService.listSites();
```

### Device Management

```typescript
import { DevicesService } from 'site-manager-api';

const devicesService = new DevicesService(client);

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

### Metrics and SD-WAN

```typescript
import { MetricsService } from 'site-manager-api';

const metricsService = new MetricsService(client);

// Get ISP metrics
const metrics = await metricsService.getISPMetrics();

// Query ISP metrics with filters
const queriedMetrics = await metricsService.queryISPMetrics({ /* filters */ });

// List SD-WAN configurations
const sdwanConfigs = await metricsService.listSDWANConfigs();

// Get SD-WAN config by ID
const config = await metricsService.getSDWANConfig('config-id');

// Get SD-WAN config status
const status = await metricsService.getSDWANConfigStatus('config-id');
```

## CLI Tool

The library includes a CLI tool for common operations:

```bash
# Set environment variable
export SITE_MANAGER_API_KEY=your-api-key

# List hosts
site-manager-cli hosts

# List sites
site-manager-cli sites

# List devices
site-manager-cli devices

# Get ISP metrics
site-manager-cli isp-metrics

# List SD-WAN configurations
site-manager-cli sd-wan-configs
```

Or using pnpm:

```bash
pnpm site-manager:cli hosts
pnpm site-manager:cli sites
pnpm site-manager:cli devices
```

## Environment Variables

Create a `~/.env` file with:

```bash
SITE_MANAGER_API_KEY=your-api-key-here
SITE_MANAGER_BASE_URL=https://api.ui.com/v1  # Optional
```

## Error Handling

The library provides specific error classes:

```typescript
import {
  SiteManagerApiError,
  SiteManagerAuthenticationError,
  SiteManagerNetworkError,
  SiteManagerRateLimitError,
} from 'site-manager-api';

try {
  const sites = await sitesService.listSites();
} catch (error) {
  if (error instanceof SiteManagerRateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof SiteManagerAuthenticationError) {
    console.error('Authentication failed - check your API key');
  } else if (error instanceof SiteManagerNetworkError) {
    console.error('Network error:', error.cause);
  } else {
    console.error('API error:', error);
  }
}
```

## Rate Limiting

The Site Manager API has rate limits:
- **Early Access (EA) version**: 100 requests per minute
- **v1 stable release**: 10,000 requests per minute

If you exceed these limits, the library will throw a `SiteManagerRateLimitError` with a `retryAfter` property indicating when you can retry.

## API Status

The Site Manager API is currently **read-only**. Write endpoints are planned for future versions.

## Documentation

- [Official Documentation](https://developer.ui.com/site-manager-api/gettingstarted)
- [API Reference](https://developer.ui.com/site-manager-api)

## License

MIT