amazon-parent-dashboard 1.0.0__tar.gz

amazon_parent_dashboard-1.0.0/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.1
+Name: amazon_parent_dashboard
+Version: 1.0.0
+Summary: A simple interface to add bonus time to your Amazon Parent Dashboard devices
+Home-page: https://github.com/GrantGMiller/amazon_parent_dashboard
+Author: Grant miller
+Author-email: grant@grant-miller.com
+License: PSF
+Project-URL: Source Code, https://github.com/GrantGMiller/amazon_parent_dashboard
+Keywords: grant miller familylink bonus time
+Description-Content-Type: text/x-rst
+Requires-Dist: requests
+Requires-Dist: pytz
+
+Amazon Kids Parent Dashboard Client
+====================================
+
+Overview
+--------
+
+This module provides an unofficial Python client for the Amazon Kids Parent
+Dashboard at https://parents.amazon.com.
+
+It was developed from browser network captures and uses Parent Dashboard
+endpoints that are not documented as a public API. Amazon may change these
+endpoints, request formats, authentication requirements, or response formats
+at any time.
+
+The client currently supports:
+
+* Retrieve the children names.
+* Reading a child's time-limit configuration.
+* Getting the current day's maximum screen-time limit.
+* Adding bonus time for a child.
+* Pausing and resuming a child's devices.
+
+Authentication requires you to copy cookies from an already authenticated Amazon session. This
+module does not implement an OAuth flow or guarantee automatic renewal of an
+expired session.
+
+Requirements/Dependencies
+-------------------------
+
+* Python 3.8 or newer.
+* ``requests``
+* ``pytz``
+
+
+Authentication
+--------------
+
+The constructor accepts cookies in one of three formats:
+
+#. A Python dictionary mapping cookie names to cookie values.
+#. A JSON string representing that dictionary.
+#. A cookie-header string containing semicolon-separated ``name=value`` pairs.
+
+You can pass cookies directly::
+
+    from parent_dashboard import ParentDashboard
+
+    cookies = {
+        "session-id": "YOUR_SESSION_ID",
+        "session-token": "YOUR_SESSION_TOKEN",
+        # Add the other cookies required by your current session.
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children={str(child_name): str(child_id)}
+    )
+
+The example cookie names above are illustrative. Copy the required cookie
+pairs from your own authenticated browser session; the exact set may vary.
+
+**Keep cookies secret.** Treat them like passwords: do not
+commit them to source control, include them in bug reports, or print them in
+logs. Use environment variables or a secrets manager and restrict access to
+the server account running the client.
+
+Configuring children
+--------------------
+
+The client does not automatically discover children names. Pass a mapping from each
+child's display name to their Amazon ``childDirectedId`` / directed ID::
+
+    children = {
+        "Forrest": "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+        "Jenny":   "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+    )
+
+Replace each placeholder with the actual directed ID for that child. The
+client matches names case-insensitively, but the supplied name must otherwise
+match one of the configured names. If ``children`` is omitted, calls that
+require a child will raise ``ParentDashboardError``.
+
+Basic usage
+-----------
+
+Get configured child names::
+
+    print(dashboard.get_children())
+
+Read the raw time-limit response for a child::
+
+    limits = dashboard.get_time_limits("Lillianne")
+    print(limits)
+
+Get the current day's screen-time limit in minutes::
+
+    max_minutes = dashboard.get_max_screentime("Lillianne")
+    if max_minutes is None:
+        print("No enabled screen-time limit was found for today.")
+    else:
+        print(f"Today's limit: {max_minutes} minutes")
+
+``get_max_screentime`` uses the configured time zone to choose the current
+weekday. It returns ``None`` when the day's schedule or content-time limits
+are disabled. Otherwise it expects the response to contain an integer value
+under ``timeLimits.contentTimeLimits.ALL`` for the matching day.
+
+Set bonus time::
+
+    dashboard.add_bonus_time("Lillianne", 15)
+
+The current implementation sends a ``PUT`` request to
+``/ajax/set-bonus-time`` with a duration of 15 minutes. **Despite the method
+name, it is not yet confirmed whether the endpoint adds 15 minutes to an
+existing bonus or sets the bonus duration to 15 minutes.** Verify this behavior
+carefully in the Parent Dashboard before relying on repeated calls. Do not
+assume calling it twice safely adds twice as much time.
+
+Pause devices for a child for 60 minutes::
+
+    dashboard.pause_devices("Rosalie", 60)
+
+Resume devices for a child::
+
+    dashboard.resume_devices("Rosalie")
+
+
+
+Time zone
+---------
+
+The constructor defaults to ``America/New_York``::
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+        time_zone="America/New_York",
+    )
+
+The time zone is sent with bonus-time requests and is also used to determine
+the weekday in ``get_max_screentime``. Use an appropriate IANA time-zone name
+for your household.
+
+Constructor reference
+---------------------
+
+``ParentDashboard(cookies=None, children=None, time_zone="America/New_York")``
+
+``cookies``
+    Cookie dictionary, JSON string, or semicolon-separated cookie-header
+    string. If omitted, the client reads ``AMAZON_PARENTS_COOKIES``. If neither
+    is set, construction raises ``AuthError``.
+
+``children``
+    Dictionary mapping child display names to directed IDs.
+
+``time_zone``
+    IANA time-zone string used for bonus-time requests and weekday selection.
+
+Public methods
+--------------
+
+``get_children()``
+    Return the configured child names as a list. This does not discover
+    children from Amazon; it returns the names supplied in ``children``.
+
+``get_time_limits(child_name)``
+    Return the raw JSON response from the adjusted-time-limits endpoint.
+
+``get_max_screentime(child_name)``
+    Return today's enabled ``ALL`` content-time limit in minutes, or ``None``
+    when the relevant limits are disabled. Raises ``ParentDashboardError`` if
+    the expected response structure is missing.
+
+``add_bonus_time(child_name, minutes)``
+    Send a bonus-time configuration request. ``minutes`` must be positive.
+    Whether the endpoint adds to or replaces the current bonus has not been
+    confirmed.
+
+``pause_devices(child_name, minutes)``
+    Request that the child's devices be paused for the requested number of
+    minutes. ``minutes`` must be positive.
+
+``resume_devices(child_name)``
+    Request that the child's devices be resumed.
+
+Exceptions
+----------
+
+``ParentDashboardError``
+    Base exception for client errors, unexpected responses, and HTTP failures.
+
+``AuthError``
+    Raised when cookies are missing/invalid, the request is redirected to
+    sign-in, or CSRF-token retrieval fails.
+
+``KeyError``
+    Raised by child lookup when the requested name is not in the configured
+    mapping.
+
+``ValueError``
+    Raised when a pause or bonus duration is not positive.
+
+Running the module directly
+---------------------------
+
+The module's ``__main__`` example expects a local ``config`` module containing
+at least these attributes::
+
+    cookie_string
+    child_name_id_map
+    child_name
+
+It also expects a ``helper`` module with a ``get_cookie_dict`` function.
+The example reads the selected child's maximum screen-time limit. Adapt these
+names to your own configuration, and do not commit real authentication
+credentials to a repository.
+
+Automation and server deployment
+--------------------------------
+
+For a scheduled job, keep your rule logic separate from the client. For
+example::
+
+    from parent_dashboard import ParentDashboard
+
+    dashboard = ParentDashboard(
+        children=children,
+        time_zone="America/New_York",
+    )
+
+    child_name = "Lillianne"
+    max_minutes = dashboard.get_max_screentime(child_name)
+
+    # Insert your own decision logic here.
+    # Only call add_bonus_time after verifying the endpoint's semantics.
+
+Run the script using a scheduler such as ``systemd`` or cron. In production:
+
+* Store credentials in environment variables or a secrets manager.
+* Run the job as a dedicated, unprivileged Linux user.
+* Log decisions and outcomes, but never log cookies, CSRF tokens, or full
+  authentication headers.
+* Handle ``AuthError`` and notify the administrator when manual sign-in is
+  required.
+* Add persistent state or an idempotency record so a retried job does not
+  accidentally award the same bonus more than once.
+* Test with a small, controlled bonus and verify the result in the Parent
+  Dashboard before enabling automatic awards.
+* Do not assume that a browser session will remain valid indefinitely. This
+  client does not implement supported OAuth refresh-token handling.
+
+Example error handling::
+
+    from parent_dashboard import AuthError, ParentDashboardError
+
+    try:
+        dashboard.add_bonus_time("Lillianne", 10)
+    except AuthError as exc:
+        # Notify yourself that the session needs attention.
+        print(f"Authentication needs attention: {exc}")
+    except ParentDashboardError as exc:
+        print(f"Parent Dashboard request failed: {exc}")
+
+Troubleshooting
+---------------
+
+**``AuthError: No cookies``**
+
+Pass ``cookies=...`` or set ``AMAZON_PARENTS_COOKIES``.
+
+**Redirected to sign-in / invalid cookies**
+
+The session may have expired or been revoked. Obtain a fresh authenticated
+session and update the configured cookies. The client cannot guarantee
+automatic reauthentication.
+
+**HTTP 401 or 403**
+
+The session may be invalid or the endpoint may
+require a different request format. For eligible read-only requests, the
+client attempts one CSRF refresh and retry. It does not automatically retry
+state-changing requests.
+
+**Unexpected time-limit response**
+
+Inspect the raw result of ``get_time_limits(child_name)``. The parser in
+``get_max_screentime`` expects ``periodConfigurations`` with a matching
+``DayOfWeek`` entry and an integer ``ALL`` value.
+
+Limitations and disclaimer
+--------------------------
+
+This is an unofficial client built from browser network captures. It is not
+an Amazon-supported SDK, and the endpoints are not guaranteed to remain
+available or compatible. The client does not currently discover child IDs,
+guarantee session renewal, or verify whether setting bonus time is additive.
+Use it only with an account and devices you are authorized to manage, and
+verify changes in the Parent Dashboard.

