unifi-client
Version:
NodeJs client for Unifi products (https://www.ui.com/)
257 lines (193 loc) • 12.6 kB
Markdown
# unifi-client
[](https://www.npmjs.com/package/unifi-client)
[](https://github.com/thib3113/unifi-client/actions/workflows/CI.yml)
[](https://codecov.io/gh/thib3113/unifi-client)
[](https://www.npmjs.com/package/unifi-client)
[](https://github.com/thib3113/unifi-client/blob/main/LICENSE)
[](https://snyk.io/test/github/thib3113/unifi-client)
[](https://snyk.io/advisor/npm-package/unifi-client)
[](https://paypal.me/thib3113)
[](https://github.com/thib3113/unifi-client/stargazers/)
[](https://packagequality.com/#?package=unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)
[](https://nodei.co/npm/unifi-client/)
This library is a nodejs client to talk with unifi rest API .
## Start
install it
```
yarn add unifi-client
```
or via npm
```
npm i unifi-client
```
and import it in your code :
```typescript
import Controller from 'unifi-client'
```
or with require :
```js
const { Controller } = require('unifi-client')
```
## Requirements
- Installed UniFi-Controller version v6 or more, UnifiOs or not ( cloud keys / UDM or just unifi controller software ) ( not tested below v6 )
- A network connectivy between unifi-client and the controller ( env http_proxy and https_proxy can be handled automaticaly, but not tested )
- An account, cloud accounts, local accounts and 2FA are available
- Node.js version >= LTS (14)
## Example
Examples are located in [examples folder](./examples)
```typescript
import Controller from 'unifi-client'
// works with local account, check examples for 2FA
const controller = new Controller({
username: 'ubnt',
password: 'ubnt',
url: 'https://unifi',
strictSSL: false
});
//login to the controller
await controller.login()
//retrieve sites
const sites = controller.getSites()
//work on one site
const site = sites[0];
//example request to get firewall rules
const rules = await site.firewall.getRules();
```
---
To work on multiples sites on the same time
```typescript
const controller = new Controller({...});
const sites = controller.getSites();
//get firewallRules on two sites
const rules = await site[0].firewall.getRules();
const rules2 = await site[1].firewall.getRules();
```
How to use the HTTP instances
```typescript
//use the controller instance directly . Authentication, url construction and other is already managed for you
const self = await controller.getInstance().get('/api/self');
//for a custom site :
const topology = await site.getInstance().get('/topology');
```
Get firewall rules, it return an array of [FWRule](https://thib3113.github.io/unifi-client/classes/Firewall_FWRule.FWRule.html)
```typescript
const rules = await site.firewall.getRules();
```
### Instances
The instances returned by `getInstance` are basicaly some [axios instances](https://github.com/axios/axios#instance-methods) . With some additions :
```typescript
//url params
// use them to manage a rest url for example
instance.get('/url/:uuid', {
urlParams: {
uuid: 'my-uuid'
}
})
// will call the url /url/my-uuid
// apiVersion :
// some api call are on the v2 api, so you can set the api version when calling
console.log(site.name); // default
site.getInstance().get('/super/endpoint', {
apiVersion: 2
});
// will call the url /v2/api/site/default/super/endpoint
```
### how to use URLs from the unifi front :
The urls of unifi are like :
- `/proxy/network/v2/api/site/default/notifications` for unifiOs
or
- `/v2/api/site/default/notifications` for non unifiOs
the url is constructed like :
`/[v<ApiVersion>/]api/site/<sitename>[/<urlToCall>]`
- ApiVersion : the version of the API (for version > 1)
- sitename : the name of the site (already included in site instance)
To illustrate, to call the url I see on my browser network tabs :
`https://192.168.1.1/proxy/network/v2/api/site/default/notifications`
I just need to :
```typescript
// configure my controller
const controller = new Controller({
username: 'ubnt',
password: 'ubnt',
url: 'https://192.168.1.1',
strictSSL: false
});
//login to the controller
await controller.login()
//retrieve sites
const sites = controller.getSites()
// select the site "default"
const site = sites.find((site) => site.name === 'default');
//call my url
const notifications = site.getInstance().get('/default/notifications', {
apiVersion: 2
});
//do something with notifications
```
More examples in the folder [examples](./examples)
## Websockets
This library supports websockets, you can listen on them with :
```typescript
// initWebSockets for controller :
await controller.initWebSockets();
// listen for controller websockets ( only for unifiOS )
controller.on() / controller.ws.on()
// listen for super site websockets
controller.superWS.on();
// initWebSockets for site :
await site.initWebSockets();
// listen for this site websockets
site.on() / site.ws.on()
// doesn't known the name of the event ? you can listen on joker :
controller.on('*', (eventName, ...args) => {
console.log(eventName, ...args);
});
// want to listen on all websockets of a controller on the same listener
// all websockets registered :
// - controller websockets if unifiOS
// - super site WS
// - all sites where ws are init ( closed or not )
controller.globalWS.on('*', (eventName, ...args) => {
console.log(eventName, ...args);
});
```
the support of websocket is experimental, and with a really bad coverage . Doesn't hesitate to open a PR, to add more websockets types
We add some optionnal dependencies to improve performances, more informations [read here](https://github.com/websockets/ws#opt-in-for-performance)
they can be skipped by using
`npm install --no-optional`
## Technical documentation
All the technical documentation is available [here](https://thib3113.github.io/unifi-client/modules)
## Work In Progress
check [technical documentation](https://thib3113.github.io/unifi-client/modules) for available methods
## Tests
This library is auto-tested on :
- UDM-pro : `latest` (`7.3.83`)
- Unifi controller : `latest`, `7.3.83`, `7.2.95`, `7.1.68`, `7.0.25`, `6.5.55`, `6.4.54`, `6.2.26`, `6.0.45`
(*only some functions are tested, in an empty environment*)
with the last node LTS
## References
This nodejs package/class uses functionality/Know-How gathered from different third-party projects:
* [UniFi-API-client](https://github.com/Art-of-WiFi/UniFi-API-client)
* [unifi_sh_api](https://dl.ui.com/unifi/5.12.35/unifi_sh_api)
* [node-unifi](https://github.com/jens-maus/node-unifi)
## Debug
To debug, you can use the [debug](https://www.npmjs.com/package/debug) library, just set the `DEBUG` environnement variable ([check this](https://github.com/visionmedia/debug#cmd)) .
* `unifi-client` : base debug namespace
* `unifi-client:<className>` : will show debug for this class (eg : unifi-client:Controller will log controller logs )
* `unifi-client:axios` : will logs axios request (can contain secrets informations)
* `unifi-client:axios:verbose` : will logs more things on axios, like send and receive payload (can contain secrets informations)
* `unifi-client:axios:curl` : will log curl cmd corresponding to the axios request (can contain secrets informations)
## Useful links
ubntwiki : https://ubntwiki.com/products/software/unifi-controller/api