refactor: add named constants, NamedTuples, TypedDicts, and display overrides

Phase 1 of dynamic typing hardening:
- Add 11 named constants to const.py replacing magic numbers across
  client.py, cli.py, and TUI modules
- Add kebab_name() utility and centralized display_name() overrides
  in models.py for consistent enum display across CLI and TUI
- Replace unnamed tuples with NamedTuples in cli.py, tui/app.py,
  tui/widgets.py, tui/media_theme_screen.py, tui/flame_color_screen.py,
  and tui/color_screen.py
- Replace dict return of _parse_login_page() with _B2CLoginFields
  NamedTuple in b2c_login.py
- Add _WireParam TypedDict and Literal["GET","POST"] in client.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: deviantintegral

src/flameconnect/__init__.py

@@ -6,6 +6,19 @@
 
 from flameconnect.auth import AbstractAuth, MsalAuth, TokenAuth
 from flameconnect.client import FlameConnectClient
+from flameconnect.const import (
+    DEFAULT_TARGET_TEMPERATURE,
+    DEFAULT_TIMER_DURATION,
+    MAX_BOOST_DURATION,
+    MAX_FLAME_SPEED,
+    MAX_TEMP_CELSIUS,
+    MAX_TEMP_FAHRENHEIT,
+    MAX_TIMER_DURATION,
+    MIN_BOOST_DURATION,
+    MIN_FLAME_SPEED,
+    MIN_TEMP_CELSIUS,
+    MIN_TEMP_FAHRENHEIT,
+)
 from flameconnect.exceptions import (
     ApiError,
     AuthenticationError,
@@ -45,6 +58,7 @@
     TimerStatus,
     convert_temp,
     display_name,
+    kebab_name,
     temp_suffix,
 )
 
@@ -92,11 +106,23 @@
     "TempUnitParam",
     "TimerParam",
     # Constants
+    "DEFAULT_TARGET_TEMPERATURE",
+    "DEFAULT_TIMER_DURATION",
+    "MAX_BOOST_DURATION",
+    "MAX_FLAME_SPEED",
+    "MAX_TEMP_CELSIUS",
+    "MAX_TEMP_FAHRENHEIT",
+    "MAX_TIMER_DURATION",
+    "MIN_BOOST_DURATION",
+    "MIN_FLAME_SPEED",
+    "MIN_TEMP_CELSIUS",
+    "MIN_TEMP_FAHRENHEIT",
     "NAMED_COLORS",
     # Type aliases
     "Parameter",
     # Utilities
     "convert_temp",
     "display_name",
+    "kebab_name",
     "temp_suffix",
 ]

src/flameconnect/b2c_login.py

@@ -8,6 +8,7 @@
 
 import logging
 import re
+from typing import NamedTuple
 from urllib.parse import urljoin, urlparse
 
 import aiohttp
@@ -46,14 +47,21 @@ def _extract_base_path(page_url: str) -> str:
     return "/"
 
 
