Release 0.1.1

Author: ludvikroed

CHANGELOG.md

@@ -6,9 +6,16 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
-### Added
+## [0.1.1] - 2026-03-17
+
+### Changed
+
+- Reduced log noise and shortened identifiers in websocket and client logging.
+- Improved error classification so auth failures surface as auth errors in more SDK methods.
+
+### Fixed
 
-- Initial packaging, tests, CI, and release setup.
+- Malformed successful API responses now raise SDK response errors instead of raw Python exceptions.
 
 ## [0.1.0] - 2026-03-16
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-homely"
-version = "0.1.0"
+version = "0.1.1"
 description = "Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere."
 readme = "README.md"
 requires-python = ">=3.12"

src/homely/__init__.py

@@ -1,6 +1,6 @@
 """Reusable Homely client package extracted from the integration."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 from .client import (
     BASE_URL,

src/homely/client.py

@@ -19,6 +19,17 @@
 REQUEST_TIMEOUT = aiohttp.ClientTimeout(total=20)
 
 
+def _log_identifier(value: str | int | None) -> str | None:
+    """Return a shortened identifier suitable for debug logs."""
+    if value is None:
+        return None
+
+    text = str(value)
+    if len(text) <= 8:
+        return text
+    return f"{text[:8]}..."
+
+
 def auth_header_value(token: str | None) -> str:
     """Return normalized Authorization header value."""
     normalized = (token or "").strip()
@@ -27,6 +38,14 @@ def auth_header_value(token: str | None) -> str:
     return f"Bearer {normalized}"
 
 
+def _response_preview(payload: Any) -> str:
+    """Return a short safe preview of a response payload for exceptions."""
+    text = repr(payload)
+    if len(text) <= 200:
+        return text
+    return f"{text[:200]}..."
+
+
 class HomelyClient:
     """Small reusable async client for the Homely cloud API."""
 
@@ -61,19 +80,31 @@ async def authenticate(
 
         Raises a typed SDK exception on failure.
         """
-        response, reason = await self.fetch_token_with_reason(username, password)
-        if response:
-            return TokenResponse.from_dict(response)
-        if reason == "invalid_auth":
+        response, status = await self._fetch_token_payload(username, password)
+        if response is not None:
+            try:
+                return TokenResponse.from_dict(response)
+            except (KeyError, TypeError, ValueError) as err:
+                raise HomelyResponseError(
+                    "Homely authentication response missing required fields",
+                    status=status,
+                    body=_response_preview(response),
+                ) from err
+        if status in (400, 401, 403):
             raise HomelyAuthError("Invalid Homely username or password")
+        if status in (200, 201):
+            raise HomelyResponseError(
+                "Homely authentication response could not be parsed",
+                status=status,
+            )
         raise HomelyConnectionError("Could not connect to Homely")
 
