beatbot-cloud 0.1.0__tar.gz

beatbot_cloud-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,27 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "beatbot-cloud"
+version = "0.1.0"
+description = "Asynchronous Python client for the Beatbot cloud API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "Beatbot Robotics" }]
+dependencies = ["aiohttp>=3.11.0"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://www.beatbot.com"
+Repository = "https://github.com/Beatbot-Robotics/beatbot-cloud-python"
+Issues = "https://github.com/Beatbot-Robotics/beatbot-cloud-python/issues"
+
+[project.optional-dependencies]
+test = [
+  "coverage[toml]>=7.6",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "ruff>=0.15",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--strict-markers"
+
+[tool.coverage.run]
+branch = true
+source = ["beatbot_cloud"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["ASYNC", "B", "E", "F", "I", "SIM", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]

beatbot_cloud-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

beatbot_cloud-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/beatbot_cloud/py.typed

@@ -0,0 +1 @@
+

beatbot_cloud-0.1.0/src/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/src/beatbot_cloud.egg-info/PKG-INFO

@@ -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/src/beatbot_cloud.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/beatbot_cloud/__init__.py
+src/beatbot_cloud/client.py
+src/beatbot_cloud/const.py
+src/beatbot_cloud/exceptions.py
+src/beatbot_cloud/models.py
+src/beatbot_cloud/py.typed
+src/beatbot_cloud/websocket.py
+src/beatbot_cloud.egg-info/PKG-INFO
+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_client.py
+tests/test_websocket.py

beatbot_cloud-0.1.0/src/beatbot_cloud.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

beatbot_cloud-0.1.0/src/beatbot_cloud.egg-info/requires.txt

@@ -0,0 +1,7 @@
+aiohttp>=3.11.0
+
+[test]
+coverage[toml]>=7.6
+pytest>=8.3
+pytest-asyncio>=0.24
+ruff>=0.15

beatbot_cloud-0.1.0/src/beatbot_cloud.egg-info/top_level.txt

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

beatbot_cloud-0.1.0/tests/test_client.py

@@ -0,0 +1,245 @@
+"""Tests for the Beatbot REST client."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+
+import pytest
+from aiohttp import ClientResponseError
+
+from beatbot_cloud import (
+    BeatbotAuthenticationError,
+    BeatbotClient,
+    BeatbotConnectionError,
+)
+from beatbot_cloud.const import OAUTH2_TOKEN_URL, REGION_API_BASE_URL
+
+
+class Response:
+    """Small response double."""
+
+    def __init__(self, data, *, status=200, content_type="application/json"):
+        self.status = status
+        self.headers = {"Content-Type": content_type}
+        self.body = data if isinstance(data, str) else json.dumps(data)
+
+    async def text(self):
+        return self.body
+
+
+class Requester:
+    """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):
+        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 envelope(data=None, *, code=200, message=None):
+    return Response({"code": code, "message": message, "data": data})
+
+
+@pytest.mark.parametrize("region", ["cn", "na", "eu"])
+def test_region_and_event_url(region):
+    api, _ = client(envelope(), region)
+    assert api._base_url == REGION_API_BASE_URL[region]
+    assert api.event_stream_url.startswith("wss://")
+
+
+def test_unknown_region():
+    with pytest.raises(ValueError, match="Unknown or missing"):
+        client(envelope(), "moon")
+
+
+def test_event_url_preserves_non_https_scheme():
+    api, _ = client(envelope())
+    api._base_url = "ws://example.test"
+    assert api.event_stream_url == "ws://example.test/openapi/v1/ha/ws"
+
+
+@pytest.mark.parametrize("status", [401, 403])
+async def test_request_rejects_auth_status(status):
+    api, _ = client(Response("denied", status=status))
+    with pytest.raises(BeatbotAuthenticationError):
+        await api._request("GET", "/test")
+
+
+async def test_request_rejects_http_error():
+    api, _ = client(Response("failed", status=500))
+    with pytest.raises(BeatbotConnectionError, match="500"):
+        await api._request("GET", "/test")
+
+
+@pytest.mark.parametrize(
+    ("response", "message"),
+    [
+        (Response("not json", content_type="text/plain"), "non-JSON"),
+        (Response("[]"), "invalid response envelope"),
+        (envelope(code=400, message="bad"), "API error 400: bad"),
+    ],
+)
+async def test_request_rejects_invalid_envelope(response, message):
+    api, _ = client(response)
+    with pytest.raises(BeatbotConnectionError, match=message):
+        await api._request("GET", "/test")
+
+
+async def test_request_forwards_options_and_returns_data():
+    api, requester = 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]
+    assert method == "POST"
+    assert url.endswith("/test")
+    assert kwargs["params"] == {"a": "b"}
+    assert kwargs["json"] == {"value": 1}
+
+
+@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):
+        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_non_oauth_exception_is_connection_error():
+    api, _ = client(RuntimeError("offline"))
+    with pytest.raises(BeatbotConnectionError, match="offline"):
+        await api._request("GET", "/test")
+
+
+async def test_get_devices_empty():
+    api, _ = client(envelope(None))
+    assert await api.get_devices() == []
+
+
+async def test_get_devices_accepts_object_payload():
+    api, _ = client(envelope({"devices": []}))
+    assert await api.get_devices() == []
+
+
+async def test_get_devices_rejects_invalid_string():
+    api, _ = client(envelope("not json"))
+    with pytest.raises(BeatbotConnectionError, match="Invalid discovery"):
+        await api.get_devices()
+
+
+async def test_get_devices_parses_models_and_capabilities():
+    configuration = json.dumps(
+        {"options": [{"value": 0, "label": "quick"}, {"value": None}]}
+    )
+    data = {
+        "devices": [
+            {},
+            {
+                "deviceId": "device-1",
+                "productId": "product-1",
+                "productCategory": "pool_clean_bot",
+                "name": "Pool bot",
+                "model": "Aqua",
+                "isOnline": True,
+                "versions": [None, {"channel": 1, "version": "2.0"}],
+                "capabilities": [
+                    None,
+                    {},
+                    {
+                        "interfaceInfo": "select.work_mode",
+                        "configuration": configuration,
+                        "retrievable": True,
+                        "proactivelyReported": True,
+                    },
+                ],
+            },
+        ]
+    }
+    api, _ = client(envelope(json.dumps(data)))
+    devices = await api.get_devices()
+    assert len(devices) == 1
+    assert devices[0].device_id == "device-1"
+    assert devices[0].work_mode_options == {0: "quick"}
+    assert devices[0].versions[0].version == "2.0"
+    assert devices[0].capabilities["select.work_mode"].retrievable
+
+
+@pytest.mark.parametrize("configuration", ["bad json", [], None])
+def test_invalid_work_mode_configuration(configuration):
+    assert (
+        BeatbotClient._parse_work_mode_options(
+            [{"interfaceInfo": "select.work_mode", "configuration": configuration}]
+        )
+        == {}
+    )
+
+
+async def test_get_device_states():
+    api, _ = client(
+        envelope(
+            {
+                "devices": [
+                    {},
+                    {"deviceId": "d1", "isOnline": True, "states": {"x": 1}},
+                ]
+            }
+        )
+    )
+    assert await api.get_device_states() == {
+        "d1": {"is_online": True, "states": {"x": 1}}
+    }
+
+
+async def test_get_device_states_invalid_string():
+    api, _ = client(envelope("bad"))
+    assert await api.get_device_states() == {}
+
+
+@pytest.mark.parametrize("data", ["bad", [], None])
+async def test_get_device_state_invalid(data):
+    api, _ = client(envelope(data))
+    assert await api.get_device_state("d1") == {}
+
+
+async def test_get_device_state():
+    api, _ = client(envelope({"isOnline": False, "states": {"battery": 10}}))
+    assert await api.get_device_state("d1") == {
+        "is_online": False,
+        "states": {"battery": 10},
+    }
+
+
+async def test_actions():
+    api, requester = 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] == [
+        {"interfaceInfo": "vacuum.start"},
+        {"interfaceInfo": "select.work_mode", "label": "quick"},
+        {"interfaceInfo": "switch.child_lock", "label": "on"},
+    ]

