@panoptic-it-solutions/unifi-api-client/README.md

A Node.js client library for the UniFi Controller API

# @panoptic-it-solutions/unifi-api-client

A modern, fully-typed Node.js client library for the UniFi Controller API.  
Supports authentication (including 2FA), robust error handling, modular endpoints, and TypeScript-first development.

---

## Installation

```sh
pnpm add @panoptic-it-solutions/unifi-api-client
# or
npm install @panoptic-it-solutions/unifi-api-client
```

---

## Basic Usage

```typescript
import { UniFiClient } from '@panoptic-it-solutions/unifi-api-client';

const client = new UniFiClient('https://unifi.example.com:8443', {
  username: 'admin',
  password: 'password',
  site: 'default', // optional, defaults to 'default'
  strictSSL: true, // optional, defaults to true
  timeout: 10000,  // optional, ms
  // logger: customLoggerInstance, // optional
});

await client.login(); // uses stored credentials

// Example: List all devices
const devices = await client.devices.listDevices();
console.log(devices);

await client.logout();
```

---

## Authentication

- **Username/password** authentication (2FA supported if enabled).
- Session persistence with automatic re-authentication.
- Emits authentication events for custom handling.

```typescript
await client.login(); // uses credentials from constructor
// or
await client.login('admin', 'password'); // override credentials
```

---

## Configuration Options

| Option      | Type     | Default   | Description                                 |
|-------------|----------|-----------|---------------------------------------------|
| username    | string   | -         | UniFi username                              |
| password    | string   | -         | UniFi password                              |
| site        | string   | 'default' | UniFi site name                             |
| strictSSL   | boolean  | true      | Enforce SSL certificate validation          |
| timeout     | number   | 10000     | Request timeout in milliseconds             |
| logger      | Logger or LoggerOptions | - | Custom logger instance or options           |

---

## API Overview

- **Devices:** List, adopt, restart, block/unblock, update firmware, etc.
- **Clients:** List, block/unblock, authorize guests, get stats.
- **Sites:** List, switch, get site info.
- **Networks:** List, create, update, delete VLANs and networks.
- **WLANs:** List, create, update, delete wireless networks.
- **Statistics:** Retrieve usage, client, device, and site stats.
- **System:** Get status, settings, logs, alerts, backups, firmware, reboot, factory reset.

---

## Example: Device Management

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

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

// Adopt a device
await client.devices.adoptDevice('aa:bb:cc:dd:ee:ff');

// Restart a device
await client.devices.restartDevice('aa:bb:cc:dd:ee:ff');

// Set device name
await client.devices.setDeviceName('aa:bb:cc:dd:ee:ff', 'My AP');
```

---

## Example: Client Management

```typescript
// List all active clients
const activeClients = await client.getActiveClients();

// Block a client
await client.blockClient('aa:bb:cc:dd:ee:ff');

// Authorize a guest client for 120 minutes
await client.authorizeGuest('aa:bb:cc:dd:ee:ff', 120);
```

---

## Example: Network and Firewall

```typescript
// List all networks
const networks = await client.getNetworks();

// Create a new network
const newNetwork = await client.createNetwork({
  name: 'IoT',
  vlan: 20,
  // ...other network options
});

// List all firewall rules
const rules = await client.getFirewallRules();
```

---

## Error Handling

All methods throw custom error classes (`UniFiApiError`, `UniFiAuthError`, etc.).

```typescript
try {
  await client.login();
  const clients = await client.getClients();
} catch (err) {
  if (err instanceof UniFiAuthError) {
    // Handle authentication error
  } else {
    // Handle other errors
  }
}
```

---

## Logging

- Built-in logger with log levels (info, warn, error, debug).
- Pass a custom logger or use the default.
- Logs authentication, requests, errors, and more.

---

## TypeScript Support

- Fully typed API and data models.
- All endpoint methods and options are type-safe.

---

## API Reference Documentation

- **Generated with [TypeDoc](https://typedoc.org/).**
- After cloning the repo, run:
  ```sh
  pnpm run docs
  ```
  Then open `docs/index.html` in your browser.

---

## Contributing

1. Fork the repo and create a feature branch.
2. Add/modify code and tests.
3. Run `pnpm test` to verify.
4. Submit a pull request with a clear description.

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

## Support

For issues, please open a ticket on [GitHub Issues](https://github.com/username/unifi-controller-api/issues).