amazon_parent_dashboard-1.0.0/README.rst

@@ -0,0 +1,304 @@
+Amazon Kids Parent Dashboard Client
+====================================
+
+Overview
+--------
+
+This module provides an unofficial Python client for the Amazon Kids Parent
+Dashboard at https://parents.amazon.com.
+
+It was developed from browser network captures and uses Parent Dashboard
+endpoints that are not documented as a public API. Amazon may change these
+endpoints, request formats, authentication requirements, or response formats
+at any time.
+
+The client currently supports:
+
+* Retrieve the children names.
+* Reading a child's time-limit configuration.
+* Getting the current day's maximum screen-time limit.
+* Adding bonus time for a child.
+* Pausing and resuming a child's devices.
+
+Authentication requires you to copy cookies from an already authenticated Amazon session. This
+module does not implement an OAuth flow or guarantee automatic renewal of an
+expired session.
+
+Requirements/Dependencies
+-------------------------
+
+* Python 3.8 or newer.
+* ``requests``
+* ``pytz``
+
+
+Authentication
+--------------
+
+The constructor accepts cookies in one of three formats:
+
+#. A Python dictionary mapping cookie names to cookie values.
+#. A JSON string representing that dictionary.
+#. A cookie-header string containing semicolon-separated ``name=value`` pairs.
+
+You can pass cookies directly::
+
+    from parent_dashboard import ParentDashboard
+
+    cookies = {
+        "session-id": "YOUR_SESSION_ID",
+        "session-token": "YOUR_SESSION_TOKEN",
+        # Add the other cookies required by your current session.
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children={str(child_name): str(child_id)}
+    )
+
+The example cookie names above are illustrative. Copy the required cookie
+pairs from your own authenticated browser session; the exact set may vary.
+
+**Keep cookies secret.** Treat them like passwords: do not
+commit them to source control, include them in bug reports, or print them in
+logs. Use environment variables or a secrets manager and restrict access to
+the server account running the client.
+
+Configuring children
+--------------------
+
+The client does not automatically discover children names. Pass a mapping from each
+child's display name to their Amazon ``childDirectedId`` / directed ID::
+
+    children = {
+        "Forrest": "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+        "Jenny":   "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+    )
+
+Replace each placeholder with the actual directed ID for that child. The
+client matches names case-insensitively, but the supplied name must otherwise
+match one of the configured names. If ``children`` is omitted, calls that
+require a child will raise ``ParentDashboardError``.
+
+Basic usage
+-----------
+
+Get configured child names::
+
+    print(dashboard.get_children())
+
+Read the raw time-limit response for a child::
+
+    limits = dashboard.get_time_limits("Lillianne")
+    print(limits)
+
+Get the current day's screen-time limit in minutes::
+
+    max_minutes = dashboard.get_max_screentime("Lillianne")
+    if max_minutes is None:
+        print("No enabled screen-time limit was found for today.")
+    else:
+        print(f"Today's limit: {max_minutes} minutes")
+
+``get_max_screentime`` uses the configured time zone to choose the current
+weekday. It returns ``None`` when the day's schedule or content-time limits
+are disabled. Otherwise it expects the response to contain an integer value
+under ``timeLimits.contentTimeLimits.ALL`` for the matching day.
+
+Set bonus time::
+
+    dashboard.add_bonus_time("Lillianne", 15)
+
+The current implementation sends a ``PUT`` request to
+``/ajax/set-bonus-time`` with a duration of 15 minutes. **Despite the method
+name, it is not yet confirmed whether the endpoint adds 15 minutes to an
+existing bonus or sets the bonus duration to 15 minutes.** Verify this behavior
+carefully in the Parent Dashboard before relying on repeated calls. Do not
+assume calling it twice safely adds twice as much time.
+
+Pause devices for a child for 60 minutes::
+
+    dashboard.pause_devices("Rosalie", 60)
+
+Resume devices for a child::
+
+    dashboard.resume_devices("Rosalie")
+
+
+
+Time zone
+---------
+
+The constructor defaults to ``America/New_York``::
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+        time_zone="America/New_York",
+    )
+
+The time zone is sent with bonus-time requests and is also used to determine
+the weekday in ``get_max_screentime``. Use an appropriate IANA time-zone name
+for your household.
+
+Constructor reference
+---------------------
+
+``ParentDashboard(cookies=None, children=None, time_zone="America/New_York")``
+
+``cookies``
+    Cookie dictionary, JSON string, or semicolon-separated cookie-header
+    string. If omitted, the client reads ``AMAZON_PARENTS_COOKIES``. If neither
+    is set, construction raises ``AuthError``.
+
+``children``
+    Dictionary mapping child display names to directed IDs.
+
+``time_zone``
+    IANA time-zone string used for bonus-time requests and weekday selection.
+
+Public methods
+--------------
+
+``get_children()``
+    Return the configured child names as a list. This does not discover
+    children from Amazon; it returns the names supplied in ``children``.
+
+``get_time_limits(child_name)``
+    Return the raw JSON response from the adjusted-time-limits endpoint.
+
+``get_max_screentime(child_name)``
+    Return today's enabled ``ALL`` content-time limit in minutes, or ``None``
+    when the relevant limits are disabled. Raises ``ParentDashboardError`` if
+    the expected response structure is missing.
+
+``add_bonus_time(child_name, minutes)``
+    Send a bonus-time configuration request. ``minutes`` must be positive.
+    Whether the endpoint adds to or replaces the current bonus has not been
+    confirmed.
+
+``pause_devices(child_name, minutes)``
+    Request that the child's devices be paused for the requested number of
+    minutes. ``minutes`` must be positive.
+
+``resume_devices(child_name)``
+    Request that the child's devices be resumed.
+
+Exceptions
+----------
+
+``ParentDashboardError``
+    Base exception for client errors, unexpected responses, and HTTP failures.
+
+``AuthError``
+    Raised when cookies are missing/invalid, the request is redirected to
+    sign-in, or CSRF-token retrieval fails.
+
+``KeyError``
+    Raised by child lookup when the requested name is not in the configured
+    mapping.
+
+``ValueError``
+    Raised when a pause or bonus duration is not positive.
+
+Running the module directly
+---------------------------
+
+The module's ``__main__`` example expects a local ``config`` module containing
+at least these attributes::
+
+    cookie_string
+    child_name_id_map
+    child_name
+
+It also expects a ``helper`` module with a ``get_cookie_dict`` function.
+The example reads the selected child's maximum screen-time limit. Adapt these
+names to your own configuration, and do not commit real authentication
+credentials to a repository.
+
+Automation and server deployment
+--------------------------------
+
+For a scheduled job, keep your rule logic separate from the client. For
+example::
+
+    from parent_dashboard import ParentDashboard
+
+    dashboard = ParentDashboard(
+        children=children,
+        time_zone="America/New_York",
+    )
+
+    child_name = "Lillianne"
+    max_minutes = dashboard.get_max_screentime(child_name)
+
+    # Insert your own decision logic here.
+    # Only call add_bonus_time after verifying the endpoint's semantics.
+
+Run the script using a scheduler such as ``systemd`` or cron. In production:
+
+* Store credentials in environment variables or a secrets manager.
+* Run the job as a dedicated, unprivileged Linux user.
+* Log decisions and outcomes, but never log cookies, CSRF tokens, or full
+  authentication headers.
+* Handle ``AuthError`` and notify the administrator when manual sign-in is
+  required.
+* Add persistent state or an idempotency record so a retried job does not
+  accidentally award the same bonus more than once.
+* Test with a small, controlled bonus and verify the result in the Parent
+  Dashboard before enabling automatic awards.
+* Do not assume that a browser session will remain valid indefinitely. This
+  client does not implement supported OAuth refresh-token handling.
+
+Example error handling::
+
+    from parent_dashboard import AuthError, ParentDashboardError
+
+    try:
+        dashboard.add_bonus_time("Lillianne", 10)
+    except AuthError as exc:
+        # Notify yourself that the session needs attention.
+        print(f"Authentication needs attention: {exc}")
+    except ParentDashboardError as exc:
+        print(f"Parent Dashboard request failed: {exc}")
+
+Troubleshooting
+---------------
+
+**``AuthError: No cookies``**
+
+Pass ``cookies=...`` or set ``AMAZON_PARENTS_COOKIES``.
+
+**Redirected to sign-in / invalid cookies**
+
+The session may have expired or been revoked. Obtain a fresh authenticated
+session and update the configured cookies. The client cannot guarantee
+automatic reauthentication.
+
+**HTTP 401 or 403**
+
+The session may be invalid or the endpoint may
+require a different request format. For eligible read-only requests, the
+client attempts one CSRF refresh and retry. It does not automatically retry
+state-changing requests.
+
+**Unexpected time-limit response**
+
+Inspect the raw result of ``get_time_limits(child_name)``. The parser in
+``get_max_screentime`` expects ``periodConfigurations`` with a matching
+``DayOfWeek`` entry and an integer ``ALL`` value.
+
+Limitations and disclaimer
+--------------------------
+
+This is an unofficial client built from browser network captures. It is not
+an Amazon-supported SDK, and the endpoints are not guaranteed to remain
+available or compatible. The client does not currently discover child IDs,
+guarantee session renewal, or verify whether setting bonus time is additive.
+Use it only with an account and devices you are authorized to manage, and
+verify changes in the Parent Dashboard.

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard/__init__.py

