@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

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

Basic Usage

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.

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

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

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

// 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.).

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.
• After cloning the repo, run:

  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 for details.

Support

For issues, please open a ticket on GitHub Issues.