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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beatbot-cloud
-Version: 0.4.0
+Version: 0.4.2
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0
@@ -46,7 +46,9 @@ events = BeatbotEventClient(
     session,
     client.event_stream_url,
     client.async_get_access_token,
-    async_handle_event,
+    state_callback=async_handle_state,
+    device_added_callback=async_handle_device_added,
+    device_removed_callback=async_handle_device_removed,
     reconnect_callback=async_handle_reconnect,
     token_refresh_callback=async_refresh_access_token,
 )
@@ -56,7 +58,11 @@ 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.
+refreshes. State callbacks receive a `BeatbotEvent`, which can be applied with
+`event.apply_to(device)`. Device-added and device-removed callbacks receive the
+device ID. The library routes cloud event types and ignores unknown types for
+these specialized callbacks. All callbacks may be synchronous or asynchronous.
+The optional positional `event_callback` remains supported and receives all events.
 
 ## Development
 

{beatbot_cloud-0.4.0 → beatbot_cloud-0.4.2}/README.md

@@ -18,7 +18,9 @@ events = BeatbotEventClient(
     session,
     client.event_stream_url,
     client.async_get_access_token,
-    async_handle_event,
+    state_callback=async_handle_state,
+    device_added_callback=async_handle_device_added,
+    device_removed_callback=async_handle_device_removed,
     reconnect_callback=async_handle_reconnect,
     token_refresh_callback=async_refresh_access_token,
 )
@@ -28,7 +30,11 @@ 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.
+refreshes. State callbacks receive a `BeatbotEvent`, which can be applied with
+`event.apply_to(device)`. Device-added and device-removed callbacks receive the
+device ID. The library routes cloud event types and ignores unknown types for
+these specialized callbacks. All callbacks may be synchronous or asynchronous.
+The optional positional `event_callback` remains supported and receives all events.
 
 ## Development
 

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

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

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

@@ -89,7 +89,7 @@ class BeatbotClient:
                 },
                 timeout=ClientTimeout(total=HTTP_API_TIMEOUT),
             )
-        except ClientError as err:
+        except (TimeoutError, ClientError) as err:
             raise BeatbotConnectionError(str(err)) from err
 
         body = await response.text()

{beatbot_cloud-0.4.0 → beatbot_cloud-0.4.2}/src/beatbot_cloud/event_client.py

@@ -29,6 +29,7 @@ _RECONNECT_DELAYS = (1.0, 2.0, 4.0, 8.0, 30.0, 60.0)
 _RECONNECT_JITTER = 0.2
 
 EventCallback = Callable[[BeatbotEvent], None | Awaitable[None]]
+DeviceCallback = Callable[[str], None | Awaitable[None]]
 ReconnectCallback = Callable[[], None | Awaitable[None]]
 TokenRefreshCallback = Callable[[str], str | Awaitable[str]]
 
@@ -41,8 +42,11 @@ class BeatbotEventClient:
         session: ClientSession,
         url: str,
         access_token: AccessTokenProvider,
-        event_callback: EventCallback,
+        event_callback: EventCallback | None = None,
         *,
+        state_callback: EventCallback | None = None,
+        device_added_callback: DeviceCallback | None = None,
+        device_removed_callback: DeviceCallback | None = None,
         reconnect_callback: ReconnectCallback | None = None,
         token_refresh_callback: TokenRefreshCallback | None = None,
     ) -> None:
@@ -51,6 +55,9 @@ class BeatbotEventClient:
         self._url = url
         self._access_token = access_token
         self._event_callback = event_callback
+        self._state_callback = state_callback
+        self._device_added_callback = device_added_callback
+        self._device_removed_callback = device_removed_callback
         self._reconnect_callback = reconnect_callback
         self._token_refresh_callback = token_refresh_callback
         self._stream: BeatbotEventStream | None = None
@@ -160,14 +167,36 @@ class BeatbotEventClient:
                 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
+                await self._async_dispatch_event(event)
         finally:
             await stream.close()
             if self._stream is stream:
                 self._stream = None
 
