tplink-omada-sdk

SDK for the TP-Link Omada Open API. Manage sites, devices, clients, networks, and more from Node.js.

Requirements

• Node.js >= 18

Installation

npm install tplink-omada-sdk

Quick Start

import { OmadaClient } from "tplink-omada-sdk";

const client = new OmadaClient({
  url: "https://use1-omada-northbound.tplinkcloud.com",
  omadacId: "YOUR_CONTROLLER_ID",
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

const { data: sites } = await client.getSites();
console.log(sites);

API Overview

OmadaClient (controller-level)

client.getSites(params?)        // List all sites
client.getSite(siteId)          // Get site details
client.updateSite(siteId, data) // Update site settings
client.getUsers(params?)        // List controller users
client.getRoles()               // List controller roles
client.webhooks                 // Webhook management (list, create, delete)

SiteContext (site-level)

Access site-scoped resources via client.site(siteId):

const site = client.site("site-id");

// Devices
site.getDevices(params?)   // All devices
site.getAps(params?)       // Access points only
site.getSwitches(params?)  // Switches only
site.getGateways(params?)  // Gateways only
site.getAp(apMac)          // Single AP by MAC

// Clients
site.getClients(params?)   // Connected clients
site.blockClient(mac)      // Block a client

// Networks
site.getNetworks(params?)  // List networks
site.createNetwork(config) // Create a network

// Sub-resources
site.wireless              // WLAN groups & SSIDs
site.hotspot               // Portals & vouchers
site.vpn                   // WireGuard & SSL VPN
site.acls                  // ACL rules
site.dashboard             // Dashboard stats

Pagination

Use the paginate helper to iterate through all pages automatically:

import { paginate } from "tplink-omada-sdk";

for await (const site of paginate((params) => client.getSites(params), {
  pageSize: 10,
})) {
  console.log(site.name);
}

Error Handling

import {
  OmadaApiError,
  OmadaAuthError,
  OmadaNetworkError,
} from "tplink-omada-sdk";

try {
  await client.getSites();
} catch (err) {
  if (err instanceof OmadaAuthError) {
    // Invalid credentials or expired token
    console.error("Auth failed:", err.errorCode, err.message);
  } else if (err instanceof OmadaApiError) {
    // Controller returned an API error
    console.error("API error:", err.errorCode, err.message);
  } else if (err instanceof OmadaNetworkError) {
    // Connection or DNS failure
    console.error("Network error:", err.message);
  }
}

Configuration (AuthConfig)

| Property | Type | Description | | --------------- | --------- | ------------------------------------------- | | url | string | Controller base URL (e.g. https://omada.example.com) | | omadacId | string | Omada controller ID | | clientId | string | OAuth2 client ID | | clientSecret | string | OAuth2 client secret | | allowInsecure | boolean | Allow HTTP connections (default: false) |

Development

pnpm install

# Build
pnpm build

# Run unit tests
pnpm test

# Run with coverage
pnpm test:coverage

# Run integration tests (requires a live controller)
OMADA_INTEGRATION_TEST=1 \
  OMADA_URL=https://use1-omada-northbound.tplinkcloud.com \
  OMADA_CLIENT_ID=... \
  OMADA_CLIENT_SECRET=... \
  OMADA_CONTROLLER_ID=... \
  pnpm test:integration

# Lint
pnpm lint

License

MIT