Coverage for custom_components/supernotify/config_flow.py: 98%

1"""Config flow for the Supernotify integration. 

2 

3A UI setup path that reproduces examples/minimal.yaml (everything auto-discovered, no required 

4fields), plus options pages for the archive, dupe_check and housekeeping settings, and a 

5subentry per recipient. Delivery, transports, scenarios, scenario_control, cameras, 

6action_groups and snooze stay YAML-only, now 

7under a top-level `supernotify:` key (see CONFIG_SCHEMA/async_setup in __init__.py) rather than 

8the legacy `notify: - platform: supernotify` block - this config entry is the sole, 

9unconditional owner of registering notify.supernotify in every case. 

10""" 

11 

12from __future__ import annotations 

13 

14import logging 

15from typing import TYPE_CHECKING, Any 

16 

17from anyio import Path 

18from homeassistant.config_entries import ( 

19 SOURCE_RECONFIGURE, 

20 ConfigEntry, 

21 ConfigFlow, 

22 ConfigFlowResult, 

23 ConfigSubentryFlow, 

24 OptionsFlow, 

25 SubentryFlowResult, 

26) 

27from homeassistant.const import ( 

28 ATTR_AREA_ID, 

29 ATTR_DEVICE_ID, 

30 ATTR_ENTITY_ID, 

31 ATTR_FLOOR_ID, 

32 ATTR_LABEL_ID, 

33 CONF_ACTION, 

34 CONF_ALIAS, 

35 CONF_DEBUG, 

36 CONF_EMAIL, 

37 CONF_ENABLED, 

38 CONF_HOST, 

39 CONF_NAME, 

40 CONF_PASSWORD, 

41 CONF_PORT, 

42 CONF_TARGET, 

43 CONF_TIMEOUT, 

44 CONF_USERNAME, 

45 CONF_VERIFY_SSL, 

46) 

47from homeassistant.core import callback 

48from homeassistant.data_entry_flow import section 

49from homeassistant.helpers import config_validation as cv 

50from homeassistant.helpers.selector import ( 

51 EntitySelector, 

52 EntitySelectorConfig, 

53 NumberSelector, 

54 NumberSelectorConfig, 

55 NumberSelectorMode, 

56 ObjectSelector, 

57 SelectOptionDict, 

58 SelectSelector, 

59 SelectSelectorConfig, 

60 TargetSelector, 

61 TextSelector, 

62 TextSelectorConfig, 

63 TextSelectorType, 

64) 

65from homeassistant.util import slugify 

66 

67from . import ARCHIVE_DIR, DOMAIN, MEDIA_DIR, TEMPLATE_DIR 

68from .compat import vol 

69from .const import ( 

70 ATTR_CUSTOM_TARGET, 

71 ATTR_DUPE_POLICY_MT, 

72 ATTR_DUPE_POLICY_MTSLP, 

73 ATTR_DUPE_POLICY_NONE, 

74 ATTR_EMAIL, 

75 ATTR_PHONE, 

76 CONF_ARCHIVE, 

77 CONF_ARCHIVE_DAYS, 

78 CONF_ARCHIVE_DIAGNOSTICS, 

79 CONF_ARCHIVE_EVENT_NAME, 

80 CONF_ARCHIVE_EVENT_SELECTION, 

81 CONF_ARCHIVE_MQTT_QOS, 

82 CONF_ARCHIVE_MQTT_RETAIN, 

83 CONF_ARCHIVE_MQTT_TOPIC, 

84 CONF_ARCHIVE_PATH, 

85 CONF_CONNECTION, 

86 CONF_DATA, 

87 CONF_DEFAULT_INCLUSION, 

88 CONF_DELIVERY, 

89 CONF_DELIVERY_CONTROL, 

90 CONF_DELIVERY_DEFAULTS, 

91 CONF_DEPRECATED_ENTITIES, 

92 CONF_DEVICE_DISCOVERY, 

93 CONF_DEVICE_DOMAIN, 

94 CONF_DEVICE_MODEL_EXCLUDE, 

95 CONF_DEVICE_MODEL_INCLUDE, 

96 CONF_DUPE_CHECK, 

97 CONF_DUPE_POLICY, 

98 CONF_ENCRYPTION, 

99 CONF_HOUSEKEEPING, 

100 CONF_HOUSEKEEPING_TIME, 

101 CONF_INCLUSION, 

102 CONF_LLM_ACTION_TOOLS, 

103 CONF_LLM_DIAGNOSTIC_TOOLS, 

104 CONF_LLM_TOOLS, 

105 CONF_LOAD, 

106 CONF_MEDIA_PATH, 

107 CONF_MEDIA_STORAGE_DAYS, 

108 CONF_MEDIA_URL_PREFIX, 

109 CONF_MOBILE_APP_ID, 

110 CONF_MOBILE_DEVICES, 

111 CONF_MOBILE_DISCOVERY, 

112 CONF_OPTIONS, 

113 CONF_PERSON, 

114 CONF_PHONE_NUMBER, 

115 CONF_PRIORITY, 

116 CONF_RECIPIENTS_DISCOVERY, 

117 CONF_SELECTION, 

118 CONF_SENTENCE_COMMANDS, 

119 CONF_SIZE, 

120 CONF_TARGET_USAGE, 

121 CONF_TEMPLATE_PATH, 

122 CONF_TRANSPORT, 

123 CONF_TTL, 

124 CONF_USER_ID, 

125 CONF_VOICE_OCCUPANCY, 

126 DEFAULT_INCLUSION_VALUES, 

127 INCLUSION_VALUES, 

128 OCCUPANCY_VALUES, 

129 PRIORITY_VALUES, 

130 SUBENTRY_TYPE_RECIPIENT, 

131 SUBENTRY_TYPE_TRANSPORT, 

132 TARGET_CATEGORY_VALUES, 

133 TARGET_USAGE_VALUES, 

134 TRANSPORT_GENERIC, 

135 recipient_subentry_title, 

136 transport_subentry_title, 

137) 

