Task 37d5e806: API client module for the integration (Feature 18) (#166)

custom_components/nestquest/api_client.py

@@ -0,0 +1,283 @@
+"""Panel-plane API client for the NestQuest integration (Feature 18).
+
+The integration talks to the NestQuest API service (Feature 16) over
+HTTP instead of reading the database: this module is the ONE place that
+speaks the API's panel plane — ``GET /api/v1/panel/snapshot`` (today's
+household snapshot) and ``POST /api/v1/panel/instances/{id}/complete``
+(completion as the tapped child profile) — authenticated with the
+static panel service token as a Bearer credential on every request.
+
+Transport-injected by construction: the constructor takes the base URL,
+the panel token, and the HTTP session to use.  The session speaks the
+aiohttp ``ClientSession`` surface (``request(method, url, headers=...,
+json=...)`` returning an async context manager whose response carries
+``status`` and ``await text()``), so tests stub the transport with NO
+network and NO aiohttp installed; production builds the client through
+:func:`client_from_entry`, which hands in Home Assistant's shared
+aiohttp session (``homeassistant.helpers.aiohttp_client
+.async_get_clientsession``).  The module itself imports NEITHER
+homeassistant NOR aiohttp at runtime (aiohttp appears only behind
+``TYPE_CHECKING`` for annotations), so the client is usable anywhere —
+the HA coupling lives in the one production factory.
+
+Every failure is typed: a transport failure (connection refused, DNS
+failure, timeout — the exchange never produced a response) and every
+non-2xx HTTP response raise :class:`NestQuestApiError`.  The error
+carries the HTTP status where there is one (so 401 and 404 are
+distinguishable at the call site) and ``None`` when there is not; the
+original transport error is chained as ``__cause__`` — nothing is
+swallowed.  There are NO retries and the client logs nothing: refresh
+cadence is the coordinator's concern (the next task), and the panel
+token is a secret that must never reach a log line or an error
+message — the error texts name the method, path, and status only.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import TYPE_CHECKING, Any
+from urllib.parse import urlparse
+
+from .const import (
+    CONF_API_BASE_URL,
+    CONF_PANEL_TOKEN,
+    DEFAULT_API_BASE_URL,
+    DEFAULT_PANEL_TOKEN,
+)
+
+if TYPE_CHECKING:
+    import aiohttp
+
+__all__ = [
+    "COMPLETE_INSTANCE_PATH",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "NestQuestApiError",
+    "NestQuestApiClient",
+    "SNAPSHOT_PATH",
+    "client_from_entry",
+    "is_valid_base_url",
+    "resolve_api_config",
+]
+
+#: The panel plane's snapshot route (Feature 16).
+SNAPSHOT_PATH = "/api/v1/panel/snapshot"
+
+#: The panel plane's completion route template (Feature 16); the
+#: ``{instance_id}`` placeholder is filled per call.
+COMPLETE_INSTANCE_PATH = "/api/v1/panel/instances/{instance_id}/complete"
+
+#: Request timeout, in seconds.  One attempt, one timeout: a hung API
+#: call surfaces as a typed error for the coordinator to report, never
+#: a retry loop.
+DEFAULT_TIMEOUT_SECONDS = 10.0
+
+
+class NestQuestApiError(Exception):
+    """A failed NestQuest API exchange, raised for every failure mode.
+
+    ``status`` carries the HTTP status when a response arrived (a
+    non-2xx response — 401 for a bad token, 404 for an unknown
+    instance) and is ``None`` when the exchange failed at the transport
+    level (connection refused, DNS failure, timeout) — so callers
+    distinguish the two with ``is_transport_error``.  The original
+    transport error, where there is one, is chained as ``__cause__``.
+    Messages carry the method, path, and status — never the request
+    headers, so the panel token can never leak through an error.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+    @property
+    def is_transport_error(self) -> bool:
+        """True when the exchange failed before any response arrived."""
+        return self.status is None
+
+
+def is_valid_base_url(value: object) -> bool:
+    """Return True when ``value`` is a usable API base URL.
+
+    A full ``http://`` or ``https://`` URL with a host — the exact
+    shape the options flow validates (form ergonomics) and the client
+    constructor enforces (fail fast, never build requests against a
+    scheme-less or host-less string).
+    """
+    if not isinstance(value, str):
+        return False
+    candidate = value.strip()
+    if not candidate:
+        return False
+    parsed = urlparse(candidate)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+
+
+def resolve_api_config(entry: Any) -> tuple[str, str]:
+    """Resolve ``(base_url, panel_token)`` off a config entry.
+
+    Precedence mirrors the options flow's stored-values resolution:
+    ``entry.options`` first (the live options-flow copy), then
+    ``entry.data`` (the config-flow-era copy), then the const defaults.
+    The token is a secret: callers must never log the returned pair.
+    """
+    options = getattr(entry, "options", None) or {}
+    data = getattr(entry, "data", None) or {}
+
+    def _pick(key: str, default: str) -> str:
+        if key in options:
+            return options[key]
+        if key in data:
+            return data[key]
+        return default
+
+    return (
+        _pick(CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+        _pick(CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
+    )
+
+
+def client_from_entry(hass: Any, entry: Any) -> NestQuestApiClient:
+    """Build the production client for a config entry.
+
+    Reads the configured base URL and panel token off the entry
+    (:func:`resolve_api_config`) and hands the client Home Assistant's
+    SHARED aiohttp session (``homeassistant.helpers.aiohttp_client
+    .async_get_clientsession``) so panel calls ride HA's one connection
+    pool.  The helper import is deferred into this function on purpose:
+    the test harness is mock-only and the module must import (and the
+    client must be stub-transport testable) without homeassistant or
+    aiohttp installed.
+    """
+    from homeassistant.helpers.aiohttp_client import async_get_clientsession
+
+    base_url, panel_token = resolve_api_config(entry)
+    return NestQuestApiClient(
+        base_url, panel_token, async_get_clientsession(hass)
+    )
+
+
+class NestQuestApiClient:
+    """Async client for the NestQuest API service's panel plane.
+
+    ONE instance per config entry (the coordinator task wires it into
+    the refresh cycle).  The client is deliberately thin: it adds the
+    Bearer credential and the base URL, enforces one timeout per
+    request, and turns every failure into :class:`NestQuestApiError` —
+    no business logic, no retries, no caching.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        panel_token: str,
+        session: aiohttp.ClientSession,
+        *,
+        timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        """Store the connection settings; the session is injected.
+
+        ``session`` is an aiohttp ``ClientSession`` in production and a
+        stub transport in tests.  ``base_url`` must be a full http(s)
+        URL and ``panel_token`` must be non-empty — a client built
+        without either can only fail later at request time with a
+        less-explicable error, so construction fails fast instead.
+        """
+        if not is_valid_base_url(base_url):
+            raise ValueError(
+                f"base_url must be a full http(s) URL, got {base_url!r}"
+            )
+        if not isinstance(panel_token, str) or not panel_token.strip():
+            raise ValueError("panel_token must be a non-empty string")
+        if (
+            not isinstance(timeout_seconds, (int, float))
+            or isinstance(timeout_seconds, bool)
+            or timeout_seconds <= 0
+        ):
+            raise ValueError(
+                f"timeout_seconds must be a positive number, got {timeout_seconds!r}"
+            )
+        self._base_url = base_url.strip().rstrip("/")
+        self._panel_token = panel_token
+        self._session = session
+        self._timeout_seconds = float(timeout_seconds)
+
+    async def get_snapshot(self) -> dict[str, Any]:
+        """Fetch and parse today's household snapshot.
+
+        Returns the JSON the snapshot route returns (``today_iso``,
+        ``cycle_day``, and the per-child list — see
+        ``api/routes_panel.py`` for the documented shape).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response.
+        """
+        return await self._request_json("GET", SNAPSHOT_PATH)
+
+    async def complete_instance(
+        self, instance_id: int, actor_child_id: int
+    ) -> dict[str, Any]:
+        """Complete one quest instance as the tapped child profile.
+
+        POSTs ``{"actor_child_id": actor_child_id}`` to the complete
+        route and returns the parsed response body (the route answers
+        ``{"status": ...}`` both for a first completion and for an
+        idempotent repeat, so a retried panel tap succeeds).  Raises
+        :class:`NestQuestApiError` on transport failure, timeout, or a
+        non-2xx response — 401 for a wrong token, 404 for an unknown
+        instance.
+        """
+        path = COMPLETE_INSTANCE_PATH.format(instance_id=instance_id)
+        return await self._request_json(
+            "POST", path, json_body={"actor_child_id": actor_child_id}
+        )
+
+    async def _request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> Any:
+        """Run ONE request and return the parsed JSON body.
+
+        The Bearer token rides the Authorization header only.  A
+        non-2xx response raises :class:`NestQuestApiError` with its
+        status; anything the transport raises (connection, timeout) is
+        wrapped as a transport-level :class:`NestQuestApiError` with
+        the original error chained — never swallowed, never retried.
+        A 2xx body that is not valid JSON is a protocol failure and
+        raises typed too, carrying the status it arrived with.
+        """
+        url = f"{self._base_url}{path}"
+        headers = {"Authorization": f"Bearer {self._panel_token}"}
+        try:
+            async with asyncio.timeout(self._timeout_seconds):
+                async with self._session.request(
+                    method, url, headers=headers, json=json_body
+                ) as response:
+                    status = response.status
+                    if not 200 <= status < 300:
+                        raise NestQuestApiError(
+                            f"NestQuest API {method} {path} failed with "
+                            f"HTTP {status}",
+                            status=status,
+                        )
+                    body_text = await response.text()
+        except asyncio.CancelledError:
+            # Cancellation is never converted: a shutting-down event
+            # loop must stop, not read a synthesized API error.
+            raise
+        except NestQuestApiError:
+            raise
+        except Exception as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} transport failure: {err}",
+                status=None,
+            ) from err
+        try:
+            return json.loads(body_text)
+        except ValueError as err:
+            raise NestQuestApiError(
+                f"NestQuest API {method} {path} returned malformed "
+                f"JSON: {err}",
+                status=status,
+            ) from err

custom_components/nestquest/core/const.py

@@ -101,6 +101,32 @@ CONF_END_OF_DAY_REPORT_ENABLED = "end_of_day_report_enabled"
 CONF_CELEBRATION_ENABLED = "celebration_enabled"
 DEFAULT_AUTOMATION_ENABLED = True
 
+# Panel-plane API client (Feature 18): the integration reaches the
+# NestQuest API service (Feature 16) over HTTP instead of the database.
+# The base URL points at the API service host serving ``/api/v1/panel/*``
+# (uvicorn's default host/port is the sensible starting point); the panel
+# service token is the static Bearer credential the panel plane requires
+# (``NESTQUEST_PANEL_TOKEN`` on the API side).  Both are stored on the
+# entry like every other setting — options first, then the entry-data
+# copy, then defaults.  The TOKEN IS A SECRET: it is never logged, never
+# echoed into error messages, and never committed.  The shipped default
+# token IS the empty string (DEFAULT_PANEL_TOKEN) — an entry with no
+# configured token is therefore NOT a working client: the options flow
+# accepts an empty token as "not configured yet" and only rejects
+# malformed (padded/whitespace-only/non-string) values — the actual
+# non-emptiness guard is enforced at client construction, where
+# NestQuestApiClient fails fast on an empty/whitespace token
+# (api_client.py).  So a caller building the client from a bare
+# entry must either ensure a token is configured first or handle the
+# construction ValueError and surface an "API not configured" state —
+# an unconfigured entry never yields a client that can only 401.
+# This mirrors the API service's fail-closed stance (api/config.py: no
+# default token exists).
+CONF_API_BASE_URL = "api_base_url"
+DEFAULT_API_BASE_URL = "http://127.0.0.1:8000"
+CONF_PANEL_TOKEN = "panel_token"
+DEFAULT_PANEL_TOKEN = ""
+
 # Quest windows (D-008): a definition may declare several day windows;
 # each produces its own instance per day and groups the panel's Quest
 # Log into three columns.  The clock ranges are stored here so they stay

custom_components/nestquest/options_flow.py

@@ -12,6 +12,7 @@ from .const import (
     CONF_ADMIN_USER_IDS,
     CONF_AFTERNOON_REMINDER_ENABLED,
     CONF_AFTERNOON_REMINDER_TIME,
+    CONF_API_BASE_URL,
     CONF_CELEBRATION_ENABLED,
     CONF_DAY_ROLLOVER_TIME,
     CONF_END_OF_DAY_REPORT_ENABLED,
@@ -21,7 +22,9 @@ from .const import (
     CONF_MORNING_SUMMARY_TIME,
     CONF_NOTIFY_TARGET,
     CONF_PANEL_IDLE_TIMEOUT,
+    CONF_PANEL_TOKEN,
     CONF_UPDATE_INTERVAL,
+    DEFAULT_API_BASE_URL,
     DEFAULT_AFTERNOON_REMINDER_TIME,
     DEFAULT_AUTOMATION_ENABLED,
     DEFAULT_DAY_ROLLOVER_TIME,
@@ -29,12 +32,14 @@ from .const import (
     DEFAULT_HORIZON_DAYS,
     DEFAULT_MORNING_SUMMARY_TIME,
     DEFAULT_PANEL_IDLE_TIMEOUT,
+    DEFAULT_PANEL_TOKEN,
     DEFAULT_UPDATE_INTERVAL,
     DOMAIN,
     MIN_UPDATE_INTERVAL,
     TIME_PATTERN,
 )
 from .admin_allowlist import list_admin_ids, set_admin_ids
+from .api_client import is_valid_base_url
 
 MIN_HORIZON_DAYS = 1
 MIN_PANEL_IDLE_TIMEOUT = 30
@@ -116,6 +121,25 @@ def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
         if toggle_value is not None and not isinstance(toggle_value, bool):
             errors[toggle_key] = "invalid"
 
+    # The panel-plane API connection (Feature 18) is OPTIONAL in raw
+    # submits the same way: a missing key keeps the current value.  The
+    # base URL must be a full http(s) URL with a host — the same check
+    # the client's constructor enforces, so a malformed URL fails at
+    # the form, not at the first request.  The token may be EMPTY (the
+    # API connection is simply not configured yet) but a non-empty one
+    # must be pasted unpadded: a padded or whitespace-only value is a
+    # clipboard mistake that would fail the token check at request
+    # time.
+    api_base_url = user_input.get(CONF_API_BASE_URL)
+    if api_base_url is not None and not is_valid_base_url(api_base_url):
+        errors[CONF_API_BASE_URL] = "invalid_url"
+    panel_token = user_input.get(CONF_PANEL_TOKEN)
+    if panel_token is not None and (
+        not isinstance(panel_token, str)
+        or panel_token != panel_token.strip()
+    ):
+        errors[CONF_PANEL_TOKEN] = "invalid"
+
     return errors
 
 
@@ -186,6 +210,18 @@ def _build_schema(
             CONF_CELEBRATION_ENABLED,
             default=current[CONF_CELEBRATION_ENABLED],
         ): _strict_bool,
+        # Panel-plane API connection (Feature 18): the base URL the API
+        # client talks to and the panel service token it presents as
+        # the Bearer credential.  Schema-validated submits always carry
+        # both (the defaults pre-fill from the stored values); raw
+        # callers omitting them keep their stored values (see
+        # _async_validate).
+        vol.Required(
+            CONF_API_BASE_URL, default=current[CONF_API_BASE_URL]
+        ): str,
+        vol.Required(
+            CONF_PANEL_TOKEN, default=current[CONF_PANEL_TOKEN]
+        ): str,
     }
     if admin_choices is not None:
         # HA's supported multi-select validator: the frontend can
@@ -336,6 +372,11 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
             data[notification_key] = user_input.get(
                 notification_key, current[notification_key]
             )
+        # The API connection section (Feature 18) stores the base URL
+        # and panel token the same fall-back-to-current way, so raw
+        # submits that predate the section keep their stored values.
+        for api_key in (CONF_API_BASE_URL, CONF_PANEL_TOKEN):
+            data[api_key] = user_input.get(api_key, current[api_key])
         if admin_ids_present:
             data[CONF_ADMIN_USER_IDS] = admin_ids
         elif admin_default:
@@ -365,6 +406,8 @@ class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
             (CONF_AFTERNOON_REMINDER_ENABLED, DEFAULT_AUTOMATION_ENABLED),
             (CONF_END_OF_DAY_REPORT_ENABLED, DEFAULT_AUTOMATION_ENABLED),
             (CONF_CELEBRATION_ENABLED, DEFAULT_AUTOMATION_ENABLED),
+            (CONF_API_BASE_URL, DEFAULT_API_BASE_URL),
+            (CONF_PANEL_TOKEN, DEFAULT_PANEL_TOKEN),
         ):
             if key in options:
                 values[key] = options[key]

custom_components/nestquest/strings.json

@@ -18,11 +18,13 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how NestQuest plans, rolls over days, idles its panel, and reaches the NestQuest API service.",
         "data": {
           "horizon_days": "Generation horizon (days)",
           "day_rollover_time": "Day rollover time (HH:MM)",
           "panel_idle_timeout": "Panel idle timeout (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token",
           "admin_user_ids": "Admin users (parents)"
         }
       }
@@ -30,6 +32,7 @@
     "errors": {
       "invalid": "Invalid value.",
       "invalid_time": "Time must use 24-hour HH:MM format.",
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
       "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.",
       "invalid_admin": "Invalid admin selection."
     }

custom_components/nestquest/translations/en.json

@@ -18,11 +18,13 @@
     "step": {
       "init": {
         "title": "NestQuest Settings",
-        "description": "Adjust how NestQuest plans, rolls over days, and idles its panel.",
+        "description": "Adjust how NestQuest plans, rolls over days, idles its panel, and reaches the NestQuest API service.",
         "data": {
           "horizon_days": "Generation horizon (days)",
           "day_rollover_time": "Day rollover time (HH:MM)",
           "panel_idle_timeout": "Panel idle timeout (seconds)",
+          "api_base_url": "NestQuest API base URL (http://host:port)",
+          "panel_token": "Panel service token",
           "admin_user_ids": "Admin users (parents)"
         }
       }
@@ -30,6 +32,7 @@
     "errors": {
       "invalid": "Invalid value.",
       "invalid_time": "Time must use 24-hour HH:MM format.",
+      "invalid_url": "Enter the API base URL as a full http:// or https:// URL with a host.",
       "no_admins": "Select at least one admin user; an empty allowlist would lock everyone out.",
       "invalid_admin": "Invalid admin selection."
     }