{"_id":"@apiclient.xyz/unifi","name":"@apiclient.xyz/unifi","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@apiclient.xyz/unifi","version":"1.1.0","private":false,"description":"an unofficial unifi api package","main":"dist_ts/index.js","typings":"dist_ts/index.d.ts","type":"module","author":{"name":"Task Venture Capital GmbH"},"license":"MIT","scripts":{"test":"(tstest test/ --verbose --logfile --timeout 60)","build":"(tsbuild tsfolders --allowimplicitany)","buildDocs":"(tsdoc)"},"devDependencies":{"@git.zone/tsbuild":"^4.1.2","@git.zone/tsrun":"^2.0.1","@git.zone/tstest":"^3.1.8","@push.rocks/qenv":"^6.1.0","@types/node":"^25.2.0"},"dependencies":{"@push.rocks/smartlog":"^3.0.0","@push.rocks/smartpath":"^6.0.0","@push.rocks/smartpromise":"^4.2.3","@push.rocks/smartrequest":"^2.1.0","@push.rocks/smartstring":"^4.0.15"},"repository":{"type":"git","url":"https://code.foss.global/apiclient.xyz/unifi.git"},"bugs":{"url":"https://code.foss.global/apiclient.xyz/unifi/issues"},"homepage":"https://code.foss.global/apiclient.xyz/unifi#readme","pnpm":{"overrides":{}},"gitHead":"f4300bce4b3d5a738bb6fd0fc4246dbe4e97a70b","_id":"@apiclient.xyz/unifi@1.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.7.0","dist":{"integrity":"sha512-BwWVs094lALWYcGcMAtN4mV4B51kqBgVZ2m9+weGyvcSus7FLtV0vKlB6gr+F1EuK1aS4zFRhkt/2h4lZh4qxA==","shasum":"02398a95e9362dd52a85f34b8c95240d080abd5e","tarball":"https://registry.npmjs.org/@apiclient.xyz/unifi/-/unifi-1.1.0.tgz","fileCount":88,"unpackedSize":395667,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDV9R2gy9ofIP0riIMySZPLjJN+jXIL1Oy4yC+LUNA6XgIhAMFKVEQR2pdId5anYExG3HEV56U1xAmuThrJoiZzpAd8"}]},"_npmUser":{"name":"lossless","email":"hello@lossless.com"},"directories":{},"maintainers":[{"name":"lossless","email":"hello@lossless.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/unifi_1.1.0_1770047213957_0.5023514619219775"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-02T15:46:53.841Z","1.1.0":"2026-02-02T15:46:54.119Z","modified":"2026-02-02T15:46:54.402Z"},"maintainers":[{"name":"lossless","email":"hello@lossless.com"}],"description":"an unofficial unifi api package","homepage":"https://code.foss.global/apiclient.xyz/unifi#readme","repository":{"type":"git","url":"https://code.foss.global/apiclient.xyz/unifi.git"},"author":{"name":"Task Venture Capital GmbH"},"bugs":{"url":"https://code.foss.global/apiclient.xyz/unifi/issues"},"license":"MIT","readme":"# @apiclient.xyz/unifi\n\nA comprehensive, unofficial TypeScript client for the UniFi ecosystem. Control your entire Ubiquiti infrastructure programmatically — Network devices, Protect cameras, Access doors, and Site Manager — all from a single, unified API. 🚀\n\n## Issue Reporting and Security\n\nFor reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.\n\n## Installation\n\n```bash\nnpm install @apiclient.xyz/unifi\n# or\npnpm add @apiclient.xyz/unifi\n# or\nyarn add @apiclient.xyz/unifi\n```\n\n## Features\n\n✨ **Four UniFi APIs in One Package**\n\n| API | Use Case | Authentication |\n|-----|----------|----------------|\n| **UnifiController** | Network devices, clients, VLANs, WLANs | API Key or Session |\n| **UnifiProtect** | Cameras, NVR, motion events, recordings | API Key or Session + CSRF |\n| **UnifiAccess** | Doors, users, NFC cards, access events | Bearer Token |\n| **UnifiAccount** | Cloud Site Manager (ui.com) | API Key |\n\n🎯 **Developer-Friendly Design**\n- Full TypeScript support with comprehensive types\n- Intuitive class-based resource management\n- Async/await throughout\n- Works with self-signed certificates (common on UniFi devices)\n\n## Quick Start\n\n### Network Controller (Local)\n\nManage your switches, access points, gateways, and connected clients:\n\n```typescript\nimport { UnifiController } from '@apiclient.xyz/unifi';\n\n// Using API key (recommended - no login required)\nconst controller = new UnifiController({\n  host: '192.168.1.1',\n  apiKey: 'your-network-api-key',\n  controllerType: 'unifi-os', // 'unifi-os' | 'udm-pro' | 'standalone'\n  verifySsl: false, // Self-signed certs\n});\n\n// List all devices\nconst devices = await controller.deviceManager.listDevices();\nfor (const device of devices) {\n  console.log(`${device.getDisplayName()} - ${device.isOnline() ? '🟢' : '🔴'}`);\n}\n\n// Get specific device types\nconst accessPoints = await controller.deviceManager.getAccessPoints();\nconst switches = await controller.deviceManager.getSwitches();\nconst gateways = await controller.deviceManager.getGateways();\n\n// Manage connected clients\nconst clients = await controller.clientManager.listActiveClients();\nconst wirelessClients = await controller.clientManager.getWirelessClients();\n\n// Find a client and block them\nconst troublemaker = await controller.clientManager.getClientByMac('aa:bb:cc:dd:ee:ff');\nif (troublemaker) {\n  await troublemaker.block();\n}\n\n// Get network configuration\nconst networks = await controller.getNetworks();\nconst wlans = await controller.getWlans();\nconst firewallRules = await controller.getFirewallRules();\nconst portForwards = await controller.getPortForwards();\n\n// System info and health\nconst health = await controller.getHealth();\nconst systemInfo = await controller.getSystemInfo();\n```\n\n### Protect NVR (Local)\n\nControl your cameras, view motion events, manage recordings:\n\n```typescript\nimport { UnifiProtect } from '@apiclient.xyz/unifi';\n\nconst protect = new UnifiProtect({\n  host: '192.168.1.1',\n  apiKey: 'your-protect-api-key',\n  verifySsl: false,\n});\n\n// Load camera data\nawait protect.refreshBootstrap();\n\n// List all cameras\nconst cameras = await protect.cameraManager.listCameras();\nfor (const camera of cameras) {\n  console.log(`📷 ${camera.name} - ${camera.isOnline() ? 'Online' : 'Offline'}`);\n  if (camera.isDoorbell()) console.log('  🔔 Doorbell');\n  if (camera.hasSmartDetect()) console.log('  🧠 Smart Detection enabled');\n}\n\n// Get cameras by status\nconst onlineCameras = await protect.cameraManager.getOnlineCameras();\nconst doorbells = await protect.cameraManager.getDoorbells();\nconst smartCameras = await protect.cameraManager.getSmartDetectCameras();\n\n// Check recent motion\nconst recentMotion = await protect.cameraManager.getCamerasWithRecentMotion(300); // Last 5 min\nconst motionEvents = await protect.cameraManager.getAllMotionEvents({ limit: 50 });\n\n// Control a camera\nconst frontDoor = await protect.cameraManager.getCameraByName('Front Door');\nif (frontDoor) {\n  await frontDoor.setRecordingMode('always'); // 'always' | 'detections' | 'never' | 'schedule'\n  await frontDoor.setMicVolume(80);\n  await frontDoor.restart();\n\n  // Get RTSP stream URL\n  const rtspUrl = frontDoor.getRtspUrl(0); // Channel 0 = highest quality\n}\n\n// NVR info\nconst nvrInfo = protect.getNvrInfo();\nconst storageInfo = protect.getStorageInfo();\nconst lights = protect.getLights();\nconst sensors = protect.getSensors();\n```\n\n### Access Controller (Local)\n\nManage doors, users, credentials, and access events:\n\n```typescript\nimport { UnifiAccess } from '@apiclient.xyz/unifi';\n\nconst access = new UnifiAccess({\n  host: '192.168.1.1',\n  token: 'your-bearer-token',\n  verifySsl: false,\n});\n\n// List all doors\nconst doors = await access.doorManager.listDoors();\nfor (const door of doors) {\n  console.log(`🚪 ${door.getDisplayName()} - ${door.getStatus()}`);\n}\n\n// Control a door\nconst mainEntrance = await access.doorManager.getDoorByName('Main Entrance');\nif (mainEntrance) {\n  await mainEntrance.unlock();\n  // Door auto-locks based on your Access settings\n\n  console.log(`Locked: ${mainEntrance.isLocked()}`);\n  console.log(`Open: ${mainEntrance.isOpen()}`);\n}\n\n// Manage users\nconst users = await access.getUsers();\nconst newUser = await access.createUser({\n  first_name: 'John',\n  last_name: 'Doe',\n  email: 'john@example.com',\n});\n\n// Assign credentials\nawait access.setUserPin(newUser.id, '1234');\nawait access.assignNfcCard(newUser.id, 'card-token-here', 'Office Card');\n\n// Grant/revoke door access\nawait access.grantAccess(newUser.id, mainEntrance.unique_id);\nawait access.revokeAccess(newUser.id, mainEntrance.unique_id);\n\n// View access events\nconst recentEvents = await access.getRecentEvents(100);\nconst doorEvents = await access.getEvents({ doorId: mainEntrance.unique_id });\n\n// Get policies and locations\nconst policies = await access.getPolicies();\nconst locations = await access.getLocations();\n```\n\n### Site Manager (Cloud)\n\nManage multiple sites via the ui.com cloud API:\n\n```typescript\nimport { UnifiAccount } from '@apiclient.xyz/unifi';\n\n// Cloud API uses api.ui.com\nconst account = new UnifiAccount({\n  apiKey: 'your-cloud-api-key', // From ui.com\n});\n\n// List all sites\nconst sites = await account.siteManager.listSites();\nfor (const site of sites) {\n  console.log(`🏢 ${site.name} (${site.siteId})`);\n}\n\n// List all hosts (consoles)\nconst hosts = await account.hostManager.listHosts();\n\n// Find specific site\nconst mainOffice = await account.siteManager.findSiteByName('Main Office');\n```\n\n## Authentication Methods\n\n### API Keys (Recommended)\n\nGenerate API keys in your UniFi console settings. API keys don't expire and don't require login/logout:\n\n```typescript\n// Network API key\nconst controller = new UnifiController({\n  host: '192.168.1.1',\n  apiKey: 'your-api-key',\n  controllerType: 'unifi-os',\n});\n\n// Already authenticated - start using immediately\nconst devices = await controller.deviceManager.listDevices();\n```\n\n### Session Authentication\n\nFor scenarios where API keys aren't available:\n\n```typescript\nconst controller = new UnifiController({\n  host: '192.168.1.1',\n  username: 'admin',\n  password: 'your-password',\n  controllerType: 'unifi-os',\n});\n\n// Must login first\nawait controller.login();\n\n// Use the API\nconst devices = await controller.deviceManager.listDevices();\n\n// Logout when done\nawait controller.logout();\n```\n\n## Device Management\n\n### Working with UnifiDevice\n\n```typescript\nconst device = await controller.deviceManager.getDeviceByMac('aa:bb:cc:dd:ee:ff');\n\n// Status checks\ndevice.isOnline();      // Connected to controller?\ndevice.isAccessPoint(); // Is this an AP?\ndevice.isSwitch();      // Is this a switch?\ndevice.isGateway();     // Is this a router/gateway?\ndevice.hasUpgrade();    // Firmware update available?\n\n// Actions\nawait device.restart();\nawait device.upgrade();\nawait device.rename('New Device Name');\nawait device.setLedOverride('off'); // 'default' | 'on' | 'off'\n\n// Switch port configuration\nawait device.setPortConfig(1, {\n  poe_mode: 'auto',\n  name: 'Camera Port',\n});\n\n// Properties\ndevice.ip;        // IP address\ndevice.mac;       // MAC address\ndevice.model;     // Model code (e.g., 'USW-24-POE')\ndevice.version;   // Firmware version\ndevice.uptime;    // Uptime in seconds\n```\n\n### Working with UnifiClient\n\n```typescript\nconst client = await controller.clientManager.getClientByIp('192.168.1.100');\n\n// Connection info\nclient.isWireless();       // WiFi or wired?\nclient.isGuest();          // Guest network?\nclient.getConnectionType(); // \"Wireless (MySSID)\" or \"Wired (Port 5)\"\nclient.getSignalQuality(); // \"Excellent\" | \"Good\" | \"Fair\" | \"Poor\"\nclient.getDataUsage();     // Total bytes (TX + RX)\n\n// Actions\nawait client.block();      // Block from network\nawait client.unblock();    // Unblock\nawait client.reconnect();  // Kick and reconnect\nawait client.rename('Living Room TV');\n\n// Properties\nclient.ip;       // IP address\nclient.mac;      // MAC address\nclient.hostname; // Device hostname\nclient.essid;    // WiFi network name\nclient.signal;   // Signal strength (dBm)\nclient.tx_bytes; // Upload bytes\nclient.rx_bytes; // Download bytes\n```\n\n### Working with UnifiCamera\n\n```typescript\nconst camera = await protect.cameraManager.getCameraById('camera-id');\n\n// Status\ncamera.isOnline();\ncamera.isDoorbell();\ncamera.hasSmartDetect();\ncamera.hasRecentMotion(60); // Motion in last 60 seconds?\ncamera.getTimeSinceLastMotion(); // Seconds since last motion\n\n// Streaming\ncamera.getRtspUrl(0);            // High quality RTSP\ncamera.getHighQualityChannel();\ncamera.getMediumQualityChannel();\ncamera.getLowQualityChannel();\n\n// Settings\nawait camera.setRecordingMode('detections');\nawait camera.setSmartDetectTypes(['person', 'vehicle']);\nawait camera.setMicVolume(50);\nawait camera.setSpeakerVolume(75);\nawait camera.rename('Garage Camera');\nawait camera.restart();\n```\n\n### Working with UnifiDoor\n\n```typescript\nconst door = await access.doorManager.getDoorById('door-id');\n\n// Status\ndoor.isLocked();   // Lock engaged?\ndoor.isOpen();     // Door physically open?\ndoor.isClosed();   // Door physically closed?\ndoor.getStatus();  // \"Locked, Closed\" etc.\n\n// Actions\nawait door.unlock();\nawait door.lock();\nawait door.rename('Back Door');\nawait door.setAlias('Employee Entrance');\n```\n\n## API Reference\n\n### Entry Point Classes\n\n| Class | Description | Manager Classes |\n|-------|-------------|-----------------|\n| `UnifiController` | Local Network Controller | `deviceManager`, `clientManager` |\n| `UnifiProtect` | Local Protect NVR | `cameraManager` |\n| `UnifiAccess` | Local Access Controller | `doorManager` |\n| `UnifiAccount` | Cloud Site Manager | `siteManager`, `hostManager` |\n\n### Resource Classes\n\n| Class | Represents |\n|-------|------------|\n| `UnifiDevice` | Network device (AP, switch, gateway) |\n| `UnifiClient` | Connected network client |\n| `UnifiCamera` | Protect camera |\n| `UnifiDoor` | Access door |\n| `UnifiSite` | Site Manager site |\n| `UnifiHost` | Site Manager host/console |\n\n### Controller Types\n\n| Type | Description |\n|------|-------------|\n| `unifi-os` | UniFi OS consoles (UDM, UDM Pro, Cloud Key Gen2+) |\n| `udm-pro` | Alias for unifi-os |\n| `standalone` | Standalone software controller |\n\n## SSL/TLS Handling\n\nUniFi devices typically use self-signed certificates. Set `verifySsl: false` to allow connections:\n\n```typescript\nconst controller = new UnifiController({\n  host: '192.168.1.1',\n  apiKey: 'key',\n  verifySsl: false, // Allow self-signed certs\n});\n```\n\nFor production environments with proper certificates, set `verifySsl: true`.\n\n## Environment Variables Example\n\nCreate a `.env` or use your preferred env management:\n\n```bash\n# Network Controller\nUNIFI_CONSOLE_IP=192.168.1.1\nUNIFI_NETWORK_API_KEY=your-network-key\n\n# Protect\nUNIFI_PROTECT_API_KEY=your-protect-key\n\n# Access\nUNIFI_ACCESS_HOST=192.168.1.1\nUNIFI_ACCESS_TOKEN=your-bearer-token\n\n# Site Manager (Cloud)\nUNIFI_CLOUD_API_KEY=your-cloud-key\n```\n\n## TypeScript Support\n\nThis package is written in TypeScript and exports comprehensive types:\n\n```typescript\nimport {\n  // Entry points\n  UnifiController,\n  UnifiProtect,\n  UnifiAccess,\n  UnifiAccount,\n\n  // Resources\n  UnifiDevice,\n  UnifiClient,\n  UnifiCamera,\n  UnifiDoor,\n  UnifiSite,\n  UnifiHost,\n\n  // Managers\n  DeviceManager,\n  ClientManager,\n  CameraManager,\n  DoorManager,\n  SiteManager,\n  HostManager,\n\n  // Interfaces\n  INetworkDevice,\n  INetworkClient,\n  IProtectCamera,\n  IAccessDoor,\n  // ... and many more\n} from '@apiclient.xyz/unifi';\n```\n\n## License and Legal Information\n\nThis repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.\n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.\n\nUse of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.\n\n### Company Information\n\nTask Venture Capital GmbH\nRegistered at District Court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n","readmeFilename":"readme.md","_rev":"1-cb8fcf03bbe511775cc123d1ed008db8"}