138from .hass_api import HomeAssistantAPI 

139from .options import ( 

140 OPTION_DEVICE_DISCOVERY, 

141 OPTION_DEVICE_DOMAIN, 

142 OPTION_DEVICE_MODEL_SELECT, 

143 SELECT_EXCLUDE, 

144 SELECT_INCLUDE, 

145) 

146from .people import PeopleRegistry, recipient_key 

147from .schema import RECIPIENT_DELIVERY_SCHEMA, RECIPIENT_SCHEMA, TRANSPORT_SCHEMA, OutcomeSelection 

148from .target import Target 

149 

150if TYPE_CHECKING: 

151 from .transport import Transport 

152 

153_LOGGER = logging.getLogger(__name__) 

154 

155# the recipient form's collapsible section holding its delivery overrides 

156SECTION_DELIVERY_OVERRIDES = "delivery_overrides" 

157 

158_DUPE_POLICIES = [ATTR_DUPE_POLICY_MTSLP, ATTR_DUPE_POLICY_MT, ATTR_DUPE_POLICY_NONE] 

159 

160# Linked from the options pages that have their own documentation page - the "?" help icon can only 

161# link to the manifest's one documentation URL 

162ARCHIVE_DOCS_URL = "https://supernotify.rhizomatics.org.uk/latest/configuration/archiving/" 

163DUPE_CHECK_DOCS_URL = "https://supernotify.rhizomatics.org.uk/latest/configuration/dupe_detection/" 

164PEOPLE_DOCS_URL = "https://supernotify.rhizomatics.org.uk/latest/configuration/people/" 

165TRANSPORTS_DOCS_URL = "https://supernotify.rhizomatics.org.uk/latest/transports/" 

166# the transport form's field for the delivery defaults it has no field of its own for, and 

167# those it does 

168ATTR_OTHER_DELIVERY_DEFAULTS = "other_delivery_defaults" 

169_TYPED_DELIVERY_DEFAULTS = ( 

170 CONF_DEBUG, 

171 CONF_ACTION, 

172 CONF_TARGET_USAGE, 

173 CONF_OPTIONS, 

174 CONF_DATA, 

175 CONF_INCLUSION, 

176 CONF_PRIORITY, 

177) 

178# the transport form's section for settings seldom changed, and the sections its delivery 

179# defaults are split into 

180SECTION_ADVANCED = "advanced" 

181SECTION_DELIVERY_DEFAULTS_TARGETS = "delivery_defaults_targets" 

182SECTION_DELIVERY_DEFAULTS_ADVANCED = "delivery_defaults_advanced" 

183_DELIVERY_DEFAULTS_SECTIONS = (CONF_DELIVERY_DEFAULTS, SECTION_DELIVERY_DEFAULTS_TARGETS, SECTION_DELIVERY_DEFAULTS_ADVANCED) 

184 

185# The Delivery Control choices meaning "not set", which leave deliveries with their transport's own 

186# default - never stored, the option is left out instead 

187NOT_SET_INCLUSION = "transport" 

188NOT_SET_OCCUPANCY = "not_controlled" 

189 

190 

191def _event_policy_str(value: Any) -> str: # ruff: ignore[any-type] 

192 """Render an OutcomeSelection as the pipe-separated name string parse_event_policy 

193 expects (e.g. "ERROR|DUPE"), whatever form it currently happens to be in. 

194 

195 A YAML-imported archive config already went through ARCHIVE_SCHEMA, which turns 

196 event_selection/diagnostics into OutcomeSelection (IntFlag) instances - stored as a raw 

197 int once round-tripped through config-entry storage. Left unconverted, that raw int would 

198 show up as a bare number in this form instead of the "ERROR"-style text it's meant to be. 

199 """ 

200 if isinstance(value, str): 

201 return value 

202 if isinstance(value, int): 

203 try: 

204 return OutcomeSelection(value).name or "NONE" 

205 except ValueError: 

206 return "NONE" 

207 return str(value) 

208 

209 

210# NONE isn't a real, independently selectable outcome - it's the empty bitmask, and an 

211# always-false no-op check in archive.py (outcome_policy & OutcomeSelection.NONE is always 

212# 0). "No outcomes ticked" already means NONE, so it's excluded from the checkbox list. 

213# Option values are lowercased since HA selector translation keys must match [a-z0-9-_]+ - 

214# the stored/parsed policy strings stay uppercase (OutcomeSelection member names). 

215_OUTCOME_OPTIONS = [flag.name.lower() for flag in OutcomeSelection if flag != OutcomeSelection.NONE and flag.name is not None] 

216 

217 

218def _event_policy_to_list(value: str) -> list[str]: 

