beatbot-cloud 0.2.0__tar.gz → 0.4.0__tar.gz

{beatbot_cloud-0.2.0/src/beatbot_cloud.egg-info → beatbot_cloud-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beatbot-cloud
-Version: 0.2.0
+Version: 0.4.0
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -32,15 +33,30 @@ It provides region-aware REST access, typed device models, and a WebSocket event
 transport without depending on Home Assistant.
 
 ```python
-from beatbot_cloud import BeatbotClient
+from beatbot_cloud import BeatbotClient, BeatbotEventClient
 
-client = BeatbotClient(region="na", requester=oauth_request)
+client = BeatbotClient(
+    region="na",
+    session=session,
+    access_token=async_get_access_token,
+)
 devices = await client.get_devices()
+
+events = BeatbotEventClient(
+    session,
+    client.event_stream_url,
+    client.async_get_access_token,
+    async_handle_event,
+    reconnect_callback=async_handle_reconnect,
+    token_refresh_callback=async_refresh_access_token,
+)
+await events.async_run()
 ```
 
-The caller owns authentication. `requester` is an async callable compatible
-with `aiohttp.ClientSession.request`; it may add or refresh OAuth credentials
-before forwarding the request.
+The caller provides an access token or a synchronous/asynchronous token provider.
+The library owns REST request construction and WebSocket reconnection; applications
+can register callbacks for events, successful reconnections, and rejected-token
+refreshes.
 
 ## Development
 
@@ -51,4 +67,3 @@ ruff check .
 ruff format --check .
 python -m build
 ```
-

beatbot_cloud-0.4.0/README.md

@@ -0,0 +1,41 @@
+# beatbot-cloud
+
+`beatbot-cloud` is the asynchronous Python client for Beatbot cloud accounts.
+It provides region-aware REST access, typed device models, and a WebSocket event
+transport without depending on Home Assistant.
+
+```python
+from beatbot_cloud import BeatbotClient, BeatbotEventClient
+
+client = BeatbotClient(
+    region="na",
+    session=session,
+    access_token=async_get_access_token,
+)
+devices = await client.get_devices()
+
+events = BeatbotEventClient(
+    session,
+    client.event_stream_url,
+    client.async_get_access_token,
+    async_handle_event,
+    reconnect_callback=async_handle_reconnect,
+    token_refresh_callback=async_refresh_access_token,
+)
+await events.async_run()
+```
+
+The caller provides an access token or a synchronous/asynchronous token provider.
+The library owns REST request construction and WebSocket reconnection; applications
+can register callbacks for events, successful reconnections, and rejected-token
+refreshes.
+
+## Development
+
+```bash
+python -m pip install -e '.[test]'
+pytest
+ruff check .
+ruff format --check .
+python -m build
+```

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "beatbot-cloud"
-version = "0.2.0"
+version = "0.4.0"
 description = "Asynchronous Python client for the Beatbot cloud API"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -18,6 +18,7 @@ classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Typing :: Typed",
 ]
 

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud/__init__.py

@@ -1,6 +1,8 @@
 """Asynchronous client for the Beatbot cloud API."""
 
+from .auth import decode_access_token
 from .client import BeatbotClient
+from .event_client import BeatbotEventClient
 from .exceptions import (
     BeatbotAuthenticationError,
     BeatbotConnectionError,
@@ -15,6 +17,7 @@ from .protocol import (
     DeviceError,
     DeviceStatus,
     ProductCategory,
+    error_for,
     error_mask_for,
     status_for,
 )
@@ -28,6 +31,7 @@ __all__ = [
     "BeatbotConnectionReplacedError",
     "BeatbotDeviceData",
     "BeatbotEvent",
+    "BeatbotEventClient",
     "BeatbotEventError",
     "BeatbotEventStream",
     "BeatbotTokenRejectedError",
@@ -37,6 +41,8 @@ __all__ = [
     "FirmwareVersion",
     "ProductCategory",
     "STATUS_BY_CATEGORY",
+    "error_for",
     "error_mask_for",
     "status_for",
+    "decode_access_token",
 ]

beatbot_cloud-0.4.0/src/beatbot_cloud/auth.py

@@ -0,0 +1,23 @@
+"""Authentication helpers for Beatbot cloud tokens."""
+
+import base64
+import binascii
+import json
+from typing import Any
+
+
+def decode_access_token(access_token: str) -> dict[str, Any] | None:
+    """Decode the claims from a JWT access token without verifying its signature."""
+    try:
+        payload = access_token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload))
+    except (
+        binascii.Error,
+        IndexError,
+        json.JSONDecodeError,
+        UnicodeDecodeError,
+        ValueError,
+    ):
+        return None
+    return claims if isinstance(claims, dict) else None

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud/client.py

@@ -6,9 +6,10 @@ import json
 import logging
 from collections.abc import Awaitable, Callable
 from http import HTTPStatus
-from typing import Any, Protocol, TypeAlias
+from inspect import isawaitable
+from typing import Any, TypeAlias
 
-from aiohttp import ClientResponseError, ClientTimeout
+from aiohttp import ClientError, ClientSession, ClientTimeout
 
 from .const import (
     DEVICE_ACTIONS_PATH,
@@ -17,7 +18,6 @@ from .const import (
     EVENTS_PATH,
     HTTP_API_TIMEOUT,
     INTERFACE_WORK_MODE,
-    OAUTH2_TOKEN_URL,
     REGION_API_BASE_URL,
     RESULT_SUCCESS_CODE,
 )
@@ -27,39 +27,36 @@ from .models import BeatbotCapability, BeatbotDeviceData, FirmwareVersion
 _LOGGER = logging.getLogger(__name__)
 
 
-class Response(Protocol):
-    """Subset of an aiohttp response used by the client."""
-
-    status: int
-    headers: dict[str, str]
-
-    async def text(self) -> str:
-        """Return the response body."""
-
-
-Requester: TypeAlias = Callable[..., Awaitable[Response]]
-
-
-def _is_oauth_reauthentication_error(err: ClientResponseError) -> bool:
-    """Return whether an OAuth token response requires user reauthentication."""
-    request_url = str(getattr(err.request_info, "real_url", "")).split("?", 1)[0]
-    return (
-        request_url == OAUTH2_TOKEN_URL
-        and HTTPStatus.BAD_REQUEST <= err.status < HTTPStatus.INTERNAL_SERVER_ERROR
-        and err.status not in (HTTPStatus.REQUEST_TIMEOUT, HTTPStatus.TOO_MANY_REQUESTS)
-    )
+AccessTokenProvider: TypeAlias = Callable[[], str | Awaitable[str]]
 
 
 class BeatbotClient:
-    """Access the Beatbot cloud API using a caller-provided request function."""
+    """Access the Beatbot cloud API."""
 
-    def __init__(self, region: str, requester: Requester) -> None:
+    def __init__(
+        self,
+        region: str,
+        session: ClientSession,
+        access_token: str | AccessTokenProvider,
+    ) -> None:
         """Initialize the client for an OAuth token's region claim."""
         try:
             self._base_url = REGION_API_BASE_URL[region]
         except KeyError as err:
             raise ValueError(f"Unknown or missing Beatbot region: {region!r}") from err
-        self._requester = requester
+        self._session = session
+        self._access_token = access_token
+
+    async def async_get_access_token(self) -> str:
+        """Return the current access token."""
+        token = (
+            self._access_token() if callable(self._access_token) else self._access_token
+        )
+        if isawaitable(token):
+            token = await token
+        if not token:
+            raise BeatbotAuthenticationError("Missing OAuth access token")
+        return token
 
     @property
     def event_stream_url(self) -> str:
@@ -79,22 +76,20 @@ class BeatbotClient:
         json_body: Any | None = None,
     ) -> Any:
         """Request and validate a Beatbot result envelope."""
+        access_token = await self.async_get_access_token()
         try:
-            response = await self._requester(
+            response = await self._session.request(
                 method,
                 f"{self._base_url}{path}",
                 params=params,
                 json=json_body,
-                headers={"Accept": "application/json"},
+                headers={
+                    "Accept": "application/json",
+                    "Authorization": f"Bearer {access_token}",
+                },
                 timeout=ClientTimeout(total=HTTP_API_TIMEOUT),
             )
-        except ClientResponseError as err:
-            if _is_oauth_reauthentication_error(err):
-                raise BeatbotAuthenticationError(
-                    "OAuth token refresh rejected; reauthentication required"
-                ) from err
-            raise BeatbotConnectionError(str(err)) from err
-        except Exception as err:
+        except ClientError as err:
             raise BeatbotConnectionError(str(err)) from err
 
         body = await response.text()

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud/const.py

@@ -21,3 +21,8 @@ EVENTS_PATH: Final = "/openapi/v1/ha/ws"
 RESULT_SUCCESS_CODE: Final = 200
 
 INTERFACE_WORK_MODE: Final = "select.work_mode"
+INTERFACE_VACUUM_STATE: Final = "vacuum.state"
+INTERFACE_VACUUM_BATTERY: Final = "vacuum.battery"
+INTERFACE_SENSOR_ERROR: Final = "sensor.error"
+INTERFACE_CHILD_LOCK: Final = "switch.child_lock"
+INTERFACE_VOICE_DISTURB: Final = "switch.voice_disturb"

beatbot_cloud-0.4.0/src/beatbot_cloud/event_client.py

@@ -0,0 +1,183 @@
+"""Resilient Beatbot cloud event client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from inspect import isawaitable
+
+from aiohttp import ClientError, ClientSession
+
+from .client import AccessTokenProvider
+from .exceptions import (
+    BeatbotAuthenticationError,
+    BeatbotConnectionError,
+    BeatbotConnectionReplacedError,
+    BeatbotEventError,
+    BeatbotTokenRejectedError,
+)
+from .models import BeatbotEvent
+from .websocket import BeatbotEventStream
+
+_LOGGER = logging.getLogger(__name__)
+
+_EVENT_DEDUP_CACHE_SIZE = 256
+_RECONNECT_DELAYS = (1.0, 2.0, 4.0, 8.0, 30.0, 60.0)
+_RECONNECT_JITTER = 0.2
+
+EventCallback = Callable[[BeatbotEvent], None | Awaitable[None]]
+ReconnectCallback = Callable[[], None | Awaitable[None]]
+TokenRefreshCallback = Callable[[str], str | Awaitable[str]]
+
+
+class BeatbotEventClient:
+    """Maintain and recover an account-scoped Beatbot event stream."""
+
+    def __init__(
+        self,
+        session: ClientSession,
+        url: str,
+        access_token: AccessTokenProvider,
+        event_callback: EventCallback,
+        *,
+        reconnect_callback: ReconnectCallback | None = None,
+        token_refresh_callback: TokenRefreshCallback | None = None,
+    ) -> None:
+        """Initialize the event client without connecting it."""
+        self._session = session
+        self._url = url
+        self._access_token = access_token
+        self._event_callback = event_callback
+        self._reconnect_callback = reconnect_callback
+        self._token_refresh_callback = token_refresh_callback
+        self._stream: BeatbotEventStream | None = None
+        self._stopping = False
+        self._token_refresh_attempted = False
+        self._has_connected = False
+        self._connection_generation = 0
+        self._next_access_token: str | None = None
+        self._seen_event_ids: OrderedDict[str, None] = OrderedDict()
+
+    async def async_run(self) -> None:
+        """Connect and receive events until closed or authentication fails."""
+        failures = 0
+        self._stopping = False
+        try:
+            while not self._stopping:
+                connection_generation = self._connection_generation
+                try:
+                    await self._async_connect_and_receive()
+                except asyncio.CancelledError:
+                    raise
+                except BeatbotConnectionReplacedError:
+                    return
+                except BeatbotTokenRejectedError as err:
+                    if (
+                        self._token_refresh_attempted
+                        or self._token_refresh_callback is None
+                    ):
+                        raise BeatbotAuthenticationError(
+                            "Event stream rejected the refreshed access token"
+                        ) from err
+                    try:
+                        token = self._token_refresh_callback(err.access_token)
+                        if isawaitable(token):
+                            token = await token
+                        if not token:
+                            raise BeatbotAuthenticationError(
+                                "Token refresh returned no access token"
+                            )
+                    except BeatbotAuthenticationError:
+                        raise
+                    except BeatbotConnectionError as refresh_err:
+                        failures += 1
+                        _LOGGER.warning(
+                            "Beatbot OAuth token refresh failed: %s", refresh_err
+                        )
+                    else:
+                        self._next_access_token = token
+                        self._token_refresh_attempted = True
+                        failures = 0
+                        continue
+                except BeatbotAuthenticationError:
+                    raise
+                except (
+                    TimeoutError,
+                    BeatbotConnectionError,
+                    ClientError,
+                    ConnectionError,
+                ) as err:
+                    if self._connection_generation != connection_generation:
+                        failures = 0
+                    failures += 1
+                    _LOGGER.warning("Beatbot event stream disconnected: %s", err)
+                except Exception:
+                    failures += 1
+                    _LOGGER.exception("Unexpected Beatbot event stream failure")
+
+                if self._stopping:
+                    return
+                delay = _RECONNECT_DELAYS[min(failures - 1, len(_RECONNECT_DELAYS) - 1)]
+                delay *= random.uniform(
+                    1.0 - _RECONNECT_JITTER, 1.0 + _RECONNECT_JITTER
+                )
+                await asyncio.sleep(delay)
+        finally:
+            await self.async_close()
+
+    async def _async_connect_and_receive(self) -> None:
+        """Connect once and receive until the connection closes."""
+        access_token = self._next_access_token
+        self._next_access_token = None
+        if access_token is None:
+            access_token = self._access_token()
+            if isawaitable(access_token):
+                access_token = await access_token
+        if not access_token:
+            raise BeatbotAuthenticationError("Missing OAuth access token")
+
+        stream = BeatbotEventStream(self._session, self._url, access_token)
+        self._stream = stream
+        try:
+            await stream.connect()
+            is_reconnect = self._has_connected
+            self._has_connected = True
+            self._connection_generation += 1
+            if is_reconnect and self._reconnect_callback is not None:
+                result = self._reconnect_callback()
+                if isawaitable(result):
+                    await result
+            while not self._stopping:
+                try:
+                    event = await stream.receive()
+                except BeatbotEventError as err:
+                    _LOGGER.warning("Ignoring malformed Beatbot event: %s", err)
+                    continue
+                self._token_refresh_attempted = False
+                if event.event_id in self._seen_event_ids:
+                    continue
+                self._remember_event(event.event_id)
+                result = self._event_callback(event)
+                if isawaitable(result):
+                    await result
+        finally:
+            await stream.close()
+            if self._stream is stream:
+                self._stream = None
+
+    async def async_close(self) -> None:
+        """Stop receiving and close the current connection."""
+        self._stopping = True
+        stream, self._stream = self._stream, None
+        if stream is not None:
+            await stream.close()
+
+    def _remember_event(self, event_id: str) -> None:
+        """Remember an event identifier for bounded duplicate suppression."""
+        self._seen_event_ids[event_id] = None
+        self._seen_event_ids.move_to_end(event_id)
+        while len(self._seen_event_ids) > _EVENT_DEDUP_CACHE_SIZE:
+            self._seen_event_ids.popitem(last=False)

beatbot_cloud-0.4.0/src/beatbot_cloud/models.py

@@ -0,0 +1,106 @@
+"""Typed Beatbot cloud models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .const import (
+    INTERFACE_CHILD_LOCK,
+    INTERFACE_SENSOR_ERROR,
+    INTERFACE_VACUUM_BATTERY,
+    INTERFACE_VACUUM_STATE,
+    INTERFACE_VOICE_DISTURB,
+    INTERFACE_WORK_MODE,
+)
+
+
+@dataclass(slots=True)
+class FirmwareVersion:
+    """A device firmware version."""
+
+    channel: int
+    version: str
+
+
+@dataclass(slots=True)
+class BeatbotCapability:
+    """A Home Assistant capability advertised by Beatbot discovery."""
+
+    interface_info: str
+    retrievable: bool = False
+    proactively_reported: bool = False
+    non_controllable: bool = False
+
+
+@dataclass(slots=True)
+class BeatbotDeviceData:
+    """A discovered Beatbot device."""
+
+    device_id: str
+    product_id: str
+    product_category: str
+    work_status: int
+    work_mode: int
+    error_code: int
+    battery_level: int
+    versions: list[FirmwareVersion]
+    is_online: bool
+    child_lock: bool = False
+    voice_disturb: bool = False
+    name: str = ""
+    model: str = ""
+    work_mode_options: dict[int, str] = field(default_factory=dict)
+    capabilities: dict[str, BeatbotCapability] = field(default_factory=dict)
+
+    def apply_state(
+        self, states: dict[str, Any] | None, is_online: bool | None = None
+    ) -> None:
+        """Apply a runtime-state response or event to this device."""
+        if states:
+            if INTERFACE_VACUUM_STATE in states:
+                self.work_status = states[INTERFACE_VACUUM_STATE]
+            if INTERFACE_VACUUM_BATTERY in states:
+                self.battery_level = states[INTERFACE_VACUUM_BATTERY]
+            if INTERFACE_SENSOR_ERROR in states:
+                self.error_code = states[INTERFACE_SENSOR_ERROR]
+            if INTERFACE_WORK_MODE in states:
+                self.work_mode = states[INTERFACE_WORK_MODE]
+            if INTERFACE_CHILD_LOCK in states:
+                self.child_lock = states[INTERFACE_CHILD_LOCK]
+            if INTERFACE_VOICE_DISTURB in states:
+                self.voice_disturb = states[INTERFACE_VOICE_DISTURB]
+        if is_online is not None:
+            self.is_online = is_online
+
+    def copy_runtime_state_from(self, other: BeatbotDeviceData) -> None:
+        """Copy the last-known runtime state from another instance."""
+        self.work_status = other.work_status
+        self.work_mode = other.work_mode
+        self.error_code = other.error_code
+        self.battery_level = other.battery_level
+        self.is_online = other.is_online
+        self.child_lock = other.child_lock
+        self.voice_disturb = other.voice_disturb
+
+
+@dataclass(frozen=True, slots=True)
+class BeatbotEvent:
+    """A validated Beatbot cloud event envelope."""
+
+    event_id: str
+    event_type: str
+    device_id: str
+    payload: dict[str, Any] | None
+
+    def apply_to(self, device: BeatbotDeviceData) -> bool:
+        """Apply a state-bearing event and return whether data changed."""
+        if self.event_type == "properties_changed":
+            assert self.payload is not None
+            device.apply_state({self.payload["interfaceInfo"]: self.payload["value"]})
+            return True
+        if self.event_type == "status":
+            assert self.payload is not None
+            device.apply_state(None, self.payload["online"])
+            return True
+        return False

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud/protocol.py

@@ -205,6 +205,18 @@ def status_for(category: ProductCategory, raw_status: int) -> DeviceStatus | Non
     return STATUS_BY_CATEGORY.get(category, {}).get(raw_status)
 
 
+def error_for(category: ProductCategory, error_code: int) -> DeviceError | None:
+    """Return the first active error for a product category."""
+    return next(
+        (
+            error
+            for error, bit in ERROR_BITS_BY_CATEGORY.get(category, ())
+            if error_code & bit
+        ),
+        None,
+    )
+
+
 def error_mask_for(category: ProductCategory, *, include_notices: bool = True) -> int:
     """Return the combined error mask for a product category."""
     return sum(

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud/websocket.py

@@ -106,6 +106,8 @@ class BeatbotEventStream:
             BeatbotEventStream._validate_property_payload(payload)
         elif event_type == "status" and not isinstance(payload.get("online"), bool):
             raise BeatbotEventError("Status event has an invalid online value")
+        elif event_type == "device_added" and payload.get("deviceId") != device_id:
+            raise BeatbotEventError("device_added payload has a mismatched deviceId")
         return BeatbotEvent(event_id, event_type, device_id, payload)
 
     @staticmethod

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0/src/beatbot_cloud.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beatbot-cloud
-Version: 0.2.0
+Version: 0.4.0
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0
@@ -13,6 +13,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -32,15 +33,30 @@ It provides region-aware REST access, typed device models, and a WebSocket event
 transport without depending on Home Assistant.
 
 ```python
-from beatbot_cloud import BeatbotClient
+from beatbot_cloud import BeatbotClient, BeatbotEventClient
 
-client = BeatbotClient(region="na", requester=oauth_request)
+client = BeatbotClient(
+    region="na",
+    session=session,
+    access_token=async_get_access_token,
+)
 devices = await client.get_devices()
+
+events = BeatbotEventClient(
+    session,
+    client.event_stream_url,
+    client.async_get_access_token,
+    async_handle_event,
+    reconnect_callback=async_handle_reconnect,
+    token_refresh_callback=async_refresh_access_token,
+)
+await events.async_run()
 ```
 
-The caller owns authentication. `requester` is an async callable compatible
-with `aiohttp.ClientSession.request`; it may add or refresh OAuth credentials
-before forwarding the request.
+The caller provides an access token or a synchronous/asynchronous token provider.
+The library owns REST request construction and WebSocket reconnection; applications
+can register callbacks for events, successful reconnections, and rejected-token
+refreshes.
 
 ## Development
 
@@ -51,4 +67,3 @@ ruff check .
 ruff format --check .
 python -m build
 ```
-

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/src/beatbot_cloud.egg-info/SOURCES.txt

@@ -2,8 +2,10 @@ LICENSE
 README.md
 pyproject.toml
 src/beatbot_cloud/__init__.py
+src/beatbot_cloud/auth.py
 src/beatbot_cloud/client.py
 src/beatbot_cloud/const.py
+src/beatbot_cloud/event_client.py
 src/beatbot_cloud/exceptions.py
 src/beatbot_cloud/models.py
 src/beatbot_cloud/protocol.py
@@ -14,6 +16,8 @@ src/beatbot_cloud.egg-info/SOURCES.txt
 src/beatbot_cloud.egg-info/dependency_links.txt
 src/beatbot_cloud.egg-info/requires.txt
 src/beatbot_cloud.egg-info/top_level.txt
+tests/test_auth.py
 tests/test_client.py
+tests/test_event_client.py
 tests/test_protocol.py
 tests/test_websocket.py

beatbot_cloud-0.4.0/tests/test_auth.py

@@ -0,0 +1,28 @@
+"""Tests for Beatbot authentication helpers."""
+
+import base64
+import json
+
+import pytest
+
+from beatbot_cloud import decode_access_token
+
+
+def test_decode_access_token() -> None:
+    """Decode valid JWT claims."""
+    payload = (
+        base64.urlsafe_b64encode(json.dumps({"sub": "user-1", "region": "eu"}).encode())
+        .decode()
+        .rstrip("=")
+    )
+
+    assert decode_access_token(f"header.{payload}.signature") == {
+        "sub": "user-1",
+        "region": "eu",
+    }
+
+
+@pytest.mark.parametrize("token", ["", "invalid", "a.!.c", "a.W10.c"])
+def test_decode_access_token_rejects_invalid_claims(token: str) -> None:
+    """Reject malformed tokens and non-object claims."""
+    assert decode_access_token(token) is None

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/tests/test_client.py

@@ -3,17 +3,17 @@
 from __future__ import annotations
 
 import json
-from types import SimpleNamespace
 
 import pytest
-from aiohttp import ClientResponseError
+from aiohttp import ClientError
 
 from beatbot_cloud import (
     BeatbotAuthenticationError,
     BeatbotClient,
     BeatbotConnectionError,
+    BeatbotEvent,
 )
-from beatbot_cloud.const import OAUTH2_TOKEN_URL, REGION_API_BASE_URL
+from beatbot_cloud.const import REGION_API_BASE_URL
 
 
 class Response:
@@ -28,23 +28,23 @@ class Response:
         return self.body
 
 
-class Requester:
+class Session:
     """Record requests and return or raise a configured result."""
 
     def __init__(self, result):
         self.result = result
         self.calls = []
 
-    async def __call__(self, method, url, **kwargs):
+    async def request(self, method, url, **kwargs):
         self.calls.append((method, url, kwargs))
         if isinstance(self.result, Exception):
             raise self.result
         return self.result
 
 
-def client(result, region="na"):
-    requester = Requester(result)
-    return BeatbotClient(region, requester), requester
+def client(result, region="na", access_token="access-token"):
+    session = Session(result)
+    return BeatbotClient(region, session, access_token), session
 
 
 def envelope(data=None, *, code=200, message=None):
@@ -97,42 +97,40 @@ async def test_request_rejects_invalid_envelope(response, message):
 
 
 async def test_request_forwards_options_and_returns_data():
-    api, requester = client(envelope({"ok": True}))
+    api, session = client(envelope({"ok": True}))
     result = await api._request(
         "POST", "/test", params={"a": "b"}, json_body={"value": 1}
     )
     assert result == {"ok": True}
-    method, url, kwargs = requester.calls[0]
+    method, url, kwargs = session.calls[0]
     assert method == "POST"
     assert url.endswith("/test")
     assert kwargs["params"] == {"a": "b"}
     assert kwargs["json"] == {"value": 1}
+    assert kwargs["headers"]["Authorization"] == "Bearer access-token"
 
 
-@pytest.mark.parametrize("status", [400, 401, 403, 499])
-async def test_terminal_oauth_error_requires_authentication(status):
-    error = ClientResponseError(
-        SimpleNamespace(real_url=OAUTH2_TOKEN_URL), (), status=status
-    )
-    api, _ = client(error)
-    with pytest.raises(BeatbotAuthenticationError):
+async def test_client_error_is_connection_error():
+    api, _ = client(ClientError("offline"))
+    with pytest.raises(BeatbotConnectionError, match="offline"):
         await api._request("GET", "/test")
 
 
-@pytest.mark.parametrize("status", [408, 429, 500])
-async def test_transient_oauth_error_is_connection_error(status):
-    error = ClientResponseError(
-        SimpleNamespace(real_url=OAUTH2_TOKEN_URL), (), status=status
-    )
-    api, _ = client(error)
-    with pytest.raises(BeatbotConnectionError):
-        await api._request("GET", "/test")
+async def test_async_access_token_provider():
+    async def access_token():
+        return "rotated-token"
 
+    api, session = client(envelope(), access_token=access_token)
 
-async def test_non_oauth_exception_is_connection_error():
-    api, _ = client(RuntimeError("offline"))
-    with pytest.raises(BeatbotConnectionError, match="offline"):
-        await api._request("GET", "/test")
+    await api.get_devices()
+
+    assert session.calls[0][2]["headers"]["Authorization"] == "Bearer rotated-token"
+
+
+async def test_missing_access_token_requires_authentication():
+    api, _ = client(envelope(), access_token="")
+    with pytest.raises(BeatbotAuthenticationError, match="Missing"):
+        await api.get_devices()
 
 
 async def test_get_devices_empty():
@@ -188,6 +186,57 @@ async def test_get_devices_parses_models_and_capabilities():
     assert devices[0].capabilities["select.work_mode"].retrievable
 
 
+def test_device_applies_and_copies_runtime_state():
+    """Runtime state is parsed by the library model without dynamic attributes."""
+    api, _ = client(envelope())
+    device = api._parse_device({"deviceId": "d1"})
+    previous = api._parse_device({"deviceId": "d1", "isOnline": True})
+    assert device is not None
+    assert previous is not None
+    previous.apply_state(
+        {
+            "vacuum.state": 5,
+            "vacuum.battery": 80,
+            "sensor.error": 2,
+            "select.work_mode": 1,
+            "switch.child_lock": True,
+            "switch.voice_disturb": True,
+        }
+    )
+    device.copy_runtime_state_from(previous)
+
+    assert device.work_status == 5
+    assert device.battery_level == 80
+    assert device.error_code == 2
+    assert device.work_mode == 1
+    assert device.child_lock
+    assert device.voice_disturb
+    assert device.is_online
+
+
+def test_state_events_apply_to_device():
+    """State-bearing events interpret their payload in the library."""
+    api, _ = client(envelope())
+    device = api._parse_device({"deviceId": "d1", "isOnline": True})
+    assert device is not None
+
+    changed = BeatbotEvent(
+        "1",
+        "properties_changed",
+        "d1",
+        {"interfaceInfo": "vacuum.battery", "value": 42},
+    ).apply_to(device)
+    online_changed = BeatbotEvent("2", "status", "d1", {"online": False}).apply_to(
+        device
+    )
+
+    assert changed
+    assert online_changed
+    assert device.battery_level == 42
+    assert not device.is_online
+    assert not BeatbotEvent("3", "unknown", "d1", {}).apply_to(device)
+
+
 @pytest.mark.parametrize("configuration", ["bad json", [], None])
 def test_invalid_work_mode_configuration(configuration):
     assert (
@@ -234,11 +283,11 @@ async def test_get_device_state():
 
 
 async def test_actions():
-    api, requester = client(envelope())
+    api, session = client(envelope())
     await api.send_action("d1", "vacuum.start")
     await api.set_work_mode("d1", "quick")
     await api.set_switch("d1", "switch.child_lock", "on")
-    assert [call[2]["json"] for call in requester.calls] == [
+    assert [call[2]["json"] for call in session.calls] == [
         {"interfaceInfo": "vacuum.start"},
         {"interfaceInfo": "select.work_mode", "label": "quick"},
         {"interfaceInfo": "switch.child_lock", "label": "on"},

beatbot_cloud-0.4.0/tests/test_event_client.py

@@ -0,0 +1,121 @@
+"""Tests for the resilient Beatbot event client."""
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock, patch
+
+import pytest
+
+from beatbot_cloud import (
+    BeatbotAuthenticationError,
+    BeatbotConnectionError,
+    BeatbotConnectionReplacedError,
+    BeatbotEvent,
+    BeatbotEventClient,
+    BeatbotEventError,
+    BeatbotTokenRejectedError,
+)
+
+
+def client(**kwargs):
+    return BeatbotEventClient(
+        SimpleNamespace(),
+        "wss://test",
+        kwargs.pop("access_token", lambda: "token"),
+        kwargs.pop("event_callback", Mock()),
+        **kwargs,
+    )
+
+
+async def test_connect_delivers_unique_events_and_ignores_malformed():
+    event_callback = Mock()
+    event = BeatbotEvent("event-1", "status", "device-1", {"online": True})
+    stream = SimpleNamespace(
+        connect=AsyncMock(),
+        receive=AsyncMock(
+            side_effect=[BeatbotEventError("bad"), event, event, asyncio.CancelledError]
+        ),
+        close=AsyncMock(),
+    )
+    event_client = client(event_callback=event_callback)
+
+    with (
+        patch("beatbot_cloud.event_client.BeatbotEventStream", return_value=stream),
+        pytest.raises(asyncio.CancelledError),
+    ):
+        await event_client._async_connect_and_receive()
+
+    event_callback.assert_called_once_with(event)
+    stream.close.assert_awaited_once()
+
+
+async def test_reconnect_callback_runs_after_first_connection():
+    reconnect_callback = AsyncMock()
+    event_client = client(reconnect_callback=reconnect_callback)
+    event_client._has_connected = True
+    stream = SimpleNamespace(
+        connect=AsyncMock(),
+        receive=AsyncMock(side_effect=asyncio.CancelledError),
+        close=AsyncMock(),
+    )
+
+    with (
+        patch("beatbot_cloud.event_client.BeatbotEventStream", return_value=stream),
+        pytest.raises(asyncio.CancelledError),
+    ):
+        await event_client._async_connect_and_receive()
+
+    reconnect_callback.assert_awaited_once()
+
+
+async def test_token_rejection_refreshes_and_reconnects():
+    refresh_callback = AsyncMock(return_value="new-token")
+    event_client = client(token_refresh_callback=refresh_callback)
+    event_client._async_connect_and_receive = AsyncMock(
+        side_effect=[
+            BeatbotTokenRejectedError("old-token"),
+            BeatbotConnectionReplacedError(),
+        ]
+    )
+
+    await event_client.async_run()
+
+    refresh_callback.assert_awaited_once_with("old-token")
+    assert event_client._next_access_token == "new-token"
+
+
+async def test_repeated_token_rejection_requires_authentication():
+    event_client = client(token_refresh_callback=AsyncMock(return_value="new-token"))
+    event_client._token_refresh_attempted = True
+    event_client._async_connect_and_receive = AsyncMock(
+        side_effect=BeatbotTokenRejectedError("new-token")
+    )
+
+    with pytest.raises(BeatbotAuthenticationError):
+        await event_client.async_run()
+
+
+async def test_connection_failure_retries():
+    event_client = client()
+    event_client._async_connect_and_receive = AsyncMock(
+        side_effect=[
+            BeatbotConnectionError("offline"),
+            BeatbotConnectionReplacedError(),
+        ]
+    )
+
+    with patch("beatbot_cloud.event_client.asyncio.sleep", AsyncMock()) as sleep:
+        await event_client.async_run()
+
+    sleep.assert_awaited_once()
+
+
+async def test_close_is_idempotent():
+    event_client = client()
+    stream = SimpleNamespace(close=AsyncMock())
+    event_client._stream = stream
+
+    await event_client.async_close()
+    await event_client.async_close()
+
+    stream.close.assert_awaited_once()

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/tests/test_protocol.py

@@ -4,6 +4,7 @@ from beatbot_cloud import (
     DeviceError,
     DeviceStatus,
     ProductCategory,
+    error_for,
     error_mask_for,
     status_for,
 )
@@ -25,3 +26,11 @@ def test_clean_base_error_mask_can_exclude_notices():
     assert faults_only & (1 << 0)
     assert not faults_only & (1 << 5)
     assert DeviceError.SELF_ERR_SPRAY.value == "self_err_spray"
+
+
+def test_error_mapping_returns_first_active_error():
+    assert (
+        error_for(ProductCategory.POOL_CLEAN_BOT, (1 << 2) | (1 << 6))
+        is DeviceError.POWER_LOW
+    )
+    assert error_for(ProductCategory.POOL_CLEAN_BOT, 0) is None

{beatbot_cloud-0.2.0 → beatbot_cloud-0.4.0}/tests/test_websocket.py

@@ -85,6 +85,14 @@ def test_parse_removed_event():
     assert event.payload is None
 
 
+def test_parse_rejects_mismatched_added_device():
+    with pytest.raises(BeatbotEventError, match="mismatched"):
+        BeatbotEventStream.parse_event(
+            '{"eventId":"1","type":"device_added","deviceId":"d",'
+            '"payload":{"deviceId":"other"}}'
+        )
+
+
 async def test_connect_and_close():
     websocket = SimpleNamespace(closed=False, close=AsyncMock())
     session = SimpleNamespace(ws_connect=AsyncMock(return_value=websocket))

beatbot_cloud-0.2.0/README.md

@@ -1,27 +0,0 @@
-# beatbot-cloud
-
-`beatbot-cloud` is the asynchronous Python client for Beatbot cloud accounts.
-It provides region-aware REST access, typed device models, and a WebSocket event
-transport without depending on Home Assistant.
-
-```python
-from beatbot_cloud import BeatbotClient
-
-client = BeatbotClient(region="na", requester=oauth_request)
-devices = await client.get_devices()
-```
-
-The caller owns authentication. `requester` is an async callable compatible
-with `aiohttp.ClientSession.request`; it may add or refresh OAuth credentials
-before forwarding the request.
-
-## Development
-
-```bash
-python -m pip install -e '.[test]'
-pytest
-ruff check .
-ruff format --check .
-python -m build
-```
-

beatbot_cloud-0.2.0/src/beatbot_cloud/models.py

@@ -1,55 +0,0 @@
-"""Typed Beatbot cloud models."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Any
-
-
-@dataclass(slots=True)
-class FirmwareVersion:
-    """A device firmware version."""
-
-    channel: int
-    version: str
-
-
-@dataclass(slots=True)
-class BeatbotCapability:
-    """A Home Assistant capability advertised by Beatbot discovery."""
-
-    interface_info: str
-    retrievable: bool = False
-    proactively_reported: bool = False
-    non_controllable: bool = False
-
-
-@dataclass(slots=True)
-class BeatbotDeviceData:
-    """A discovered Beatbot device."""
-
-    device_id: str
-    product_id: str
-    product_category: str
-    work_status: int
-    work_mode: int
-    error_code: int
-    battery_level: int
-    versions: list[FirmwareVersion]
-    is_online: bool
-    child_lock: bool = False
-    voice_disturb: bool = False
-    name: str = ""
-    model: str = ""
-    work_mode_options: dict[int, str] = field(default_factory=dict)
-    capabilities: dict[str, BeatbotCapability] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True)
-class BeatbotEvent:
-    """A validated Beatbot cloud event envelope."""
-
-    event_id: str
-    event_type: str
-    device_id: str
-    payload: dict[str, Any] | None