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 |