diff --git a/UniFi-Client.-.md b/UniFi-Client.-.md deleted file mode 100644 index 1e5d13b..0000000 --- a/UniFi-Client.-.md +++ /dev/null @@ -1,207 +0,0 @@ -# UniFi Client - -Full API reference for the `unifi` package. See [[Home]] for installation and configuration. - -## Client - -### Creating a Client - -```go -import "forge.lthn.ai/core/go-netops/unifi" - -// From config file + env vars + flag overrides (recommended) -client, err := unifi.NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey, nil) - -// Direct construction -client, err := unifi.New(url, user, pass, apikey, insecure) -``` - -- **`NewFromConfig(flagURL, flagUser, flagPass, flagAPIKey string, flagInsecure *bool)`** -- Resolves credentials from config/env/flags. Returns error if no credentials are configured. -- **`New(url, user, pass, apikey string, insecure bool)`** -- Creates a client directly. Set `insecure` to `true` for self-signed certificates (home lab controllers). - -### Client Methods - -```go -client.API() *uf.Unifi // Access underlying unpoller SDK client -client.URL() string // Controller URL -``` - -## Configuration - -### Config Resolution - -`ResolveConfig` merges all three config sources: - -```go -url, user, pass, apikey, insecure, err := unifi.ResolveConfig( - flagURL, flagUser, flagPass, flagAPIKey, flagInsecure, -) -``` - -### Persisting Config - -```go -err := unifi.SaveConfig(url, user, pass, apikey, insecurePtr) -``` - -Writes to `~/.core/config.yaml` under the `unifi.*` keys. - -### Config Constants - -| Constant | Key | Env Var | -|---|---|---| -| `ConfigKeyURL` | `unifi.url` | `UNIFI_URL` | -| `ConfigKeyUser` | `unifi.user` | `UNIFI_USER` | -| `ConfigKeyPass` | `unifi.pass` | `UNIFI_PASS` | -| `ConfigKeyAPIKey` | `unifi.apikey` | `UNIFI_APIKEY` | -| `ConfigKeyInsecure` | `unifi.insecure` | `UNIFI_INSECURE` | - -## Sites - -```go -sites, err := client.GetSites() // returns []*uf.Site -``` - -Returns all sites registered on the controller. - -## Clients (Connected Devices) - -### ClientFilter - -```go -type ClientFilter struct { - Site string // Filter by site name (empty = all sites) - Wired bool // Show only wired clients - Wireless bool // Show only wireless clients -} -``` - -### Querying Clients - -```go -// All clients across all sites -clients, err := client.GetClients(unifi.ClientFilter{}) - -// Wireless clients on "default" site -clients, err := client.GetClients(unifi.ClientFilter{ - Site: "default", - Wireless: true, -}) -``` - -Returns `[]*uf.Client` from the unpoller SDK. - -## Networks - -### NetworkConf - -```go -type NetworkConf struct { - ID string `json:"_id"` - Name string `json:"name"` - Purpose string `json:"purpose"` // wan, corporate, remote-user-vpn - IPSubnet string `json:"ip_subnet"` // CIDR e.g. "10.69.1.1/24" - VLAN int `json:"vlan"` - VLANEnabled bool `json:"vlan_enabled"` - Enabled bool `json:"enabled"` - NetworkGroup string `json:"networkgroup"` // LAN, WAN, WAN2 - NetworkIsolationEnabled bool `json:"network_isolation_enabled"` - InternetAccessEnabled bool `json:"internet_access_enabled"` - IsNAT bool `json:"is_nat"` - DHCPEnabled bool `json:"dhcpd_enabled"` - DHCPStart string `json:"dhcpd_start"` - DHCPStop string `json:"dhcpd_stop"` - DHCPDNS1 string `json:"dhcpd_dns_1"` - DHCPDNS2 string `json:"dhcpd_dns_2"` - MDNSEnabled bool `json:"mdns_enabled"` - // ... additional fields for firewall, VPN, WAN config -} -``` - -### Querying Networks - -```go -// Get all networks for a site (empty string defaults to "default") -networks, err := client.GetNetworks("default") -``` - -Uses the raw controller API (`/api/s/{site}/rest/networkconf`) for full `networkconf` data. - -## Routes - -### Route - -```go -type Route struct { - Network string `json:"pfx"` // CIDR prefix e.g. "10.69.1.0/24" - NextHop string `json:"nh"` // Next-hop address or interface - Interface string `json:"intf"` // e.g. "br0", "eth4" - Type string `json:"type"` // "S" static, "C" connected, "K" kernel, "B" bgp, "O" ospf - Distance int `json:"distance"` // Administrative distance - Metric int `json:"metric"` - Uptime int `json:"uptime"` // Seconds - Selected bool `json:"fib"` // In forwarding table -} -``` - -### Querying Routes - -```go -routes, err := client.GetRoutes("default") - -// Human-readable route type -name := unifi.RouteTypeName("S") // "static" -``` - -Uses the raw controller API (`/api/s/{site}/stat/routing`). - -### Route Type Codes - -| Code | Name | -|---|---| -| `S` | static | -| `C` | connected | -| `K` | kernel | -| `B` | bgp | -| `O` | ospf | - -## Devices - -### DeviceInfo - -A flat representation of any UniFi infrastructure device: - -```go -type DeviceInfo struct { - Name string - IP string - Mac string - Model string - Version string - Type string // uap, usw, usg, udm, uxg - Status int // 1 = online -} -``` - -### Querying Devices - -```go -// Raw device container (access points, switches, gateways, etc.) -devices, err := client.GetDevices("default") // returns *uf.Devices - -// Flat list with optional type filter -all, err := client.GetDeviceList("default", "") // all device types -aps, err := client.GetDeviceList("default", "uap") // access points only -sws, err := client.GetDeviceList("default", "usw") // switches only -gws, err := client.GetDeviceList("default", "udm") // dream machines -``` - -### Device Types - -| Type | Description | -|---|---| -| `uap` | UniFi Access Points | -| `usw` | UniFi Switches | -| `usg` | UniFi Security Gateways | -| `udm` | UniFi Dream Machines | -| `uxg` | UniFi Next-Gen Gateways |