Initial commit: Omada API TypeScript library

README.md

@@ -0,0 +1,188 @@
+# 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.
+