python-homely 0.1.1__tar.gz → 0.1.2__tar.gz

{python_homely-0.1.1/src/python_homely.egg-info → python_homely-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-homely
-Version: 0.1.1
+Version: 0.1.2
 Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
 Author: Ludvik Blichfeldt Rød
 License-Expression: MIT
@@ -102,14 +102,23 @@ async def main() -> None:
 
 - `authenticate(username, password) -> TokenResponse`
 - `refresh_access_token(refresh_token) -> TokenResponse`
+- `fetch_token_details(username, password) -> TokenEndpointResult`
+- `fetch_refresh_token_details(refresh_token) -> TokenEndpointResult`
 - `get_locations_or_raise(token) -> list[dict]`
 - `get_home_data_or_raise(token, location_id) -> dict`
 - `HomelyWebSocket(...).connect_or_raise()`
 
+Legacy compatibility helpers remain available:
+
+- `fetch_token_with_reason(username, password) -> tuple[dict | None, str | None]`
+- `fetch_token(username, password) -> dict | None`
+- `fetch_refresh_token(refresh_token) -> dict | None`
+
 Main exports:
 
 - `HomelyClient`
 - `HomelyWebSocket`
+- `TokenEndpointResult`
 - `TokenResponse`
 - `HomelyConnectionError`
 - `HomelyAuthError`
@@ -121,12 +130,33 @@ Main exports:
 - `HomelyConnectionError`: network or service unavailable
 - `HomelyAuthError`: invalid credentials or rejected token
 - `HomelyResponseError`: unexpected response or HTTP failure
+  Carries `status` and `body_preview` when available.
 - `HomelyWebSocketError`: websocket could not be established
 
+## Token Diagnostics
+
+If you need more than success/failure, use the detailed token helpers:
+
+```python
+result = await client.fetch_refresh_token_details(refresh_token)
+if result.ok:
+    print(result.token.access_token)
+else:
+    print(result.reason, result.status, result.detail, result.body_preview)
+```
+
+`TokenEndpointResult.reason` can distinguish between invalid credentials, invalid refresh
+tokens, network errors, timeouts, malformed JSON, malformed payloads, empty responses, and
+unexpected HTTP failures.
+
+## Websocket Note
+
+Refreshing an access token does not require forcing an already-connected websocket to reconnect.
+The websocket token only matters when a new websocket connection is established or re-established.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 
-⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐
-
+⭐ If you find this package useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

{python_homely-0.1.1 → python_homely-0.1.2}/README.md

@@ -69,14 +69,23 @@ async def main() -> None:
 
 - `authenticate(username, password) -> TokenResponse`
 - `refresh_access_token(refresh_token) -> TokenResponse`
+- `fetch_token_details(username, password) -> TokenEndpointResult`
+- `fetch_refresh_token_details(refresh_token) -> TokenEndpointResult`
 - `get_locations_or_raise(token) -> list[dict]`
 - `get_home_data_or_raise(token, location_id) -> dict`
 - `HomelyWebSocket(...).connect_or_raise()`
 
+Legacy compatibility helpers remain available:
+
+- `fetch_token_with_reason(username, password) -> tuple[dict | None, str | None]`
+- `fetch_token(username, password) -> dict | None`
+- `fetch_refresh_token(refresh_token) -> dict | None`
+
 Main exports:
 
 - `HomelyClient`
 - `HomelyWebSocket`
+- `TokenEndpointResult`
 - `TokenResponse`
 - `HomelyConnectionError`
 - `HomelyAuthError`
@@ -88,12 +97,33 @@ Main exports:
 - `HomelyConnectionError`: network or service unavailable
 - `HomelyAuthError`: invalid credentials or rejected token
 - `HomelyResponseError`: unexpected response or HTTP failure
+  Carries `status` and `body_preview` when available.
 - `HomelyWebSocketError`: websocket could not be established
 
+## Token Diagnostics
+
+If you need more than success/failure, use the detailed token helpers:
+
+```python
+result = await client.fetch_refresh_token_details(refresh_token)
+if result.ok:
+    print(result.token.access_token)
+else:
+    print(result.reason, result.status, result.detail, result.body_preview)
+```
+
+`TokenEndpointResult.reason` can distinguish between invalid credentials, invalid refresh
+tokens, network errors, timeouts, malformed JSON, malformed payloads, empty responses, and
+unexpected HTTP failures.
+
+## Websocket Note
+
+Refreshing an access token does not require forcing an already-connected websocket to reconnect.
+The websocket token only matters when a new websocket connection is established or re-established.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 
-⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐
-
+⭐ If you find this package useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

{python_homely-0.1.1 → python_homely-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-homely"
-version = "0.1.1"
+version = "0.1.2"
 description = "Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -51,6 +51,9 @@ package-dir = {"" = "src"}
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+homely = ["py.typed"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

{python_homely-0.1.1 → python_homely-0.1.2}/src/homely/__init__.py

@@ -1,6 +1,6 @@
 """Reusable Homely client package extracted from the integration."""
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"
 
 from .client import (
     BASE_URL,
@@ -15,7 +15,7 @@ from .exceptions import (
     HomelyResponseError,
     HomelyWebSocketError,
 )
-from .models import TokenResponse
+from .models import TokenEndpointResult, TokenResponse
 from .websocket import HomelyWebSocket
 
 __all__ = [
@@ -29,6 +29,7 @@ __all__ = [
     "HomelyAuthError",
     "HomelyResponseError",
     "HomelyWebSocketError",
+    "TokenEndpointResult",
     "TokenResponse",
     "auth_header_value",
 ]

{python_homely-0.1.1 → python_homely-0.1.2}/src/homely/client.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Any
+from typing import Any, NoReturn
 
 import aiohttp
 
@@ -11,7 +11,7 @@ from .exceptions import (
     HomelyConnectionError,
     HomelyResponseError,
 )
-from .models import TokenResponse
+from .models import TokenEndpointResult, TokenFailureReason, TokenResponse
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -46,6 +46,36 @@ def _response_preview(payload: Any) -> str:
     return f"{text[:200]}..."
 
 
+def _text_preview(text: str | None) -> str | None:
+    """Return a trimmed short preview of response text."""
+    if text is None:
+        return None
+
+    preview = text.strip()
+    if not preview:
+        return None
+    if len(preview) <= 200:
+        return preview
+    return f"{preview[:200]}..."
+
+
+def _error_detail(err: BaseException) -> str:
+    """Return a compact detail string for logs and typed results."""
+    detail = str(err).strip()
+    if detail:
+        return detail
+    return err.__class__.__name__
+
+
+def _coarse_token_reason(reason: TokenFailureReason | None) -> str | None:
+    """Map detailed token failure reasons to the legacy coarse reason set."""
+    if reason == "invalid_auth":
+        return "invalid_auth"
+    if reason is None:
+        return None
+    return "cannot_connect"
+
+
 class HomelyClient:
     """Small reusable async client for the Homely cloud API."""
 
@@ -80,24 +110,17 @@ class HomelyClient:
 
         Raises a typed SDK exception on failure.
         """
-        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")
+        result = await self.fetch_token_details(username, password)
+        if result.token is not None:
+            return result.token
+        self._raise_token_endpoint_failure(
+            result,
+            invalid_reason="invalid_auth",
+            invalid_message="Invalid Homely username or password",
+            connection_message="Could not connect to Homely",
+            malformed_message="Homely authentication response could not be parsed",
+            response_message="Homely authentication failed",
+        )
 
     async def _fetch_token_payload(
         self,
@@ -105,39 +128,25 @@ class HomelyClient:
         password: str,
     ) -> tuple[dict[str, Any] | None, int | None]:
         """Fetch access token payload and include HTTP status when available."""
-        url = f"{self._base_url}oauth/token"
+        result = await self.fetch_token_details(username, password)
+        return result.raw, result.status
+
+    async def fetch_token_details(
+        self,
+        username: str,
+        password: str,
+    ) -> TokenEndpointResult:
+        """Fetch a token and return a detailed typed result."""
         payload = {
             "username": username,
             "password": password,
         }
-
-        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 parsed, response.status
-
-                _LOGGER.debug("Token fetch failed with status=%s", response.status)
-                return None, response.status
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.debug("Token fetch network error: %s", err)
-            return None, None
+        return await self._post_token_endpoint(
+            endpoint="oauth/token",
+            payload=payload,
+            invalid_reason="invalid_auth",
+            action="Token fetch",
+        )
 
     async def fetch_token_with_reason(
         self,
@@ -145,12 +154,10 @@ class HomelyClient:
         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"
+        result = await self.fetch_token_details(username, password)
+        if result.raw is not None:
+            return result.raw, None
+        return None, _coarse_token_reason(result.reason)
 
     async def fetch_token(
         self,
@@ -158,71 +165,185 @@ class HomelyClient:
         password: str,
     ) -> dict[str, Any] | None:
         """Fetch access token from API."""
-        response, _reason = await self.fetch_token_with_reason(username, password)
-        return response
+        result = await self.fetch_token_details(username, password)
+        return result.raw
 
     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"
+        result = await self.fetch_refresh_token_details(refresh_token)
+        return result.raw, result.status
+
+    async def fetch_refresh_token_details(
+        self,
+        refresh_token: str,
+    ) -> TokenEndpointResult:
+        """Refresh a token and return a detailed typed result."""
         payload = {
             "refresh_token": refresh_token,
         }
+        return await self._post_token_endpoint(
+            endpoint="oauth/refresh-token",
+            payload=payload,
+            invalid_reason="invalid_refresh_token",
+            action="Token refresh",
+        )
+
+    async def fetch_refresh_token(self, refresh_token: str) -> dict[str, Any] | None:
+        """Refresh access token using refresh token."""
+        result = await self.fetch_refresh_token_details(refresh_token)
+        return result.raw
+
+    async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
+        """Refresh access token and return a typed token response."""
+        result = await self.fetch_refresh_token_details(refresh_token)
+        if result.token is not None:
+            return result.token
+        self._raise_token_endpoint_failure(
+            result,
+            invalid_reason="invalid_refresh_token",
+            invalid_message="Homely rejected the supplied refresh token",
+            connection_message="Could not refresh Homely access token",
+            malformed_message="Homely refresh response could not be parsed",
+            response_message="Homely refresh request failed",
+        )
+
+    async def _post_token_endpoint(
+        self,
+        *,
+        endpoint: str,
+        payload: dict[str, Any],
+        invalid_reason: TokenFailureReason,
+        action: str,
+    ) -> TokenEndpointResult:
+        """Post to a token endpoint and return a detailed typed result."""
+        url = f"{self._base_url}{endpoint}"
 
         try:
             async with self._session.post(url, json=payload, timeout=self._timeout) as response:
+                body_preview = await self._response_text_preview(response)
                 if response.status in (200, 201):
                     try:
                         parsed = await response.json()
                     except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        detail = _error_detail(err)
                         _LOGGER.debug(
-                            "Token refresh returned invalid JSON status=%s: %s",
+                            "%s returned invalid JSON status=%s: %s",
+                            action,
                             response.status,
-                            err,
+                            detail,
+                        )
+                        return TokenEndpointResult(
+                            reason="invalid_json",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=body_preview,
                         )
-                        return None, response.status
                     if not isinstance(parsed, dict):
+                        detail = f"payload_type={type(parsed).__name__}"
                         _LOGGER.debug(
-                            "Token refresh returned unexpected payload type status=%s payload_type=%s",
+                            "%s returned unexpected payload type status=%s payload_type=%s",
+                            action,
                             response.status,
                             type(parsed).__name__,
                         )
-                        return None, response.status
-                    _LOGGER.debug("Token refresh successful")
-                    return parsed, response.status
-                _LOGGER.debug("Token refresh failed with status=%s", response.status)
-                return None, response.status
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.debug("Token refresh network error: %s", err)
-            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
+                        return TokenEndpointResult(
+                            reason="invalid_payload",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=_response_preview(parsed),
+                        )
+                    if not parsed:
+                        _LOGGER.debug(
+                            "%s returned an empty payload status=%s",
+                            action,
+                            response.status,
+                        )
+                        return TokenEndpointResult(
+                            reason="empty_response",
+                            status=response.status,
+                            body_preview=_response_preview(parsed),
+                        )
+                    try:
+                        token = TokenResponse.from_dict(parsed)
+                    except (KeyError, TypeError, ValueError) as err:
+                        detail = _error_detail(err)
+                        _LOGGER.debug(
+                            "%s returned malformed payload status=%s: %s",
+                            action,
+                            response.status,
+                            detail,
+                        )
+                        return TokenEndpointResult(
+                            reason="invalid_payload",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=_response_preview(parsed),
+                        )
+                    _LOGGER.debug("%s successful", action)
+                    return TokenEndpointResult(token=token, status=response.status)
+
+                if response.status in (400, 401, 403):
+                    _LOGGER.debug("%s rejected with status=%s", action, response.status)
+                    return TokenEndpointResult(
+                        reason=invalid_reason,
+                        status=response.status,
+                        body_preview=body_preview,
+                    )
+
+                _LOGGER.debug("%s failed with status=%s", action, response.status)
+                return TokenEndpointResult(
+                    reason="http_error",
+                    status=response.status,
+                    body_preview=body_preview,
+                )
+        except TimeoutError as err:
+            detail = _error_detail(err)
+            _LOGGER.debug("%s timeout: %s", action, detail)
+            return TokenEndpointResult(reason="timeout", detail=detail)
+        except aiohttp.ClientError as err:
+            detail = _error_detail(err)
+            _LOGGER.debug("%s network error: %s", action, detail)
+            return TokenEndpointResult(reason="network_error", detail=detail)
+
+    async def _response_text_preview(self, response: aiohttp.ClientResponse) -> str | None:
+        """Read and shorten response text for diagnostics when available."""
+        try:
+            return _text_preview(await response.text())
+        except (TypeError, ValueError, UnicodeDecodeError) as err:
+            _LOGGER.debug("Could not read response text status=%s: %s", response.status, err)
+            return None
 
-    async def refresh_access_token(self, refresh_token: str) -> TokenResponse:
-        """Refresh access token and return a typed token 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):
+    def _raise_token_endpoint_failure(
+        self,
+        result: TokenEndpointResult,
+        *,
+        invalid_reason: TokenFailureReason,
+        invalid_message: str,
+        connection_message: str,
+        malformed_message: str,
+        response_message: str,
+    ) -> NoReturn:
+        """Raise a typed SDK exception for a failed token endpoint result."""
+        if result.reason == invalid_reason:
+            raise HomelyAuthError(invalid_message)
+        if result.reason in ("timeout", "network_error"):
+            raise HomelyConnectionError(connection_message)
+        if result.reason in ("invalid_json", "invalid_payload", "empty_response"):
             raise HomelyResponseError(
-                "Homely refresh response could not be parsed",
-                status=status,
+                malformed_message,
+                status=result.status,
+                body=result.body_preview,
+                body_preview=result.body_preview,
             )
-        raise HomelyConnectionError("Could not refresh Homely access token")
+        raise HomelyResponseError(
+            response_message,
+            status=result.status,
+            body=result.body_preview,
+            body_preview=result.body_preview,
+        )
 
     async def _get_locations_payload(
         self,
@@ -246,7 +367,8 @@ class HomelyClient:
                         return None, response.status
                     if not isinstance(parsed, list):
                         _LOGGER.debug(
-                            "Locations fetch returned unexpected payload type status=%s payload_type=%s",
+                            "Locations fetch returned unexpected payload type "
+                            "status=%s payload_type=%s",
                             response.status,
                             type(parsed).__name__,
                         )
@@ -303,7 +425,8 @@ class HomelyClient:
                         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",
+                            "Location data fetch returned invalid JSON "
+                            "status=%s location_id=%s: %s",
                             response.status,
                             _log_identifier(location_id),
                             err,
@@ -311,7 +434,8 @@ class HomelyClient:
                         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",
+                            "Location data fetch returned unexpected payload "
+                            "type status=%s location_id=%s payload_type=%s",
                             response.status,
                             _log_identifier(location_id),
                             type(parsed).__name__,

{python_homely-0.1.1 → python_homely-0.1.2}/src/homely/exceptions.py

@@ -23,10 +23,14 @@ class HomelyResponseError(HomelyError):
         *,
         status: int | None = None,
         body: str | None = None,
+        body_preview: str | None = None,
     ) -> None:
         """Initialize the exception with optional response details."""
         super().__init__(message)
         self.status = status
+        if body_preview is None:
+            body_preview = body
+        self.body_preview = body_preview
         self.body = body
 
 

{python_homely-0.1.1 → python_homely-0.1.2}/src/homely/models.py

@@ -2,7 +2,18 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
+
+TokenFailureReason = Literal[
+    "invalid_auth",
+    "invalid_refresh_token",
+    "http_error",
+    "network_error",
+    "timeout",
+    "invalid_json",
+    "invalid_payload",
+    "empty_response",
+]
 
 
 @dataclass(slots=True)
@@ -29,3 +40,26 @@ class TokenResponse:
             expires_in=parsed_expires_in,
             raw=dict(data),
         )
+
+
+@dataclass(slots=True)
+class TokenEndpointResult:
+    """Detailed result returned by authentication and refresh helpers."""
+
+    token: TokenResponse | None = None
+    reason: TokenFailureReason | None = None
+    status: int | None = None
+    detail: str | None = None
+    body_preview: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        """Return whether the request produced a usable token response."""
+        return self.token is not None
+
+    @property
+    def raw(self) -> dict[str, Any] | None:
+        """Return the raw token payload when available."""
+        if self.token is None:
+            return None
+        return self.token.raw

{python_homely-0.1.1 → python_homely-0.1.2}/src/homely/websocket.py

@@ -45,9 +45,9 @@ class HomelyWebSocket:
         self.location_id = location_id
         self.token = token
         self.on_data_update = on_data_update
-        self.socket = None
+        self.socket: Any | None = None
         self._is_closing = False
-        self._reconnect_task: asyncio.Task | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
         self._reconnect_interval = 300
         self._reconnect_warn_every = 12
         self._status_update_callback = status_update_callback
@@ -268,7 +268,7 @@ class HomelyWebSocket:
             return False
 
         try:
-            import socketio
+            import socketio  # type: ignore[import-untyped]
         except ImportError:
             _LOGGER.error("python-socketio is not installed. WebSocket disabled %s.", self._ctx())
             self._set_status("Disconnected", "socketio missing")
@@ -293,35 +293,36 @@ class HomelyWebSocket:
                 engineio_logger=False,
             )
 
-            @self.socket.event
-            async def connect():
+            async def connect() -> None:
                 self._on_connect()
 
-            @self.socket.event
-            async def disconnect(*args):
+            async def disconnect(*args: Any) -> None:
                 self._on_disconnect(self._build_reason(args[0] if args else None))
 
-            @self.socket.event
-            async def message(data):
+            async def message(data: Any) -> None:
                 self._on_event(data)
 
-            @self.socket.event
-            async def event(data):
+            async def event(data: Any) -> None:
                 self._on_event(data)
 
-            @self.socket.on("*")
-            async def catch_all(event, data):
+            async def catch_all(event: str, data: Any) -> None:
                 if event not in ("connect", "disconnect", "message", "event", "connect_error"):
                     _LOGGER.debug("WebSocket event %s type=%s", self._ctx(), event)
                     self._on_event({"type": event, "payload": data})
 
-            @self.socket.event
-            async def connect_error(data):
+            async def connect_error(data: Any) -> None:
                 raw_reason = self._build_reason(data)
                 reason = f"connect_error: {raw_reason}" if raw_reason else "connect_error"
                 _LOGGER.debug("WebSocket connect_error %s: %s", self._ctx(), reason)
                 self._on_disconnect(reason)
 
+            self.socket.on("connect", connect)
+            self.socket.on("disconnect", disconnect)
+            self.socket.on("message", message)
+            self.socket.on("event", event)
+            self.socket.on("*", catch_all)
+            self.socket.on("connect_error", connect_error)
+
             bearer_token = self._bearer_value(self.token)
             query = urlencode(
                 {

{python_homely-0.1.1 → python_homely-0.1.2/src/python_homely.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-homely
-Version: 0.1.1
+Version: 0.1.2
 Summary: Async Python client for the Homely cloud API, built for Home Assistant but usable anywhere.
 Author: Ludvik Blichfeldt Rød
 License-Expression: MIT
@@ -102,14 +102,23 @@ async def main() -> None:
 
 - `authenticate(username, password) -> TokenResponse`
 - `refresh_access_token(refresh_token) -> TokenResponse`
+- `fetch_token_details(username, password) -> TokenEndpointResult`
+- `fetch_refresh_token_details(refresh_token) -> TokenEndpointResult`
 - `get_locations_or_raise(token) -> list[dict]`
 - `get_home_data_or_raise(token, location_id) -> dict`
 - `HomelyWebSocket(...).connect_or_raise()`
 
+Legacy compatibility helpers remain available:
+
+- `fetch_token_with_reason(username, password) -> tuple[dict | None, str | None]`
+- `fetch_token(username, password) -> dict | None`
+- `fetch_refresh_token(refresh_token) -> dict | None`
+
 Main exports:
 
 - `HomelyClient`
 - `HomelyWebSocket`
+- `TokenEndpointResult`
 - `TokenResponse`
 - `HomelyConnectionError`
 - `HomelyAuthError`
@@ -121,12 +130,33 @@ Main exports:
 - `HomelyConnectionError`: network or service unavailable
 - `HomelyAuthError`: invalid credentials or rejected token
 - `HomelyResponseError`: unexpected response or HTTP failure
+  Carries `status` and `body_preview` when available.
 - `HomelyWebSocketError`: websocket could not be established
 
+## Token Diagnostics
+
+If you need more than success/failure, use the detailed token helpers:
+
+```python
+result = await client.fetch_refresh_token_details(refresh_token)
+if result.ok:
+    print(result.token.access_token)
+else:
+    print(result.reason, result.status, result.detail, result.body_preview)
+```
+
+`TokenEndpointResult.reason` can distinguish between invalid credentials, invalid refresh
+tokens, network errors, timeouts, malformed JSON, malformed payloads, empty responses, and
+unexpected HTTP failures.
+
+## Websocket Note
+
+Refreshing an access token does not require forcing an already-connected websocket to reconnect.
+The websocket token only matters when a new websocket connection is established or re-established.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).
 
 
-⭐ If you find this integration useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐
-
+⭐ If you find this package useful, please consider giving it a star on [GitHub](https://github.com/ludvikroed/python-homely)! ⭐

{python_homely-0.1.1 → python_homely-0.1.2}/src/python_homely.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/homely/__init__.py
 src/homely/client.py
 src/homely/exceptions.py
 src/homely/models.py
+src/homely/py.typed
 src/homely/websocket.py
 src/python_homely.egg-info/PKG-INFO
 src/python_homely.egg-info/SOURCES.txt

python_homely-0.1.2/src/python_homely.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

{python_homely-0.1.1 → python_homely-0.1.2}/tests/test_sdk.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import aiohttp
+import pytest
 
 from homely import (
     HomelyAuthError,
@@ -10,6 +11,7 @@ from homely import (
     HomelyResponseError,
     HomelyWebSocket,
     HomelyWebSocketError,
+    TokenEndpointResult,
     TokenResponse,
     __version__,
     auth_header_value,
@@ -87,7 +89,7 @@ class _FakeAsyncCallable:
 async def test_sdk_exports_public_symbols():
     """The SDK should expose a clean public surface."""
     assert auth_header_value("token") == "Bearer token"
-    assert __version__ == "0.1.1"
+    assert __version__ == "0.1.2"
 
 
 async def test_authenticate_returns_typed_token():
@@ -119,6 +121,84 @@ async def test_authenticate_returns_typed_token():
     )
 
 
+async def test_fetch_token_details_returns_typed_result():
+    """Detailed token fetches should preserve both token and metadata."""
+    client = HomelyClient(
+        _FakeSession(
+            post_response=_FakeResponse(
+                status=200,
+                json_data={
+                    "access_token": "token",
+                    "refresh_token": "refresh",
+                    "expires_in": 1800,
+                },
+            )
+        )
+    )
+
+    result = await client.fetch_token_details("user", "pass")
+
+    assert result == TokenEndpointResult(
+        token=TokenResponse(
+            access_token="token",
+            refresh_token="refresh",
+            expires_in=1800,
+            raw={
+                "access_token": "token",
+                "refresh_token": "refresh",
+                "expires_in": 1800,
+            },
+        ),
+        status=200,
+    )
+    assert result.ok is True
+    assert result.raw == {
+        "access_token": "token",
+        "refresh_token": "refresh",
+        "expires_in": 1800,
+    }
+
+
+async def test_fetch_token_details_returns_invalid_auth_reason():
+    """Detailed token fetches should classify auth failures explicitly."""
+    client = HomelyClient(
+        _FakeSession(
+            post_response=_FakeResponse(status=401, text_data='{"error":"unauthorized"}')
+        )
+    )
+
+    result = await client.fetch_token_details("user", "pass")
+
+    assert result.ok is False
+    assert result.reason == "invalid_auth"
+    assert result.status == 401
+    assert result.body_preview == '{"error":"unauthorized"}'
+
+
+async def test_fetch_token_details_returns_timeout_reason():
+    """Detailed token fetches should preserve timeout classification."""
+    client = HomelyClient(_FakeSession(post_exc=TimeoutError()))
+
+    result = await client.fetch_token_details("user", "pass")
+
+    assert result.reason == "timeout"
+    assert result.detail == "TimeoutError"
+
+
+async def test_fetch_token_with_reason_remains_backward_compatible():
+    """Legacy coarse token reasons should still be preserved."""
+    client = HomelyClient(
+        _FakeSession(
+            post_response=_FakeResponse(status=200, json_exc=ValueError("bad json"))
+        )
+    )
+
+    response, reason = await client.fetch_token_with_reason("user", "pass")
+
+    assert response is None
+    assert reason == "cannot_connect"
+
+
 async def test_authenticate_raises_auth_error():
     """Authentication failures should raise HomelyAuthError."""
     client = HomelyClient(_FakeSession(post_response=_FakeResponse(status=401)))
@@ -131,6 +211,26 @@ async def test_authenticate_raises_auth_error():
         raise AssertionError("Expected HomelyAuthError")
 
 
+async def test_authenticate_raises_response_error_with_body_preview_on_invalid_json():
+    """Malformed successful auth payloads should include a short body preview."""
+    client = HomelyClient(
+        _FakeSession(
+            post_response=_FakeResponse(
+                status=200,
+                text_data="not-json",
+                json_exc=ValueError("bad json"),
+            )
+        )
+    )
+
+    with pytest.raises(HomelyResponseError) as err_info:
+        await client.authenticate("user", "pass")
+
+    assert err_info.value.status == 200
+    assert err_info.value.body_preview == "not-json"
+    assert err_info.value.body == "not-json"
+
+
 async def test_refresh_access_token_raises_connection_error_on_timeout():
     """Refresh failures should raise HomelyConnectionError."""
     client = HomelyClient(_FakeSession(post_exc=TimeoutError()))
@@ -155,6 +255,99 @@ async def test_refresh_access_token_raises_auth_error_on_expired_refresh_token()
         raise AssertionError("Expected HomelyAuthError")
 
 
+async def test_fetch_refresh_token_details_returns_http_error_with_preview():
+    """Detailed refresh fetches should include status and body previews."""
+    client = HomelyClient(
+        _FakeSession(post_response=_FakeResponse(status=503, text_data="upstream down"))
+    )
+
+    result = await client.fetch_refresh_token_details("refresh-token")
+
+    assert result.reason == "http_error"
+    assert result.status == 503
+    assert result.body_preview == "upstream down"
+
+
+async def test_fetch_refresh_token_details_returns_invalid_payload_for_non_dict_success():
+    """Detailed refresh fetches should reject non-dict success payloads explicitly."""
+    client = HomelyClient(
+        _FakeSession(post_response=_FakeResponse(status=200, json_data=["bad-payload"]))
+    )
+
+    result = await client.fetch_refresh_token_details("refresh-token")
+
+    assert result.token is None
+    assert result.reason == "invalid_payload"
+    assert result.status == 200
+    assert result.detail == "payload_type=list"
+    assert result.body_preview == "['bad-payload']"
+
+
+async def test_fetch_refresh_token_wrapper_remains_backward_compatible():
+    """The legacy refresh wrapper should still return the raw payload on success."""
+    client = HomelyClient(
+        _FakeSession(
+            post_response=_FakeResponse(
+                status=200,
+                json_data={
+                    "access_token": "token",
+                    "refresh_token": "refresh",
+                    "expires_in": 120,
+                },
+            )
+        )
+    )
+
+    response = await client.fetch_refresh_token("refresh-token")
+
+    assert response == {
+        "access_token": "token",
+        "refresh_token": "refresh",
+        "expires_in": 120,
+    }
+
+
+async def test_refresh_access_token_raises_response_error_with_preview():
+    """Refresh HTTP failures should surface response metadata for callers."""
+    client = HomelyClient(
+        _FakeSession(post_response=_FakeResponse(status=503, text_data="upstream down"))
+    )
+
+    with pytest.raises(HomelyResponseError) as err_info:
+        await client.refresh_access_token("refresh-token")
+
+    assert err_info.value.status == 503
+    assert err_info.value.body_preview == "upstream down"
+    assert err_info.value.body == "upstream down"
+
+
+async def test_response_error_preserves_body_and_preview_separately():
+    """Response errors should keep body and body_preview as separate fields."""
+    err = HomelyResponseError(
+        "bad response",
+        status=502,
+        body="full body",
+        body_preview="trimmed preview",
+    )
+
+    assert err.status == 502
+    assert err.body == "full body"
+    assert err.body_preview == "trimmed preview"
+
+
+async def test_response_error_uses_body_as_preview_when_preview_is_missing():
+    """Response errors should keep legacy body-only construction working."""
+    err = HomelyResponseError(
+        "bad response",
+        status=502,
+        body="full body",
+    )
+
+    assert err.status == 502
+    assert err.body == "full body"
+    assert err.body_preview == "full body"
+
+
 async def test_get_locations_or_raise_raises_connection_error():
     """Location lookup failures should raise HomelyConnectionError."""
     client = HomelyClient(_FakeSession(get_exc=aiohttp.ClientError("boom")))
@@ -198,7 +391,12 @@ async def test_get_home_data_or_raise_raises_response_error():
 async def test_authenticate_raises_response_error_on_malformed_success_payload():
     """Malformed successful auth responses should raise HomelyResponseError."""
     client = HomelyClient(
-        _FakeSession(post_response=_FakeResponse(status=200, json_data={"refresh_token": "refresh"}))
+        _FakeSession(
+            post_response=_FakeResponse(
+                status=200,
+                json_data={"refresh_token": "refresh"},
+            )
+        )
     )
 
     try:
@@ -211,7 +409,14 @@ async def test_authenticate_raises_response_error_on_malformed_success_payload()
 
 async def test_get_locations_or_raise_raises_response_error_on_malformed_success_payload():
     """Malformed successful location responses should raise HomelyResponseError."""
-    client = HomelyClient(_FakeSession(get_response=_FakeResponse(status=200, json_data={"bad": "payload"})))
+    client = HomelyClient(
+        _FakeSession(
+            get_response=_FakeResponse(
+                status=200,
+                json_data={"bad": "payload"},
+            )
+        )
+    )
 
     try:
         await client.get_locations_or_raise("token")