Type-safe API client with full TypeScript support
OAuth2 authentication with automatic token refresh
Support for all Omada devices:
- Routers (ER605, etc.)
- Switches (SG218R, etc.)
- Access Points (EAP)
Complete device management (list, configure, reboot, adopt)
Network configuration (VLANs, DHCP, routing)
Firewall and NAT rule management
Switch port configuration and PoE management
Router WAN/LAN configuration

Installation

pnpm install
pnpm build

Usage

Basic Setup

import { OmadaClient } from 'omada-api';

const client = new OmadaClient({
  baseUrl: 'https://192.168.11.10:8043',
  clientId: 'your-api-key',
  clientSecret: 'your-api-secret',
  siteId: 'your-site-id', // Optional, will auto-detect
  verifySSL: false, // Set to true for production
});

Device Management

import { DevicesService, DeviceType } from 'omada-api';

const devicesService = new DevicesService(client);

// List all devices
const devices = await devicesService.listDevices();

// Get routers
const routers = await devicesService.getRouters();

// Get switches
const switches = await devicesService.getSwitches();

// Get device details
const device = await devicesService.getDevice('device-id');

// Reboot a device
await devicesService.rebootDevice('device-id');

Network Configuration

import { NetworksService } from 'omada-api';

const networksService = new NetworksService(client);

// List VLANs
const vlans = await networksService.listVLANs();

// Create a VLAN
const vlan = await networksService.createVLAN({
  name: 'VLAN-100',
  vlanId: 100,
  subnet: '10.100.0.0/24',
  gateway: '10.100.0.1',
  dhcpEnable: true,
  dhcpRangeStart: '10.100.0.100',
  dhcpRangeEnd: '10.100.0.200',
  dns1: '8.8.8.8',
  dns2: '1.1.1.1',
});

Router Operations

import { RouterService } from 'omada-api';

const routerService = new RouterService(client);

// Get WAN ports
const wanPorts = await routerService.getWANPorts('router-device-id');

// Configure WAN port
await routerService.configureWANPort('router-device-id', 1, {
  connectionType: 'static',
  ip: '192.168.1.100',
  gateway: '192.168.1.1',
});

Switch Operations

import { SwitchService } from 'omada-api';

const switchService = new SwitchService(client);

// Get switch ports
const ports = await switchService.getSwitchPorts('switch-device-id');

// Configure a port
await switchService.configurePort('switch-device-id', 1, {
  enable: true,
  name: 'Port 1',
  vlanMode: 'access',
  nativeVlanId: 100,
});

// Control PoE
await switchService.setPoE('switch-device-id', 1, true);

Firewall Rules

import { FirewallService } from 'omada-api';

const firewallService = new FirewallService(client);

// Create firewall rule
await firewallService.createFirewallRule({
  name: 'Allow SSH',
  enable: true,
  action: 'allow',
  protocol: 'tcp',
  dstPort: '22',
  direction: 'in',
  priority: 100,
});

Environment Variables

The library can be configured via environment variables:

OMADA_CONTROLLER_URL=https://192.168.11.10:8043
OMADA_API_KEY=your-api-key
OMADA_API_SECRET=your-api-secret
OMADA_SITE_ID=your-site-id  # Optional
OMADA_VERIFY_SSL=false  # Set to true for production

Error Handling

The library provides specific error classes for different error scenarios:

import {
  OmadaApiError,
  OmadaAuthenticationError,
  OmadaDeviceNotFoundError,
  OmadaConfigurationError,
} from 'omada-api';

try {
  await devicesService.getDevice('device-id');
} catch (error) {
  if (error instanceof OmadaDeviceNotFoundError) {
    console.error('Device not found');
  } else if (error instanceof OmadaAuthenticationError) {
    console.error('Authentication failed');
  } else if (error instanceof OmadaApiError) {
    console.error('API error:', error.message);
  }
}

API Reference

See the TypeScript type definitions for complete API documentation. All services and types are fully typed.