189 lines
4.1 KiB
Markdown
189 lines
4.1 KiB
Markdown
# Omada API Library
|
|
|
|
TypeScript library for interacting with TP-Link Omada Controller REST API.
|
|
|
|
## Features
|
|
|
|
- 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
|
|
|
|
```bash
|
|
pnpm install
|
|
pnpm build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Basic Setup
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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.
|
|
|