@@ -0,0 +1,357 @@
+"""Unofficial client for https://parents.amazon.com (Amazon Kids Parent Dashboard).
+
+Built from a browser HAR capture. Endpoints confirmed by the HAR:
+
+    POST /ajax/set-offscreen-time      pause / resume devices
+    PUT  /ajax/set-bonus-time          bonus time
+    GET  /ajax/get-adjusted-time-limits?childDirectedId=...
+
+NOT covered by the HAR (see TODOs below):
+    * how to list children / map names -> directed IDs
+    * the response shape of get-adjusted-time-limits
+    * where the x-amzn-csrf token comes from (best-effort scrape of the home page)
+
+Auth: the HAR had its cookies stripped, so this takes your logged-in
+amazon.com cookies from the constructor or the AMAZON_PARENTS_COOKIES env var
+(either a JSON object or a "name=value; name=value" header string).
+"""
+
+import json
+import os
+import re
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Union
+
+import pytz
+import requests
+
+import config
+
+BASE_URL = "https://parents.amazon.com"
+USER_AGENT = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36"
+)
+
+# Best-effort guesses for where the page embeds the CSRF token. Unverified.
+_CSRF_PATTERNS = [
+    re.compile(r'"csrfToken"\s*:\s*"([^"]+)"'),
+    re.compile(r'"x-amzn-csrf"\s*:\s*"([^"]+)"', re.I),
+    re.compile(r'<meta[^>]+name=["\']x-amzn-csrf["\'][^>]+content=["\']([^"\']+)', re.I),
+    re.compile(r'<meta[^>]+name=["\']csrf-token["\'][^>]+content=["\']([^"\']+)', re.I),
+    re.compile(r'ft-panda-csrf-token=([^;\s,]+)', ) # this is the one we want
+]
+
+
+class ParentDashboardError(Exception):
+    pass
+
+
+class AuthError(ParentDashboardError):
+    pass
+
+
+def _parse_cookies(raw: Union[str, Dict[str, str]]) -> Dict[str, str]:
+    if isinstance(raw, dict):
+        return raw
+    raw = raw.strip()
+    if raw.startswith("{"):
+        return json.loads(raw)
+    cookies = {}
+    for part in raw.split(";"):
+        if "=" in part:
+            k, v = part.split("=", 1)
+            cookies[k.strip()] = v.strip()
+    return cookies
+
+
+class ParentDashboard:
+    def __init__(
+            self,
+            cookies: Optional[Union[str, Dict[str, str]]] = None,
+            csrf_token: Optional[str] = None,  # this will be populated automatically on a failed request.
+            children: Optional[Dict[str, str]] = None,
+            time_zone: str = "America/New_York",
+    ):
+        """
+        :param cookies: logged-in amazon.com cookies (dict, JSON string, or
+            "k=v; k=v" string). Falls back to $AMAZON_PARENTS_COOKIES.
+        :param csrf_token: optional x-amzn-csrf value. If omitted, uses
+            $AMAZON_PARENTS_CSRF_TOKEN or scrapes it from the home page.
+        :param children: mapping of child name -> directed ID
+            (e.g. {"Alex": "amzn1.account.AEZ5..."}). The IDs appear in the
+            request bodies in the browser network tab.
+        :param time_zone: IANA zone sent with bonus-time requests.
+        """
+        raw = cookies or os.environ.get("AMAZON_PARENTS_COOKIES")
+        if not raw:
+            raise AuthError(
+                "No cookies. Pass cookies=... or set AMAZON_PARENTS_COOKIES."
+            )
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "user-agent": USER_AGENT,
+                "accept": "application/json, text/plain, */*",
+                "origin": BASE_URL,
+                "referer": BASE_URL + "/",
+            }
+        )
+        self._session.cookies.update(_parse_cookies(raw))
+        self._csrf = csrf_token or os.environ.get("AMAZON_PARENTS_CSRF_TOKEN")
+        if self._csrf:
+            self._session.cookies.set("ft-panda-csrf-token", self._csrf)
+        self._children: Optional[Dict[str, str]] = dict(children) if children else None
+        self._time_zone = time_zone
+
+    # ------------------------------------------------------------------ http
+
+    def discover_child_directed_ids(self) -> Dict[str, str]:
+        """Discover child names and directed IDs from the dashboard HTML."""
+
+        response = self._request(
+            method='get',
+            path=f"/",
+        )
+        response.raise_for_status()
+
+        if "signin" in response.url.lower():
+            raise AuthError("Cookies are expired or invalid.")
+
+        # Extract the JSON string passed to JSON.parse(...).
+        match = re.search(
+            r"window\.__PREFETCHED_HOUSEHOLD\s*=\s*"
+            r"JSON\.parse\('((?:\\.|[^'\\])*)'\)\s*;",
+            response.text,
+        )
+
+        if not match:
+            raise ParentDashboardError(
+                "Could not find __PREFETCHED_HOUSEHOLD in the dashboard HTML."
+            )
+
+        # The JavaScript string contains escaped JSON. Decode the string
+        # before parsing the resulting JSON object.
+        household_json = json.loads(f'"{match.group(1)}"')
+        household = json.loads(household_json)
+
+        children = {
+            member["firstName"]: member["directedId"]
+            for member in household.get("members", [])
+            if member.get("role") == "CHILD"
+               and member.get("firstName")
+               and member.get("directedId")
+        }
+
+        if not children:
+            raise ParentDashboardError(
+                "No children were found in the household data."
+            )
+
+
+        self._children = children
+        return children
+
+    def _refresh_csrf(self) -> None:
+        resp = self._session.get(BASE_URL + "/")
+        if "signin" in resp.url:
+            raise AuthError("Cookies are expired or invalid (redirected to sign-in).")
+        for pattern in _CSRF_PATTERNS:
+            m = pattern.search(str(resp.headers))
+            if m:
+                self._csrf = m.group(1)
+                self._session.cookies.set("ft-panda-csrf-token", self._csrf)
+                return
+        raise AuthError(
+            "Couldn't find the CSRF token in the home page. Copy the "
+            "'x-amzn-csrf' request header from your browser and pass "
+            "csrf_token=... instead."
+        )
+
+    def _request(self, method: str, path: str, *, params=None, body=None,
+                 _retry: bool = True) -> requests.Response:
+        print('_request=', method, path, params, body)
+        if not self._csrf:
+            self._refresh_csrf()
+
+        resp = self._session.request(
+            method,
+            BASE_URL + path,
+            params=params,
+            json=body,
+            headers={"x-amzn-csrf": self._csrf},
+        )
+        print('139 resp.text=', resp.text)
+        if "signin" in resp.url:
+            raise AuthError("Cookies are expired or invalid (redirected to sign-in).")
+        if resp.status_code in (401, 403) and _retry and method.upper() in {
+            "GET", "HEAD", "OPTIONS"
+        }:
+            previous_csrf = self._csrf
+            try:
+                print('_request response=', resp.status_code, resp.text)
+                print('_request response.headers=', resp.headers)
+                self._refresh_csrf()
+            except AuthError as exc:
+                raise AuthError(
+                    f"{method} {path} -> {resp.status_code}; "
+                    f"CSRF refresh failed: {exc}; response: {resp.text[:200]}"
+                ) from exc
+            if self._csrf != previous_csrf:
+                return self._request(
+                    method, path, params=params, body=body, _retry=False
+                )
+        if not resp.ok:
+            print('160 _request response=', resp.status_code, resp.text, resp.url)
+            print('161 _request response.headers=', resp.headers)
+            raise ParentDashboardError(
+                f"{method} {path} -> {resp.status_code}: {resp.text[:200]}"
+            )
+        return resp
+
+    # -------------------------------------------------------------- children
+
+    def _load_children(self) -> Dict[str, str]:
+        """Return child names mapped to their Amazon directed IDs."""
+        if self._children is None:
+            self.discover_child_directed_ids()
+        return self._children
+
+    def _child_id(self, child_name: str) -> str:
+        children = self._load_children()
+        for name, directed_id in children.items():
+            if name.lower() == child_name.lower():
+                return directed_id
+        raise KeyError(f"Unknown child {child_name!r}; known: {list(children)}")
+
+    # ------------------------------------------------------------ public API
+
+    def get_children(self) -> List[str]:
+        '''
+        Return the names of the children
+        :return:
+        '''
+        return list(self._load_children())
+
+    def add_bonus_time(self, child_name: str, minutes: int) -> None:
+        '''
+        Add bonus time to the child
+
+        Note: the endpoint is "set-bonus-time" and the UI row is labelled
+        "update bonus time", so this may SET the bonus to `minutes` rather
+        than add to an existing bonus. Verify by calling it twice.
+        :param child_name:
+        :param minutes:
+        :return: bool response.ok
+        '''
+        if minutes <= 0:
+            raise ValueError("minutes must be positive")
+        resp = self._request(
+            "PUT",
+            "/ajax/set-bonus-time",
+            body={
+                "childDirectedId": self._child_id(child_name),
+                "currentTime": datetime.now(timezone.utc).strftime(
+                    "%Y-%m-%dT%H:%M:%S.%f"
+                )[:-3] + "Z",
+                "currentTimeZone": self._time_zone,
+                "bonusTimeConfigurationType": "Duration",
+                "bonusTimeDurationInMinutes": int(minutes),
+            },
+        )
+        return resp.ok
+
+    def get_time_limits(self, child_name: str) -> dict:
+        """Raw JSON from /ajax/get-adjusted-time-limits (shape not in the HAR)."""
+        resp = self._request(
+            "GET",
+            "/ajax/get-adjusted-time-limits",
+            params={"childDirectedId": self._child_id(child_name)},
+        )
+        return resp.json()
+
+    def get_max_screentime(self, child_name: str) -> Optional[int]:
+        '''
+        Get today's screentime limit in minutes, or None if the child has no
+        time limit enabled for today.
+
+        Response shape (confirmed from a capture): {"periodConfigurations":
+        [{"type": "DayOfWeek", "name": "Monday", "enabled": bool,
+        "timeLimits": {"contentTimeLimitsEnabled": bool,
+        "contentTimeLimits": {...}}, ...}, ...]}
+        :param child_name:
+        :return:
+        '''
+        data = self.get_time_limits(child_name)
+        weekday = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
+                   "Saturday", "Sunday"][datetime.now(pytz.timezone(self._time_zone)).weekday()]
+        day = next(
+            (p for p in data.get("periodConfigurations", [])
+             if p.get("type") == "DayOfWeek" and p.get("name") == weekday),
+            None,
+        )
+        if day is None:
+            raise ParentDashboardError(f"No {weekday} entry in time-limit response")
+        limits = day.get("timeLimits", {})
+        if not day.get("enabled") or not limits.get("contentTimeLimitsEnabled"):
+            return None
+        content_time_limits = limits.get("contentTimeLimits", {})
+        total_minutes = content_time_limits.get("ALL")
+        if not isinstance(total_minutes, int) or isinstance(total_minutes, bool):
+            raise ParentDashboardError(
+                "Enabled content time limits are missing an integer 'ALL' value: "
+                f"{content_time_limits!r}"
+            )
+        return total_minutes
+
+    def pause_devices(self, child_name: str, minutes: int) -> None:
+        '''
+        Pause/lock the devices for the child
+
+        The HAR only shows 60 minutes (the UI picks from a dropdown); other
+        durations are untested.
+        :param child_name:
+        :param minutes:
+        :return:
+        '''
+        if minutes <= 0:
+            raise ValueError("minutes must be positive")
+        self._request(
+            "POST",
+            "/ajax/set-offscreen-time",
+            body={
+                "directedIds": [self._child_id(child_name)],
+                "expirationTimeInSeconds": int(minutes) * 60,
+            },
+        )
+
+    def resume_devices(self, child_name: str):
+        '''
+        Resume/unlock the devices for the child
+        :param child_name:
+        :return:
+        '''
+        self._request(
+            "POST",
+            "/ajax/set-offscreen-time",
+            body={
+                "directedIds": [self._child_id(child_name)],
+                "expirationTimeInSeconds": -1,
+            },
+        )
+
+
+if __name__ == "__main__":
+    pd = ParentDashboard(
+        cookies=config.cookie_string,
+    )
+
+    child_name = config.child_name
+    max_time = pd.get_max_screentime(child_name)
+    print(f'Max time for {child_name} is {max_time}')
+
+    is_success = pd.add_bonus_time(child_name, 15)
+    print(f'{"successfully" if is_success else "failed"} added bonus time to {child_name}')
+
+    max_time = pd.get_max_screentime(child_name)
+    print(f'Max time for {child_name} is {max_time}')

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard.egg-info/PKG-INFO