+    async def _async_dispatch_event(self, event: BeatbotEvent) -> None:
+        """Route cloud event types to consumer callbacks."""
+        if self._event_callback is not None:
+            result = self._event_callback(event)
+            if isawaitable(result):
+                await result
+        if event.event_type in ("properties_changed", "status"):
+            if self._state_callback is not None:
+                result = self._state_callback(event)
+                if isawaitable(result):
+                    await result
+        elif event.event_type == "device_added":
+            if self._device_added_callback is not None:
+                result = self._device_added_callback(event.device_id)
+                if isawaitable(result):
+                    await result
+        elif (
+            event.event_type == "device_removed"
+            and self._device_removed_callback is not None
+        ):
+            result = self._device_removed_callback(event.device_id)
+            if isawaitable(result):
+                await result
+
     async def async_close(self) -> None:
         """Stop receiving and close the current connection."""
         self._stopping = True

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: beatbot-cloud
-Version: 0.4.0
+Version: 0.4.2
 Summary: Asynchronous Python client for the Beatbot cloud API
 Author: Beatbot Robotics
 License-Expression: Apache-2.0
@@ -46,7 +46,9 @@ events = BeatbotEventClient(
     session,
     client.event_stream_url,
     client.async_get_access_token,
-    async_handle_event,
+    state_callback=async_handle_state,
+    device_added_callback=async_handle_device_added,
+    device_removed_callback=async_handle_device_removed,
     reconnect_callback=async_handle_reconnect,
     token_refresh_callback=async_refresh_access_token,
 )
@@ -56,7 +58,11 @@ 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.
+refreshes. State callbacks receive a `BeatbotEvent`, which can be applied with
+`event.apply_to(device)`. Device-added and device-removed callbacks receive the
+device ID. The library routes cloud event types and ignores unknown types for
+these specialized callbacks. All callbacks may be synchronous or asynchronous.
+The optional positional `event_callback` remains supported and receives all events.
 
 ## Development
 

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

@@ -116,6 +116,12 @@ async def test_client_error_is_connection_error():
         await api._request("GET", "/test")
 
 
+async def test_timeout_is_connection_error():
+    api, _ = client(TimeoutError("timed out"))
+    with pytest.raises(BeatbotConnectionError, match="timed out"):
+        await api._request("GET", "/test")
+
+
 async def test_async_access_token_provider():
     async def access_token():
         return "rotated-token"

{beatbot_cloud-0.4.0 → beatbot_cloud-0.4.2}/tests/test_event_client.py

@@ -49,6 +49,76 @@ async def test_connect_delivers_unique_events_and_ignores_malformed():
     stream.close.assert_awaited_once()
 
 
+@pytest.mark.parametrize("callback_type", [Mock, AsyncMock])
+@pytest.mark.parametrize(
+    ("event_type", "callback_name", "payload"),
+    [
+        (
+            "properties_changed",
+            "state_callback",
+            {"interfaceInfo": "vacuum.battery", "value": 42},
+        ),
+        ("status", "state_callback", {"online": False}),
+        ("device_added", "device_added_callback", {"deviceId": "device-1"}),
+        ("device_removed", "device_removed_callback", None),
+    ],
+)
+async def test_dispatches_specialized_callbacks(
+    callback_type, event_type, callback_name, payload
+):
+    callback = callback_type()
+    event = BeatbotEvent("event-1", event_type, "device-1", payload)
+    event_client = client(event_callback=None, **{callback_name: callback})
+    stream = SimpleNamespace(
+        connect=AsyncMock(),
+        receive=AsyncMock(side_effect=[event, event, 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()
+
+    argument = event if callback_name == "state_callback" else "device-1"
+    callback.assert_called_once_with(argument)
+    if callback_type is AsyncMock:
+        callback.assert_awaited_once_with(argument)
+
+
+@pytest.mark.parametrize(
+    "event_type",
+    ["status", "properties_changed", "device_added", "device_removed", "future_type"],
+)
+async def test_dispatch_without_callbacks(event_type):
+    event_client = client(event_callback=None)
+    await event_client._async_dispatch_event(
+        BeatbotEvent("event-1", event_type, "device-1", {})
+    )
+
+
+async def test_unknown_event_only_reaches_legacy_callback():
+    legacy = Mock()
+    state = Mock()
+    added = Mock()
+    removed = Mock()
+    event_client = client(
+        event_callback=legacy,
+        state_callback=state,
+        device_added_callback=added,
+        device_removed_callback=removed,
+    )
+    event = BeatbotEvent("event-1", "future_type", "device-1", {})
+
+    await event_client._async_dispatch_event(event)
+
+    legacy.assert_called_once_with(event)
+    state.assert_not_called()
+    added.assert_not_called()
+    removed.assert_not_called()
+
+
 async def test_reconnect_callback_runs_after_first_connection():
     reconnect_callback = AsyncMock()
     event_client = client(reconnect_callback=reconnect_callback)