feat(cloud-sdk): authenticate client requests

packages/cloud-platform/cloud/sdk/client.py

@@ -13,6 +13,21 @@ from typing import Any
 import httpx
 
 
+class CloudAPIError(httpx.HTTPStatusError):
+    def __init__(self, response: httpx.Response, detail: str) -> None:
+        super().__init__(
+            f"cloud API request failed with status {response.status_code}: {detail}",
+            request=response.request,
+            response=response,
+        )
+        self.status_code = response.status_code
+        self.detail = detail
+
+
+class CloudAuthorizationError(CloudAPIError):
+    pass
+
+
 class CloudClient:
     """A minimal Python wrapper for the platform SDK's ``/v1`` routes."""
 
@@ -22,9 +37,15 @@ class CloudClient:
         *,
         http_client: httpx.Client | Any = None,
         api_prefix: str = "/v1",
+        token: str | None = None,
+        auth: httpx.Auth | None = None,
     ) -> None:
+        if token is not None and auth is not None:
+            raise ValueError("token and auth are mutually exclusive")
         self._base_url = base_url.rstrip("/")
         self._api_prefix = api_prefix.rstrip("/")
+        self._headers = {"Authorization": f"Bearer {token}"} if token else None
+        self._auth = auth
         if http_client is None:
             self._http = httpx.Client(base_url=self._base_url)
             self._owns_client = True
@@ -61,32 +82,27 @@ class CloudClient:
                 "driver_type": driver_type,
                 "capability_tags": list(capability_tags or []),
             }
-        resp = self._http.post(self._url("/tasks"), json=payload)
-        resp.raise_for_status()
+        resp = self._request("POST", "/tasks", json=payload)
         return resp.json()
 
     def get_task_status(self, task_id: str) -> dict[str, Any]:
-        resp = self._http.get(self._url(f"/tasks/{task_id}"))
-        resp.raise_for_status()
+        resp = self._request("GET", f"/tasks/{task_id}")
         return resp.json()
 
     # ----------------------------------------------------------------- devices
 
     def list_devices(self) -> list[dict[str, Any]]:
-        resp = self._http.get(self._url("/devices"))
-        resp.raise_for_status()
+        resp = self._request("GET", "/devices")
         return resp.json()
 
     def list_hosts(self) -> list[dict[str, Any]]:
-        resp = self._http.get(self._url("/hosts"))
-        resp.raise_for_status()
+        resp = self._request("GET", "/hosts")
         return resp.json()
 
     # ----------------------------------------------------------------- plugins
 
     def list_plugins(self) -> list[dict[str, Any]]:
-        resp = self._http.get(self._url("/plugins"))
-        resp.raise_for_status()
+        resp = self._request("GET", "/plugins")
         return resp.json()
 
     def register_plugin(
@@ -103,11 +119,38 @@ class CloudClient:
             "entry_point_kind": entry_point_kind,
             "target": target,
         }
-        resp = self._http.post(self._url("/plugins"), json=payload)
-        resp.raise_for_status()
+        resp = self._request("POST", "/plugins", json=payload)
         return resp.json()
 
     # ------------------------------------------------------------------ helpers
 
     def _url(self, path: str) -> str:
         return f"{self._base_url}{self._api_prefix}{path}"
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        response = self._http.request(
+            method,
+            self._url(path),
+            json=json,
+            headers=self._headers,
+            auth=self._auth,
+        )
+        if response.is_success:
+            return response
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        detail = payload.get("detail") or "request rejected"
+        error_type = (
+            CloudAuthorizationError
+            if response.status_code in {401, 403}
+            else CloudAPIError
+        )
+        raise error_type(response, str(detail))