beatbot-cloud 0.1.0__py3-none-any.whl

beatbot_cloud/__init__.py

@@ -0,0 +1,24 @@
+"""Asynchronous client for the Beatbot cloud API."""
+
+from .client import BeatbotClient
+from .exceptions import (
+    BeatbotAuthenticationError,
+    BeatbotConnectionError,
+    BeatbotConnectionReplacedError,
+    BeatbotTokenRejectedError,
+)
+from .models import BeatbotCapability, BeatbotDeviceData, BeatbotEvent, FirmwareVersion
+from .websocket import BeatbotEventStream
+
+__all__ = [
+    "BeatbotAuthenticationError",
+    "BeatbotCapability",
+    "BeatbotClient",
+    "BeatbotConnectionError",
+    "BeatbotConnectionReplacedError",
+    "BeatbotDeviceData",
+    "BeatbotEvent",
+    "BeatbotEventStream",
+    "BeatbotTokenRejectedError",
+    "FirmwareVersion",
+]

beatbot_cloud/client.py

@@ -0,0 +1,285 @@
+"""Region-aware asynchronous Beatbot REST client."""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Awaitable, Callable
+from http import HTTPStatus
+from typing import Any, Protocol, TypeAlias
+
+from aiohttp import ClientResponseError, ClientTimeout
+
+from .const import (
+    DEVICE_ACTIONS_PATH,
+    DEVICE_STATES_PATH,
+    DEVICES_PATH,
+    EVENTS_PATH,
+    HTTP_API_TIMEOUT,
+    INTERFACE_WORK_MODE,
+    OAUTH2_TOKEN_URL,
+    REGION_API_BASE_URL,
+    RESULT_SUCCESS_CODE,
+)
+from .exceptions import BeatbotAuthenticationError, BeatbotConnectionError
+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)
+    )
+
+
+class BeatbotClient:
+    """Access the Beatbot cloud API using a caller-provided request function."""
+
+    def __init__(self, region: str, requester: Requester) -> 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
+
+    @property
+    def event_stream_url(self) -> str:
+        """Return the region-routed WebSocket endpoint."""
+        if self._base_url.startswith("https://"):
+            base_url = f"wss://{self._base_url.removeprefix('https://')}"
+        else:
+            base_url = self._base_url
+        return f"{base_url}{EVENTS_PATH}"
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, str] | None = None,
+        json_body: Any | None = None,
+    ) -> Any:
+        """Request and validate a Beatbot result envelope."""
+        try:
+            response = await self._requester(
+                method,
+                f"{self._base_url}{path}",
+                params=params,
+                json=json_body,
+                headers={"Accept": "application/json"},
+                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:
+            raise BeatbotConnectionError(str(err)) from err
+
+        body = await response.text()
+        if response.status in (HTTPStatus.UNAUTHORIZED, HTTPStatus.FORBIDDEN):
+            raise BeatbotAuthenticationError(f"Unauthorized: {response.status}")
+        if response.status >= HTTPStatus.BAD_REQUEST:
+            raise BeatbotConnectionError(f"API request failed: {response.status}")
+
+        try:
+            payload = json.loads(body)
+        except (json.JSONDecodeError, TypeError) as err:
+            content_type = response.headers.get("Content-Type", "unknown")
+            _LOGGER.warning(
+                "Beatbot API returned non-JSON response (%s, %s)",
+                response.status,
+                content_type,
+            )
+            raise BeatbotConnectionError(
+                f"API returned non-JSON response ({response.status}, {content_type})"
+            ) from err
+
+        if not isinstance(payload, dict):
+            raise BeatbotConnectionError("API returned an invalid response envelope")
+        if payload.get("code") != RESULT_SUCCESS_CODE:
+            raise BeatbotConnectionError(
+                f"API error {payload.get('code')}: {payload.get('message')}"
+            )
+        return payload.get("data")
+
+    async def get_devices(self) -> list[BeatbotDeviceData]:
+        """Return devices discovered for the account."""
+        raw = await self._request("GET", DEVICES_PATH)
+        if not raw:
+            return []
+        if isinstance(raw, str):
+            try:
+                discovery = json.loads(raw)
+            except (json.JSONDecodeError, TypeError) as err:
+                raise BeatbotConnectionError(
+                    f"Invalid discovery payload: {err}"
+                ) from err
+        else:
+            discovery = raw
+
+        devices = (discovery or {}).get("devices") or []
+        return [
+            parsed
+            for device in devices
+            if (parsed := self._parse_device(device)) is not None
+        ]
+
+    @staticmethod
+    def _parse_device(device: dict[str, Any]) -> BeatbotDeviceData | None:
+        """Parse a discovery device, ignoring entries without an ID."""
+        device_id = device.get("deviceId") or ""
+        if not device_id:
+            return None
+        versions = [
+            FirmwareVersion(
+                channel=item.get("channel", 0), version=item.get("version") or ""
+            )
+            for item in (device.get("versions") or [])
+            if isinstance(item, dict)
+        ]
+        capabilities = device.get("capabilities")
+        return BeatbotDeviceData(
+            device_id=device_id,
+            product_id=device.get("productId") or "",
+            product_category=device.get("productCategory") or "",
+            name=device.get("name") or "",
+            model=device.get("model") or "",
+            work_status=0,
+            work_mode=0,
+            error_code=0,
+            battery_level=0,
+            versions=versions,
+            is_online=bool(device.get("isOnline", False)),
+            work_mode_options=BeatbotClient._parse_work_mode_options(capabilities),
+            capabilities=BeatbotClient._parse_capabilities(capabilities),
+        )
+
+    @staticmethod
+    def _parse_work_mode_options(
+        capabilities: list[dict[str, Any]] | None,
+    ) -> dict[int, str]:
+        """Extract the per-device work-mode value-to-label mapping."""
+        for capability in capabilities or []:
+            if not isinstance(capability, dict):
+                continue
+            if capability.get("interfaceInfo") != INTERFACE_WORK_MODE:
+                continue
+            configuration = capability.get("configuration")
+            if isinstance(configuration, str):
+                try:
+                    configuration = json.loads(configuration)
+                except (json.JSONDecodeError, TypeError):
+                    configuration = None
+            if not isinstance(configuration, dict):
+                return {}
+            options: dict[int, str] = {}
+            for option in configuration.get("options") or []:
+                value = option.get("value")
+                label = option.get("label")
+                if value is not None and label:
+                    options[value] = label
+            return options
+        return {}
+
+    @staticmethod
+    def _parse_capabilities(
+        capabilities: list[dict[str, Any]] | None,
+    ) -> dict[str, BeatbotCapability]:
+        """Parse discovery capabilities into a mapping by interface key."""
+        parsed: dict[str, BeatbotCapability] = {}
+        for capability in capabilities or []:
+            if not isinstance(capability, dict):
+                continue
+            interface_info = capability.get("interfaceInfo")
+            if not interface_info:
+                continue
+            parsed[interface_info] = BeatbotCapability(
+                interface_info=interface_info,
+                retrievable=bool(capability.get("retrievable", False)),
+                proactively_reported=bool(capability.get("proactivelyReported", False)),
+                non_controllable=bool(capability.get("nonControllable", False)),
+            )
+        return parsed
+
+    async def get_device_states(self) -> dict[str, dict[str, Any]]:
+        """Return batched runtime state for all devices."""
+        raw = await self._request("GET", DEVICE_STATES_PATH)
+        if isinstance(raw, str):
+            try:
+                payload = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                return {}
+        else:
+            payload = raw
+        devices = (payload or {}).get("devices") or []
+        return {
+            device["deviceId"]: {
+                "is_online": device.get("isOnline"),
+                "states": device.get("states") or {},
+            }
+            for device in devices
+            if device.get("deviceId")
+        }
+
+    async def get_device_state(self, device_id: str) -> dict[str, Any]:
+        """Return runtime state for one device."""
+        raw = await self._request("GET", f"{DEVICE_ACTIONS_PATH}/{device_id}/state")
+        if isinstance(raw, str):
+            try:
+                payload = json.loads(raw)
+            except (json.JSONDecodeError, TypeError):
+                return {}
+        else:
+            payload = raw
+        if not isinstance(payload, dict):
+            return {}
+        return {
+            "is_online": payload.get("isOnline"),
+            "states": payload.get("states") or {},
+        }
+
+    async def send_action(self, device_id: str, interface_info: str) -> None:
+        """Issue a parameterless action by its interface key."""
+        await self._request(
+            "POST",
+            f"{DEVICE_ACTIONS_PATH}/{device_id}/actions",
+            json_body={"interfaceInfo": interface_info},
+        )
+
+    async def set_work_mode(self, device_id: str, label: str) -> None:
+        """Set a device's work mode by its advertised label."""
+        await self._request(
+            "POST",
+            f"{DEVICE_ACTIONS_PATH}/{device_id}/actions",
+            json_body={"interfaceInfo": INTERFACE_WORK_MODE, "label": label},
+        )
+
+    async def set_switch(self, device_id: str, interface_info: str, label: str) -> None:
+        """Set an on/off capability."""
+        await self._request(
+            "POST",
+            f"{DEVICE_ACTIONS_PATH}/{device_id}/actions",
+            json_body={"interfaceInfo": interface_info, "label": label},
+        )

beatbot_cloud/const.py

@@ -0,0 +1,23 @@
+"""Beatbot cloud protocol constants."""
+
+from typing import Final
+
+HTTP_API_TIMEOUT: Final = 30
+OAUTH2_AUTHORIZE_URL: Final = "https://oauth.beatbot.com/oauth2/authorize"
+OAUTH2_TOKEN_URL: Final = "https://oauth.beatbot.com/oauth2/token"
+OAUTH2_CLIENT_ID: Final = "home-assistant"
+OAUTH2_SCOPE: Final = "device:info"
+
+REGION_API_BASE_URL: Final = {
+    "cn": "https://cn-iot.beatbot.com",
+    "na": "https://na-iot.beatbot.com",
+    "eu": "https://eu-iot.beatbot.com",
+}
+
+DEVICES_PATH: Final = "/openapi/v1/ha"
+DEVICE_STATES_PATH: Final = "/openapi/v1/ha/state"
+DEVICE_ACTIONS_PATH: Final = "/openapi/v1/ha"
+EVENTS_PATH: Final = "/openapi/v1/ha/ws"
+RESULT_SUCCESS_CODE: Final = 200
+
+INTERFACE_WORK_MODE: Final = "select.work_mode"

beatbot_cloud/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions raised by the Beatbot cloud client."""
+
+
+class BeatbotError(Exception):
+    """Base class for Beatbot client errors."""
+
+
+class BeatbotAuthenticationError(BeatbotError):
+    """The credentials are invalid and user authentication is required."""
+
+
+class BeatbotConnectionError(BeatbotError):
+    """The Beatbot cloud service could not be reached or returned bad data."""
+
+
+class BeatbotTokenRejectedError(BeatbotAuthenticationError):
+    """An access token was rejected and may be refreshed once."""
+
+    def __init__(self, access_token: str, *, handshake: bool = False) -> None:
+        super().__init__("access token rejected")
+        self.access_token = access_token
+        self.handshake = handshake
+
+
+class BeatbotConnectionReplacedError(BeatbotError):
+    """The server replaced this event stream with a newer connection."""

beatbot_cloud/models.py

@@ -0,0 +1,55 @@
+"""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

beatbot_cloud/py.typed

@@ -0,0 +1 @@
+

beatbot_cloud/websocket.py

@@ -0,0 +1,114 @@
+"""Low-level Beatbot cloud WebSocket event transport."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from aiohttp import (
+    ClientSession,
+    ClientWebSocketResponse,
+    WSMsgType,
+    WSServerHandshakeError,
+)
+
+from .exceptions import (
+    BeatbotAuthenticationError,
+    BeatbotConnectionError,
+    BeatbotConnectionReplacedError,
+    BeatbotTokenRejectedError,
+)
+from .models import BeatbotEvent
+
+
+class BeatbotEventStream:
+    """Connect to and receive validated events from a Beatbot account stream."""
+
+    def __init__(
+        self,
+        session: ClientSession,
+        url: str,
+        access_token: str,
+        *,
+        heartbeat: float = 30.0,
+        receive_timeout: float = 90.0,
+    ) -> None:
+        """Initialize an event stream without connecting it."""
+        self._session = session
+        self._url = url
+        self._access_token = access_token
+        self._heartbeat = heartbeat
+        self._receive_timeout = receive_timeout
+        self._ws: ClientWebSocketResponse | None = None
+
+    async def connect(self) -> None:
+        """Open the WebSocket connection."""
+        try:
+            self._ws = await self._session.ws_connect(
+                self._url,
+                headers={"Authorization": f"Bearer {self._access_token}"},
+                heartbeat=self._heartbeat,
+                autoping=True,
+            )
+        except WSServerHandshakeError as err:
+            if err.status == 401:
+                raise BeatbotTokenRejectedError(
+                    self._access_token, handshake=True
+                ) from err
+            if err.status == 403:
+                raise BeatbotAuthenticationError from err
+            raise BeatbotConnectionError(str(err)) from err
+
+    async def receive(self) -> BeatbotEvent:
+        """Receive and validate the next text event."""
+        if self._ws is None:
+            raise RuntimeError("Event stream is not connected")
+        message = await self._ws.receive(timeout=self._receive_timeout)
+        if message.type is WSMsgType.TEXT:
+            return self.parse_event(message.data)
+        if message.type in (WSMsgType.CLOSE, WSMsgType.CLOSED, WSMsgType.ERROR):
+            self._raise_for_close_code(self._ws.close_code, self._ws.exception())
+        raise BeatbotConnectionError(f"Unexpected WebSocket message: {message.type}")
+
+    @staticmethod
+    def parse_event(raw: str) -> BeatbotEvent:
+        """Parse and validate a Beatbot event envelope."""
+        try:
+            event: Any = json.loads(raw)
+        except (json.JSONDecodeError, TypeError) as err:
+            raise BeatbotConnectionError("Event is not valid JSON") from err
+        if not isinstance(event, dict):
+            raise BeatbotConnectionError("Event is not an object")
+        event_id = event.get("eventId")
+        event_type = event.get("type")
+        device_id = event.get("deviceId")
+        if not all(
+            isinstance(value, str) and value
+            for value in (event_id, event_type, device_id)
+        ):
+            raise BeatbotConnectionError("Event is missing eventId, type, or deviceId")
+        payload = event.get("payload")
+        if event_type == "device_removed":
+            if payload is not None:
+                raise BeatbotConnectionError("device_removed payload is not null")
+        elif not isinstance(payload, dict):
+            raise BeatbotConnectionError("Event payload is not an object")
+        return BeatbotEvent(event_id, event_type, device_id, payload)
+
+    def _raise_for_close_code(
+        self, code: int | None, error: BaseException | None
+    ) -> None:
+        """Translate Beatbot close codes into public client exceptions."""
+        if code == 4001:
+            raise BeatbotTokenRejectedError(self._access_token) from error
+        if code == 4002:
+            raise BeatbotConnectionReplacedError from error
+        if code == 4003:
+            raise BeatbotAuthenticationError from error
+        raise BeatbotConnectionError(f"WebSocket closed with code {code}") from error
+
+    async def close(self) -> None:
+        """Close the stream if connected."""
+        websocket, self._ws = self._ws, None
+        if websocket is not None and not websocket.closed:
+            await websocket.close()

beatbot_cloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: beatbot-cloud
+Version: 0.1.0
+Summary: Asynchronous Python client for the Beatbot cloud API
+Author: Beatbot Robotics
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://www.beatbot.com
+Project-URL: Repository, https://github.com/Beatbot-Robotics/beatbot-cloud-python
+Project-URL: Issues, https://github.com/Beatbot-Robotics/beatbot-cloud-python/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.11.0
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.6; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Requires-Dist: ruff>=0.15; extra == "test"
+Dynamic: license-file
+
+# 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.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+beatbot_cloud/__init__.py,sha256=cXcWVEDI_EU2UdjDlJn5SnunpQM4fEoAqr9l6LWl9Kw,663
+beatbot_cloud/client.py,sha256=yUJtCHMeR5vfzUzdV2XpWYXcStslaRe2kDnWX0mIA00,10655
+beatbot_cloud/const.py,sha256=qtjuxVPUW1JtiZZaQHTYR1bBbUOJsFxQ0Tbm0mkomcI,731
+beatbot_cloud/exceptions.py,sha256=zlmxrdV-SuVQ35c7ZlaBtplNojsdzXFuc5NLxjnh9gU,846
+beatbot_cloud/models.py,sha256=GLgftkkVqbXN8a3BYil4GCZaKUYgZ_F_tYF41ljfdgw,1247
+beatbot_cloud/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+beatbot_cloud/websocket.py,sha256=ukrdiVvGhYLR8uSLLIpFqWuayAwbExc__XEMHgOMJIY,4275
+beatbot_cloud-0.1.0.dist-info/licenses/LICENSE,sha256=yMukxtKwZ3JaL4OSNUSa_KSSGoXmIJtTJV_8Nkh8Gpo,746
+beatbot_cloud-0.1.0.dist-info/METADATA,sha256=NHtvdo0YUXdq62hJARsKbj7mtR0VGq6a4-onk570Qy4,1734
+beatbot_cloud-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+beatbot_cloud-0.1.0.dist-info/top_level.txt,sha256=rBtWms-oy74qMMPYS21LqxPcKCMRf6TiliXmXfzbTNw,14
+beatbot_cloud-0.1.0.dist-info/RECORD,,

beatbot_cloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

beatbot_cloud-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,18 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Beatbot Robotics
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

beatbot_cloud-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+beatbot_cloud