-    async def fetch_token_with_reason(
+    async def _fetch_token_payload(
         self,
         username: str,
         password: str,
-    ) -> tuple[dict[str, Any] | None, str | None]:
-        """Fetch access token and return optional reason key on failure."""
+    ) -> tuple[dict[str, Any] | None, int | None]:
+        """Fetch access token payload and include HTTP status when available."""
         url = f"{self._base_url}oauth/token"
         payload = {
             "username": username,
@@ -83,18 +114,43 @@ async def fetch_token_with_reason(
         try:
             async with self._session.post(url, json=payload, timeout=self._timeout) as response:
                 if response.status in (200, 201):
+                    try:
+                        parsed = await response.json()
+                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        _LOGGER.debug(
+                            "Token fetch returned invalid JSON status=%s: %s",
+                            response.status,
+                            err,
+                        )
+                        return None, response.status
+                    if not isinstance(parsed, dict):
+                        _LOGGER.debug(
+                            "Token fetch returned unexpected payload type status=%s payload_type=%s",
+                            response.status,
+                            type(parsed).__name__,
+                        )
+                        return None, response.status
                     _LOGGER.debug("Token fetch successful")
-                    return await response.json(), None
-
-                if response.status in (400, 401, 403):
-                    _LOGGER.debug("Token fetch rejected with status=%s", response.status)
-                    return None, "invalid_auth"
+                    return parsed, response.status
 
-                _LOGGER.warning("Token fetch failed with status=%s", response.status)
-                return None, "cannot_connect"
+                _LOGGER.debug("Token fetch failed with status=%s", response.status)
+                return None, response.status
         except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.warning("Token fetch network error: %s", err)
-            return None, "cannot_connect"
+            _LOGGER.debug("Token fetch network error: %s", err)
+            return None, None
+
+    async def fetch_token_with_reason(
+        self,
+        username: str,
+        password: str,
+    ) -> tuple[dict[str, Any] | None, str | None]:
+        """Fetch access token and return optional reason key on failure."""
+        response, status = await self._fetch_token_payload(username, password)
+        if response is not None:
+            return response, None
+        if status in (400, 401, 403):
+            return None, "invalid_auth"
+        return None, "cannot_connect"
 
     async def fetch_token(
         self,
@@ -105,8 +161,11 @@ async def fetch_token(
         response, _reason = await self.fetch_token_with_reason(username, password)
         return response
 
-    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
-        """Refresh access token using refresh token."""
+    async def _fetch_refresh_token_payload(
+        self,
+        refresh_token: str,
+    ) -> tuple[dict[str, Any] | None, int | None]:
+        """Refresh access token payload and include HTTP status when available."""
         url = f"{self._base_url}oauth/refresh-token"
         payload = {
             "refresh_token": refresh_token,
@@ -115,42 +174,108 @@ async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None
         try:
             async with self._session.post(url, json=payload, timeout=self._timeout) as response:
                 if response.status in (200, 201):
+                    try:
+                        parsed = await response.json()
+                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        _LOGGER.debug(
+                            "Token refresh returned invalid JSON status=%s: %s",
+                            response.status,
+                            err,
+                        )
+                        return None, response.status
+                    if not isinstance(parsed, dict):
+                        _LOGGER.debug(
+                            "Token refresh returned unexpected payload type status=%s payload_type=%s",
+                            response.status,
+                            type(parsed).__name__,
+                        )
+                        return None, response.status
                     _LOGGER.debug("Token refresh successful")
-                    return await response.json()
+                    return parsed, response.status
                 _LOGGER.debug("Token refresh failed with status=%s", response.status)
-                return None
+                return None, response.status
         except (aiohttp.ClientError, TimeoutError) as err:
             _LOGGER.debug("Token refresh network error: %s", err)
-            return None
+            return None, None
+
+    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
+        """Refresh access token using refresh token."""
+        response, _status = await self._fetch_refresh_token_payload(refresh_token)
+        return response
 
     async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
         """Refresh access token and return a typed token response."""
-        response = await self.fetch_refresh_token(refresh_token)
-        if response:
-            return TokenResponse.from_dict(response)
+        response, status = await self._fetch_refresh_token_payload(refresh_token)
+        if response is not None:
+            try:
+                return TokenResponse.from_dict(response)
+            except (KeyError, TypeError, ValueError) as err:
+                raise HomelyResponseError(
+                    "Homely refresh response missing required fields",
+                    status=status,
+                    body=_response_preview(response),
+                ) from err
+        if status in (400, 401, 403):
+            raise HomelyAuthError("Homely rejected the supplied refresh token")
+        if status in (200, 201):
+            raise HomelyResponseError(
+                "Homely refresh response could not be parsed",
+                status=status,
+            )
         raise HomelyConnectionError("Could not refresh Homely access token")
 
-    async def get_locations(self, token: str) -> list[dict[str, Any]] | None:
-        """Get locations from API."""
+    async def _get_locations_payload(
+        self,
+        token: str,
+    ) -> tuple[list[dict[str, Any]] | None, int | None]:
+        """Get locations payload and include HTTP status when available."""
         url = f"{self._base_url}locations"
         headers = {"Authorization": auth_header_value(token)}
 
         try:
             async with self._session.get(url, headers=headers, timeout=self._timeout) as response:
                 if response.status == 200:
+                    try:
+                        parsed = await response.json()
+                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        _LOGGER.debug(
+                            "Locations fetch returned invalid JSON status=%s: %s",
+                            response.status,
+                            err,
+                        )
+                        return None, response.status
+                    if not isinstance(parsed, list):
+                        _LOGGER.debug(
+                            "Locations fetch returned unexpected payload type status=%s payload_type=%s",
+                            response.status,
+                            type(parsed).__name__,
+                        )
+                        return None, response.status
                     _LOGGER.debug("Locations fetch successful")
-                    return await response.json()
+                    return parsed, response.status
                 _LOGGER.debug("Locations fetch failed with status=%s", response.status)
-                return None
+                return None, response.status
         except (aiohttp.ClientError, TimeoutError) as err:
             _LOGGER.debug("Locations fetch network error: %s", err)
-            return None
+            return None, None
+
+    async def get_locations(self, token: str) -> list[dict[str, Any]] | None:
+        """Get locations from API."""
+        locations, _status = await self._get_locations_payload(token)
+        return locations
 
     async def get_locations_or_raise(self, token: str) -> list[dict[str, Any]]:
         """Get locations from API or raise a typed exception."""
-        locations = await self.get_locations(token)
+        locations, status = await self._get_locations_payload(token)
         if locations is not None:
             return locations
+        if status in (401, 403):
+            raise HomelyAuthError("Homely rejected the supplied access token")
+        if status == 200:
+            raise HomelyResponseError(
+                "Homely locations response could not be parsed",
+                status=status,
+            )
         raise HomelyConnectionError("Could not fetch Homely locations")
 
     async def get_home_data(
@@ -174,20 +299,35 @@ async def get_home_data_with_status(
         try:
             async with self._session.get(url, headers=headers, timeout=self._timeout) as response:
                 if response.status == 200:
-                    return await response.json(), response.status
-                body = await response.text()
-                body_preview = body.replace("\n", " ")[:200]
+                    try:
+                        parsed = await response.json()
+                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        _LOGGER.debug(
+                            "Location data fetch returned invalid JSON status=%s location_id=%s: %s",
+                            response.status,
+                            _log_identifier(location_id),
+                            err,
+                        )
+                        return None, response.status
+                    if not isinstance(parsed, dict):
+                        _LOGGER.debug(
+                            "Location data fetch returned unexpected payload type status=%s location_id=%s payload_type=%s",
+                            response.status,
+                            _log_identifier(location_id),
+                            type(parsed).__name__,
+                        )
+                        return None, response.status
+                    return parsed, response.status
                 _LOGGER.debug(
-                    "Location data fetch failed with status=%s location_id=%s body_preview=%r",
+                    "Location data fetch failed with status=%s location_id=%s",
                     response.status,
-                    location_id,
-                    body_preview,
+                    _log_identifier(location_id),
                 )
                 return None, response.status
         except (aiohttp.ClientError, TimeoutError) as err:
             _LOGGER.debug(
                 "Location data fetch network error location_id=%s: %s",
-                location_id,
+                _log_identifier(location_id),
                 err,
             )
             return None, None