219 """Turn a stored OutcomeSelection value into the list of names a multi-select needs.""" 

220 policy_str = _event_policy_str(value) 

221 return [] if policy_str in ("", "NONE") else [part.lower() for part in policy_str.split("|")] 

222 

223 

224def _event_policy_from_list(values: list[str]) -> str: 

225 """Turn a submitted multi-select list back into the pipe-separated string 

226 ARCHIVE_SCHEMA's parse_event_policy expects.""" 

227 return "|".join(value.upper() for value in values) if values else "NONE" 

228 

229 

230def extract_legacy_options(import_data: dict[str, Any]) -> dict[str, Any]: 

231 """Pull the archive/dupe_check/housekeeping option blocks out of a legacy YAML config dict, 

232 normalizing archive's event_selection/diagnostics the same way a fresh entry would. 

233 

234 Shared by async_step_import (fresh entry bootstrap) and repairs.py's migration flow, which 

235 also needs this when merging legacy config into an entry that already exists - e.g. one 

236 auto-bootstrapped blank by async_setup before the interactive repair ever runs (see 

237 repairs.py's async_sync_entry_from_legacy_config). 

238 """ 

239 archive: dict[str, Any] = dict(import_data.get(CONF_ARCHIVE) or {}) 

240 if CONF_ARCHIVE_EVENT_SELECTION in archive: 

241 archive[CONF_ARCHIVE_EVENT_SELECTION] = _event_policy_str(archive[CONF_ARCHIVE_EVENT_SELECTION]) 

242 if CONF_ARCHIVE_DIAGNOSTICS in archive: 

243 archive[CONF_ARCHIVE_DIAGNOSTICS] = _event_policy_str(archive[CONF_ARCHIVE_DIAGNOSTICS]) 

244 

245 housekeeping: dict[str, Any] = dict(import_data.get(CONF_HOUSEKEEPING) or {}) 

246 housekeeping_time = housekeeping.get(CONF_HOUSEKEEPING_TIME) 

247 if housekeeping_time is not None and not isinstance(housekeeping_time, str): 

248 # cv.time on the YAML side already coerced this into a datetime.time 

249 housekeeping[CONF_HOUSEKEEPING_TIME] = housekeeping_time.isoformat() 

250 

251 options: dict[str, Any] = {} 

252 if archive: 

253 options[CONF_ARCHIVE] = archive 

254 if import_data.get(CONF_DUPE_CHECK): 

255 options[CONF_DUPE_CHECK] = import_data[CONF_DUPE_CHECK] 

256 if housekeeping: 

257 options[CONF_HOUSEKEEPING] = housekeeping 

258 return options 

259 

260 

261def extract_legacy_data(import_data: dict[str, Any]) -> dict[str, Any]: 

262 """Pull the template_path/media_path/media_url_prefix/mobile_discovery/recipients_discovery 

263 settings out of a legacy YAML config dict, defaulting anything not set - the same defaults a 

264 fresh entry would get. Deliberately excludes `name`, which repairs.py's 

265 async_sync_entry_from_legacy_config merges in separately (it isn't defaulted the same way). 

266 

267 Shared by async_step_import (fresh entry bootstrap) and repairs.py's migration flow, which 

268 also needs this when merging legacy config into an entry that already exists - e.g. one 

269 auto-bootstrapped blank by async_setup before the interactive repair ever runs (see 

270 repairs.py's async_sync_entry_from_legacy_config). Without this, a "simple" install with 

271 nothing that needs a repair (no delivery/transports/scenarios/etc to move into 

272 supernotify.yaml) would silently keep running on defaults forever, ignoring a customized 

273 template_path/media_path/etc in the legacy block. 

274 """ 

275 return { 

276 CONF_TEMPLATE_PATH: import_data.get(CONF_TEMPLATE_PATH, TEMPLATE_DIR), 

277 CONF_MEDIA_PATH: import_data.get(CONF_MEDIA_PATH, MEDIA_DIR), 

278 CONF_MEDIA_URL_PREFIX: import_data.get(CONF_MEDIA_URL_PREFIX, "/supernotify/media"), 

279 CONF_MOBILE_DISCOVERY: import_data.get(CONF_MOBILE_DISCOVERY, True), 

280 CONF_RECIPIENTS_DISCOVERY: import_data.get(CONF_RECIPIENTS_DISCOVERY, True), 

281 } 

282 

283 

284def _user_schema(defaults: dict[str, Any] | None = None) -> vol.Schema: 

285 # cv.string, not cv.path: cv.path fails voluptuous-serialize schema conversion used by 

286 # the config flow frontend ("Unable to convert schema" / HTTP 500). 

287 defaults = defaults or {} 

288 return vol.Schema({ 

289 # Determines the registered notify.<name> action (slugified) - matches the legacy 

290 # notify platform's `name:` YAML field, which this replaces as the sole source of truth. 

291 vol.Optional(CONF_NAME, default=defaults.get(CONF_NAME, DOMAIN)): cv.string, 

292 vol.Optional(CONF_TEMPLATE_PATH, default=defaults.get(CONF_TEMPLATE_PATH, TEMPLATE_DIR)): cv.string, 

293 vol.Optional(CONF_MEDIA_PATH, default=defaults.get(CONF_MEDIA_PATH, MEDIA_DIR)): cv.string, 

294 vol.Optional(CONF_MEDIA_URL_PREFIX, default=defaults.get(CONF_MEDIA_URL_PREFIX, "/supernotify/media")): cv.string, 

295 vol.Optional(CONF_MOBILE_DISCOVERY, default=defaults.get(CONF_MOBILE_DISCOVERY, True)): cv.boolean, 

296 vol.Optional(CONF_RECIPIENTS_DISCOVERY, default=defaults.get(CONF_RECIPIENTS_DISCOVERY, True)): cv.boolean, 

297 }) 

