python-homely 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

homely/__init__.py

@@ -1,6 +1,6 @@
 """Reusable Homely client package extracted from the integration."""
 
-__version__ = "0.1.0"
+__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",
 ]

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__)
 
@@ -19,6 +19,17 @@ BASE_URL = "https://sdk.iotiliti.cloud/homely/"
 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,44 @@ 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]}..."
+
+
+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."""
 
@@ -61,40 +110,54 @@ class HomelyClient:
 
         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":
-            raise HomelyAuthError("Invalid Homely username or password")
-        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_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."""
-        url = f"{self._base_url}oauth/token"
+    ) -> tuple[dict[str, Any] | None, int | None]:
+        """Fetch access token payload and include HTTP status when available."""
+        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,
         }
+        return await self._post_token_endpoint(
+            endpoint="oauth/token",
+            payload=payload,
+            invalid_reason="invalid_auth",
+            action="Token fetch",
+        )
 
-        try:
-            async with self._session.post(url, json=payload, timeout=self._timeout) as response:
-                if response.status in (200, 201):
-                    _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"
-
-                _LOGGER.warning("Token fetch failed with status=%s", response.status)
-                return None, "cannot_connect"
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.warning("Token fetch network error: %s", err)
-            return None, "cannot_connect"
+    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."""
+        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,
@@ -102,55 +165,239 @@ 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(self, refresh_token: str) -> dict[str, Any] | None:
-        """Refresh access token using refresh token."""
-        url = f"{self._base_url}oauth/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."""
+        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):
-                    _LOGGER.debug("Token refresh successful")
-                    return await response.json()
-                _LOGGER.debug("Token refresh failed with status=%s", response.status)
-                return None
-        except (aiohttp.ClientError, TimeoutError) as err:
-            _LOGGER.debug("Token refresh network error: %s", err)
+                    try:
+                        parsed = await response.json()
+                    except (aiohttp.ContentTypeError, TypeError, ValueError) as err:
+                        detail = _error_detail(err)
+                        _LOGGER.debug(
+                            "%s returned invalid JSON status=%s: %s",
+                            action,
+                            response.status,
+                            detail,
+                        )
+                        return TokenEndpointResult(
+                            reason="invalid_json",
+                            status=response.status,
+                            detail=detail,
+                            body_preview=body_preview,
+                        )
+                    if not isinstance(parsed, dict):
+                        detail = f"payload_type={type(parsed).__name__}"
+                        _LOGGER.debug(
+                            "%s returned unexpected payload type status=%s payload_type=%s",
+                            action,
+                            response.status,
+                            type(parsed).__name__,
+                        )
+                        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 = await self.fetch_refresh_token(refresh_token)
-        if response:
-            return TokenResponse.from_dict(response)
-        raise HomelyConnectionError("Could not refresh Homely access token")
+    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(
+                malformed_message,
+                status=result.status,
+                body=result.body_preview,
+                body_preview=result.body_preview,
+            )
+        raise HomelyResponseError(
+            response_message,
+            status=result.status,
+            body=result.body_preview,
+            body_preview=result.body_preview,
+        )
 
-    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 +421,37 @@ class HomelyClient:
         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

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
 
 

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

homely/py.typed

@@ -0,0 +1 @@
+

homely/websocket.py

@@ -14,6 +14,17 @@ from .exceptions import HomelyWebSocketError
 _LOGGER = logging.getLogger(__name__)
 
 
+def _log_identifier(value: str | int | None) -> str | None:
+    """Return a shortened identifier suitable for logs."""
+    if value is None:
+        return None
+
+    text = str(value)
+    if len(text) <= 8:
+        return text
+    return f"{text[:8]}..."
+
+
 class HomelyWebSocket:
     """WebSocket client for Homely using Socket.IO."""
 
@@ -34,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
@@ -45,9 +56,12 @@ class HomelyWebSocket:
 
     def _ctx(self, device_id: str | None = None) -> str:
         """Build consistent log context."""
-        base = f"context_id={self.context_id} location_id={self.location_id}"
+        base = (
+            f"context_id={_log_identifier(self.context_id)} "
+            f"location_id={_log_identifier(self.location_id)}"
+        )
         if device_id:
-            return f"{base} device_id={device_id}"
+            return f"{base} device_id={_log_identifier(device_id)}"
         return base
 
     @property
@@ -82,14 +96,14 @@ class HomelyWebSocket:
 
         if status_changed:
             if status == "Connected":
-                _LOGGER.info("WebSocket connected %s", self._ctx())
+                _LOGGER.debug("WebSocket connected %s", self._ctx())
             elif status == "Disconnected":
                 if reason and self._should_warn_disconnect(reason):
