AlexaPy 1.29.25__tar.gz → 1.30.0__tar.gz

{alexapy-1.29.25 → alexapy-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AlexaPy
-Version: 1.29.25
+Version: 1.30.0
 Summary: Python API to control Amazon Echo Devices Programmatically.
 License: Apache-2.0
 License-File: AUTHORS.md

{alexapy-1.29.25 → alexapy-1.30.0}/alexapy/alexaapi.py

@@ -137,9 +137,7 @@ class AlexaAPI:
         cached = getattr(login, "_alexa_api_url", None)
         if cached:
             _LOGGER.debug(
-                "%s: Returning cached url: %s",
-                hide_email(login.email),
-                cached
+                "%s: Returning cached url: %s", hide_email(login.email), cached
             )
             return cached
 
@@ -159,9 +157,7 @@ class AlexaAPI:
 
         try:
             resp = await session.get(
-                endpoints_url,
-                headers=local_headers,
-                ssl=login._ssl
+                endpoints_url, headers=local_headers, ssl=login._ssl
             )
             text = await resp.text()
             _LOGGER.debug(
@@ -176,10 +172,7 @@ class AlexaAPI:
             if resp.status == 200:
                 try:
                     data = json.loads(text)
-                    api_url = (
-                         data.get("websiteApiUrl", "")
-                        .rstrip("/")
-                    )
+                    api_url = data.get("websiteApiUrl", "").rstrip("/")
                     if api_url:
                         login._alexa_api_url = api_url
                         _LOGGER.debug(
@@ -191,7 +184,7 @@ class AlexaAPI:
                     else:
                         _LOGGER.debug(
                             "%s: Unable to extract websiteApiUrl from /api/endpoints",
-                            hide_email(login.email)
+                            hide_email(login.email),
                         )
                 except ValueError:
                     _LOGGER.debug(
@@ -516,7 +509,7 @@ class AlexaAPI:
                     for marker in (
                         "Rate exceeded",
                         "ThrottlingException",
-                        "Too many requests"
+                        "Too many requests",
                     )
                 )
                 and not getattr(login, "_rate_retry_inflight", False)
@@ -1494,6 +1487,177 @@ class AlexaAPI:
         AlexaAPI.devices[login.email] = []
         return AlexaAPI.devices[login.email]
 
+    @staticmethod
+    @_catch_all_exceptions
+    async def get_child_mode(
+        login: AlexaLogin, serial: str, device_type: str
+    ) -> bool | None:
+        """Return whether Amazon Kids (child mode) is active for a device.
+
+        Amazon models the Amazon Kids/child state per device as the boolean
+        ``isChildDirectedDevice``.
+
+        Args:
+        login (AlexaLogin): Successfully logged in AlexaLogin
+        serial (str): The device serial number
+        device_type (str): The device type
+
+        Returns:
+        Optional[bool]: True if Amazon Kids is active, False if not,
+            None if the state could not be determined.
+
+        """
+        response = await AlexaAPI._static_request(
+            "get",
+            login,
+            "/api/device/op-mode",
+            query={"deviceType": device_type, "deviceSerialNumber": serial},
+        )
+        value, _valid = await get_json_value(response, "isChildDirectedDevice", bool)
+        return value
+
+    @staticmethod
+    @_catch_all_exceptions
+    async def disable_child_mode(
+        login: AlexaLogin, serial: str, device_type: str
+    ) -> None:
+        """Disable Amazon Kids (child mode) for a device.
+
+        Unassigns the device from any child profile, which turns Amazon Kids
+        off (``isChildDirectedDevice`` becomes False).
+
+        Args:
+        login (AlexaLogin): Successfully logged in AlexaLogin
+        serial (str): The device serial number
+        device_type (str): The device type
+
+        """
+        await AlexaAPI._static_request(
+            "post",
+            login,
+            f"/api/unassign-device-from-child/{serial}/{device_type}",
+        )
+
+    @staticmethod
+    def _parent_dashboard_subdomain(login: AlexaLogin) -> str:
+        """Return the region subdomain of the Amazon Kids parent dashboard.
+
+        Amazon serves the parental-controls dashboard from a localized
+        subdomain (e.g. ``eltern.amazon.de`` in Germany, ``parents.amazon.com``
+        elsewhere).
+        """
+        return {"amazon.de": "eltern"}.get(login.url, "parents")
+
+    @staticmethod
+    @_catch_all_exceptions
+    async def get_child_profiles(login: AlexaLogin) -> list[dict[str, Any]] | None:
+        """Return the child profiles of the Amazon household.
+
+        Each entry contains at least ``firstName``, ``age`` and ``directedId``;
+        the ``directedId`` is required to enable Amazon Kids on a device.
+
+        Args:
+        login (AlexaLogin): Successfully logged in AlexaLogin
+
+        Returns:
+        Optional[list[dict]]: The CHILD household members, or None on error.
+
+        """
+        response = await AlexaAPI._static_request(
+            "get",
+            login,
+            "/ajax/get-household-with-age",
+            sub_domain=AlexaAPI._parent_dashboard_subdomain(login),
+        )
+        members, valid = await get_json_value(response, "members", list)
+        if not valid or not members:
+            return []
+        return [member for member in members if member.get("role") == "CHILD"]
+
+    @staticmethod
+    @_catch_all_exceptions
+    async def get_device_child(
+        login: AlexaLogin, serial: str, device_type: str
+    ) -> str | None:
+        """Return the directedId of the child a device is assigned to.
+
+        Args:
+        login (AlexaLogin): Successfully logged in AlexaLogin
+        serial (str): The device serial number
+        device_type (str): The device type
+
+        Returns:
+        Optional[str]: The child directedId, or None if unassigned/unknown.
+
+        """
+        response = await AlexaAPI._static_request(
+            "get",
+            login,
+            "/ajax/get-oobe-device-data",
+            query={"deviceId": serial, "deviceTypeId": device_type},
+            sub_domain=AlexaAPI._parent_dashboard_subdomain(login),
+        )
+        value, _valid = await get_json_value(response, "childDirectedId", str)
+        return value or None
+
+    @staticmethod
+    @_catch_all_exceptions
+    async def enable_child_mode(
+        login: AlexaLogin, serial: str, device_type: str, child_directed_id: str
+    ) -> None:
+        """Enable Amazon Kids by assigning a device to a child profile.
+
+        The parent dashboard uses its own CSRF token (``ft-panda-csrf-token``),
+        which is seeded by loading the device onboarding page first; the token
+        is then echoed back in the ``x-amzn-csrf`` header.
+
+        Args:
+        login (AlexaLogin): Successfully logged in AlexaLogin
+        serial (str): The device serial number
+        device_type (str): The device type
+        child_directed_id (str): directedId of the child (see get_child_profiles)
+
+        """
+        sub_domain = AlexaAPI._parent_dashboard_subdomain(login)
+        # Seed the parent-dashboard CSRF cookie (ft-panda-csrf-token).
+        await AlexaAPI._static_request(
+            "get",
+            login,
+            f"/oobe/brownie/start/{device_type}/{serial}",
+            sub_domain=sub_domain,
+        )
+        additional_headers = {
+            "Referer": (
+                f"https://{sub_domain}.{login.url}"
+                f"/oobe/brownie/start/{device_type}/{serial}"
+            ),
+            "Origin": f"https://{sub_domain}.{login.url}",
+        }
+        try:
+            # The ft-panda-csrf-token cookie is scoped to the parent-dashboard
+            # host, so it must be read for that host (not the default one).
+            additional_headers["x-amzn-csrf"] = login._get_cookies_from_session(
+                f"{sub_domain}.{login.url}"
+            )["ft-panda-csrf-token"].value
+        except (KeyError, AttributeError):
+            _LOGGER.debug(
+                "%s: ft-panda-csrf-token not found after bootstrap; "
+                "assign may be rejected",
+                hide_email(login.email),
+            )
+        await AlexaAPI._static_request(
+            "post",
+            login,
+            "/ajax/assign-device-to-child",
+            data={
+                "deviceId": serial,
+                "deviceTypeId": device_type,
+                "childDirectedId": child_directed_id,
+            },
+            additional_headers=additional_headers,
+            sub_domain=sub_domain,
+        )
+
     @staticmethod
     @_catch_all_exceptions
     async def get_wake_words(login: AlexaLogin) -> list[dict[str, Any]] | None:
@@ -1633,9 +1797,7 @@ class AlexaAPI:
 
             record_key = (record.get("recordKey") or "").split("#")
             o["deviceType"] = (
-                record_key[2]
-                if len(record_key) > 2 and record_key[2]
-                else None
+                record_key[2] if len(record_key) > 2 and record_key[2] else None
             )
             o["creationTimestamp"] = record.get("timestamp")
             o["deviceSerialNumber"] = record_key[3] if len(record_key) > 3 else None
@@ -2072,8 +2234,10 @@ class AlexaAPI:
         # 🔹 Use discovered base instead of hard-coded NA
         api_base = await AlexaAPI._get_alexa_api_base(login)
         ts = int(time.time() * 1000)
-        url = URL(api_base).with_path("/api/notifications").update_query(
-            {"cached": "true", "_": str(ts)}
+        url = (
+            URL(api_base)
+            .with_path("/api/notifications")
+            .update_query({"cached": "true", "_": str(ts)})
         )
 
         headers = AlexaAPI._build_notifications_headers(login)

{alexapy-1.29.25 → alexapy-1.30.0}/alexapy/alexahttp2.py

@@ -55,9 +55,34 @@ class HTTP2EchoClient:
         close_callback: Callable[[], Coroutine[Any, Any, None]],
         error_callback: Callable[[str], Coroutine[Any, Any, None]],
         loop: asyncio.AbstractEventLoop | None = None,
+        *,
+        read_timeout: float | None = 300,
     ) -> None:
-        """Init for threading and HTTP2 Push Connection."""
+        """Init for threading and HTTP2 Push Connection.
+
+        Args:
+            login: Authenticated AlexaLogin whose session opens the
+                directives stream.
+            msg_callback: Coroutine invoked with each directive message
+                parsed from the stream.
+            open_callback: Coroutine invoked once the HTTP2 stream has been
+                accepted and opened.
+            close_callback: Coroutine invoked when the stream is closed.
+            error_callback: Coroutine invoked with an error message when the
+                connection fails.
+            loop: Event loop to schedule tasks on; defaults to the running
+                loop when omitted.
+            read_timeout: Maximum seconds to wait between chunks of data on
+                the directives stream before treating the connection as stale
+                and closing it. A healthy stream carries multipart keepalive
+                traffic well inside this window; a stream that has gone silent
+                without a transport-level close delivers nothing and would
+                otherwise hang forever without any error. Pass None to disable
+                the check (previous behavior).
+        """
         assert login.session is not None
+        if read_timeout is not None and read_timeout <= 0:
+            raise ValueError("read_timeout must be positive or None")
         self._options = {
             "method": "GET",
             "path": "/v20160207/directives",
@@ -81,10 +106,21 @@ class HTTP2EchoClient:
             loop if loop else asyncio.get_event_loop()
         )
         self._last_ping = datetime.datetime(1, 1, 1)
+        self._last_activity: datetime.datetime | None = None
+        self._read_timeout = read_timeout
         self._tasks = set()
         self._opened: asyncio.Event = asyncio.Event()
         self._closing: bool = False
 
+    @property
+    def last_activity(self) -> datetime.datetime | None:
+        """Return when data last arrived on the directives stream.
+
+        Any traffic counts, including multipart keepalive boundaries, not
+        only parsed directives. None until the first chunk arrives.
+        """
+        return self._last_activity
+
     async def async_run(self) -> None:
         """Start Async WebSocket Listener.
 
@@ -133,7 +169,11 @@ class HTTP2EchoClient:
                 headers={
                     "authorization": self._options["authorization"],
                 },
-                timeout=httpx.Timeout(None),
+                # Never time out the overall stream, but bound the gap between
+                # chunks: the server sends keepalive boundaries continuously,
+                # so a long silent gap means the connection is dead even if
+                # the transport still looks open.
+                timeout=httpx.Timeout(None, read=self._read_timeout),
             ) as response:
                 # Validate the stream was accepted before reporting "open" upstream.
                 if response.status_code in (401, 403):
@@ -164,6 +204,24 @@ class HTTP2EchoClient:
 
             # Otherwise, normal disconnect.
             return
+        except httpx.ReadTimeout:
+            # No data (not even keepalives) inside the read window: the
+            # stream has gone silent without a transport-level close. Handle
+            # it so the consumer reconnects instead of hanging forever.
+            _LOGGER.debug(
+                "HTTP2 stream silent for %ss; closing stale connection",
+                self._read_timeout,
+            )
+
+            # If we never reached "open", propagate so the caller waiting on
+            # open sees a failed connect. The shared finally below still
+            # notifies close once, as it does for the other error paths.
+            if not self._opened.is_set():
+                raise
+
+            # Otherwise, treat like a normal disconnect so reconnect runs.
+            self.on_close(f"HTTP2 stream silent for {self._read_timeout}s")
+            return
         except Exception as exception_:
             # Surface unexpected failures so callers waiting for open can fail fast.
             _LOGGER.debug("HTTP2 exception: %s", exception_)
@@ -178,6 +236,7 @@ class HTTP2EchoClient:
         """Handle New Message."""
         reauth_required = "Unable to authenticate the request. Please provide a valid authorization token."  # noqa: E501
         _LOGGER.debug("Received raw message: %s", message)
+        self._last_activity = datetime.datetime.now(datetime.UTC)
         for line in message.splitlines():
             if line.startswith("------"):
                 if not self.boundary:  # set boundary character

{alexapy-1.29.25 → alexapy-1.30.0}/alexapy/alexalogin.py

@@ -703,6 +703,12 @@ class AlexaLogin:
             try:
                 async with aiofiles.open(cookiefile, "rb") as myfile:
                     raw_cookie_file = await myfile.read()
+                if not raw_cookie_file:
+                    _LOGGER.debug(
+                        "Cookie file %s is empty; ignoring it",
+                        cookiefile.replace(self.email, hide_email(self.email)),
+                    )
+                    continue
                 try:
                     cookies = loads(raw_cookie_file.decode())
                     if self._debug:
@@ -880,95 +886,114 @@ class AlexaLogin:
                 pass
         return data
 
-    async def test_loggedin(self, cookies: dict[str, str] | None = None) -> bool:
-        """Function that will test the connection is logged in.
+    async def test_loggedin(
+        self,
+        cookies: dict[str, str] | None = None,
+        *,
+        rebuild_session: bool = True,
+    ) -> bool:
+        """Test whether the connection is logged in.
+
+        Attempts to retrieve the authenticated customer and compare the returned
+        email address with the expected login email.
 
-        Tests:
-        - Attempts to get authentication and compares to expected login email
-        Returns false if unsuccessful getting json or the emails don't match
-        Returns false if no csrf found; necessary to issue commands
+        Returns False if the response cannot be decoded, the email does not match,
+        or no usable authenticated session can be confirmed.
         """
         if self._debug:
-            _LOGGER.debug("Testing whether logged in to alexa.%s", self._url)
+            _LOGGER.debug(
+                "Testing whether logged in to alexa.%s (rebuild_session=%s)",
+                self._url,
+                rebuild_session
+            )
             _LOGGER.debug("Cookies: %s", cookies)
             _LOGGER.debug("Session Cookies:\n%s", self._print_session_cookies())
             _LOGGER.debug("Header: %s", dumps(self._headers))
+
         if not self._session:
             self._create_session()
-        await self.get_tokens()
-        await self.register_capabilities()
-        await self.exchange_token_for_cookies()
-        await self.get_csrf()
-        path = (
-            self._prefix
-            + "amazon.com"
-            + f"/api/users/me?platform=ios&version={CALL_VERSION}"
-        )
-        self._log_cookies_for_url(path)
-        get_resp = await self._session.get(
-            path,
-            cookies=cookies,
-            ssl=self._ssl,
-        )
-        email = None
-        json = None
-        await self._process_resp(get_resp)
-        try:
-            json = await get_resp.json()
-            email = json.get("email")
-        except (JSONDecodeError, SimpleJSONDecodeError, ContentTypeError) as ex:
-            _LOGGER.debug(
-                "Not logged in: %s",
-                EXCEPTION_TEMPLATE.format(type(ex).__name__, ex.args),
-            )
-            if self.url.lower() == "amazon.com":
-                return False
-        # Convert from amazon.com domain to native domain
-        if self.url.lower() != "amazon.com":
-            self._headers["authority"] = f"www.{self._url}"
+
+        if rebuild_session:
+            await self.get_tokens()
+            await self.register_capabilities()
+            await self.exchange_token_for_cookies()
+            await self.get_csrf()
+
+        domains = [self._url]
+        if self._url.lower() != "amazon.com":
+            domains.append("amazon.com")
+
+        customer = None
+
+        for domain in domains:
+            self._headers["authority"] = f"www.{domain}"
             path = (
                 self._prefix
-                + self._url
+                + domain
                 + f"/api/users/me?platform=ios&version={CALL_VERSION}"
             )
+
             self._log_cookies_for_url(path)
-            get_resp = await self._session.get(path)
+            get_resp = await self._session.get(
+                path,
+                cookies=cookies,
+                ssl=self._ssl,
+            )
             await self._process_resp(get_resp)
+
             try:
-                json = await get_resp.json()
-                email = json.get("email")
-            except (JSONDecodeError, SimpleJSONDecodeError, ContentTypeError) as ex:
+                customer = await get_resp.json()
+            except (
+                JSONDecodeError,
+                SimpleJSONDecodeError,
+                ContentTypeError,
+            ) as ex:
                 _LOGGER.debug(
-                    "Not logged in: %s",
+                    "Not logged in to %s: %s",
+                    domain,
                     EXCEPTION_TEMPLATE.format(type(ex).__name__, ex.args),
                 )
-                return False
-        self.customer_id = json.get("id")
-        if (email and email.lower() == self.email.lower()) or "@" not in self.email:
-            if "@" in self.email:
-                _LOGGER.debug(
-                    "Logged in as %s to %s with id: %s",
-                    hide_email(email),
-                    self.url,
-                    self.customer_id,
-                )
-            else:
-                _LOGGER.debug(
-                    "Logged in as to %s mobile account %s with %s",
-                    hide_email(email),
-                    self.url,
-                    self.customer_id,
-                )
-            self.stats["login_timestamp"] = datetime.datetime.now()
-            self.stats["api_calls"] = 0
-            await self.check_domain()
-            await self.finalize_login()
-            return True
-        _LOGGER.debug(
-            "Not logged in due to email mismatch to stored %s", hide_email(email)
-        )
-        await self.reset()
-        return False
+                continue
+
+            email = customer.get("email")
+            if (email and email.lower() == self.email.lower()) or "@" not in self.email:
+                break
+
+            _LOGGER.debug(
+                "Login email from %s did not match stored email: %s",
+                domain,
+                hide_email(email),
+            )
+            customer = None
+
+        if customer is None:
+            _LOGGER.debug("Not logged in to any attempted Alexa domain")
+            await self.reset()
+            return False
+
+        email = customer.get("email")
+        self.customer_id = customer.get("id")
+
+        if "@" in self.email:
+            _LOGGER.debug(
+                "Logged in as %s to %s with id: %s",
+                hide_email(email),
+                self.url,
+                self.customer_id,
+            )
+        else:
+            _LOGGER.debug(
+                "Logged in as %s to mobile account %s with %s",
+                hide_email(email),
+                self.url,
+                self.customer_id,
+            )
+
+        self.stats["login_timestamp"] = datetime.datetime.now()
+        self.stats["api_calls"] = 0
+        await self.check_domain()
+        await self.finalize_login()
+        return True
 
     async def get_csrf_token(self) -> str | None:
         """Get an anti-CSRF token from an Amazon webpage."""
@@ -1045,11 +1070,44 @@ class AlexaLogin:
     ) -> None:
         """Login to Amazon."""
         data = data or {}
+
+        # Prefer the persisted OAuth device registration whenever a refresh token
+        # is available. Access tokens and website cookies are short-lived runtime
+        # credentials and can be rebuilt silently from the refresh token without
+        # device registration, capability registration, or stored credentials.
+        if self.refresh_token:
+            _LOGGER.debug("Attempting login using the stored OAuth refresh token")
+            if not self._session:
+                self._create_session()
+            recovered = (
+                await self.refresh_access_token()
+                and await self.exchange_token_for_cookies()
+                and await self.get_csrf()
+                and await self.test_loggedin(rebuild_session=False)
+            )
+            if recovered:
+                _LOGGER.info(
+                    "Logged in %s using the stored OAuth refresh token",
+                    hide_email(self.email),
+                )
+                return
+            _LOGGER.debug(
+                "OAuth refresh-token login failed; falling back to stored cookies"
+            )
+            await self.reset()
+
+        # Retain persisted-cookie login as a compatibility fallback for accounts
+        # without a usable OAuth refresh token.
         if cookies:
-            _LOGGER.debug("Using cookies to log in")
-            if await self.test_loggedin(cookies):
+            _LOGGER.debug("Using stored cookies to log in")
+            if await self.test_loggedin(
+                cookies,
+                rebuild_session=False,
+            ):
                 return
+            _LOGGER.debug("Stored-cookie login failed; falling back to credentials")
             await self.reset()
+
         _LOGGER.debug("Using credentials to log in")
         if not self._site:
             site: URL = self.start_url
@@ -1212,18 +1270,31 @@ class AlexaLogin:
                 assert isinstance(cookie_jar, aiohttp.CookieJar)
                 if self._debug:
                     _LOGGER.debug("Saving cookie to %s", cookiefile)
+                temp_cookiefile = f"{self._cookiefile[0]}.{uuid4().hex}.tmp"
                 try:
                     serialized_cookie_jar = _serialize_cookie_jar(cookie_jar)
-                    async with aiofiles.open(
-                        self._cookiefile[0], mode="w"
-                    ) as localfile:
-                        await localfile.write(dumps(serialized_cookie_jar))
+                    serialized_cookies = dumps(serialized_cookie_jar)
+                    async with aiofiles.open(temp_cookiefile, mode="w") as localfile:
+                        await localfile.write(serialized_cookies)
+                        await localfile.flush()
+
+                    # The temporary file is created beside the destination so
+                    # os.replace() is atomic on the same filesystem. The live
+                    # cookie file therefore remains valid until the replacement
+                    # is complete, even if shutdown interrupts the write.
+                    await asyncio.to_thread(
+                        os.replace, temp_cookiefile, self._cookiefile[0]
+                    )
                 except (OSError, EOFError, TypeError, AttributeError) as ex:
                     _LOGGER.debug(
                         "Error saving serialized cookie to %s: %s",
                         self._cookiefile[0].replace(self.email, hide_email(self.email)),
                         EXCEPTION_TEMPLATE.format(type(ex).__name__, ex.args),
                     )
+                finally:
+                    with contextlib.suppress(OSError):
+                        if os.path.exists(temp_cookiefile):
+                            await aioos.remove(temp_cookiefile)
             elif (cookiefile) and os.path.exists(cookiefile):
                 _LOGGER.debug(
                     "Removing outdated cookiefile %s",

{alexapy-1.29.25 → alexapy-1.30.0}/pyproject.toml

@@ -1,7 +1,7 @@
 #  SPDX-License-Identifier: Apache-2.0
 [tool.poetry]
 name = "AlexaPy"
-version = "1.29.25"
+version = "1.30.0"
 description = "Python API to control Amazon Echo Devices Programmatically."
 authors = [
   "Keaton Taylor <keatonstaylor@gmail.com>",