Release 0.1.2

Author: ludvikroed

CHANGELOG.md

@@ -6,6 +6,22 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-03-19
+
+### Added
+
+- Added `TokenEndpointResult` with detailed auth/refresh failure metadata.
+- Added `fetch_token_details()` and `fetch_refresh_token_details()` for typed, non-raising
+  token endpoint diagnostics.
+
+### Changed
+
+- `authenticate()` and `refresh_access_token()` now classify malformed responses, HTTP failures,
+  auth failures, and network failures more precisely.
+- `HomelyResponseError` now carries `body_preview` in addition to HTTP status metadata.
+- Legacy token helpers remain available as compatibility wrappers on top of the new detailed
+  token methods.
+
 ## [0.1.1] - 2026-03-17
 
 ### Changed

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)! ⭐

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"]

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 @@
     HomelyResponseError,
     HomelyWebSocketError,
 )
-from .models import TokenResponse
+from .models import TokenEndpointResult, TokenResponse
 from .websocket import HomelyWebSocket
 
 __all__ = [
@@ -29,6 +29,7 @@
     "HomelyAuthError",
     "HomelyResponseError",
     "HomelyWebSocketError",
+    "TokenEndpointResult",
     "TokenResponse",
     "auth_header_value",
 ]