UniFi Go Library Development

Expert assistant for developing with **github.com/unpoller/unifi/v5**, a Go library that pulls data from Ubiquiti UniFi controllers (clients, devices, sites, alarms, events, etc.). This library is read-only by design and does not modify controller settings.

Project Context

**Entry point**: `unifi.NewUnifi(config *Config)` → authenticated `*Unifi` client

**Typical usage flow**:

1. Create `Config` with controller URL and credentials

2. Call `NewUnifi(config)` to get authenticated client

3. Call `GetSites()` to retrieve sites

4. Call `GetClients(sites)` or `GetDevices(sites)` for data

5. Optionally fetch `GetAlarms`, `GetEvents`, `GetAnomalies`, etc.

**Returns**: Strongly-typed structs including `[]*Site`, `[]*Client`, `*Devices` (with device type slices: `UAPs`, `USWs`, `USGs`, `UDMs`, `UXGs`, `PDUs`, `UBBs`, `UCIs`), plus alarms, events, DPI stats, and traffic data.

Instructions

1. Follow Go Coding Standards

**Linting**: Project uses `.golangci.yaml` with strict rules:

**Error handling**:

**Imports**:

**Pre-commit checks**:

```bash

golangci-lint run

go test ./...

```

2. Write Tests Following Project Patterns

**Test package naming**: Use `package unifi` with `// nolint: testpackage` where needed

**Test structure**:

**Example test pattern**:

```go

func TestGetDevices(t *testing.T) {

t.Parallel()

client := &mocks.MockUnifi{

// setup mock

}

devices, err := client.GetDevices(sites)

require.NoError(t, err)

assert.NotEmpty(t, devices.UAPs)

}

```

3. Understand UniFi API Patterns

**Local Controller Authentication**:

**Endpoint pattern**: `/api/s/{site}/...` where `{site}` is typically `"default"`. UDM Pro requires `/proxy/network` prefix.

**Response format**:

```json

{

"data": [...],

"meta": {"rc": "ok", "count": 10}

}

```

**Error format**:

```json

{

"data": [],

"meta": {"msg": "api.err.LoginRequired", "rc": "error"}

}

```

**Key endpoints** (constants in `types.go`):

**Code patterns**:

4. Remote Site Manager API (Cloud)

**Base URL**: `https://api.ui.com/v1/`

**Authentication**: API key in `X-API-Key` header (read-only)

**Rate limits**:

**Implementation**: See `remote.go` (`RemoteAPIClient`) for discovering consoles and sites managed via UniFi Site Manager.

5. Architecture Patterns

**Package layout**:

**UnifiClient interface**: Defined in `types.go`

**Config structure**:

6. Adding New Features

When extending the library:

**Follow existing patterns**:

**For new device/client types**:

1. Extend `Devices` struct with new slice field

2. Update `parseDevices` to handle new type detection

3. Add getter method following `GetUAPs`/`GetUSWs` style

4. Update `mocks.MockUnifi` to implement new methods

5. Verify interface compliance: `var _ unifi.UnifiClient = &YourClient{}`

**For new endpoints**:

1. Add constant to `types.go` (e.g., `APINewEndpointPath`)

2. Create method following pattern: `func (u *Unifi) GetNewData(site *Site) (*NewData, error)`

3. Use `fmt.Sprintf(APINewEndpointPath, site.Name)` for path

4. Add response struct with proper JSON tags

5. Write tests with mocked responses

7. Common Tasks

**Adding a new device type**:

1. Define struct in appropriate file with JSON tags

2. Add slice field to `Devices`: `NewDevices []*NewDevice`

3. Update `parseDevices` switch statement

4. Add getter: `func (d *Devices) GetNewDevices() []*NewDevice`

5. Update mocks and add tests

**Adding a new data endpoint**:

1. Add constant: `const APINewDataPath = "/api/s/%s/stat/newdata"`

2. Create method: `func (u *Unifi) GetNewData(sites []*Site) (*NewDataResponse, error)`

3. Loop sites, call `u.GetData`, aggregate results

4. Add mock implementation

5. Write unit tests

**Debugging API calls**:

Constraints

Example Usage

```go

// Create config

config := &unifi.Config{

URL: "https://unifi.example.com:8443",

User: "admin",

Pass: "password",

ErrorLog: log.Printf,

DebugLog: log.Printf,

}

// Create client

client, err := unifi.NewUnifi(config)

if err != nil {

log.Fatal(err)

}

// Get sites

sites, err := client.GetSites()

if err != nil {

log.Fatal(err)

}

// Get devices

devices, err := client.GetDevices(sites)

if err != nil {

log.Fatal(err)

}

// Access specific device types

for _, uap := range devices.UAPs {

fmt.Printf("AP: %s (%s)\n", uap.Name, uap.Mac)

}

```