ui-cli 1.2.1__py3-none-any.whl

ui_cli/__init__.py

@@ -0,0 +1,31 @@
+"""UniFi Site Manager CLI - Manage your UniFi infrastructure from the command line."""
+
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+
+def _version_file_path() -> Path:
+    """Return the repository version file path when running from a source checkout."""
+    return Path(__file__).resolve().parents[2] / "VERSION"
+
+
+def _read_version_file() -> str:
+    """Read the repository version during local source execution."""
+    version_file = _version_file_path()
+    if version_file.exists():
+        return version_file.read_text(encoding="utf-8").strip()
+    return "0.0.0"
+
+
+def _detect_version() -> str:
+    """Prefer the checkout version file and fall back to installed package metadata."""
+    version_file = _version_file_path()
+    if version_file.exists():
+        return version_file.read_text(encoding="utf-8").strip()
+    try:
+        return version("ui-cli")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+__version__ = _detect_version()

ui_cli/client.py

@@ -0,0 +1,269 @@
+"""Async HTTP client for UniFi Site Manager API."""
+
+from typing import Any
+
+import httpx
+
+from ui_cli.config import settings
+
+
+class APIError(Exception):
+    """Base exception for API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class AuthenticationError(APIError):
+    """Raised when API key is invalid or missing."""
+
+    pass
+
+
+class RateLimitError(APIError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str, retry_after: int | None = None):
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class UniFiClient:
+    """Async client for UniFi Site Manager API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: int | None = None,
+    ):
+        self.api_key = api_key or settings.api_key
+        self.base_url = (base_url or settings.api_url).rstrip("/")
+        self.timeout = timeout or settings.timeout
+
+        if not self.api_key:
+            raise AuthenticationError(
+                "API key not configured. Set UNIFI_API_KEY environment variable or create a .env file."
+            )
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get request headers with authentication."""
+        return {
+            "X-API-Key": self.api_key,
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make an authenticated request to the API."""
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.request(
+                method=method,
+                url=url,
+                headers=self._get_headers(),
+                params=params,
+            )
+
+            # Handle errors
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid API key", status_code=401)
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    retry_after=int(retry_after) if retry_after else None,
+                )
+            elif response.status_code >= 400:
+                raise APIError(
+                    f"API error: {response.text}",
+                    status_code=response.status_code,
+                )
+
+            return response.json()
+
+    async def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Make a GET request."""
+        return await self._request("GET", endpoint, params=params)
+
+    # ========== Hosts ==========
+
+    async def list_hosts(self) -> list[dict[str, Any]]:
+        """List all hosts associated with the account."""
+        response = await self.get("/hosts")
+        return response.get("data", [])
+
+    async def get_host(self, host_id: str) -> dict[str, Any]:
+        """Get details for a specific host."""
+        response = await self.get(f"/hosts/{host_id}")
+        return response.get("data", {})
+
+    # ========== Sites ==========
+
+    async def list_sites(self) -> list[dict[str, Any]]:
+        """List all sites."""
+        response = await self.get("/sites")
+        return response.get("data", [])
+
+    # ========== Devices ==========
+
+    async def list_devices_raw(
+        self,
+        host_ids: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """List all devices grouped by host (raw API response)."""
+        params = {}
+        if host_ids:
+            params["hostIds[]"] = host_ids
+        response = await self.get("/devices", params=params if params else None)
+        return response.get("data", [])
+
+    async def list_devices(
+        self,
+        host_ids: list[str] | None = None,
+    ) -> list[dict[str, Any]]:
+        """List all devices, flattened with host info included."""
+        raw_data = await self.list_devices_raw(host_ids=host_ids)
+
+        # Flatten: API returns devices grouped by host
+        devices = []
+        for host_group in raw_data:
+            host_id = host_group.get("hostId", "")
+            host_name = host_group.get("hostName", "")
+            for device in host_group.get("devices", []):
+                # Add host info to each device
+                device["hostId"] = host_id
+                device["hostName"] = host_name
+                devices.append(device)
+
+        return devices
+
+    # ========== ISP Metrics (Early Access API) ==========
+
+    async def get_isp_metrics(
+        self,
+        metric_type: str = "1h",
+        duration_hours: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get ISP metrics.
+
+        Args:
+            metric_type: Either '5m' (24h retention) or '1h' (30d retention)
+            duration_hours: Hours of data to retrieve. Defaults to 24 for 5m, 168 (7 days) for 1h
+
+        Note: Uses Early Access API endpoint (/ea/)
+        """
+        from datetime import datetime, timedelta, timezone
+
+        # Set default duration based on metric type
+        if duration_hours is None:
+            duration_hours = 24 if metric_type == "5m" else 168  # 7 days for hourly
+
+        # Calculate timestamps
+        end_time = datetime.now(timezone.utc)
+        begin_time = end_time - timedelta(hours=duration_hours)
+
+        params = {
+            "beginTimestamp": begin_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "endTimestamp": end_time.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        }
+
+        # ISP metrics uses EA endpoint, not v1
+        ea_url = self.base_url.replace("/v1", "/ea")
+        url = f"{ea_url}/isp-metrics/{metric_type}"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(url, headers=self._get_headers(), params=params)
+
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid API key", status_code=401)
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    retry_after=int(retry_after) if retry_after else None,
+                )
+            elif response.status_code >= 400:
+                raise APIError(
+                    f"API error: {response.text}",
+                    status_code=response.status_code,
+                )
+
+            raw_data = response.json().get("data", [])
+
+            # Flatten the nested structure
+            metrics = []
+            for site_data in raw_data:
+                site_id = site_data.get("siteId", "")
+                host_id = site_data.get("hostId", "")
+                for period in site_data.get("periods", []):
+                    wan_data = period.get("data", {}).get("wan", {})
+                    metrics.append({
+                        "siteId": site_id,
+                        "hostId": host_id,
+                        "timestamp": period.get("metricTime", ""),
+                        "avgLatency": wan_data.get("avgLatency"),
+                        "maxLatency": wan_data.get("maxLatency"),
+                        "downloadKbps": wan_data.get("download_kbps"),
+                        "uploadKbps": wan_data.get("upload_kbps"),
+                        "uptime": wan_data.get("uptime"),
+                        "downtime": wan_data.get("downtime"),
+                        "packetLoss": wan_data.get("packetLoss"),
+                        "ispName": wan_data.get("ispName"),
+                        "ispAsn": wan_data.get("ispAsn"),
+                    })
+
+            return metrics
+
+    # ========== SD-WAN (Early Access API) ==========
+
+    async def _ea_get(self, endpoint: str) -> dict[str, Any]:
+        """Make a GET request to the Early Access API."""
+        ea_url = self.base_url.replace("/v1", "/ea")
+        url = f"{ea_url}/{endpoint.lstrip('/')}"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            response = await client.get(url, headers=self._get_headers())
+
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid API key", status_code=401)
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    retry_after=int(retry_after) if retry_after else None,
+                )
+            elif response.status_code >= 400:
+                raise APIError(
+                    f"API error: {response.text}",
+                    status_code=response.status_code,
+                )
+
+            return response.json()
+
+    async def list_sdwan_configs(self) -> list[dict[str, Any]]:
+        """List all SD-WAN configurations."""
+        response = await self._ea_get("/sd-wan-configs")
+        return response.get("data", [])
+
+    async def get_sdwan_config(self, config_id: str) -> dict[str, Any]:
+        """Get details for a specific SD-WAN configuration."""
+        response = await self._ea_get(f"/sd-wan-configs/{config_id}")
+        return response.get("data", {})
+
+    async def get_sdwan_status(self, config_id: str) -> dict[str, Any]:
+        """Get deployment status for a specific SD-WAN configuration."""
+        response = await self._ea_get(f"/sd-wan-configs/{config_id}/status")
+        return response.get("data", {})

