unifi-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/CHANGELOG.md

@@ -2,15 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.2](https://github.com/rvben/unifi-cli/compare/v0.3.1...v0.3.2) - 2026-08-10
 
+### Fixed
+
+- **config**: write the config atomically on Windows too ([0c2977e](https://github.com/rvben/unifi-cli/commit/0c2977e238ccb09ca2949560568c4f8b8fd528db))
+- **config**: replace the config file atomically instead of writing in place ([9ba19fb](https://github.com/rvben/unifi-cli/commit/9ba19fbde8b498488f43b1af1ab1d2771189d672))
+- **output**: keep 408 and 429 retryable instead of permanent client errors ([1068bae](https://github.com/rvben/unifi-cli/commit/1068baed75ce232028fec0277c1ca38324723a35))
+- **ports**: keep the attachment flag tri-state instead of reading absence as gone ([de2e770](https://github.com/rvben/unifi-cli/commit/de2e770d30cbc3cba64cf5b06640549a9655c776))
+- **config**: create the credentials file with owner-only permissions ([8b7789d](https://github.com/rvben/unifi-cli/commit/8b7789d2d87edc5819e950573130000370c6939f))
+- **schema**: publish an error and confirmation contract that matches runtime ([5176ccf](https://github.com/rvben/unifi-cli/commit/5176ccfefeb08df4fecd0d7a6d83882f5e06c57f))
+- **ports**: report a stale last connection as unattached ([e80cda5](https://github.com/rvben/unifi-cli/commit/e80cda542fce27db385fc43bd69093c265ead464))
 
+## [0.3.1](https://github.com/rvben/unifi-cli/compare/v0.3.0...v0.3.1) - 2026-08-10
+
+### Added
+
+- **ports**: add ports command tree with single-port PoE power-cycling ([b14794e](https://github.com/rvben/unifi-cli/commit/b14794e976638f7c4a5a21639ebe8a8b011ab25c))
+
+### Fixed
 
+- **cli**: prompt before every destructive command, not just ports cycle ([ae49798](https://github.com/rvben/unifi-cli/commit/ae4979886d63b4dd982a3a38de34a0ff343d5f18))
+- **schema**: publish flags as boolean and port/watch as integer ([7c21144](https://github.com/rvben/unifi-cli/commit/7c21144d93afa68cb021a9191c769dea4af496ba))
+- **ports**: give the PoE class label its colon and align the detail column ([1cd56d0](https://github.com/rvben/unifi-cli/commit/1cd56d03c3e0ec12a025030a051c135a1fa0865c))
 
 ## [0.3.0](https://github.com/rvben/unifi-cli/compare/v0.2.3...v0.3.0) - 2026-07-09
 
+### Added
+
+- **clients list**: project `ssid`, `signal`, `uptime`, `network`, `vlan`, `tx_bytes`, `rx_bytes`, `blocked` and `connected_at`. Answering "which SSID is each client on" cost one API call per client; it is now one call for the whole list.
+- **networks list**: a `list` subcommand, matching `clients`, `devices` and `events`. Bare `unifi networks` still works.
+
+### Changed
+
+- **clients list**: `ip` is now the address a client currently holds, read from the live `stat/sta` record. It previously came from the integration API's `ipAddress`, which retains the last address a client ever had and outlives the lease. A client with no current lease now reports `ip: null` instead of a stale address, and `clients list` agrees with `clients show`.
+
 ### Fixed
 
 - **clients**: stop three silent-failure modes in the agent contract ([5e50bb7](https://github.com/rvben/unifi-cli/commit/5e50bb704777407acf244856bc435f7ceccd7b00))
+- **--fields**: an unknown field is now a usage error (exit 2) naming the offender and the valid set, raised before the config loads or a connection opens. It previously returned `{}` per row with exit 0, which is indistinguishable from a query that matched nothing. `schema` and `--fields` read the same field tables, so the published contract and the enforced one cannot drift.
 
 ## [0.2.3](https://github.com/rvben/unifi-cli/compare/v0.2.2...v0.2.3) - 2026-07-07
 

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/Cargo.lock

@@ -2786,7 +2786,7 @@ checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853"
 
 [[package]]
 name = "unifi-cli"
-version = "0.3.0"
+version = "0.3.2"
 dependencies = [
  "clap",
  "clap_complete",

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "unifi-cli"
-version = "0.3.0"
+version = "0.3.2"
 edition = "2024"
 rust-version = "1.90"
 description = "CLI for UniFi Network controller"

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unifi-cli
-Version: 0.3.0
+Version: 0.3.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: System Administrators
@@ -79,7 +79,17 @@ export UNIFI_ACCEPT_INVALID_CERTS=true
 
 ### Config file
 
-`~/.config/unifi/config.toml`:
+Linux: `~/.config/unifi/config.toml`.
+macOS: `~/Library/Application Support/unifi/config.toml`.
+Windows: `%APPDATA%\unifi\config.toml`.
+
+`unifi config init` writes a new file and renames it over any existing config
+instead of writing in place, so a failed write leaves the previous config
+intact. On Linux and macOS the new file is created with mode 0600, since it
+holds an API key and optionally a Protect password. Because the credentials go
+straight into a file that is already 0600, they are never readable by another
+local account, not even for the moment between the write and a chmod. On
+Windows the file inherits its directory's ACL.
 
 ```toml
 host = "https://unifi.example.com"
@@ -122,6 +132,20 @@ API keys, passwords, session cookies, and stream URLs.
 When `unifi config init` cannot verify the controller's certificate, it offers
 to trust the controller and saves `accept_invalid_certs = true` for you.
 
+### Destructive commands
+
+`clients block`, `clients unblock`, `clients kick`, `devices restart`,
+`devices upgrade`, `ports cycle` and `protect rtsps delete` all ask before they
+act. On a terminal you get a yes/no question naming the target; declining exits
+2 with `kind: confirmation_required` and sends nothing. When stdin is not a
+terminal there is nobody to ask, so they refuse with the same error unless you
+pass `--yes`, which skips the question everywhere.
+
+`unifi schema` marks exactly these commands `confirmation_required: true`, so a
+caller can tell them apart from mutating commands that act immediately
+(`devices locate`, `clients set-fixed-ip`, `protect rtsps create`) without
+hardcoding the list.
+
 ## TUI dashboard
 
 ```bash
@@ -173,6 +197,79 @@ unifi devices locate aa:bb:cc:dd:ee:ff        # Blink locate LED
 unifi devices locate aa:bb:cc:dd:ee:ff --off  # Stop blinking
 ```
 
+### Ports
+
+Find which switch port a device is plugged into, then power-cycle just that
+port instead of rebooting the whole switch:
+
+```bash
+# Which port is my Pi on? Matches by name (case-insensitive substring),
+# MAC, or IP.
+unifi ports find garage-pi
+unifi ports find aa:bb:cc:dd:ee:10
+
+# Inspect it: PoE mode, class, voltage, current, and what's attached
+unifi ports show aa:bb:cc:dd:ee:ff 5
+
+# Bounce PoE on that port only, leaving the rest of the switch untouched
+unifi ports cycle aa:bb:cc:dd:ee:ff 5
+```
+
+`ports find`'s output feeds directly into `show` and `cycle`: `device_mac`
+and `port_idx` are the *switch's* MAC and port index, not the attached
+device's. A name is ambiguous only when it matches more than one device
+that's actually on a switch port; that returns `kind: conflict` (exit 6)
+listing the candidates rather than guessing. Other client records sharing
+the name (a device's WiFi interface reporting under the same name as its
+wired one, say) don't cause a conflict if they're not themselves on a port.
+A device that has moved between switch ports appears once per port it has
+ever used, with a `connected` field distinguishing its current port from
+stale history.
+
+`ports show` exposes the port's PoE telemetry: `poe_mode`, `poe_class`,
+`poe_voltage`, `poe_current`, `poe_good`, and the MAC of the attached device
+(`attached_mac`). The controller keeps a port's last connection record after
+the device is unplugged, so `attached_mac` is set only when the controller
+affirms the record is live. The MAC is still reported as
+`attached_last_seen_mac` and the controller's own flag as `attached_connected`
+(true, false, or null when the firmware does not report it), so a caller can
+tell "gone" from "not reported". The text output renders the three cases as
+`aa:bb:cc:dd:ee:ff`, `- (last seen aa:bb:cc:dd:ee:ff)` and
+`unknown (last seen aa:bb:cc:dd:ee:ff)`. Nothing that has been unplugged is
+ever presented as currently attached.
+
+`ports cycle` is destructive. On a terminal it shows what is about to lose
+power and asks for confirmation; when piped it requires `--yes` and
+otherwise exits 2 with `kind: confirmation_required`. It reads the port
+table first, then refuses **without ever sending the power-cycle command**
+when:
+
+- the port is not PoE-capable (an SFP+ port, say) → `kind: conflict`, exit 6
+- the port's PoE is administratively off → `kind: conflict`, exit 6
+- the port isn't currently delivering PoE (`poe_enable: false`) → `kind: conflict`, exit 6
+- the device has no such port index → `kind: not_found`, exit 4
+
+The off interval (how long the port stays unpowered) is chosen by the
+switch firmware, not by this CLI. The power-cycle command takes only the
+target port, with no duration parameter, on either the legacy endpoint or
+the Integration API, so the interval isn't configurable and varies by
+device model and firmware version. IEEE 802.3 PoE detection timing imposes
+a floor regardless: expect the port to sit dark for roughly 1-2 seconds at
+minimum before power returns.
+
+List ports for one device, or across every device:
+
+```bash
+unifi ports list aa:bb:cc:dd:ee:ff
+unifi ports list --limit 20 --fields port_idx,poe_power
+```
+
+`ports list` returns the paginated `{items, total, limit, offset}` envelope
+used by the other list commands. `unifi devices ports <MAC>` remains an
+alias for `unifi ports list <MAC>`; it keeps its original bare-JSON-array
+shape for backward compatibility, and both emit the same per-row fields,
+including `device_mac` and `device_name`.
+
 ### Events
 
 ```bash
@@ -252,14 +349,21 @@ unifi schema    # Dumps all commands, arguments, output fields as JSON
 
 ### Distinct exit codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Configuration error |
-| 3 | Authentication error (401/403) |
-| 4 | Not found (404) |
-| 5 | API error (server error) |
+| Code | `kind` | Meaning |
+|------|--------|---------|
+| 0 | - | Success |
+| 1 | `general_error` | General error (including transport failures) |
+| 2 | `config_error` | Configuration or usage error |
+| 2 | `confirmation_required` | A destructive command ran without `--yes` and without a TTY |
+| 3 | `auth_error` | Authentication error (401/403) |
+| 4 | `not_found` | Not found (404) |
+| 5 | `client_error` | The controller rejected the request itself (4xx other than 401/403/404/408/429); retrying it unchanged cannot help |
+| 5 | `retry_later` | The controller invited a retry (429 rate limited, 408 request timeout); back off and send the same request again |
+| 5 | `api_error` | The controller failed to serve the request (5xx); may be transient |
+| 6 | `conflict` | The request cannot succeed against the resource's current state, refused locally before any API call |
+
+`unifi schema` publishes the same table under `errors`, with a `retryable` flag
+per kind, so an agent can branch on it without parsing prose.
 
 ## Development
 

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/README.md

@@ -58,7 +58,17 @@ export UNIFI_ACCEPT_INVALID_CERTS=true
 
 ### Config file
 
-`~/.config/unifi/config.toml`:
+Linux: `~/.config/unifi/config.toml`.
+macOS: `~/Library/Application Support/unifi/config.toml`.
+Windows: `%APPDATA%\unifi\config.toml`.
+
+`unifi config init` writes a new file and renames it over any existing config
+instead of writing in place, so a failed write leaves the previous config
+intact. On Linux and macOS the new file is created with mode 0600, since it
+holds an API key and optionally a Protect password. Because the credentials go
+straight into a file that is already 0600, they are never readable by another
+local account, not even for the moment between the write and a chmod. On
+Windows the file inherits its directory's ACL.
 
 ```toml
 host = "https://unifi.example.com"
@@ -101,6 +111,20 @@ API keys, passwords, session cookies, and stream URLs.
 When `unifi config init` cannot verify the controller's certificate, it offers
 to trust the controller and saves `accept_invalid_certs = true` for you.
 
+### Destructive commands
+
+`clients block`, `clients unblock`, `clients kick`, `devices restart`,
+`devices upgrade`, `ports cycle` and `protect rtsps delete` all ask before they
+act. On a terminal you get a yes/no question naming the target; declining exits
+2 with `kind: confirmation_required` and sends nothing. When stdin is not a
+terminal there is nobody to ask, so they refuse with the same error unless you
+pass `--yes`, which skips the question everywhere.
+
+`unifi schema` marks exactly these commands `confirmation_required: true`, so a
+caller can tell them apart from mutating commands that act immediately
+(`devices locate`, `clients set-fixed-ip`, `protect rtsps create`) without
+hardcoding the list.
+
 ## TUI dashboard
 
 ```bash
@@ -152,6 +176,79 @@ unifi devices locate aa:bb:cc:dd:ee:ff        # Blink locate LED
 unifi devices locate aa:bb:cc:dd:ee:ff --off  # Stop blinking
 ```
 
+### Ports
+
+Find which switch port a device is plugged into, then power-cycle just that
+port instead of rebooting the whole switch:
+
+```bash
+# Which port is my Pi on? Matches by name (case-insensitive substring),
+# MAC, or IP.
+unifi ports find garage-pi
+unifi ports find aa:bb:cc:dd:ee:10
+
+# Inspect it: PoE mode, class, voltage, current, and what's attached
+unifi ports show aa:bb:cc:dd:ee:ff 5
+
+# Bounce PoE on that port only, leaving the rest of the switch untouched
+unifi ports cycle aa:bb:cc:dd:ee:ff 5
+```
+
+`ports find`'s output feeds directly into `show` and `cycle`: `device_mac`
+and `port_idx` are the *switch's* MAC and port index, not the attached
+device's. A name is ambiguous only when it matches more than one device
+that's actually on a switch port; that returns `kind: conflict` (exit 6)
+listing the candidates rather than guessing. Other client records sharing
+the name (a device's WiFi interface reporting under the same name as its
+wired one, say) don't cause a conflict if they're not themselves on a port.
+A device that has moved between switch ports appears once per port it has
+ever used, with a `connected` field distinguishing its current port from
+stale history.
+
+`ports show` exposes the port's PoE telemetry: `poe_mode`, `poe_class`,
+`poe_voltage`, `poe_current`, `poe_good`, and the MAC of the attached device
+(`attached_mac`). The controller keeps a port's last connection record after
+the device is unplugged, so `attached_mac` is set only when the controller
+affirms the record is live. The MAC is still reported as
+`attached_last_seen_mac` and the controller's own flag as `attached_connected`
+(true, false, or null when the firmware does not report it), so a caller can
+tell "gone" from "not reported". The text output renders the three cases as
+`aa:bb:cc:dd:ee:ff`, `- (last seen aa:bb:cc:dd:ee:ff)` and
+`unknown (last seen aa:bb:cc:dd:ee:ff)`. Nothing that has been unplugged is
+ever presented as currently attached.
+
+`ports cycle` is destructive. On a terminal it shows what is about to lose
+power and asks for confirmation; when piped it requires `--yes` and
+otherwise exits 2 with `kind: confirmation_required`. It reads the port
+table first, then refuses **without ever sending the power-cycle command**
+when:
+
+- the port is not PoE-capable (an SFP+ port, say) → `kind: conflict`, exit 6
+- the port's PoE is administratively off → `kind: conflict`, exit 6
+- the port isn't currently delivering PoE (`poe_enable: false`) → `kind: conflict`, exit 6
+- the device has no such port index → `kind: not_found`, exit 4
+
+The off interval (how long the port stays unpowered) is chosen by the
+switch firmware, not by this CLI. The power-cycle command takes only the
+target port, with no duration parameter, on either the legacy endpoint or
+the Integration API, so the interval isn't configurable and varies by
+device model and firmware version. IEEE 802.3 PoE detection timing imposes
+a floor regardless: expect the port to sit dark for roughly 1-2 seconds at
+minimum before power returns.
+
+List ports for one device, or across every device:
+
+```bash
+unifi ports list aa:bb:cc:dd:ee:ff
+unifi ports list --limit 20 --fields port_idx,poe_power
+```
+
+`ports list` returns the paginated `{items, total, limit, offset}` envelope
+used by the other list commands. `unifi devices ports <MAC>` remains an
+alias for `unifi ports list <MAC>`; it keeps its original bare-JSON-array
+shape for backward compatibility, and both emit the same per-row fields,
+including `device_mac` and `device_name`.
+
 ### Events
 
 ```bash
@@ -231,14 +328,21 @@ unifi schema    # Dumps all commands, arguments, output fields as JSON
 
 ### Distinct exit codes
 
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 1 | General error |
-| 2 | Configuration error |
-| 3 | Authentication error (401/403) |
-| 4 | Not found (404) |
-| 5 | API error (server error) |
+| Code | `kind` | Meaning |
+|------|--------|---------|
+| 0 | - | Success |
+| 1 | `general_error` | General error (including transport failures) |
+| 2 | `config_error` | Configuration or usage error |
+| 2 | `confirmation_required` | A destructive command ran without `--yes` and without a TTY |
+| 3 | `auth_error` | Authentication error (401/403) |
+| 4 | `not_found` | Not found (404) |
+| 5 | `client_error` | The controller rejected the request itself (4xx other than 401/403/404/408/429); retrying it unchanged cannot help |
+| 5 | `retry_later` | The controller invited a retry (429 rate limited, 408 request timeout); back off and send the same request again |
+| 5 | `api_error` | The controller failed to serve the request (5xx); may be transient |
+| 6 | `conflict` | The request cannot succeed against the resource's current state, refused locally before any API call |
+
+`unifi schema` publishes the same table under `errors`, with a `retryable` flag
+per kind, so an agent can branch on it without parsing prose.
 
 ## Development
 

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/src/api/client.rs

@@ -105,7 +105,7 @@ impl UnifiClient {
                 .get_integration("/proxy/network/integration/v1/sites")
                 .await?;
             let site = resp.data.into_iter().next().ok_or_else(|| {
-                ApiError::Other("No sites found — check that the API key has site access".into())
+                ApiError::Other("No sites found. Check that the API key has site access".into())
             })?;
             self.site_id = Some(site.id);
         }
@@ -339,6 +339,18 @@ impl UnifiClient {
         Ok(())
     }
 
+    /// Power-cycle a single PoE port. `mac` is the **switch's** MAC, not the
+    /// attached device's.
+    pub async fn power_cycle_port(&self, mac: &str, port_idx: u32) -> Result<(), ApiError> {
+        let formatted = format_mac(&normalize_mac(mac));
+        self.post_legacy_cmd(
+            "devmgr",
+            serde_json::json!({"cmd": "power-cycle", "mac": formatted, "port_idx": port_idx}),
+        )
+        .await?;
+        Ok(())
+    }
+
     pub async fn upgrade_device(&self, mac: &str) -> Result<(), ApiError> {
         let formatted = format_mac(&normalize_mac(mac));
         self.post_legacy_cmd(
@@ -407,6 +419,13 @@ impl UnifiClient {
             .ok_or_else(|| ApiError::NotFound(format!("Device with MAC {mac}")))
     }
 
+    /// Every device that reports a port table, in one request. `/stat/device`
+    /// already returns all devices with their port tables, so the unfiltered
+    /// listing costs no more than the filtered one.
+    pub async fn list_all_device_ports(&self) -> Result<Vec<DeviceWithPorts>, ApiError> {
+        self.get_legacy("/stat/device").await
+    }
+
     // All clients with bandwidth data (legacy endpoint for richer stats)
     pub async fn list_clients_legacy(&self) -> Result<Vec<LegacyClient>, ApiError> {
         self.get_legacy("/stat/sta").await
@@ -558,7 +577,7 @@ impl ProtectSession {
     ) -> Result<Self, ApiError> {
         let base_url = normalize_base_url(host)?;
 
-        // Don't use cookie_provider — the `partitioned` cookie attribute
+        // Don't use cookie_provider: the `partitioned` cookie attribute
         // isn't handled by reqwest's jar. We extract the token manually.
         let http = reqwest::Client::builder()
             .danger_accept_invalid_certs(options.accept_invalid_certs)

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/src/api/mod.rs

@@ -6,7 +6,7 @@ pub use client::ProtectSession;
 pub use client::UnifiClient;
 pub use client::error_for_status;
 pub use types::{
-    ApiError, Client, Device, DeviceWithPorts, Event, HealthSubsystem, HostSystem, LegacyClient,
-    LegacyDevice, LegacyResponse, Network, PortEntry, SysInfo, format_bytes, format_mac,
-    format_uptime, normalize_mac,
+    ApiError, Client, Device, DeviceWithPorts, Event, HealthSubsystem, HostSystem, LastConnection,
+    LegacyClient, LegacyDevice, LegacyResponse, Network, PortEntry, SysInfo, format_bytes,
+    format_mac, format_uptime, normalize_mac,
 };

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/src/api/tests.rs

@@ -145,6 +145,17 @@ fn api_error_display_auth() {
     assert!(display.contains("Hint:"));
 }
 
+#[test]
+fn api_error_display_conflict_has_no_prefix() {
+    // Unlike Auth/NotFound (sentence fragments that get a prefix added),
+    // Conflict messages are written whole, to be read by an operator as-is.
+    let err = ApiError::Conflict("Port 5 on aa:bb:cc:dd:ee:ff does not support PoE.".into());
+    assert_eq!(
+        err.to_string(),
+        "Port 5 on aa:bb:cc:dd:ee:ff does not support PoE."
+    );
+}
+
 #[test]
 fn api_error_display_other() {
     let err = ApiError::Other("something went wrong".into());
@@ -762,7 +773,7 @@ fn client_clean_name_falls_back_to_hostname() {
 
 #[test]
 fn client_clean_name_hyphenated_not_stripped() {
-    // "host-ee:ff" has no space before the hex — it's part of the hostname, not a MAC suffix
+    // "host-ee:ff" has no space before the hex, so it's part of the hostname, not a MAC suffix
     let json = r#"{"hostname": "host-ee:ff", "macAddress": "aa:bb:cc:dd:ee:ff"}"#;
     let client: Client = serde_json::from_str(json).unwrap();
     assert_eq!(client.clean_name(), "host-ee:ff");
@@ -812,3 +823,70 @@ fn legacy_client_clean_name_no_mac() {
     let client: LegacyClient = serde_json::from_str(json).unwrap();
     assert_eq!(client.clean_name(), "device ee:ff");
 }
+
+// --- PortEntry PoE telemetry ---
+
+#[test]
+fn port_entry_parses_poe_telemetry_with_string_numbers() {
+    // The controller returns poe_voltage/poe_current/poe_power as JSON
+    // strings on some firmware, the same quirk PR #3 fixed for poe_power.
+    let json = serde_json::json!({
+        "port_idx": 3,
+        "name": "Port 3",
+        "up": true,
+        "port_poe": true,
+        "poe_enable": true,
+        "poe_mode": "auto",
+        "poe_class": "Class 3",
+        "poe_power": "5.00",
+        "poe_voltage": "53.75",
+        "poe_current": "93.00",
+        "poe_good": true,
+        "autoneg": true,
+        "enable": true,
+        "is_uplink": false,
+        "stp_state": "forwarding",
+        "tx_errors": 0,
+        "rx_errors": 0,
+        "last_connection": {
+            "mac": "aa:bb:cc:dd:ee:20",
+            "connected": true,
+            "last_seen": 1783622695
+        }
+    });
+    let p: PortEntry = serde_json::from_value(json).expect("PortEntry must parse");
+    assert_eq!(p.poe_mode.as_deref(), Some("auto"));
+    assert_eq!(p.poe_class.as_deref(), Some("Class 3"));
+    assert_eq!(p.poe_voltage, Some(53.75));
+    assert_eq!(p.poe_current, Some(93.00));
+    assert_eq!(p.poe_good, Some(true));
+    assert_eq!(p.stp_state.as_deref(), Some("forwarding"));
+    assert_eq!(p.autoneg, Some(true));
+    assert_eq!(p.enable, Some(true));
+    assert_eq!(p.is_uplink, Some(false));
+    let lc = p.last_connection.expect("last_connection present");
+    assert_eq!(lc.mac.as_deref(), Some("aa:bb:cc:dd:ee:20"));
+    assert_eq!(lc.connected, Some(true));
+}
+
+#[test]
+fn port_entry_tolerates_absent_last_connection() {
+    // A port nothing has ever linked to omits last_connection entirely.
+    // This is exactly how the empty test-target port was identified.
+    let json = serde_json::json!({
+        "port_idx": 4,
+        "name": "Port 4",
+        "up": false,
+        "port_poe": true,
+        "poe_enable": false,
+        "poe_mode": "auto"
+    });
+    let p: PortEntry = serde_json::from_value(json).expect("PortEntry must parse");
+    assert!(p.last_connection.is_none());
+    assert_eq!(p.poe_voltage, None);
+    assert!(!p.up);
+    // Absent tri-state keys must read as unknown, never as a confident "no".
+    assert_eq!(p.enable, None, "absent enable must not read as disabled");
+    assert_eq!(p.autoneg, None);
+    assert_eq!(p.is_uplink, None);
+}

{unifi_cli-0.3.0 → unifi_cli-0.3.2}/src/api/types.rs

@@ -302,10 +302,43 @@ pub struct PortEntry {
     pub poe_power: Option<f64>,
     #[serde(default)]
     pub port_poe: bool,
+    /// "auto", "off", "passthrough", "passive24v". Absent on some firmware.
+    pub poe_mode: Option<String>,
+    pub poe_class: Option<String>,
+    #[serde(default, deserialize_with = "deserialize_string_or_number_f64")]
+    pub poe_voltage: Option<f64>,
+    #[serde(default, deserialize_with = "deserialize_string_or_number_f64")]
+    pub poe_current: Option<f64>,
+    pub poe_good: Option<bool>,
+    /// Auto-negotiation state. `Option`, not a defaulted bool, like `enable`
+    /// and `is_uplink` below: a firmware that omits this key must not be
+    /// reported as "auto-negotiation off". Matches `poe_good` above; contrast
+    /// `up`/`poe_enable`, where an absent key genuinely does mean false.
+    pub autoneg: Option<bool>,
+    /// Administrative enable state. Same tri-state rationale as `autoneg`: an
+    /// absent key must not be reported as "port administratively disabled".
+    pub enable: Option<bool>,
+    /// Whether this port is the switch's uplink. Same tri-state rationale as
+    /// `autoneg`: an absent key must not be reported as "not an uplink".
+    pub is_uplink: Option<bool>,
+    pub stp_state: Option<String>,
+    pub tx_errors: Option<u64>,
+    pub rx_errors: Option<u64>,
+    /// Absent entirely on a port nothing has linked to within retention.
+    pub last_connection: Option<LastConnection>,
     pub tx_bytes: Option<u64>,
     pub rx_bytes: Option<u64>,
 }
 
+/// The device most recently seen on a port. `connected` distinguishes a live
+/// attachment from a stale record of a device that has since moved.
+#[derive(Debug, Deserialize)]
+pub struct LastConnection {
+    pub mac: Option<String>,
+    pub connected: Option<bool>,
+    pub last_seen: Option<u64>,
+}
+
 fn deserialize_string_or_number_f64<'de, D>(deserializer: D) -> Result<Option<f64>, D::Error>
 where
     D: serde::Deserializer<'de>,
@@ -485,9 +518,16 @@ pub type RtspsStreams = std::collections::HashMap<String, Option<String>>;
 #[derive(Debug)]
 pub enum ApiError {
     Http(reqwest::Error),
-    Api { status: u16, message: String },
+    Api {
+        status: u16,
+        message: String,
+    },
     NotFound(String),
     Auth(String),
+    /// A request that cannot succeed against the resource's current state,
+    /// rejected locally before any HTTP call. Published by `unifi schema`
+    /// as kind `conflict`, exit code 6.
+    Conflict(String),
     Other(String),
 }
 
@@ -570,6 +610,7 @@ impl fmt::Display for ApiError {
                     "\n  Hint: Check your API key. Generate one in UniFi Settings > API"
                 )
             }
+            ApiError::Conflict(msg) => write!(f, "{msg}"),
             ApiError::Other(msg) => write!(f, "{msg}"),
         }
     }