298 

299 

300async def _ensure_directory_exists(path_str: str) -> str | None: 

301 """Create a directory if it doesn't exist yet, mirroring MediaStorage.initialize()'s own 

302 tolerant runtime behavior (media_grab.py). Returns an error description on a genuine 

303 failure to create/access it, None on success.""" 

304 try: 

305 path = Path(path_str) 

306 if not path.is_absolute(): 

307 path = await path.absolute() 

308 if not await path.exists(): 

309 await path.mkdir(parents=True, exist_ok=True) 

310 except (OSError, ValueError) as err: 

311 return str(err) 

312 return None 

313 

314 

315async def _validate_user_input(user_input: dict[str, Any]) -> dict[str, str]: 

316 """Validate template_path/media_path at config-flow submission time, creating each 

317 directory if it doesn't exist yet. Catching a genuine failure here surfaces a typo'd or 

318 unwritable path immediately in the wizard, instead of leaving the user to discover it 

319 later via a repair issue. A blank value is left untouched - both fields are optional. 

320 """ 

321 errors: dict[str, str] = {} 

322 

323 template_path = user_input.get(CONF_TEMPLATE_PATH) 

324 if template_path: 

325 error = await _ensure_directory_exists(template_path) 

326 if error: 

327 errors[CONF_TEMPLATE_PATH] = "template_path_invalid" 

328 _LOGGER.debug("SUPERNOTIFY Invalid template_path %s: %s", template_path, error) 

329 

330 media_path = user_input.get(CONF_MEDIA_PATH) 

331 if media_path: 

332 error = await _ensure_directory_exists(media_path) 

333 if error: 

334 errors[CONF_MEDIA_PATH] = "media_path_invalid" 

335 _LOGGER.debug("SUPERNOTIFY Invalid media_path %s: %s", media_path, error) 

336 

337 return errors 

338 

339 

340class SupernotifyConfigFlow(ConfigFlow, domain=DOMAIN): 

341 """Handle a Supernotify config flow.""" 

342 

343 VERSION = 1 

344 