@@ -0,0 +1,318 @@
+Metadata-Version: 2.1
+Name: amazon_parent_dashboard
+Version: 1.0.0
+Summary: A simple interface to add bonus time to your Amazon Parent Dashboard devices
+Home-page: https://github.com/GrantGMiller/amazon_parent_dashboard
+Author: Grant miller
+Author-email: grant@grant-miller.com
+License: PSF
+Project-URL: Source Code, https://github.com/GrantGMiller/amazon_parent_dashboard
+Keywords: grant miller familylink bonus time
+Description-Content-Type: text/x-rst
+Requires-Dist: requests
+Requires-Dist: pytz
+
+Amazon Kids Parent Dashboard Client
+====================================
+
+Overview
+--------
+
+This module provides an unofficial Python client for the Amazon Kids Parent
+Dashboard at https://parents.amazon.com.
+
+It was developed from browser network captures and uses Parent Dashboard
+endpoints that are not documented as a public API. Amazon may change these
+endpoints, request formats, authentication requirements, or response formats
+at any time.
+
+The client currently supports:
+
+* Retrieve the children names.
+* Reading a child's time-limit configuration.
+* Getting the current day's maximum screen-time limit.
+* Adding bonus time for a child.
+* Pausing and resuming a child's devices.
+
+Authentication requires you to copy cookies from an already authenticated Amazon session. This
+module does not implement an OAuth flow or guarantee automatic renewal of an
+expired session.
+
+Requirements/Dependencies
+-------------------------
+
+* Python 3.8 or newer.
+* ``requests``
+* ``pytz``
+
+
+Authentication
+--------------
+
+The constructor accepts cookies in one of three formats:
+
+#. A Python dictionary mapping cookie names to cookie values.
+#. A JSON string representing that dictionary.
+#. A cookie-header string containing semicolon-separated ``name=value`` pairs.
+
+You can pass cookies directly::
+
+    from parent_dashboard import ParentDashboard
+
+    cookies = {
+        "session-id": "YOUR_SESSION_ID",
+        "session-token": "YOUR_SESSION_TOKEN",
+        # Add the other cookies required by your current session.
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children={str(child_name): str(child_id)}
+    )
+
+The example cookie names above are illustrative. Copy the required cookie
+pairs from your own authenticated browser session; the exact set may vary.
+
+**Keep cookies secret.** Treat them like passwords: do not
+commit them to source control, include them in bug reports, or print them in
+logs. Use environment variables or a secrets manager and restrict access to
+the server account running the client.
+
+Configuring children
+--------------------
+
+The client does not automatically discover children names. Pass a mapping from each
+child's display name to their Amazon ``childDirectedId`` / directed ID::
+
+    children = {
+        "Forrest": "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+        "Jenny":   "amzn1.account.REPLACE_WITH_DIRECTED_ID",
+    }
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+    )
+
+Replace each placeholder with the actual directed ID for that child. The
+client matches names case-insensitively, but the supplied name must otherwise
+match one of the configured names. If ``children`` is omitted, calls that
+require a child will raise ``ParentDashboardError``.
+
+Basic usage
+-----------
+
+Get configured child names::
+
+    print(dashboard.get_children())
+
+Read the raw time-limit response for a child::
+
+    limits = dashboard.get_time_limits("Lillianne")
+    print(limits)
+
+Get the current day's screen-time limit in minutes::
+
+    max_minutes = dashboard.get_max_screentime("Lillianne")
+    if max_minutes is None:
+        print("No enabled screen-time limit was found for today.")
+    else:
+        print(f"Today's limit: {max_minutes} minutes")
+
+``get_max_screentime`` uses the configured time zone to choose the current
+weekday. It returns ``None`` when the day's schedule or content-time limits
+are disabled. Otherwise it expects the response to contain an integer value
+under ``timeLimits.contentTimeLimits.ALL`` for the matching day.
+
+Set bonus time::
+
+    dashboard.add_bonus_time("Lillianne", 15)
+
+The current implementation sends a ``PUT`` request to
+``/ajax/set-bonus-time`` with a duration of 15 minutes. **Despite the method
+name, it is not yet confirmed whether the endpoint adds 15 minutes to an
+existing bonus or sets the bonus duration to 15 minutes.** Verify this behavior
+carefully in the Parent Dashboard before relying on repeated calls. Do not
+assume calling it twice safely adds twice as much time.
+
+Pause devices for a child for 60 minutes::
+
+    dashboard.pause_devices("Rosalie", 60)
+
+Resume devices for a child::
+
+    dashboard.resume_devices("Rosalie")
+
+
+
+Time zone
+---------
+
+The constructor defaults to ``America/New_York``::
+
+    dashboard = ParentDashboard(
+        cookies=cookies,
+        children=children,
+        time_zone="America/New_York",
+    )
+
+The time zone is sent with bonus-time requests and is also used to determine
+the weekday in ``get_max_screentime``. Use an appropriate IANA time-zone name
+for your household.
+
+Constructor reference
+---------------------
+
+``ParentDashboard(cookies=None, children=None, time_zone="America/New_York")``
+
+``cookies``
+    Cookie dictionary, JSON string, or semicolon-separated cookie-header
+    string. If omitted, the client reads ``AMAZON_PARENTS_COOKIES``. If neither
+    is set, construction raises ``AuthError``.
+
+``children``
+    Dictionary mapping child display names to directed IDs.
+
+``time_zone``
+    IANA time-zone string used for bonus-time requests and weekday selection.
+
+Public methods
+--------------
+
+``get_children()``
+    Return the configured child names as a list. This does not discover
+    children from Amazon; it returns the names supplied in ``children``.
+
+``get_time_limits(child_name)``
+    Return the raw JSON response from the adjusted-time-limits endpoint.
+
+``get_max_screentime(child_name)``
+    Return today's enabled ``ALL`` content-time limit in minutes, or ``None``
+    when the relevant limits are disabled. Raises ``ParentDashboardError`` if
+    the expected response structure is missing.
+
+``add_bonus_time(child_name, minutes)``
+    Send a bonus-time configuration request. ``minutes`` must be positive.
+    Whether the endpoint adds to or replaces the current bonus has not been
+    confirmed.
+
+``pause_devices(child_name, minutes)``
+    Request that the child's devices be paused for the requested number of
+    minutes. ``minutes`` must be positive.
+
+``resume_devices(child_name)``
+    Request that the child's devices be resumed.
+
+Exceptions
+----------
+
+``ParentDashboardError``
+    Base exception for client errors, unexpected responses, and HTTP failures.
+
+``AuthError``
+    Raised when cookies are missing/invalid, the request is redirected to
+    sign-in, or CSRF-token retrieval fails.
+
+``KeyError``
+    Raised by child lookup when the requested name is not in the configured
+    mapping.
+
+``ValueError``
+    Raised when a pause or bonus duration is not positive.
+
+Running the module directly
+---------------------------
+
+The module's ``__main__`` example expects a local ``config`` module containing
+at least these attributes::
+
+    cookie_string
+    child_name_id_map
+    child_name
+
+It also expects a ``helper`` module with a ``get_cookie_dict`` function.
+The example reads the selected child's maximum screen-time limit. Adapt these
+names to your own configuration, and do not commit real authentication
+credentials to a repository.
+
+Automation and server deployment
+--------------------------------
+
+For a scheduled job, keep your rule logic separate from the client. For
+example::
+
+    from parent_dashboard import ParentDashboard
+
+    dashboard = ParentDashboard(
+        children=children,
+        time_zone="America/New_York",
+    )
+
+    child_name = "Lillianne"
+    max_minutes = dashboard.get_max_screentime(child_name)
+
+    # Insert your own decision logic here.
+    # Only call add_bonus_time after verifying the endpoint's semantics.
+
+Run the script using a scheduler such as ``systemd`` or cron. In production:
+
+* Store credentials in environment variables or a secrets manager.
+* Run the job as a dedicated, unprivileged Linux user.
+* Log decisions and outcomes, but never log cookies, CSRF tokens, or full
+  authentication headers.
+* Handle ``AuthError`` and notify the administrator when manual sign-in is
+  required.
+* Add persistent state or an idempotency record so a retried job does not
+  accidentally award the same bonus more than once.
+* Test with a small, controlled bonus and verify the result in the Parent
+  Dashboard before enabling automatic awards.
+* Do not assume that a browser session will remain valid indefinitely. This
+  client does not implement supported OAuth refresh-token handling.
+
+Example error handling::
+
+    from parent_dashboard import AuthError, ParentDashboardError
+
+    try:
+        dashboard.add_bonus_time("Lillianne", 10)
+    except AuthError as exc:
+        # Notify yourself that the session needs attention.
+        print(f"Authentication needs attention: {exc}")
+    except ParentDashboardError as exc:
+        print(f"Parent Dashboard request failed: {exc}")
+
+Troubleshooting
+---------------
+
+**``AuthError: No cookies``**
+
+Pass ``cookies=...`` or set ``AMAZON_PARENTS_COOKIES``.
+
+**Redirected to sign-in / invalid cookies**
+
+The session may have expired or been revoked. Obtain a fresh authenticated
+session and update the configured cookies. The client cannot guarantee
+automatic reauthentication.
+
+**HTTP 401 or 403**
+
+The session may be invalid or the endpoint may
+require a different request format. For eligible read-only requests, the
+client attempts one CSRF refresh and retry. It does not automatically retry
+state-changing requests.
+
+**Unexpected time-limit response**
+
+Inspect the raw result of ``get_time_limits(child_name)``. The parser in
+``get_max_screentime`` expects ``periodConfigurations`` with a matching
+``DayOfWeek`` entry and an integer ``ALL`` value.
+
+Limitations and disclaimer
+--------------------------
+
+This is an unofficial client built from browser network captures. It is not
+an Amazon-supported SDK, and the endpoints are not guaranteed to remain
+available or compatible. The client does not currently discover child IDs,
+guarantee session renewal, or verify whether setting bonus time is additive.
+Use it only with an account and devices you are authorized to manage, and
+verify changes in the Parent Dashboard.

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.rst
+setup.py
+amazon_parent_dashboard/__init__.py
+amazon_parent_dashboard.egg-info/PKG-INFO
+amazon_parent_dashboard.egg-info/SOURCES.txt
+amazon_parent_dashboard.egg-info/dependency_links.txt
+amazon_parent_dashboard.egg-info/requires.txt
+amazon_parent_dashboard.egg-info/top_level.txt

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests
+pytz