ui_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules."""

ui_cli/commands/devices.py

@@ -0,0 +1,187 @@
+"""Device management commands."""
+
+import asyncio
+from collections import Counter
+from enum import Enum
+from typing import Annotated
+
+import typer
+
+from ui_cli.client import APIError, UniFiClient
+from ui_cli.output import (
+    OutputFormat,
+    output_count_table,
+    output_csv,
+    output_json,
+    print_error,
+    render_output,
+)
+
+app = typer.Typer(help="Manage UniFi devices")
+
+# Column definitions for devices table
+DEVICE_COLUMNS = [
+    ("id", "ID"),
+    ("name", "Name"),
+    ("model", "Model"),
+    ("ip", "IP Address"),
+    ("mac", "MAC"),
+    ("productLine", "Product Line"),
+    ("status", "Status"),
+    ("version", "Version"),
+    ("hostName", "Host"),
+]
+
+
+class GroupBy(str, Enum):
+    """Device grouping options."""
+
+    HOST = "host"
+    MODEL = "model"
+    STATUS = "status"
+    PRODUCT_LINE = "product-line"
+
+
+@app.command("list")
+def list_devices(
+    host: Annotated[
+        str | None,
+        typer.Option(
+            "--host",
+            "-H",
+            help="Filter devices by host ID",
+        ),
+    ] = None,
+    output: Annotated[
+        OutputFormat,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: table, json, or csv",
+        ),
+    ] = OutputFormat.TABLE,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show detailed request/response information",
+        ),
+    ] = False,
+) -> None:
+    """List all UniFi devices managed by your hosts."""
+
+    async def _list() -> list:
+        client = UniFiClient()
+        host_ids = [host] if host else None
+        return await client.list_devices(host_ids=host_ids)
+
+    try:
+        devices = asyncio.run(_list())
+
+        if verbose:
+            typer.echo(f"Found {len(devices)} device(s)")
+
+        render_output(
+            data=devices,
+            output_format=output,
+            columns=DEVICE_COLUMNS,
+            title="UniFi Devices",
+            verbose=verbose,
+        )
+    except APIError as e:
+        print_error(e.message)
+        raise typer.Exit(1)
+
+
+@app.command("count")
+def count_devices(
+    by: Annotated[
+        GroupBy | None,
+        typer.Option(
+            "--by",
+            "-b",
+            help="Group count by: host, model, status, or product-line",
+        ),
+    ] = None,
+    host: Annotated[
+        str | None,
+        typer.Option(
+            "--host",
+            "-H",
+            help="Filter devices by host ID",
+        ),
+    ] = None,
+    output: Annotated[
+        OutputFormat,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output format: table, json, or csv",
+        ),
+    ] = OutputFormat.TABLE,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Show detailed request/response information",
+        ),
+    ] = False,
+) -> None:
+    """Count devices with optional grouping."""
+
+    async def _list() -> list:
+        client = UniFiClient()
+        host_ids = [host] if host else None
+        return await client.list_devices(host_ids=host_ids)
+
+    try:
+        devices = asyncio.run(_list())
+
+        if by is None:
+            # Simple total count
+            count_data = {"total": len(devices)}
+
+            if output == OutputFormat.JSON:
+                output_json(count_data, verbose=verbose)
+            elif output == OutputFormat.CSV:
+                output_csv([count_data])
+            else:
+                typer.echo(f"Total devices: {len(devices)}")
+            return
+
+        # Group by specified field
+        key_map = {
+            GroupBy.HOST: ("hostName", "Host"),
+            GroupBy.MODEL: ("model", "Model"),
+            GroupBy.STATUS: ("status", "Status"),
+            GroupBy.PRODUCT_LINE: ("productLine", "Product Line"),
+        }
+
+        field_key, header = key_map[by]
+        counts: Counter = Counter()
+
+        for device in devices:
+            value = device.get(field_key, "Unknown") or "Unknown"
+            counts[value] += 1
+
+        if output == OutputFormat.JSON:
+            output_json(dict(counts), verbose=verbose)
+        elif output == OutputFormat.CSV:
+            csv_data = [{header: k, "Count": v} for k, v in counts.items()]
+            output_csv(csv_data)
+        else:
+            output_count_table(
+                counts=dict(counts),
+                group_header=header,
+                count_header="Count",
+                title=f"Device Count by {header}",
+            )
+
+        if verbose:
+            typer.echo(f"Total: {sum(counts.values())} device(s)")
+
+    except APIError as e:
+        print_error(e.message)
+        raise typer.Exit(1)