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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beatbot-cloud
-Version: 0.2.0
+Version: 0.3.0
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "beatbot-cloud"
-version = "0.2.0"
+version = "0.3.0"
 description = "Asynchronous Python client for the Beatbot cloud API"
 readme = "README.md"
 requires-python = ">=3.11"

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

@@ -1,5 +1,6 @@
 """Asynchronous client for the Beatbot cloud API."""
 
+from .auth import decode_access_token
 from .client import BeatbotClient
 from .exceptions import (
     BeatbotAuthenticationError,
@@ -39,4 +40,5 @@ __all__ = [
     "STATUS_BY_CATEGORY",
     "error_mask_for",
     "status_for",
+    "decode_access_token",
 ]

beatbot_cloud-0.3.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.3.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.3.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.3.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.3.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.3.0
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0

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

@@ -2,6 +2,7 @@ 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/exceptions.py
@@ -14,6 +15,7 @@ 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_protocol.py
 tests/test_websocket.py

beatbot_cloud-0.3.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.3.0}/tests/test_client.py

@@ -12,6 +12,7 @@ from beatbot_cloud import (
     BeatbotAuthenticationError,
     BeatbotClient,
     BeatbotConnectionError,
+    BeatbotEvent,
 )
 from beatbot_cloud.const import OAUTH2_TOKEN_URL, REGION_API_BASE_URL
 
@@ -188,6 +189,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 (

{beatbot_cloud-0.2.0 → beatbot_cloud-0.3.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/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