{"id":17278999,"url":"https://github.com/thib3113/unifi-client","last_synced_at":"2025-04-06T09:06:53.087Z","repository":{"id":37007155,"uuid":"350072947","full_name":"thib3113/unifi-client","owner":"thib3113","description":"NodeJs client for Unifi products  - https://www.ui.com/","archived":false,"fork":false,"pushed_at":"2025-03-30T06:27:46.000Z","size":50734,"stargazers_count":42,"open_issues_count":6,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T07:24:27.757Z","etag":null,"topics":["cloud-key","network","node-unifi","ubiquiti","udm","udm-pro","unifi","unifi-client","unifi-controller"],"latest_commit_sha":null,"homepage":"https://thib3113.github.io/unifi-client","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thib3113.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"thib3113","custom":"paypal.me/thib3113"}},"created_at":"2021-03-21T17:40:48.000Z","updated_at":"2025-03-26T20:56:12.000Z","dependencies_parsed_at":"2024-04-18T19:29:45.617Z","dependency_job_id":"499f4cf7-61db-4f8f-b57b-22301371c20c","html_url":"https://github.com/thib3113/unifi-client","commit_stats":{"total_commits":799,"total_committers":5,"mean_commits":159.8,"dds":0.5406758448060075,"last_synced_commit":"2a93ba328f9c01992eefd864a2b2881778ae8da4"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thib3113%2Funifi-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thib3113%2Funifi-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thib3113%2Funifi-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thib3113%2Funifi-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thib3113","download_url":"https://codeload.github.com/thib3113/unifi-client/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247457799,"owners_count":20941906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-key","network","node-unifi","ubiquiti","udm","udm-pro","unifi","unifi-client","unifi-controller"],"created_at":"2024-10-15T09:15:15.257Z","updated_at":"2025-04-06T09:06:53.067Z","avatar_url":"https://github.com/thib3113.png","language":"TypeScript","funding_links":["https://github.com/sponsors/thib3113","paypal.me/thib3113","https://paypal.me/thib3113"],"categories":["API Libraries"],"sub_categories":["Node.js / JavaScript"],"readme":"\n# unifi-client\n[![NPM version](https://img.shields.io/npm/v/unifi-client.svg)](https://www.npmjs.com/package/unifi-client)\n[![CI](https://github.com/thib3113/unifi-client/actions/workflows/CI.yml/badge.svg)](https://github.com/thib3113/unifi-client/actions/workflows/CI.yml)\n[![codecov](https://codecov.io/gh/thib3113/unifi-client/branch/main/graph/badge.svg?token=MZKEJ9F2WR)](https://codecov.io/gh/thib3113/unifi-client)\n[![Downloads](https://img.shields.io/npm/dm/unifi-client.svg)](https://www.npmjs.com/package/unifi-client)\n[![License](https://img.shields.io/github/license/thib3113/unifi-client.svg)](https://github.com/thib3113/unifi-client/blob/main/LICENSE)\n[![Known Vulnerabilities](https://snyk.io/test/github/thib3113/unifi-client/badge.svg)](https://snyk.io/test/github/thib3113/unifi-client)\n[![unifi-client](https://snyk.io/advisor/npm-package/unifi-client/badge.svg)](https://snyk.io/advisor/npm-package/unifi-client)\n[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg?logo=paypal)](https://paypal.me/thib3113)\n[![GitHub stars](https://img.shields.io/github/stars/thib3113/unifi-client.svg?style=social\u0026label=Star)](https://github.com/thib3113/unifi-client/stargazers/)\n[![Package Quality](https://packagequality.com/shield/unifi-client.svg)](https://packagequality.com/#?package=unifi-client)\n\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=bugs)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=code_smells)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=thib3113_unifi-client\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=thib3113_unifi-client)\n\n![Dependencies update - renovate](https://img.shields.io/badge/renovate-enabled-green?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjUgNSAzNzAgMzcwIj48Y2lyY2xlIGN4PSIxODkiIGN5PSIxOTAiIHI9IjE4NCIgZmlsbD0iI2ZlMiIvPjxwYXRoIGZpbGw9IiM4YmIiIGQ9Ik0yNTEgMjU2bC0zOC0zOGExNyAxNyAwIDAxMC0yNGw1Ni01NmMyLTIgMi02IDAtN2wtMjAtMjFhNSA1IDAgMDAtNyAwbC0xMyAxMi05LTggMTMtMTNhMTcgMTcgMCAwMTI0IDBsMjEgMjFjNyA3IDcgMTcgMCAyNGwtNTYgNTdhNSA1IDAgMDAwIDdsMzggMzh6Ii8+PHBhdGggZmlsbD0iI2Q1MSIgZD0iTTMwMCAyODhsLTggOGMtNCA0LTExIDQtMTYgMGwtNDYtNDZjLTUtNS01LTEyIDAtMTZsOC04YzQtNCAxMS00IDE1IDBsNDcgNDdjNCA0IDQgMTEgMCAxNXoiLz48cGF0aCBmaWxsPSIjYjMwIiBkPSJNMjg1IDI1OGw3IDdjNCA0IDQgMTEgMCAxNWwtOCA4Yy00IDQtMTEgNC0xNiAwbC02LTdjNCA1IDExIDUgMTUgMGw4LTdjNC01IDQtMTIgMC0xNnoiLz48cGF0aCBmaWxsPSIjYTMwIiBkPSJNMjkxIDI2NGw4IDhjNCA0IDQgMTEgMCAxNmwtOCA3Yy00IDUtMTEgNS0xNSAwbC05LThjNSA1IDEyIDUgMTYgMGw4LThjNC00IDQtMTEgMC0xNXoiLz48cGF0aCBmaWxsPSIjZTYyIiBkPSJNMjYwIDIzM2wtNC00Yy02LTYtMTctNi0yMyAwLTcgNy03IDE3IDAgMjRsNCA0Yy00LTUtNC0xMSAwLTE2bDgtOGM0LTQgMTEtNCAxNSAweiIvPjxwYXRoIGZpbGw9IiNiNDAiIGQ9Ik0yODQgMzA0Yy00IDAtOC0xLTExLTRsLTQ3LTQ3Yy02LTYtNi0xNiAwLTIybDgtOGM2LTYgMTYtNiAyMiAwbDQ3IDQ2YzYgNyA2IDE3IDAgMjNsLTggOGMtMyAzLTcgNC0xMSA0em0tMzktNzZjLTEgMC0zIDAtNCAybC04IDdjLTIgMy0yIDcgMCA5bDQ3IDQ3YTYgNiAwIDAwOSAwbDctOGMzLTIgMy02IDAtOWwtNDYtNDZjLTItMi0zLTItNS0yeiIvPjxwYXRoIGZpbGw9IiMxY2MiIGQ9Ik0xNTIgMTEzbDE4LTE4IDE4IDE4LTE4IDE4em0xLTM1bDE4LTE4IDE4IDE4LTE4IDE4em0tOTAgODlsMTgtMTggMTggMTgtMTggMTh6bTM1LTM2bDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMxZGQiIGQ9Ik0xMzQgMTMxbDE4LTE4IDE4IDE4LTE4IDE4em0tMzUgMzZsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzJiYiIgZD0iTTExNiAxNDlsMTgtMTggMTggMTgtMTggMTh6bTU0LTU0bDE4LTE4IDE4IDE4LTE4IDE4em0tODkgOTBsMTgtMTggMTggMTgtMTggMTh6bTEzOS04NWwyMyAyM2M0IDQgNCAxMSAwIDE2TDE0MiAyNDBjLTQgNC0xMSA0LTE1IDBsLTI0LTI0Yy00LTQtNC0xMSAwLTE1bDEwMS0xMDFjNS01IDEyLTUgMTYgMHoiLz48cGF0aCBmaWxsPSIjM2VlIiBkPSJNMTM0IDk1bDE4LTE4IDE4IDE4LTE4IDE4em0tNTQgMThsMTgtMTcgMTggMTctMTggMTh6bTU1LTUzbDE4LTE4IDE4IDE4LTE4IDE4em05MyA0OGwtOC04Yy00LTUtMTEtNS0xNiAwTDEwMyAyMDFjLTQgNC00IDExIDAgMTVsOCA4Yy00LTQtNC0xMSAwLTE1bDEwMS0xMDFjNS00IDEyLTQgMTYgMHoiLz48cGF0aCBmaWxsPSIjOWVlIiBkPSJNMjcgMTMxbDE4LTE4IDE4IDE4LTE4IDE4em01NC01M2wxOC0xOCAxOCAxOC0xOCAxOHoiLz48cGF0aCBmaWxsPSIjMGFhIiBkPSJNMjMwIDExMGwxMyAxM2M0IDQgNCAxMSAwIDE2TDE0MiAyNDBjLTQgNC0xMSA0LTE1IDBsLTEzLTEzYzQgNCAxMSA0IDE1IDBsMTAxLTEwMWM1LTUgNS0xMSAwLTE2eiIvPjxwYXRoIGZpbGw9IiMxYWIiIGQ9Ik0xMzQgMjQ4Yy00IDAtOC0yLTExLTVsLTIzLTIzYTE2IDE2IDAgMDEwLTIzTDIwMSA5NmExNiAxNiAwIDAxMjIgMGwyNCAyNGM2IDYgNiAxNiAwIDIyTDE0NiAyNDNjLTMgMy03IDUtMTIgNXptNzgtMTQ3bC00IDItMTAxIDEwMWE2IDYgMCAwMDAgOWwyMyAyM2E2IDYgMCAwMDkgMGwxMDEtMTAxYTYgNiAwIDAwMC05bC0yNC0yMy00LTJ6Ii8+PC9zdmc+\n)\n\n\n[![NPM](https://nodei.co/npm/unifi-client.png)](https://nodei.co/npm/unifi-client/)\n\nThis library is a nodejs client to talk with unifi rest API .\n\n## Start\n\ninstall it\n```\nyarn add unifi-client\n```\n\nor via npm\n\n```\nnpm i unifi-client\n```\n\nand import it in your code :\n```typescript\nimport Controller from 'unifi-client'\n```\n\nor with require :\n```js\nconst { Controller } = require('unifi-client')\n```\n\n## Requirements\n\n- Installed UniFi-Controller version v6 or more, UnifiOs or not ( cloud keys / UDM or just unifi controller software ) ( not tested below v6 )\n- A network connectivy between unifi-client and the controller ( env http_proxy and https_proxy can be handled automaticaly, but not tested )\n- An account, cloud accounts, local accounts and 2FA are available\n- Node.js version \u003e= LTS (14)\n\n## Example\n\nExamples are located in [examples folder](./examples)\n\n```typescript\nimport Controller from 'unifi-client'\n\n// works with local account, check examples for 2FA\nconst controller = new Controller({\n  username: 'ubnt',\n  password: 'ubnt',\n  url: 'https://unifi',\n  strictSSL: false\n});\n\n//login to the controller\nawait controller.login()\n\n//retrieve sites\nconst sites = controller.getSites()\n\n//work on one site\nconst site = sites[0];\n\n//example request to get firewall rules\nconst rules = await site.firewall.getRules();\n```\n---\n\nTo work on multiples sites on the same time\n```typescript\nconst controller = new Controller({...});\n\nconst sites = controller.getSites();\n\n//get firewallRules on two sites\nconst rules = await site[0].firewall.getRules();\nconst rules2 = await site[1].firewall.getRules();\n```\n\nHow to use the HTTP instances\n```typescript\n//use the controller instance directly . Authentication, url construction and other is already managed for you\nconst self = await controller.getInstance().get('/api/self');\n\n//for a custom site :\nconst topology = await site.getInstance().get('/topology');\n```\n\nGet firewall rules, it return an array of [FWRule](https://thib3113.github.io/unifi-client/classes/Firewall_FWRule.FWRule.html)\n\n```typescript\nconst rules = await site.firewall.getRules();\n```\n\n### Instances\nThe instances returned by `getInstance` are basicaly some [axios instances](https://github.com/axios/axios#instance-methods) . With some additions :\n```typescript\n//url params\n// use them to manage a rest url for example\ninstance.get('/url/:uuid', {\n    urlParams: {\n        uuid: 'my-uuid'\n    }\n})\n// will call the url /url/my-uuid\n\n\n// apiVersion :\n// some api call are on the v2 api, so you can set the api version when calling\nconsole.log(site.name); // default\nsite.getInstance().get('/super/endpoint', {\n    apiVersion: 2\n});\n// will call the url /v2/api/site/default/super/endpoint\n```\n\n### how to use URLs from the unifi front :\nThe urls of unifi are like :\n\n- `/proxy/network/v2/api/site/default/notifications` for unifiOs\nor\n- `/v2/api/site/default/notifications` for non unifiOs\n\nthe url is constructed like :\n`/[v\u003cApiVersion\u003e/]api/site/\u003csitename\u003e[/\u003curlToCall\u003e]`\n- ApiVersion : the version of the API (for version \u003e 1)\n- sitename : the name of the site (already included in site instance)\n\nTo illustrate, to call the url I see on my browser network tabs :\n\n`https://192.168.1.1/proxy/network/v2/api/site/default/notifications`\n\nI just need to :\n```typescript\n// configure my controller\nconst controller = new Controller({\n    username: 'ubnt',\n    password: 'ubnt',\n    url: 'https://192.168.1.1',\n    strictSSL: false\n});\n\n//login to the controller\nawait controller.login()\n\n//retrieve sites\nconst sites = controller.getSites()\n\n// select the site \"default\"\nconst site = sites.find((site) =\u003e site.name === 'default');\n\n//call my url\nconst notifications = site.getInstance().get('/default/notifications', {\n    apiVersion: 2\n});\n\n//do something with notifications\n```\n\nMore examples in the folder [examples](./examples)\n\n## Websockets\nThis library supports websockets, you can listen on them with :\n```typescript\n// initWebSockets for controller :\nawait controller.initWebSockets();\n\n// listen for controller websockets ( only for unifiOS )\ncontroller.on() / controller.ws.on()\n\n// listen for super site websockets\ncontroller.superWS.on();\n\n\n// initWebSockets for site :\nawait site.initWebSockets();\n// listen for this site websockets\nsite.on() / site.ws.on()\n\n// doesn't known the name of the event ? you can listen on joker :\ncontroller.on('*', (eventName, ...args) =\u003e {\n    console.log(eventName, ...args);\n});\n\n// want to listen on all websockets of a controller on the same listener\n// all websockets registered :\n// - controller websockets if unifiOS\n// - super site WS\n// - all sites where ws are init ( closed or not )\ncontroller.globalWS.on('*', (eventName, ...args) =\u003e {\n    console.log(eventName, ...args);\n});\n```\n\nthe support of websocket is experimental, and with a really bad coverage . Doesn't hesitate to open a PR, to add more websockets types\n\nWe add some optionnal dependencies to improve performances, more informations [read here](https://github.com/websockets/ws#opt-in-for-performance)\nthey can be skipped by using\n`npm install --no-optional`\n\n## Technical documentation\nAll the technical documentation is available [here](https://thib3113.github.io/unifi-client/modules)\n\n## Work In Progress\ncheck [technical documentation](https://thib3113.github.io/unifi-client/modules) for available methods\n\n## Tests\nThis library is auto-tested on :\n- UDM-pro : `latest` (`7.3.83`)\n\n- 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`\n  (*only some functions are tested, in an empty environment*)\n\nwith the last node LTS\n\n## References\nThis nodejs package/class uses functionality/Know-How gathered from different third-party projects:\n\n* [UniFi-API-client](https://github.com/Art-of-WiFi/UniFi-API-client)\n* [unifi_sh_api](https://dl.ui.com/unifi/5.12.35/unifi_sh_api)\n* [node-unifi](https://github.com/jens-maus/node-unifi)\n\n## Debug\nTo 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)) .\n\n* `unifi-client` : base debug namespace\n* `unifi-client:\u003cclassName\u003e` : will show debug for this class (eg : unifi-client:Controller will log controller logs )\n* `unifi-client:axios` : will logs axios request (can contain secrets informations)\n* `unifi-client:axios:verbose` : will logs more things on axios, like send and receive payload (can contain secrets informations)\n* `unifi-client:axios:curl` : will log curl cmd corresponding to the axios request (can contain secrets informations)\n\n## Useful links\nubntwiki : https://ubntwiki.com/products/software/unifi-controller/api\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthib3113%2Funifi-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthib3113%2Funifi-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthib3113%2Funifi-client/lists"}