-                    _LOGGER.warning("WebSocket disconnected %s (%s)", self._ctx(), reason)
+                    _LOGGER.info("WebSocket disconnected %s (%s)", self._ctx(), reason)
                 elif reason:
                     _LOGGER.debug("WebSocket disconnected %s (%s)", self._ctx(), reason)
                 else:
-                    _LOGGER.warning("WebSocket disconnected %s", self._ctx())
+                    _LOGGER.info("WebSocket disconnected %s", self._ctx())
             else:
                 if reason:
                     _LOGGER.debug(
@@ -198,14 +212,14 @@ class HomelyWebSocket:
 
         self._reconnect_task = loop.create_task(self._reconnect_loop())
         if reason:
-            _LOGGER.info(
+            _LOGGER.debug(
                 "Started reconnect loop %s (%s). interval=%ss, retries=infinite",
                 self._ctx(),
                 reason,
                 self._reconnect_interval,
             )
         else:
-            _LOGGER.info(
+            _LOGGER.debug(
                 "Started reconnect loop %s. interval=%ss, retries=infinite",
                 self._ctx(),
                 self._reconnect_interval,
@@ -228,11 +242,11 @@ class HomelyWebSocket:
             _LOGGER.debug("WebSocket reconnect attempt %s started %s", attempt, self._ctx())
             success = await self.connect(from_reconnect_loop=True)
             if success:
-                _LOGGER.info("WebSocket reconnect attempt %s succeeded %s", attempt, self._ctx())
+                _LOGGER.debug("WebSocket reconnect attempt %s succeeded %s", attempt, self._ctx())
                 return
 
-            if attempt == 1 or attempt % self._reconnect_warn_every == 0:
-                _LOGGER.warning(
+            if attempt % self._reconnect_warn_every == 0:
+                _LOGGER.info(
                     "WebSocket reconnect attempt %s failed %s. Retrying in %s seconds",
                     attempt,
                     self._ctx(),
@@ -254,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")
@@ -279,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.0.dist-info → python_homely-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-homely
-Version: 0.1.0
+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.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+homely/__init__.py,sha256=PlZPdFw1D9L2lBeNmdKAsYGgLHjjwRP3XAwmYBRo2Is,746
+homely/client.py,sha256=iqM1ChFEVez5PJcvWk8BlkkVx4bekaQacBa-rAvSxpo,18276
+homely/exceptions.py,sha256=w6y5MC8yjPe5QtI-YEKUsbAPF1D0ARWx6ZkRsLTjrgQ,1040
+homely/models.py,sha256=8chNpjo1SF4TGww7XPWFUK3kXILH3bSmUnjNteyfsys,1842
+homely/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+homely/websocket.py,sha256=g6WJxvEjt-pjWkEk3qyBdhs6OCX3l-hGBOJ3dcPxHCI,15538
+python_homely-0.1.2.dist-info/licenses/LICENSE,sha256=nNVHKvQjryAonWsz5TbhzLd6M2kZaoNUvhxz92MgeAA,1079
+python_homely-0.1.2.dist-info/METADATA,sha256=piiYKUni3USyn2FNt6V8qvVCwDOk6aCkBKAesK7a78Q,5239
+python_homely-0.1.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_homely-0.1.2.dist-info/top_level.txt,sha256=auE-j6ghVMdT_jAw04jiXthgbuLpi-jYBU0fCkKvREQ,7
+python_homely-0.1.2.dist-info/RECORD,,

python_homely-0.1.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-homely/__init__.py,sha256=9vuclgRmKvpI76PVl1CnTxnezHmSUlPRNuIUjbYY35Y,698
-homely/client.py,sha256=0UQVZFjPMPGMad4kSsDuiiXV_LR4EkZ0J_9TfMEKoj4,7677
-homely/exceptions.py,sha256=g1v7QR9uDydzDCH12FD-3pZN2MGPJu1lDgAnNdT0lCA,893
-homely/models.py,sha256=NgNwYeOo4UiiyP29iFM0rN7k2HIkxZg4s5DivgfdYKM,968
-homely/websocket.py,sha256=DQruxEKuY0K2pEPcz8ltdOZ3NTLZwKKP4eHvDYy73uQ,14978
-python_homely-0.1.0.dist-info/licenses/LICENSE,sha256=nNVHKvQjryAonWsz5TbhzLd6M2kZaoNUvhxz92MgeAA,1079
-python_homely-0.1.0.dist-info/METADATA,sha256=8LKHkP-iwB32Afhpc4uLU9nrSkmJwM78jThVW6E-ZYw,4062
-python_homely-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_homely-0.1.0.dist-info/top_level.txt,sha256=auE-j6ghVMdT_jAw04jiXthgbuLpi-jYBU0fCkKvREQ,7
-python_homely-0.1.0.dist-info/RECORD,,