@camstack/addon-import-alexa 0.2.176 → 0.2.178

package/i18n/en.json

@@ -14,7 +14,6 @@
   "echoTarget.s_echo.title": "Echo",
   "echoTarget.s_echo.brokerId.label": "Amazon account",
   "echoTarget.s_echo.echoId.label": "Echo",
-  "echoTarget.s_echo.volume.label": "Volume",
   "echoTarget.s_echo.respectDnd.label": "Respect Do Not Disturb",
   "globalSettings": {
     "s_alexa-proxy-login": {

package/i18n/it.json

@@ -14,7 +14,6 @@
   "echoTarget.s_echo.title": "Echo",
   "echoTarget.s_echo.brokerId.label": "Account Amazon",
   "echoTarget.s_echo.echoId.label": "Echo",
-  "echoTarget.s_echo.volume.label": "Volume",
   "echoTarget.s_echo.respectDnd.label": "Rispetta Non disturbare",
   "globalSettings": {
     "s_alexa-proxy-login": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-import-alexa",
-  "version": "0.2.176",
+  "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.729"
+      "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:
@@ -89,9 +131,6 @@ class Session:
         text = message.get("text")
         if not isinstance(text, str) or text == "":
             raise ValueError("text required")
-        volume = message.get("volume")
-        if not isinstance(volume, int):
-            volume = 40
         locale = REGION_LOCALE.get(self._gateway.region, "en-GB")
         outcomes: list[dict] = []
         for serial in targets:
@@ -104,7 +143,7 @@ class Session:
                 continue
             try:
                 if op == "speak":
-                    sequence = build_speak_sequence(target, text, volume, locale)
+                    sequence = build_speak_sequence(target, text, locale)
                     await self._gateway.speak(sequence, target["customerId"])
                 else:
                     announcement = build_announcement(target, text, locale)

package/python/alexa_sequences.py

@@ -29,27 +29,12 @@ def _speak_node(target: EchoTarget, text: str, locale: str) -> dict:
     }
 
 
-def _volume_node(target: EchoTarget, volume: int, nxt: dict) -> dict:
-    return {
-        "@type": "com.amazon.alexa.behaviors.model.OpaquePayloadOperationNode",
-        "type": "Alexa.DeviceControls.Volume",
-        "operationPayload": {
-            "deviceType": target["deviceType"],
-            "deviceSerialNumber": target["id"],
-            "customerId": target["customerId"],
-            "value": volume,
-        },
-        "next": nxt,
-    }
-
-
-def build_speak_sequence(target: EchoTarget, text: str, volume: int, locale: str) -> dict:
-    """Volume, then speech. Speak honours Do Not Disturb on the device."""
+def build_speak_sequence(target: EchoTarget, text: str, locale: str) -> dict:
+    """Speech at the Echo's current volume. Speak honours Do Not Disturb on the device."""
     speak = _speak_node(target, text, locale)
-    start = _volume_node(target, volume, speak) if volume >= 0 else speak
     return {
         "@type": "com.amazon.alexa.behaviors.model.Sequence",
-        "startNode": start,
+        "startNode": speak,
     }
 
 
@@ -72,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)])
 

package/python/test_alexa_protocol.py

@@ -136,19 +136,20 @@ class ProtocolTests(unittest.TestCase):
         session = Session(gateway)
         spoken = run(
             session,
-            {"id": "4", "op": "speak", "targets": ["echo-1"], "text": "Person at the door", "volume": 30},
+            {"id": "4", "op": "speak", "targets": ["echo-1"], "text": "Person at the door"},
         )
         self.assertTrue(spoken["result"]["outcomes"][0]["ok"])
         sequence = gateway.spoken[0]["sequence"]
-        self.assertEqual(sequence["startNode"]["type"], "Alexa.DeviceControls.Volume")
-        self.assertEqual(sequence["startNode"]["next"]["type"], "Alexa.Speak")
+        # No volume node: the Echo speaks at its current volume.
+        self.assertEqual(sequence["startNode"]["type"], "Alexa.Speak")
+        self.assertNotIn("next", sequence["startNode"])
         self.assertEqual(
-            sequence["startNode"]["next"]["operationPayload"]["textToSpeak"],
+            sequence["startNode"]["operationPayload"]["textToSpeak"],
             "Person at the door",
         )
         announced = run(
             session,
-            {"id": "5", "op": "announce", "targets": ["echo-1"], "text": "Hello", "volume": 30},
+            {"id": "5", "op": "announce", "targets": ["echo-1"], "text": "Hello"},
         )
         self.assertTrue(announced["result"]["outcomes"][0]["ok"])
         self.assertEqual(gateway.announced[0]["content"][0]["speak"]["value"], "Hello")
@@ -167,7 +168,7 @@ class ProtocolTests(unittest.TestCase):
 
     def test_sequence_helpers_do_not_embed_markup(self) -> None:
         target = {"id": "echo-1", "deviceType": "T", "customerId": "c"}
-        sequence = build_speak_sequence(target, "plain", 10, "en-GB")
+        sequence = build_speak_sequence(target, "plain", "en-GB")
         self.assertNotIn("<", json.dumps(sequence))
         announcement = build_announcement(target, "plain", "en-GB")
         self.assertEqual(announcement["content"][0]["speak"]["type"], "text")