@camstack/addon-import-alexa 0.2.177 → 0.2.178

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-import-alexa",
-  "version": "0.2.177",
+  "version": "0.2.178",
   "description": "Alexa device-import provider for CamStack — imports the smart-home devices in a user's Alexa account via the unofficial alexa-remote2 cookie/token client (the inverse of the Alexa exporter)",
   "keywords": [
     "camstack",
@@ -68,7 +68,7 @@
       }
     ],
     "requires": {
-      "server": ">=1.2.730"
+      "server": ">=1.2.731"
     }
   },
   "files": [

package/python/alexa_gateway.py

@@ -5,12 +5,35 @@ Never log the refresh token, the cookie blob, or the session file contents.
 
 from __future__ import annotations
 
+import asyncio
 import time
 from pathlib import Path
+from types import SimpleNamespace
 
-from alexa_sequences import EchoTarget
+from alexa_sequences import EchoTarget, build_volume_node
 
 REGIONS = ("NA", "EU", "FE")
+REGION_LOCALE = {"NA": "en-US", "EU": "en-GB", "FE": "ja-JP"}
+
+# The `/api/np/command` bodies. Only these four are offered.
+NP_COMMANDS = {
+    "play": "PlayCommand",
+    "pause": "PauseCommand",
+    "next": "NextCommand",
+    "previous": "PreviousCommand",
+}
+RATE_LIMITED = "rate-limited"
+
+
+class RateLimitedError(Exception):
+    """Amazon answered 429. It is a refusal to retry later, never an empty answer."""
+
+    code = RATE_LIMITED
+
+
+def is_rate_limited(err: BaseException) -> bool:
+    """alexapy raises AlexapyTooManyRequestsError; matched by name so this module needs no import of it."""
+    return any(kind.__name__ == "AlexapyTooManyRequestsError" for kind in type(err).__mro__)
 
 
 def classify_login(status: dict) -> str:
@@ -83,6 +106,21 @@ class AlexaPyGateway:
         self._last_success_at: float | None = None
         self._session_path = ""
         self._region = "EU"
+        self._serial_locks: dict[str, asyncio.Lock] = {}
+
+    def _lock(self, serial: str) -> asyncio.Lock:
+        """One request at a time per Echo: Amazon throttles an account that hammers one device."""
+        lock = self._serial_locks.get(serial)
+        if lock is None:
+            lock = asyncio.Lock()
+            self._serial_locks[serial] = lock
+        return lock
+
+    def _api_for(self, serial: str, device_type: str):
+        login = self._require_login()
+        _AlexaLogin, AlexaAPI = _import_alexapy()
+        shim = SimpleNamespace(device_serial_number=serial, _device_type=device_type, _locale=None)
+        return AlexaAPI(shim, login)
 
     @property
     def region(self) -> str:
@@ -204,6 +242,90 @@ class AlexaPyGateway:
         await AlexaAPI(None, login).run_behavior(node, queue_delay=0)
         self._touch_success()
 
+    async def player_state(self, serial: str, device_type: str) -> dict:
+        """The raw `playerInfo` of one Echo. A missing body is an error, not an idle player."""
+        async with self._lock(serial):
+            try:
+                body = await self._api_for(serial, device_type).get_state()
+            except Exception as err:  # noqa: BLE001 — typed below
+                if is_rate_limited(err):
+                    raise RateLimitedError("amazon rate limit (429) on the player state") from err
+                raise
+        if not isinstance(body, dict):
+            raise RuntimeError("amazon returned no player state")
+        info = body.get("playerInfo")
+        self._touch_success()
+        return {"playerInfo": info if isinstance(info, dict) else {}}
+
+    async def np_command(self, serial: str, command: str) -> None:
+        body = NP_COMMANDS.get(command)
+        if body is None:
+            raise ValueError(f"unknown media command {command!r}")
+        device_type = self._device_type_of(serial)
+        async with self._lock(serial):
+            try:
+                await self._api_for(serial, device_type).set_media({"type": body})
+            except Exception as err:  # noqa: BLE001 — typed below
+                if is_rate_limited(err):
+                    raise RateLimitedError("amazon rate limit (429) on a media command") from err
+                raise
+        self._touch_success()
+
+    async def set_volume(self, serial: str, level: int) -> None:
+        target = self.target_for(serial)
+        if target is None:
+            raise ValueError("unknown echo")
+        node = build_volume_node(target, max(0, min(100, int(level))), REGION_LOCALE.get(self._region, "en-GB"))
+        login = self._require_login()
+        _AlexaLogin, AlexaAPI = _import_alexapy()
+        async with self._lock(serial):
+            try:
+                await AlexaAPI(None, login).run_behavior(node, queue_delay=0)
+            except Exception as err:  # noqa: BLE001 — typed below
+                if is_rate_limited(err):
+                    raise RateLimitedError("amazon rate limit (429) on the volume") from err
+                raise
+        self._touch_success()
+
+    async def dnd_state(self) -> dict:
+        """Do Not Disturb of every device, in one call."""
+        login = self._require_login()
+        _AlexaLogin, AlexaAPI = _import_alexapy()
+        try:
+            body = await AlexaAPI.get_dnd_state(login)
+        except Exception as err:  # noqa: BLE001 — typed below
+            if is_rate_limited(err):
+                raise RateLimitedError("amazon rate limit (429) on Do Not Disturb") from err
+            raise
+        if not isinstance(body, dict):
+            raise RuntimeError("amazon returned no Do Not Disturb list")
+        rows = body.get("doNotDisturbDeviceStatusList")
+        devices = []
+        for row in rows if isinstance(rows, list) else []:
+            serial = row.get("deviceSerialNumber") if isinstance(row, dict) else None
+            enabled = row.get("enabled") if isinstance(row, dict) else None
+            if isinstance(serial, str) and serial != "" and isinstance(enabled, bool):
+                devices.append({"serial": serial, "enabled": enabled})
+        self._touch_success()
+        return {"devices": devices}
+
+    async def set_dnd(self, serial: str, enabled: bool) -> None:
+        device_type = self._device_type_of(serial)
+        async with self._lock(serial):
+            try:
+                await self._api_for(serial, device_type).set_dnd_state(enabled)
+            except Exception as err:  # noqa: BLE001 — typed below
+                if is_rate_limited(err):
+                    raise RateLimitedError("amazon rate limit (429) on Do Not Disturb") from err
+                raise
+        self._touch_success()
+
+    def _device_type_of(self, serial: str) -> str:
+        target = self.target_for(serial)
+        if target is None:
+            raise ValueError("unknown echo")
+        return target["deviceType"]
+
     async def session_status(self) -> dict:
         age = 0
         if self._signed_in_at is not None:

package/python/alexa_protocol.py

@@ -36,6 +36,16 @@ class Gateway(Protocol):
 
     async def session_status(self) -> dict: ...
 
+    async def player_state(self, serial: str, device_type: str) -> dict: ...
+
+    async def np_command(self, serial: str, command: str) -> None: ...
+
+    async def set_volume(self, serial: str, level: int) -> None: ...
+
+    async def dnd_state(self) -> dict: ...
+
+    async def set_dnd(self, serial: str, enabled: bool) -> None: ...
+
     def target_for(self, serial: str) -> EchoTarget | None: ...
 
 
@@ -46,6 +56,13 @@ def _read_secret(path: str) -> str:
     return Path(path).read_text(encoding="utf-8").strip()
 
 
+def _serial(message: dict) -> str:
+    serial = message.get("serial")
+    if not isinstance(serial, str) or serial == "":
+        raise ValueError("serial required")
+    return serial
+
+
 class Session:
     def __init__(self, gateway: Gateway) -> None:
         self._gateway = gateway
@@ -58,7 +75,11 @@ class Session:
         try:
             result = await self._dispatch(op, message)
         except Exception as err:  # noqa: BLE001 — the line must answer; the message is the error
-            return {"id": request_id, "ok": False, "error": str(err)}
+            failure: dict = {"id": request_id, "ok": False, "error": str(err)}
+            code = getattr(err, "code", None)
+            if isinstance(code, str):
+                failure["code"] = code
+            return failure
         return {"id": request_id, "ok": True, "result": result}
 
     async def _dispatch(self, op: object, message: dict) -> dict:
@@ -80,6 +101,27 @@ class Session:
             return await self._utter("announce", message)
         if op == "session_status":
             return await self._gateway.session_status()
+        if op == "player_state":
+            return await self._gateway.player_state(
+                _serial(message), str(message.get("deviceType", ""))
+            )
+        if op == "np_command":
+            await self._gateway.np_command(_serial(message), str(message.get("command", "")))
+            return {}
+        if op == "set_volume":
+            level = message.get("level")
+            if isinstance(level, bool) or not isinstance(level, (int, float)):
+                raise ValueError("level required")
+            await self._gateway.set_volume(_serial(message), int(level))
+            return {}
+        if op == "dnd_state":
+            return await self._gateway.dnd_state()
+        if op == "set_dnd":
+            enabled = message.get("enabled")
+            if not isinstance(enabled, bool):
+                raise ValueError("enabled required")
+            await self._gateway.set_dnd(_serial(message), enabled)
+            return {}
         raise ValueError(f"unknown op {op!r}")
 
     async def _utter(self, op: str, message: dict) -> dict:

package/python/alexa_sequences.py

@@ -57,3 +57,18 @@ def build_announcement(target: EchoTarget, text: str, locale: str) -> dict:
             ],
         },
     }
