overseer
2b6b7431b5
The integration will consume the NestQuest API service (Feature 16) over HTTP instead of reading the database. This adds the one module that speaks the panel plane: api_client.py with get_snapshot() and complete_instance(), a typed NestQuestApiError for transport failures and non-2xx responses (carrying the HTTP status so 401/404 are distinguishable), one timeout per request and no retry loops. The HTTP session is injected, so tests exercise the client against a stub transport with no network and no aiohttp; the production factory hands in HA's shared aiohttp session and resolves the base URL and panel service token off the config entry (options, then entry data, then defaults). The two new settings are wired into the options flow like every other section (validation mirrored with the client's constructor rules); the token is a secret and is never logged or echoed into error messages. Coordinator wiring is the next task.
418 lines
17 KiB
Python
418 lines
17 KiB
Python
"""Options flow for NestQuest post-setup settings."""
|
|
from __future__ import annotations
|
|
|
|
from typing import Any
|
|
|
|
import voluptuous as vol
|
|
from homeassistant import config_entries
|
|
from homeassistant.data_entry_flow import FlowResult
|
|
from homeassistant.helpers import config_validation as cv
|
|
|
|
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,
|
|
CONF_END_OF_DAY_REPORT_TIME,
|
|
CONF_HORIZON_DAYS,
|
|
CONF_MORNING_SUMMARY_ENABLED,
|
|
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,
|
|
DEFAULT_END_OF_DAY_REPORT_TIME,
|
|
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
|
|
|
|
|
|
def _parse_time(value: str) -> bool:
|
|
"""Return True when value is a valid 24-hour HH:MM string."""
|
|
return TIME_PATTERN.fullmatch(value) is not None
|
|
|
|
|
|
def _async_validate(user_input: dict[str, Any]) -> dict[str, str]:
|
|
"""Validate user input and return field-level errors instead of raising."""
|
|
errors: dict[str, str] = {}
|
|
|
|
horizon_days = user_input.get(CONF_HORIZON_DAYS)
|
|
if (
|
|
isinstance(horizon_days, bool)
|
|
or not isinstance(horizon_days, int)
|
|
or horizon_days < MIN_HORIZON_DAYS
|
|
):
|
|
errors[CONF_HORIZON_DAYS] = "invalid"
|
|
|
|
day_rollover_time = user_input.get(CONF_DAY_ROLLOVER_TIME)
|
|
if not isinstance(day_rollover_time, str) or not _parse_time(day_rollover_time):
|
|
errors[CONF_DAY_ROLLOVER_TIME] = "invalid_time"
|
|
|
|
panel_idle_timeout = user_input.get(CONF_PANEL_IDLE_TIMEOUT)
|
|
if (
|
|
isinstance(panel_idle_timeout, bool)
|
|
or not isinstance(panel_idle_timeout, int)
|
|
or panel_idle_timeout < MIN_PANEL_IDLE_TIMEOUT
|
|
):
|
|
errors[CONF_PANEL_IDLE_TIMEOUT] = "invalid"
|
|
|
|
# The coordinator refresh interval (Feature 10) is OPTIONAL in raw
|
|
# submits: a missing key keeps the current value, so pre-Feature-10
|
|
# form payloads (and API callers) are unaffected. Schema-validated
|
|
# submits always carry it.
|
|
update_interval = user_input.get(CONF_UPDATE_INTERVAL)
|
|
if update_interval is not None and (
|
|
isinstance(update_interval, bool)
|
|
or not isinstance(update_interval, int)
|
|
or update_interval < MIN_UPDATE_INTERVAL
|
|
):
|
|
errors[CONF_UPDATE_INTERVAL] = "invalid"
|
|
|
|
# The notification section (Feature 11) is OPTIONAL in raw submits
|
|
# the same way: a missing key keeps the current value. The three
|
|
# times are strict HH:MM; the notify target is a non-empty HA
|
|
# service name; the toggles are real booleans.
|
|
for time_key in (
|
|
CONF_MORNING_SUMMARY_TIME,
|
|
CONF_AFTERNOON_REMINDER_TIME,
|
|
CONF_END_OF_DAY_REPORT_TIME,
|
|
):
|
|
time_value = user_input.get(time_key)
|
|
if time_value is not None and (
|
|
not isinstance(time_value, str) or not _parse_time(time_value)
|
|
):
|
|
errors[time_key] = "invalid_time"
|
|
notify_target = user_input.get(CONF_NOTIFY_TARGET)
|
|
if notify_target is not None and not isinstance(notify_target, str):
|
|
errors[CONF_NOTIFY_TARGET] = "invalid"
|
|
elif isinstance(notify_target, str) and notify_target != (
|
|
notify_target.strip()
|
|
):
|
|
# An EMPTY target is valid — it means "no notifications
|
|
# configured yet" and is the shipped default; a value that
|
|
# differs from its own trim (padded or whitespace-only) is
|
|
# malformed and rejected.
|
|
errors[CONF_NOTIFY_TARGET] = "invalid"
|
|
for toggle_key in (
|
|
CONF_MORNING_SUMMARY_ENABLED,
|
|
CONF_AFTERNOON_REMINDER_ENABLED,
|
|
CONF_END_OF_DAY_REPORT_ENABLED,
|
|
CONF_CELEBRATION_ENABLED,
|
|
):
|
|
toggle_value = user_input.get(toggle_key)
|
|
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
|
|
|
|
|
|
def _strict_bool(value: object) -> bool:
|
|
"""Require a real bool; voluptuous ``bool`` would coerce strings."""
|
|
if not isinstance(value, bool):
|
|
raise vol.Invalid(f"expected a boolean, got {value!r}")
|
|
return value
|
|
|
|
|
|
def _build_schema(
|
|
current: dict[str, Any],
|
|
*,
|
|
admin_choices: dict[str, str] | None = None,
|
|
admin_default: list[str] | None = None,
|
|
) -> vol.Schema:
|
|
"""Build the form schema, pre-filled with the current values.
|
|
|
|
The admin picker is a multi-select of EXISTING Home Assistant users
|
|
(never a free-text field — the allowlist stores user IDs); its
|
|
default is the current database allowlist, so an untouched submit
|
|
re-saves exactly who is already allowed. The notification section
|
|
(Feature 11) carries the household's notify target, the three
|
|
automation times, and four enable toggles — defaults from
|
|
:mod:`~.const`, never a hard-coded personal target.
|
|
"""
|
|
fields: dict[Any, Any] = {
|
|
vol.Required(
|
|
CONF_HORIZON_DAYS, default=current[CONF_HORIZON_DAYS]
|
|
): int,
|
|
vol.Required(
|
|
CONF_DAY_ROLLOVER_TIME, default=current[CONF_DAY_ROLLOVER_TIME]
|
|
): str,
|
|
vol.Required(
|
|
CONF_PANEL_IDLE_TIMEOUT, default=current[CONF_PANEL_IDLE_TIMEOUT]
|
|
): int,
|
|
vol.Required(
|
|
CONF_UPDATE_INTERVAL, default=current[CONF_UPDATE_INTERVAL]
|
|
): int,
|
|
vol.Required(
|
|
CONF_NOTIFY_TARGET, default=current[CONF_NOTIFY_TARGET]
|
|
): str,
|
|
vol.Required(
|
|
CONF_MORNING_SUMMARY_TIME,
|
|
default=current[CONF_MORNING_SUMMARY_TIME],
|
|
): str,
|
|
vol.Required(
|
|
CONF_AFTERNOON_REMINDER_TIME,
|
|
default=current[CONF_AFTERNOON_REMINDER_TIME],
|
|
): str,
|
|
vol.Required(
|
|
CONF_END_OF_DAY_REPORT_TIME,
|
|
default=current[CONF_END_OF_DAY_REPORT_TIME],
|
|
): str,
|
|
vol.Required(
|
|
CONF_MORNING_SUMMARY_ENABLED,
|
|
default=current[CONF_MORNING_SUMMARY_ENABLED],
|
|
): _strict_bool,
|
|
vol.Required(
|
|
CONF_AFTERNOON_REMINDER_ENABLED,
|
|
default=current[CONF_AFTERNOON_REMINDER_ENABLED],
|
|
): _strict_bool,
|
|
vol.Required(
|
|
CONF_END_OF_DAY_REPORT_ENABLED,
|
|
default=current[CONF_END_OF_DAY_REPORT_ENABLED],
|
|
): _strict_bool,
|
|
vol.Required(
|
|
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
|
|
# serialize the field as a real picker of the given choices.
|
|
fields[
|
|
vol.Optional(
|
|
CONF_ADMIN_USER_IDS, default=list(admin_default or [])
|
|
)
|
|
] = cv.multi_select(admin_choices)
|
|
return vol.Schema(fields)
|
|
|
|
|
|
class NestQuestOptionsFlow(config_entries.OptionsFlowWithConfigEntry):
|
|
"""Handle the options flow for NestQuest."""
|
|
|
|
def _async_database(self):
|
|
"""Return the runtime database for this entry, or None.
|
|
|
|
Real HA only opens the options flow for an existing entry, so
|
|
the runtime record (and its database) exists; the None branch
|
|
covers direct construction in tests and degraded states.
|
|
"""
|
|
hass_data = getattr(self.hass, "data", None)
|
|
if not isinstance(hass_data, dict):
|
|
return None
|
|
record = hass_data.get(DOMAIN, {}).get(self.config_entry.entry_id)
|
|
database = getattr(record, "database", None)
|
|
return database if getattr(database, "connected", False) else None
|
|
|
|
async def _async_admin_choices(self) -> dict[str, str]:
|
|
"""Map HA user id -> display name for the picker.
|
|
|
|
Real Home Assistant always provides ``hass.auth``; a missing
|
|
one (direct construction in tests, degraded harness) degrades
|
|
to an empty picker rather than crashing the form.
|
|
"""
|
|
auth = getattr(self.hass, "auth", None)
|
|
if auth is None:
|
|
return {}
|
|
users = await auth.async_get_users()
|
|
return {
|
|
user.id: user.name
|
|
for user in users
|
|
if getattr(user, "id", None)
|
|
}
|
|
|
|
async def _async_current_admin_ids(self) -> list[str]:
|
|
"""Return the current allowlist, or [] without a database."""
|
|
database = self._async_database()
|
|
if database is None:
|
|
return []
|
|
return await list_admin_ids(database)
|
|
|
|
async def async_step_init(
|
|
self, user_input: dict[str, Any] | None = None
|
|
) -> FlowResult:
|
|
"""Manage the NestQuest options."""
|
|
admin_choices = await self._async_admin_choices()
|
|
admin_default = await self._async_current_admin_ids()
|
|
if user_input is None:
|
|
return self.async_show_form(
|
|
step_id="init",
|
|
data_schema=_build_schema(
|
|
self._current_values(),
|
|
admin_choices=admin_choices,
|
|
admin_default=admin_default,
|
|
),
|
|
)
|
|
|
|
errors = _async_validate(user_input)
|
|
# The admin ids are validated only when the key is present:
|
|
# schema-validated submits always carry it (vol.Optional's
|
|
# default fills from the current allowlist), while raw callers
|
|
# omitting the key keep the field untouched.
|
|
admin_ids_present = CONF_ADMIN_USER_IDS in user_input
|
|
admin_ids = user_input.get(CONF_ADMIN_USER_IDS)
|
|
if errors:
|
|
return self.async_show_form(
|
|
step_id="init",
|
|
data_schema=_build_schema(
|
|
self._current_values(),
|
|
admin_choices=admin_choices,
|
|
admin_default=admin_default,
|
|
),
|
|
errors=errors,
|
|
)
|
|
if admin_ids_present and (
|
|
not isinstance(admin_ids, list)
|
|
or any(not isinstance(value, str) for value in admin_ids)
|
|
):
|
|
errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
|
|
elif admin_ids_present and not admin_ids:
|
|
# An empty allowlist fails closed: saving zero admins is
|
|
# refused, never silently applied.
|
|
errors[CONF_ADMIN_USER_IDS] = "no_admins"
|
|
elif admin_ids_present and any(
|
|
value not in admin_choices for value in admin_ids
|
|
):
|
|
# The schema enforces membership for real HA submits; this
|
|
# backs the raw-input path up so an unknown id can never
|
|
# reach the allowlist.
|
|
errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
|
|
elif admin_ids_present and len(set(admin_ids)) != len(admin_ids):
|
|
# set_admin_ids refuses duplicates with ValueError; a flow
|
|
# submission must surface that as a field error instead of
|
|
# an unhandled crash.
|
|
errors[CONF_ADMIN_USER_IDS] = "invalid_admin"
|
|
if errors:
|
|
return self.async_show_form(
|
|
step_id="init",
|
|
data_schema=_build_schema(
|
|
self._current_values(),
|
|
admin_choices=admin_choices,
|
|
admin_default=admin_default,
|
|
),
|
|
errors=errors,
|
|
)
|
|
|
|
# Apply the picker's selection to the allowlist when the
|
|
# runtime database is reachable; the selection is always
|
|
# stored on the entry as the disaster-recovery copy.
|
|
database = self._async_database()
|
|
if database is not None and admin_ids_present:
|
|
await set_admin_ids(database, admin_ids)
|
|
data = {
|
|
CONF_HORIZON_DAYS: user_input[CONF_HORIZON_DAYS],
|
|
CONF_DAY_ROLLOVER_TIME: user_input[CONF_DAY_ROLLOVER_TIME],
|
|
CONF_PANEL_IDLE_TIMEOUT: user_input[CONF_PANEL_IDLE_TIMEOUT],
|
|
CONF_UPDATE_INTERVAL: user_input.get(
|
|
CONF_UPDATE_INTERVAL,
|
|
self._current_values()[CONF_UPDATE_INTERVAL],
|
|
),
|
|
}
|
|
# The notification section (Feature 11) stores the household's
|
|
# choices the same fall-back-to-current way, so raw submits
|
|
# that predate the section keep their stored values.
|
|
current = self._current_values()
|
|
for notification_key in (
|
|
CONF_NOTIFY_TARGET,
|
|
CONF_MORNING_SUMMARY_TIME,
|
|
CONF_AFTERNOON_REMINDER_TIME,
|
|
CONF_END_OF_DAY_REPORT_TIME,
|
|
CONF_MORNING_SUMMARY_ENABLED,
|
|
CONF_AFTERNOON_REMINDER_ENABLED,
|
|
CONF_END_OF_DAY_REPORT_ENABLED,
|
|
CONF_CELEBRATION_ENABLED,
|
|
):
|
|
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:
|
|
# HA replaces entry.options wholesale, so an omitted picker
|
|
# field must carry the CURRENT allowlist forward: dropping
|
|
# it would leave only the stale config-flow copy in entry
|
|
# data, and a later database loss would resurrect admins
|
|
# the owner has since removed.
|
|
data[CONF_ADMIN_USER_IDS] = list(admin_default)
|
|
return self.async_create_entry(title="NestQuest", data=data)
|
|
|
|
def _current_values(self) -> dict[str, Any]:
|
|
"""Resolve current values from entry options, then entry data, then defaults."""
|
|
options = self.options
|
|
entry_data = getattr(self.config_entry, "data", None) or {}
|
|
values: dict[str, Any] = {}
|
|
for key, default in (
|
|
(CONF_HORIZON_DAYS, DEFAULT_HORIZON_DAYS),
|
|
(CONF_DAY_ROLLOVER_TIME, DEFAULT_DAY_ROLLOVER_TIME),
|
|
(CONF_PANEL_IDLE_TIMEOUT, DEFAULT_PANEL_IDLE_TIMEOUT),
|
|
(CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL),
|
|
(CONF_NOTIFY_TARGET, ""),
|
|
(CONF_MORNING_SUMMARY_TIME, DEFAULT_MORNING_SUMMARY_TIME),
|
|
(CONF_AFTERNOON_REMINDER_TIME, DEFAULT_AFTERNOON_REMINDER_TIME),
|
|
(CONF_END_OF_DAY_REPORT_TIME, DEFAULT_END_OF_DAY_REPORT_TIME),
|
|
(CONF_MORNING_SUMMARY_ENABLED, DEFAULT_AUTOMATION_ENABLED),
|
|
(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]
|
|
elif key in entry_data:
|
|
values[key] = entry_data[key]
|
|
else:
|
|
values[key] = default
|
|
return values |