-def _parse_login_page(html: str, page_url: str) -> dict[str, str]:
+class _B2CLoginFields(NamedTuple):
+    csrf: str
+    tx: str
+    p: str
+    post_url: str
+    confirmed_url: str
+
+
+def _parse_login_page(html: str, page_url: str) -> _B2CLoginFields:
     """Extract B2C form fields from the login page HTML.
 
     Looks for the SETTINGS JavaScript object which contains transId and
     csrf, plus derives the SelfAsserted POST URL from the page URL.
 
-    Returns a dict with keys: csrf, tx, p, base_url, post_url,
-    confirmed_url.
+    Returns a _B2CLoginFields named tuple.
 
     Raises:
         AuthenticationError: If required fields cannot be found.
@@ -81,13 +89,13 @@ def _parse_login_page(html: str, page_url: str) -> dict[str, str]:
     post_url = f"{origin}{base}SelfAsserted?{qs}"
     confirmed_url = f"{origin}{base}api/CombinedSigninAndSignup/confirmed"
 
-    return {
-        "csrf": csrf,
-        "tx": tx,
-        "p": p,
-        "post_url": post_url,
-        "confirmed_url": confirmed_url,
-    }
+    return _B2CLoginFields(
+        csrf=csrf,
+        tx=tx,
+        p=p,
+        post_url=post_url,
+        confirmed_url=confirmed_url,
+    )
 
 
 def _build_cookie_header(
@@ -184,9 +192,9 @@ async def b2c_login_with_credentials(auth_uri: str, email: str, password: str) -
             fields = _parse_login_page(login_html, page_url)
             _LOGGER.debug(
                 "Parsed login page: csrf=%s, tx=%s, p=%s",
-                fields["csrf"][:16] + "...",
-                fields["tx"][:40] + "...",
-                fields["p"],
+                fields.csrf[:16] + "...",
+                fields.tx[:40] + "...",
+                fields.p,
             )
 
             # Step 3: POST credentials to SelfAsserted endpoint
@@ -198,7 +206,7 @@ async def b2c_login_with_credentials(auth_uri: str, email: str, password: str) -
             parsed_page = urlparse(page_url)
             origin = f"{parsed_page.scheme}://{parsed_page.netloc}"
             post_headers = {
-                "X-CSRF-TOKEN": fields["csrf"],
+                "X-CSRF-TOKEN": fields.csrf,
                 "X-Requested-With": "XMLHttpRequest",
                 "Referer": auth_uri,
                 "Origin": origin,
@@ -209,12 +217,12 @@ async def b2c_login_with_credentials(auth_uri: str, email: str, password: str) -
             # Build an unquoted Cookie header — aiohttp's cookie jar
             # wraps values containing +/= in double-quotes, but B2C
             # requires plain unquoted values.
-            cookie_header = _build_cookie_header(jar, fields["post_url"])
+            cookie_header = _build_cookie_header(jar, fields.post_url)
             post_headers["Cookie"] = cookie_header
             _LOGGER.debug(">>>   cookies: %s", cookie_header[:200])
             _log_request(
                 "POST",
-                fields["post_url"],
+                fields.post_url,
                 headers=post_headers,
                 data=post_data,
             )
@@ -227,7 +235,7 @@ async def b2c_login_with_credentials(auth_uri: str, email: str, password: str) -
                 cookie_jar=aiohttp.DummyCookieJar(),
             ) as raw_session:
                 async with raw_session.post(
-                    yarl.URL(fields["post_url"], encoded=True),
+                    yarl.URL(fields.post_url, encoded=True),
                     data=post_data,
                     headers=post_headers,
                     allow_redirects=False,
@@ -265,13 +273,13 @@ async def b2c_login_with_credentials(auth_uri: str, email: str, password: str) -
                 # (csrf_token, tx) as browsers send them.
                 confirmed_qs = (
                     f"rememberMe=false"
-                    f"&csrf_token={fields['csrf']}"
-                    f"&tx={fields['tx']}"
-                    f"&p={fields['p']}"
+                    f"&csrf_token={fields.csrf}"
+                    f"&tx={fields.tx}"
+                    f"&p={fields.p}"
                 )
 
                 # Follow redirects manually to catch custom-scheme one
-                next_url: str = fields["confirmed_url"] + "?" + confirmed_qs
+                next_url: str = fields.confirmed_url + "?" + confirmed_qs
                 confirmed_headers = {
                     "Cookie": cookie_header,
                 }

src/flameconnect/cli.py

@@ -8,13 +8,20 @@
 import sys
 import webbrowser
 from dataclasses import replace
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, NamedTuple
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
 
 from flameconnect.auth import MsalAuth
 from flameconnect.client import FlameConnectClient
+from flameconnect.const import (
+    DEFAULT_TARGET_TEMPERATURE,
+    MAX_BOOST_DURATION,
+    MAX_FLAME_SPEED,
+    MIN_BOOST_DURATION,
+    MIN_FLAME_SPEED,
+)
 from flameconnect.models import (
     NAMED_COLORS,
     Brightness,
@@ -97,6 +104,13 @@
     "celsius": TempUnit.CELSIUS,
 }
 
+
+class _FlameEffectSetter(NamedTuple):
+    field: str
+    lookup: dict[str, object]
+    label: str
+
+
 _SET_PARAM_NAMES = (
     "mode, flame-speed, brightness, pulsating, flame-color,"
     " media-theme, heat-status, heat-mode, heat-temp, timer,"
@@ -149,7 +163,7 @@ def _display_flame_effect(param: FlameEffectParam) -> None:
     print(f"  {'─' * 40}")
     flame = display_name(param.flame_effect)
     print(f"    Flame:          {flame}")
-    print(f"    Flame Speed:    {param.flame_speed} / 5")
+    print(f"    Flame Speed:    {param.flame_speed} / {MAX_FLAME_SPEED}")
     brightness = display_name(param.brightness)
     pulsating = display_name(param.pulsating_effect)
     print(f"    Brightness:     {brightness}")
@@ -374,43 +388,43 @@ async def cmd_status(client: FlameConnectClient, fire_id: str) -> None:
         _display_parameter(param, temp_unit)
 
 
-_FLAME_EFFECT_SETTERS: dict[str, tuple[str, dict[str, object], str]] = {
-    "brightness": (
+_FLAME_EFFECT_SETTERS: dict[str, _FlameEffectSetter] = {
+    "brightness": _FlameEffectSetter(
         "brightness",
         {"low": Brightness.LOW, "high": Brightness.HIGH},
         "Brightness",
     ),
-    "pulsating": (
+    "pulsating": _FlameEffectSetter(
         "pulsating_effect",
         dict[str, object](_PULSATING_LOOKUP),
         "Pulsating effect",
     ),
-    "flame-color": (
+    "flame-color": _FlameEffectSetter(
         "flame_color",
         dict[str, object](_FLAME_COLOR_LOOKUP),
         "Flame color",
     ),
-    "media-theme": (
+    "media-theme": _FlameEffectSetter(
         "media_theme",
         dict[str, object](_MEDIA_THEME_LOOKUP),
         "Media theme",
     ),
-    "flame-effect": (
+    "flame-effect": _FlameEffectSetter(
         "flame_effect",
         {"on": FlameEffect.ON, "off": FlameEffect.OFF},
         "Flame effect",
     ),
-    "media-light": (
+    "media-light": _FlameEffectSetter(
         "media_light",
         {"on": LightStatus.ON, "off": LightStatus.OFF},
         "Media light",
     ),
-    "overhead-light": (
+    "overhead-light": _FlameEffectSetter(
         "light_status",
         {"on": LightStatus.ON, "off": LightStatus.OFF},
         "Overhead light",
     ),
-    "ambient-sensor": (
+    "ambient-sensor": _FlameEffectSetter(
         "ambient_sensor",
         {"on": LightStatus.ON, "off": LightStatus.OFF},
         "Ambient sensor",
@@ -477,7 +491,9 @@ async def _set_mode(client: FlameConnectClient, fire_id: str, value: str) -> Non
             current_mode = param
             break
 
-    temperature = current_mode.target_temperature if current_mode else 22.0
+    temperature = (
+        current_mode.target_temperature if current_mode else DEFAULT_TARGET_TEMPERATURE
+    )
     mode = FireMode.STANDBY if value == "standby" else FireMode.MANUAL
     mode_param = ModeParam(mode=mode, target_temperature=temperature)
     await client.write_parameters(fire_id, [mode_param])
@@ -489,8 +505,11 @@ async def _set_flame_speed(
 ) -> None:
     """Set flame speed (1-5)."""
     speed = int(value)
-    if speed < 1 or speed > 5:
-        print("Error: flame-speed must be between 1 and 5.")
+    if speed < MIN_FLAME_SPEED or speed > MAX_FLAME_SPEED:
+        print(
+            f"Error: flame-speed must be between"
+            f" {MIN_FLAME_SPEED} and {MAX_FLAME_SPEED}."
+        )
         sys.exit(1)
     overview = await client.get_fire_overview(fire_id)
     current = _find_param(overview.parameters, FlameEffectParam)
@@ -540,8 +559,12 @@ async def _set_heat_mode(client: FlameConnectClient, fire_id: str, value: str) -
         except (ValueError, IndexError):
             print("Error: boost format is boost:<minutes> (e.g., boost:15).")
             sys.exit(1)
-        if not 1 <= boost_minutes <= 20:
-            print("Error: boost duration must be 1-20 minutes.")
+        if not MIN_BOOST_DURATION <= boost_minutes <= MAX_BOOST_DURATION:
+            print(
+                f"Error: boost duration must be"
+                f" {MIN_BOOST_DURATION}-{MAX_BOOST_DURATION}"
+                " minutes."
+            )
             sys.exit(1)
         heat_mode = HeatMode.BOOST
     elif value in _HEAT_MODE_LOOKUP:

src/flameconnect/client.py

@@ -5,12 +5,17 @@
 import base64
 import logging
 from dataclasses import replace
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
 from urllib.parse import quote
 
 import aiohttp
 
-from flameconnect.const import API_BASE, DEFAULT_HEADERS, ParameterId
+from flameconnect.const import (
+    API_BASE,
+    DEFAULT_HEADERS,
+    DEFAULT_TARGET_TEMPERATURE,
+    ParameterId,
+)
 
 if TYPE_CHECKING:
     from flameconnect.auth import AbstractAuth
@@ -37,6 +42,11 @@
 _LOGGER = logging.getLogger(__name__)
 
 
+class _WireParam(TypedDict):
+    ParameterId: int
+    Value: str
+
+
 def _parse_fire_features(data: dict[str, Any]) -> FireFeatures:
     """Parse a FireFeature JSON object into a FireFeatures dataclass."""
     return FireFeatures(
@@ -124,7 +134,7 @@ async def __aexit__(self, *exc: object) -> None:
 
     async def _request(
         self,
-        method: str,
+        method: Literal["GET", "POST"],
         url: str,
         json: dict[str, Any] | None = None,
     ) -> Any:
@@ -259,11 +269,11 @@ async def write_parameters(self, fire_id: str, params: list[Parameter]) -> None:
         """
         url = f"{API_BASE}/api/Fires/WriteWifiParameters"
 