beatbot_cloud-0.1.0/tests/test_websocket.py

@@ -0,0 +1,124 @@
+"""Tests for the Beatbot WebSocket transport."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from aiohttp import WSMsgType, WSServerHandshakeError
+
+from beatbot_cloud import (
+    BeatbotAuthenticationError,
+    BeatbotConnectionError,
+    BeatbotConnectionReplacedError,
+    BeatbotEventStream,
+    BeatbotTokenRejectedError,
+)
+
+
+def stream(session=None):
+    return BeatbotEventStream(session or SimpleNamespace(), "wss://test", "token")
+
+
+@pytest.mark.parametrize(
+    "raw",
+    ["not-json", "[]", "{}", '{"eventId":"1","type":"status","deviceId":"d"}'],
+)
+def test_parse_rejects_invalid_events(raw):
+    with pytest.raises(BeatbotConnectionError):
+        BeatbotEventStream.parse_event(raw)
+
+
+def test_parse_rejects_removed_payload():
+    with pytest.raises(BeatbotConnectionError, match="not null"):
+        BeatbotEventStream.parse_event(
+            '{"eventId":"1","type":"device_removed","deviceId":"d","payload":{}}'
+        )
+
+
+def test_parse_event():
+    event = BeatbotEventStream.parse_event(
+        '{"eventId":"1","type":"status","deviceId":"d","payload":{"online":true}}'
+    )
+    assert event.event_id == "1"
+    assert event.payload == {"online": True}
+
+
+def test_parse_removed_event():
+    event = BeatbotEventStream.parse_event(
+        '{"eventId":"1","type":"device_removed","deviceId":"d","payload":null}'
+    )
+    assert event.payload is None
+
+
+async def test_connect_and_close():
+    websocket = SimpleNamespace(closed=False, close=AsyncMock())
+    session = SimpleNamespace(ws_connect=AsyncMock(return_value=websocket))
+    event_stream = stream(session)
+    await event_stream.connect()
+    await event_stream.close()
+    websocket.close.assert_awaited_once()
+
+
+@pytest.mark.parametrize(
+    ("status", "error_type"),
+    [
+        (401, BeatbotTokenRejectedError),
+        (403, BeatbotAuthenticationError),
+        (500, BeatbotConnectionError),
+    ],
+)
+async def test_connect_translates_handshake_errors(status, error_type):
+    error = WSServerHandshakeError(
+        SimpleNamespace(real_url="wss://test"), (), status=status
+    )
+    session = SimpleNamespace(ws_connect=AsyncMock(side_effect=error))
+    with pytest.raises(error_type):
+        await stream(session).connect()
+
+
+async def test_receive_requires_connection():
+    with pytest.raises(RuntimeError, match="not connected"):
+        await stream().receive()
+
+
+async def test_receive_text_event():
+    message = SimpleNamespace(
+        type=WSMsgType.TEXT,
+        data='{"eventId":"1","type":"status","deviceId":"d","payload":{"online":true}}',
+    )
+    event_stream = stream()
+    event_stream._ws = SimpleNamespace(receive=AsyncMock(return_value=message))
+    assert (await event_stream.receive()).device_id == "d"
+
+
+@pytest.mark.parametrize(
+    ("code", "error_type"),
+    [
+        (4001, BeatbotTokenRejectedError),
+        (4002, BeatbotConnectionReplacedError),
+        (4003, BeatbotAuthenticationError),
+        (4008, BeatbotConnectionError),
+    ],
+)
+async def test_receive_translates_close_codes(code, error_type):
+    message = SimpleNamespace(type=WSMsgType.CLOSE, data=None)
+    event_stream = stream()
+    event_stream._ws = SimpleNamespace(
+        receive=AsyncMock(return_value=message),
+        close_code=code,
+        exception=lambda: None,
+    )
+    with pytest.raises(error_type):
+        await event_stream.receive()
+
+
+async def test_receive_rejects_unexpected_message():
+    message = SimpleNamespace(type=WSMsgType.BINARY, data=b"data")
+    event_stream = stream()
+    event_stream._ws = SimpleNamespace(receive=AsyncMock(return_value=message))
+    with pytest.raises(BeatbotConnectionError, match="Unexpected"):
+        await event_stream.receive()
+
+
+async def test_close_without_connection():
+    await stream().close()