+
+
+def build_volume_node(target: EchoTarget, level: int, locale: str) -> dict:
+    """The behaviour node that sets an Echo's volume. `level` is a whole percent, 0 to 100."""
+    return {
+        "@type": "com.amazon.alexa.behaviors.model.OpaquePayloadOperationNode",
+        "type": "Alexa.DeviceControls.Volume",
+        "operationPayload": {
+            "deviceType": target["deviceType"],
+            "deviceSerialNumber": target["id"],
+            "locale": locale,
+            "customerId": target["customerId"],
+            "value": level,
+        },
+    }

package/python/test_alexa_gateway_echo.py

@@ -0,0 +1,149 @@
+"""Echo media ops with a mocked AlexaAPI. These tests must not contact Amazon."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import types
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from alexa_gateway import AlexaPyGateway, RateLimitedError
+from alexa_protocol import Session
+
+
+class AlexapyTooManyRequestsError(Exception):
+    pass
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def install_fake(state=None, dnd=None, raises=None):
+    calls: dict = {"behaviors": [], "media": [], "dnd_set": [], "state_for": [], "active": 0, "max_active": 0}
+
+    class FakeAPI:
+        def __init__(self, device, login):
+            self.device = device
+
+        async def get_state(self):
+            calls["active"] += 1
+            calls["max_active"] = max(calls["max_active"], calls["active"])
+            await asyncio.sleep(0.01)
+            calls["active"] -= 1
+            calls["state_for"].append((self.device.device_serial_number, self.device._device_type))
+            if raises:
+                raise raises
+            return state
+
+        async def set_media(self, data):
+            if raises:
+                raise raises
+            calls["media"].append((self.device.device_serial_number, data))
+
+        async def set_dnd_state(self, enabled):
+            if raises:
+                raise raises
+            calls["dnd_set"].append((self.device.device_serial_number, enabled))
+
+        async def run_behavior(self, node, queue_delay=0):
+            if raises:
+                raise raises
+            calls["behaviors"].append(node)
+
+        @staticmethod
+        async def get_dnd_state(login):
+            if raises:
+                raise raises
+            return dnd
+
+    package = types.ModuleType("alexapy")
+    package.AlexaAPI = FakeAPI
+    package.AlexaLogin = object
+    sys.modules["alexapy"] = package
+    gateway = AlexaPyGateway()
+    gateway._login = object()
+    gateway._devices = [{"id": "s1", "deviceType": "T1", "customerId": "c1"}]
+    return gateway, calls
+
+
+class EchoMediaTests(unittest.TestCase):
+    def tearDown(self) -> None:
+        sys.modules.pop("alexapy", None)
+
+    def test_player_state_returns_the_raw_player_info(self) -> None:
+        gateway, calls = install_fake(state={"playerInfo": {"state": "PLAYING", "volume": {"volume": 30}}})
+        result = run(gateway.player_state("s1", "T1"))
+        self.assertEqual(result["playerInfo"]["state"], "PLAYING")
+        self.assertEqual(calls["state_for"], [("s1", "T1")])
+
+    def test_a_missing_body_is_an_error_never_an_idle_player(self) -> None:
+        gateway, _ = install_fake(state=None)
+        with self.assertRaises(RuntimeError):
+            run(gateway.player_state("s1", "T1"))
+
+    def test_a_429_is_a_typed_error_through_the_protocol(self) -> None:
+        gateway, _ = install_fake(raises=AlexapyTooManyRequestsError("Too Many Requests"))
+        response = run(Session(gateway).handle({"id": "1", "op": "player_state", "serial": "s1", "deviceType": "T1"}))
+        self.assertFalse(response["ok"])
+        self.assertEqual(response["code"], "rate-limited")
+        with self.assertRaises(RateLimitedError):
+            run(gateway.dnd_state())
+
+    def test_requests_for_one_serial_never_overlap(self) -> None:
+        gateway, calls = install_fake(state={"playerInfo": {}})
+
+        async def both():
+            await asyncio.gather(gateway.player_state("s1", "T1"), gateway.player_state("s1", "T1"))
+
+        run(both())
+        self.assertEqual(calls["max_active"], 1)
+
+    def test_np_command_maps_the_four_commands_and_refuses_others(self) -> None:
+        gateway, calls = install_fake()
+        for name in ("play", "pause", "next", "previous"):
+            run(gateway.np_command("s1", name))
+        self.assertEqual(
+            [data["type"] for _, data in calls["media"]],
+            ["PlayCommand", "PauseCommand", "NextCommand", "PreviousCommand"],
+        )
+        with self.assertRaises(ValueError):
+            run(gateway.np_command("s1", "rewind"))
+
+    def test_set_volume_posts_the_volume_behaviour_clamped(self) -> None:
+        gateway, calls = install_fake()
+        run(gateway.set_volume("s1", 140))
+        node = calls["behaviors"][0]
+        self.assertEqual(node["type"], "Alexa.DeviceControls.Volume")
+        self.assertEqual(node["operationPayload"]["value"], 100)
+        self.assertEqual(node["operationPayload"]["deviceSerialNumber"], "s1")
+
+    def test_dnd_state_is_one_call_for_every_device(self) -> None:
+        gateway, _ = install_fake(
+            dnd={
+                "doNotDisturbDeviceStatusList": [
+                    {"deviceSerialNumber": "s1", "enabled": True},
+                    {"deviceSerialNumber": "s2", "enabled": False},
+                    {"deviceSerialNumber": "s3"},
+                ]
+            }
+        )
+        result = run(gateway.dnd_state())
+        self.assertEqual(result["devices"], [{"serial": "s1", "enabled": True}, {"serial": "s2", "enabled": False}])
+
+    def test_set_dnd_goes_to_the_device(self) -> None:
+        gateway, calls = install_fake()
+        run(gateway.set_dnd("s1", True))
+        self.assertEqual(calls["dnd_set"], [("s1", True)])
+
+    def test_an_unknown_echo_is_refused(self) -> None:
+        gateway, _ = install_fake()
+        with self.assertRaises(ValueError):
+            run(gateway.set_volume("nope", 10))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/test_alexa_gateway_send.py

@@ -60,7 +60,7 @@ class SendTests(unittest.TestCase):
 
     def test_speak_posts_the_sequence_start_node_immediately(self):
         posted: list = []
-        sequence = build_speak_sequence(TARGET, "hello", 30, "it-IT")
+        sequence = build_speak_sequence(TARGET, "hello", "it-IT")
         asyncio.run(self._gateway(posted).speak(sequence, "A1CUST"))
         self.assertEqual(posted, [(sequence["startNode"], 0)])