-        wire_params: list[dict[str, Any]] = []
+        wire_params: list[_WireParam] = []
         for param in params:
             param_id = _get_parameter_id(param)
             value = encode_parameter(param)
-            wire_params.append({"ParameterId": param_id, "Value": value})
+            wire_params.append(_WireParam(ParameterId=param_id, Value=value))
 
         payload: dict[str, Any] = {
             "FireId": fire_id,
@@ -293,7 +303,11 @@ async def turn_on(self, fire_id: str) -> None:
             elif isinstance(param, FlameEffectParam):
                 current_flame = param
 
-        temperature = current_mode.target_temperature if current_mode else 22.0
+        temperature = (
+            current_mode.target_temperature
+            if current_mode
+            else DEFAULT_TARGET_TEMPERATURE
+        )
 
         new_mode = ModeParam(mode=FireMode.MANUAL, target_temperature=temperature)
 
@@ -322,7 +336,11 @@ async def turn_off(self, fire_id: str) -> None:
                 current_mode = param
                 break
 
-        temperature = current_mode.target_temperature if current_mode else 22.0
+        temperature = (
+            current_mode.target_temperature
+            if current_mode
+            else DEFAULT_TARGET_TEMPERATURE
+        )
 
         mode_param = ModeParam(mode=FireMode.STANDBY, target_temperature=temperature)
         await self.write_parameters(fire_id, [mode_param])