345 async def async_step_user(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

346 errors: dict[str, str] = {} 

347 if user_input is not None: 

348 errors = await _validate_user_input(user_input) 

349 if not errors: 

350 return self.async_create_entry(title="Supernotify", data=user_input) 

351 return self.async_show_form(step_id="user", data_schema=_user_schema(user_input), errors=errors) 

352 

353 async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

354 """Let the user change the global settings of an existing entry. 

355 

356 These fields are config-entry *data* (set at initial setup), not options, so HA's 

357 guidance is a reconfigure step rather than the options flow - which instead covers 

358 archive/dupe_check/housekeeping, genuine runtime preferences. 

359 """ 

360 entry = self._get_reconfigure_entry() 

361 errors: dict[str, str] = {} 

362 if user_input is not None: 

363 errors = await _validate_user_input(user_input) 

364 if not errors: 

365 # async_update_and_abort, not async_update_reload_and_abort: async_setup_entry 

366 # registers an update listener, which async_update_entry already fires (and 

367 # reloads via) whenever entry.data changes - calling the "_reload" variant too 

368 # would reload twice and log an HA deprecation warning about the redundancy. 

369 return self.async_update_and_abort(entry, data_updates=user_input) 

370 defaults = user_input if user_input is not None else dict(entry.data) 

371 return self.async_show_form(step_id="reconfigure", data_schema=_user_schema(defaults), errors=errors) 

372 

373 async def async_step_import(self, import_data: dict[str, Any]) -> ConfigFlowResult: 

374 """Bootstrap a config entry, optionally seeded from a legacy YAML config dict. 

375 

376 Two callers: __init__.py's async_setup (a from-scratch install with no entry yet) and 

377 async_reload_yaml_config_and_entries's bootstrap, and repairs.py's migration flow (a 

378 leftover legacy `notify: - platform: supernotify` block, possibly with real 

379 archive/housekeeping/dupe_check/name/template_path/etc already set) - both pass 

380 `data={}` for a genuinely fresh install, or the raw legacy config dict to preserve an 

381 existing installation's settings (notably `name`, which determines the registered 

382 notify.<name> action - see __init__.py's async_setup_entry). 

383 

384 Duplicate-entry protection is the same single_config_entry manifest flag used by the 

385 user step (it covers SOURCE_IMPORT too), so no unique_id bookkeeping is needed here. 

386 """ 

387 data: dict[str, Any] = { 

388 CONF_NAME: import_data.get(CONF_NAME, DOMAIN), 

389 **extract_legacy_data(import_data), 

390 } 

391 

392 options = extract_legacy_options(import_data) 

393 

394 _LOGGER.info( 

395 "SUPERNOTIFY Config entry bootstrapped (data=%s,options=%s)", 

396 ";".join(data.keys()), 

397 ";".join(options.keys()), 

398 ) 

399 return self.async_create_entry(title="Supernotify", data=data, options=options) 

400 

401 @staticmethod 

402 def async_get_options_flow(config_entry: ConfigEntry) -> SupernotifyOptionsFlow: 

403 return SupernotifyOptionsFlow() 

404 

405 @classmethod 

406 @callback 

407 def async_get_supported_subentry_types(cls, config_entry: ConfigEntry) -> dict[str, type[ConfigSubentryFlow]]: 

408 return {SUBENTRY_TYPE_RECIPIENT: RecipientSubentryFlow, SUBENTRY_TYPE_TRANSPORT: TransportSubentryFlow} 

409 

410 

411class SupernotifyOptionsFlow(OptionsFlow): 

412 """Options pages for archive, dupe_check, housekeeping and LLM tools settings.""" 

413 

414 async def async_step_init(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

415 return self.async_show_menu( 

416 step_id="init", menu_options=["archive", "dupe_check", "housekeeping", "delivery_control", "llm_tools"] 

417 ) 

418 

419 async def async_step_archive(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

420 current: dict[str, Any] = self.config_entry.options.get(CONF_ARCHIVE, {}) 

421 if user_input is not None: 

422 file_section = user_input["file"] 

423 mqtt_section = user_input["mqtt"] 

424 event_section = user_input["event"] 

425 processed = { 

426 CONF_ENABLED: user_input[CONF_ENABLED], 

427 CONF_ARCHIVE_PATH: file_section[CONF_ARCHIVE_PATH], 

428 CONF_ARCHIVE_DAYS: file_section[CONF_ARCHIVE_DAYS], 

429 CONF_ARCHIVE_MQTT_TOPIC: mqtt_section[CONF_ARCHIVE_MQTT_TOPIC], 

430 CONF_ARCHIVE_MQTT_QOS: mqtt_section[CONF_ARCHIVE_MQTT_QOS], 

431 CONF_ARCHIVE_MQTT_RETAIN: mqtt_section[CONF_ARCHIVE_MQTT_RETAIN], 

432 CONF_ARCHIVE_EVENT_NAME: event_section[CONF_ARCHIVE_EVENT_NAME], 

433 CONF_ARCHIVE_EVENT_SELECTION: _event_policy_from_list(event_section[CONF_ARCHIVE_EVENT_SELECTION]), 

434 CONF_ARCHIVE_DIAGNOSTICS: _event_policy_from_list(event_section[CONF_ARCHIVE_DIAGNOSTICS]), 

435 } 

436 return self.async_create_entry(title="", data={**self.config_entry.options, CONF_ARCHIVE: processed}) 

437 outcome_selector = SelectSelector( 

438 SelectSelectorConfig(options=_OUTCOME_OPTIONS, multiple=True, translation_key="outcome_selection") 

439 ) 

440 schema = vol.Schema({ 

441 vol.Optional(CONF_ENABLED, default=False): cv.boolean, 

442 # section wrapper keys must be vol.Required, not vol.Optional: with Optional, the 

443 # frontend silently ignores both default and suggested_value for everything inside 

444 # (and for the rest of the form too) - https://github.com/home-assistant/frontend/issues/22419 

445 # No default= here - matches the working pattern in this repo's other integrations 

446 # (autoarm, remote_logger). 

447 vol.Required("file"): section( 

448 vol.Schema({ 

449 # cv.string, not cv.path: cv.path fails voluptuous-serialize schema 

450 # conversion used by the config flow frontend ("Unable to convert 

451 # schema" / HTTP 500). 

452 vol.Optional(CONF_ARCHIVE_PATH, default=ARCHIVE_DIR): cv.string, 

453 vol.Optional(CONF_ARCHIVE_DAYS, default=3): cv.positive_int, 

454 }), 

455 {"collapsed": False}, 

456 ), 

457 vol.Required("mqtt"): section( 

458 vol.Schema({ 

459 vol.Optional(CONF_ARCHIVE_MQTT_TOPIC, default=""): cv.string, 

460 vol.Optional(CONF_ARCHIVE_MQTT_QOS, default=0): cv.positive_int, 

461 vol.Optional(CONF_ARCHIVE_MQTT_RETAIN, default=False): cv.boolean, 

462 }), 

463 {"collapsed": True}, 

464 ), 

465 vol.Required("event"): section( 

466 vol.Schema({ 

467 vol.Optional(CONF_ARCHIVE_EVENT_NAME, default="supernotification"): cv.string, 

468 vol.Optional(CONF_ARCHIVE_EVENT_SELECTION, default=[]): outcome_selector, 

469 vol.Optional(CONF_ARCHIVE_DIAGNOSTICS, default=[]): outcome_selector, 

470 }), 

471 {"collapsed": True}, 

472 ), 

473 }) 

474 # A plain vol.Optional(default=...) only sets the server-side validation fallback - 

475 # once a section is present, the frontend needs description.suggested_value (for 

476 # every field, not just the section-nested ones) to pre-fill an existing entry's 

477 # current values. 

478 suggested_values = { 

479 CONF_ENABLED: current.get(CONF_ENABLED, False), 

480 "file": { 

481 CONF_ARCHIVE_PATH: current.get(CONF_ARCHIVE_PATH, ARCHIVE_DIR), 

482 CONF_ARCHIVE_DAYS: current.get(CONF_ARCHIVE_DAYS, 3), 

483 }, 

484 "mqtt": { 

485 CONF_ARCHIVE_MQTT_TOPIC: current.get(CONF_ARCHIVE_MQTT_TOPIC, ""), 

486 CONF_ARCHIVE_MQTT_QOS: current.get(CONF_ARCHIVE_MQTT_QOS, 0), 

487 CONF_ARCHIVE_MQTT_RETAIN: current.get(CONF_ARCHIVE_MQTT_RETAIN, False), 

488 }, 

489 "event": { 

490 CONF_ARCHIVE_EVENT_NAME: current.get(CONF_ARCHIVE_EVENT_NAME, "supernotification"), 

491 CONF_ARCHIVE_EVENT_SELECTION: _event_policy_to_list(current.get(CONF_ARCHIVE_EVENT_SELECTION, "NONE")), 

492 CONF_ARCHIVE_DIAGNOSTICS: _event_policy_to_list(current.get(CONF_ARCHIVE_DIAGNOSTICS, "ERROR")), 

493 }, 

494 } 

495 schema = self.add_suggested_values_to_schema(schema, suggested_values) 

496 return self.async_show_form( 

497 step_id="archive", data_schema=schema, description_placeholders={"learn_more_url": ARCHIVE_DOCS_URL} 

498 ) 

499 

500 async def async_step_dupe_check(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

501 current: dict[str, Any] = self.config_entry.options.get(CONF_DUPE_CHECK, {}) 

502 if user_input is not None: 

503 return self.async_create_entry(title="", data={**self.config_entry.options, CONF_DUPE_CHECK: user_input}) 

504 schema = vol.Schema({ 

505 vol.Optional(CONF_TTL, default=current.get(CONF_TTL, 120)): cv.positive_int, 

506 vol.Optional(CONF_SIZE, default=current.get(CONF_SIZE, 100)): cv.positive_int, 

507 vol.Optional(CONF_DUPE_POLICY, default=current.get(CONF_DUPE_POLICY, ATTR_DUPE_POLICY_MTSLP)): SelectSelector( 

508 SelectSelectorConfig(options=_DUPE_POLICIES, translation_key="dupe_policy") 

509 ), 

510 }) 

511 return self.async_show_form( 

512 step_id="dupe_check", data_schema=schema, description_placeholders={"learn_more_url": DUPE_CHECK_DOCS_URL} 

513 ) 

514 

515 async def async_step_housekeeping(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

516 current: dict[str, Any] = self.config_entry.options.get(CONF_HOUSEKEEPING, {}) 

517 if user_input is not None: 

518 return self.async_create_entry(title="", data={**self.config_entry.options, CONF_HOUSEKEEPING: user_input}) 

519 housekeeping_time = current.get(CONF_HOUSEKEEPING_TIME, "00:00:01") 

520 if not isinstance(housekeeping_time, str): 

521 # a YAML-imported entry may still have a raw datetime.time from before this was fixed 

522 housekeeping_time = housekeeping_time.isoformat() 

523 schema = vol.Schema({ 

524 vol.Optional(CONF_HOUSEKEEPING_TIME, default=housekeeping_time): cv.string, 

525 vol.Optional(CONF_MEDIA_STORAGE_DAYS, default=current.get(CONF_MEDIA_STORAGE_DAYS, 7)): cv.positive_int, 

526 }) 

527 # only offered while there are some, carried over from an earlier version 

528 from .binary_sensor import deprecated_entity_ids 

529 

530 if deprecated_entity_ids(self.hass, self.config_entry.entry_id): 

531 schema = schema.extend({ 

532 vol.Optional(CONF_DEPRECATED_ENTITIES, default=current.get(CONF_DEPRECATED_ENTITIES, True)): cv.boolean 

533 }) 

534 return self.async_show_form(step_id="housekeeping", data_schema=schema) 

535 

536 async def async_step_delivery_control(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

537 """Defaults for deliveries that don't set their own - inclusion, and occupancy for spoken 

538 deliveries""" 

539 current: dict[str, Any] = self.config_entry.options.get(CONF_DELIVERY_CONTROL, {}) 

540 if user_input is not None: 

541 control: dict[str, Any] = {} 

542 if user_input[CONF_DEFAULT_INCLUSION] != NOT_SET_INCLUSION: 

543 control[CONF_DEFAULT_INCLUSION] = user_input[CONF_DEFAULT_INCLUSION] 

544 if user_input[CONF_VOICE_OCCUPANCY] != NOT_SET_OCCUPANCY: 

545 control[CONF_VOICE_OCCUPANCY] = user_input[CONF_VOICE_OCCUPANCY] 

546 return self.async_create_entry(title="", data={**self.config_entry.options, CONF_DELIVERY_CONTROL: control}) 

547 schema = vol.Schema({ 

548 vol.Optional( 

549 CONF_DEFAULT_INCLUSION, default=current.get(CONF_DEFAULT_INCLUSION, NOT_SET_INCLUSION) 

550 ): SelectSelector( 

551 SelectSelectorConfig( 

552 options=[NOT_SET_INCLUSION, *DEFAULT_INCLUSION_VALUES], translation_key=CONF_DEFAULT_INCLUSION 

553 ) 

554 ), 

555 vol.Optional(CONF_VOICE_OCCUPANCY, default=current.get(CONF_VOICE_OCCUPANCY, NOT_SET_OCCUPANCY)): SelectSelector( 

556 SelectSelectorConfig(options=[NOT_SET_OCCUPANCY, *OCCUPANCY_VALUES], translation_key=CONF_VOICE_OCCUPANCY) 

557 ), 

558 }) 

559 return self.async_show_form(step_id="delivery_control", data_schema=schema) 

560 

561 async def async_step_llm_tools(self, user_input: dict[str, Any] | None = None) -> ConfigFlowResult: 

562 """Which tools llm.py offers to AI conversation agents and the MCP server, and whether 

563 sentences.py registers commands with the built-in agent""" 

564 current: dict[str, Any] = self.config_entry.options.get(CONF_LLM_TOOLS, {}) 

565 if user_input is not None: 

566 return self.async_create_entry(title="", data={**self.config_entry.options, CONF_LLM_TOOLS: user_input}) 

567 schema = vol.Schema({ 

568 vol.Optional(CONF_LLM_ACTION_TOOLS, default=current.get(CONF_LLM_ACTION_TOOLS, False)): cv.boolean, 

569 vol.Optional(CONF_LLM_DIAGNOSTIC_TOOLS, default=current.get(CONF_LLM_DIAGNOSTIC_TOOLS, False)): cv.boolean, 

570 vol.Optional(CONF_SENTENCE_COMMANDS, default=current.get(CONF_SENTENCE_COMMANDS, False)): cv.boolean, 

571 }) 

572 return self.async_show_form(step_id="llm_tools", data_schema=schema) 

573 

574 

575# The target categories the target selector gives, as in supernotify.notify - anything else is 

576# a custom target, entered as text 

577_SELECTOR_TARGET_CATEGORIES = (ATTR_ENTITY_ID, ATTR_DEVICE_ID, ATTR_AREA_ID, ATTR_FLOOR_ID, ATTR_LABEL_ID) 

578# Custom targets recognised without a "category:" prefix 

579_PLAIN_CUSTOM_CATEGORIES = (ATTR_EMAIL, ATTR_PHONE) 

580 

581 

582def target_from_fields(selected: dict[str, Any] | None, custom: list[str] | None) -> dict[str, list[str]]: 

583 """Build a recipient target from the target selector and custom target fields, the same 

584 pair supernotify.notify offers. A custom target is a "category:value", whose value passes the 

585 category's own check where it's one of TARGET_CATEGORY_VALUES, or an e-mail address or phone 

586 number on its own. Raises vol.Invalid for one that is neither.""" 

587 target: dict[str, list[str]] = {} 

588 for category, values in (selected or {}).items(): 

589 if found := [str(v) for v in cv.ensure_list(values) if v]: 

590 target[category] = found 

591 for value in custom or []: 

592 value = value.strip() 

593 if not value: 

594 continue 

595 prefix, sep, rest = value.partition(":") 

596 if sep and rest and not rest.startswith("/") and prefix == slugify(prefix): 

597 category, value = prefix, rest 

598 # a custom category, for a generic transport, is left as it is 

599 if category in TARGET_CATEGORY_VALUES and (check := getattr(Target, f"is_{category}", None)) and not check(value): 

600 raise vol.Invalid(f"not a valid {category}: {value}") 

601 else: 

602 category = next(iter(Target([value]).targets)) 

603 if category not in _PLAIN_CUSTOM_CATEGORIES: 

604 raise vol.Invalid(f"unrecognised custom target {value}") 

605 target.setdefault(category, []) 

606 if value not in target[category]: 

607 target[category].append(value) 

608 return target 

609 

610 

611def target_to_fields(target: Any) -> tuple[dict[str, list[str]], list[str]]: # ruff: ignore[any-type] 

612 """Split a recipient target back into the target selector and custom target fields""" 

613 as_dict: dict[str, list[str]] = Target(target).as_dict() if target else {} 

614 selected: dict[str, list[str]] = {} 

615 custom: list[str] = [] 

616 for category, values in as_dict.items(): 

617 if category in _SELECTOR_TARGET_CATEGORIES: 

618 selected[category] = list(values) 

619 elif category in _PLAIN_CUSTOM_CATEGORIES: 

620 custom.extend(values) 

621 else: 

622 custom.extend(f"{category}:{v}" for v in values) 

623 return selected, custom 

624 

625 

626class RecipientSubentryFlow(ConfigSubentryFlow): 

627 """Add or change a recipient - who, how to reach them, which of their mobile devices to 

628 use, and how individual deliveries treat them. 

629 

630 The recipient is held in RECIPIENT_SCHEMA shape as the steps go, and saved from the menu. 

631 A recipient adds to, or overrides, the one discovered for the same person or user. 

632 """ 

633 

634 def __init__(self) -> None: 

635 self._recipient: dict[str, Any] = {} 

636 # the new recipient's subentry unique_id, from recipient_key() 

637 self._key: str | None = None 

638 

639 async def async_step_user(self, user_input: dict[str, Any] | None = None) -> SubentryFlowResult: 

640 """Who the recipient is - a person, a user with no person, or by name, someone who isn't a 

641 Home Assistant user. Those discovered are recipients already, so this is mostly for the last""" 

642 errors: dict[str, str] = {} 

643 if user_input is not None: 

644 key = recipient_key(user_input) 

645 if not key: 

646 errors["base"] = "person_or_user_required" 

647 elif any(s.unique_id == key for s in self._get_entry().subentries.values()): 

648 return self.async_abort(reason="already_configured") 

649 else: 

650 self._key = key 

651 self._recipient = {k: v for k, v in user_input.items() if v} 

652 # a person's own user, which Home Assistant keeps on the person 

653 if (person := self._recipient.get(CONF_PERSON)) and CONF_USER_ID not in self._recipient: 

654 state = self.hass.states.get(person) 

655 if state and isinstance(user_id := state.attributes.get(CONF_USER_ID), str): 

656 self._recipient[CONF_USER_ID] = user_id 

657 # only a Home Assistant user has mobile app devices 

658 has_user = CONF_PERSON in self._recipient or CONF_USER_ID in self._recipient 

659 self._recipient[CONF_MOBILE_DISCOVERY] = has_user and self._mobile_discovery_default() 

660 return await self.async_step_details() 

661 # only users with no person, since one with a person is chosen by the person 

662 person_user_ids = {s.attributes.get(CONF_USER_ID) for s in self.hass.states.async_all("person")} 

663 users = {k: v for k, v in (await HomeAssistantAPI(self.hass).async_real_user_ids()).items() if k not in person_user_ids} 

664 fields: dict[Any, Any] = {vol.Optional(CONF_PERSON): EntitySelector(EntitySelectorConfig(domain="person"))} 

665 if users: 

666 fields[vol.Optional(CONF_USER_ID)] = SelectSelector( 

667 SelectSelectorConfig(options=[SelectOptionDict(value=k, label=v) for k, v in users.items()]) 

668 ) 

669 fields[vol.Optional(CONF_ALIAS)] = TextSelector() 

670 schema = vol.Schema(fields) 

671 return self.async_show_form( 

672 step_id="user", data_schema=schema, errors=errors, description_placeholders={"learn_more_url": PEOPLE_DOCS_URL} 

673 ) 

674 

675 async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None) -> SubentryFlowResult: 

676 self._recipient = dict(self._get_reconfigure_subentry().data) 

677 return await self.async_step_details() 

678 

679 async def async_step_details(self, user_input: dict[str, Any] | None = None) -> SubentryFlowResult: 

680 """How to reach the recipient, and which of their mobile devices to use""" 

681 errors: dict[str, str] = {} 

682 devices = self._mobile_device_options() 

683 if user_input is not None: 

684 try: 

685 target = target_from_fields(user_input.get(CONF_TARGET), user_input.get(ATTR_CUSTOM_TARGET)) 

686 except vol.Invalid: 

687 errors[ATTR_CUSTOM_TARGET] = "invalid_custom_target" 

688 try: 

689 delivery = RECIPIENT_DELIVERY_SCHEMA(user_input.get(SECTION_DELIVERY_OVERRIDES, {}).get(CONF_DELIVERY) or {}) 

690 except vol.Invalid: 

691 errors["base"] = "invalid_delivery" 

692 if not errors: 

693 # the alias is who someone that isn't a Home Assistant user is, so can't be left blank 

694 has_user = CONF_PERSON in self._recipient or CONF_USER_ID in self._recipient 

695 for key in (CONF_ALIAS, CONF_EMAIL, CONF_PHONE_NUMBER): 

696 if user_input.get(key): 

697 self._recipient[key] = user_input[key] 

698 elif key != CONF_ALIAS or has_user: 

699 self._recipient.pop(key, None) 

700 self._recipient[CONF_ENABLED] = user_input[CONF_ENABLED] 

701 self._recipient[CONF_MOBILE_DISCOVERY] = user_input[CONF_MOBILE_DISCOVERY] 

702 for key, value in ((CONF_TARGET, target), (CONF_DELIVERY, delivery)): 

703 if value: 

704 self._recipient[key] = value 

705 else: 

706 self._recipient.pop(key, None) 

707 selected = user_input.get(CONF_MOBILE_DEVICES, []) 

708 self._recipient[CONF_MOBILE_DEVICES] = [ 

709 {CONF_MOBILE_APP_ID: d["value"], CONF_ENABLED: d["value"] in selected} for d in devices 

710 ] 

711 return await self.async_step_save() 

712 

713 selected_target, custom_target = target_to_fields(self._recipient.get(CONF_TARGET)) 

714 disabled = { 

715 d.get(CONF_MOBILE_APP_ID) for d in self._recipient.get(CONF_MOBILE_DEVICES, []) if not d.get(CONF_ENABLED, True) 

716 } 

717 schema = vol.Schema({ 

718 vol.Optional(CONF_ALIAS): TextSelector(), 

719 vol.Optional(CONF_EMAIL): TextSelector(TextSelectorConfig(type=TextSelectorType.EMAIL)), 

720 vol.Optional(CONF_PHONE_NUMBER): TextSelector(TextSelectorConfig(type=TextSelectorType.TEL)), 

721 vol.Optional(CONF_ENABLED, default=True): cv.boolean, 

722 vol.Optional(CONF_MOBILE_DISCOVERY, default=True): cv.boolean, 

723 vol.Optional(CONF_MOBILE_DEVICES): SelectSelector(SelectSelectorConfig(options=devices, multiple=True)), 

724 vol.Optional(CONF_TARGET): TargetSelector(), 

725 vol.Optional(ATTR_CUSTOM_TARGET): TextSelector(TextSelectorConfig(multiple=True)),