amazon_parent_dashboard-1.0.0/amazon_parent_dashboard.egg-info/top_level.txt

@@ -0,0 +1 @@
+amazon_parent_dashboard

amazon_parent_dashboard-1.0.0/setup.cfg

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

amazon_parent_dashboard-1.0.0/setup.py

@@ -0,0 +1,30 @@
+from os import path
+
+from setuptools import setup
+
+this_directory = path.abspath(path.dirname(__file__))
+with open(path.join(this_directory, 'README.rst'), encoding='utf-8') as f:
+    long_description = f.read()
+
+packages = ['amazon_parent_dashboard']
+
+setup(
+    name="amazon_parent_dashboard",
+    version="1.0.0",  # works on my machine
+    packages=packages,
+    install_requires=[
+        "requests",
+        'pytz'
+    ],
+    author="Grant miller",
+    author_email="grant@grant-miller.com",
+    description="A simple interface to add bonus time to your Amazon Parent Dashboard devices",
+    long_description=long_description,
+    long_description_content_type="text/x-rst",
+    license="PSF",
+    keywords="grant miller familylink bonus time",
+    url="https://github.com/GrantGMiller/amazon_parent_dashboard",  # project home page, if any
+    project_urls={
+        "Source Code": "https://github.com/GrantGMiller/amazon_parent_dashboard",
+    },
+)