fix: handle ResultCode in get_fire_overview to prevent crash when offline (#81)

* docs: handle ResultCode in get_fire_overview (plan 19)

Add plan for fixing TypeError crash when fireplace is offline.
The API returns ResultCode != 0 with WifiFireOverview: null for
offline/failed/unavailable fireplaces, but our client unconditionally
accesses WifiFireOverview causing a crash. The plan introduces a
FireOverviewResultCode enum, FireUnavailableError exception, and
a guard clause in get_fire_overview.

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

* fix: handle ResultCode in get_fire_overview to prevent crash when offline

The GetFireOverview API returns a ResultCode field that indicates
whether the fireplace is reachable. When ResultCode != 0 (offline,
failed, no longer available, updating firmware), WifiFireOverview is
null. Our client unconditionally accessed it, causing a TypeError crash.

- Add FireOverviewResultCode enum mirroring the API's 5 result codes
- Add FireUnavailableError exception carrying result_code and optional
  Fire metadata from FireDetails
- Add guard clause in get_fire_overview to check ResultCode before
  accessing WifiFireOverview
- Extract shared _parse_fire helper to deduplicate Fire construction
  across get_fires, get_fire_overview success path, and error path
- Export new types from __init__.py
- Add tests for all result code paths, backward compatibility,
  malformed FireDetails, turn_on/turn_off propagation

Refs: deviantintegral/flame_connect_ha#55

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: deviantintegral

.ai/task-manager/plans/19--handle-fire-overview-result-code/plan-19--handle-fire-overview-result-code.md

@@ -22,6 +22,7 @@
 from flameconnect.exceptions import (
     ApiError,
     AuthenticationError,
+    FireUnavailableError,
     FlameConnectError,
     ProtocolError,
 )
@@ -34,6 +35,7 @@
     FireFeatures,
     FireMode,
     FireOverview,
+    FireOverviewResultCode,
     FlameColor,
     FlameEffect,
     FlameEffectParam,
@@ -73,12 +75,14 @@
     # Exceptions
     "ApiError",
     "AuthenticationError",
+    "FireUnavailableError",
     "FlameConnectError",
     "ProtocolError",
     # Enums
     "Brightness",
     "ConnectionState",
     "FireMode",
+    "FireOverviewResultCode",
     "FlameColor",
     "FlameEffect",
     "HeatControl",

src/flameconnect/__init__.py

@@ -19,13 +19,14 @@
 
 if TYPE_CHECKING:
     from flameconnect.auth import AbstractAuth
-from flameconnect.exceptions import ApiError
+from flameconnect.exceptions import ApiError, FireUnavailableError
 from flameconnect.models import (
     ConnectionState,
     Fire,
     FireFeatures,
     FireMode,
     FireOverview,
+    FireOverviewResultCode,
     FlameEffect,
     FlameEffectParam,
     HeatModeParam,
@@ -77,6 +78,28 @@ def _parse_fire_features(data: dict[str, Any]) -> FireFeatures:
     )
 
 
+def _parse_fire(data: dict[str, Any], features: FireFeatures | None = None) -> Fire:
+    """Build a Fire dataclass from a JSON dict.
+
+    Used by get_fires, get_fire_overview (success path), and the
+    get_fire_overview error path (FireDetails).
+    """
+    if features is None:
+        features = _parse_fire_features(data.get("FireFeature", {}))
+    return Fire(
+        fire_id=data["FireId"],
+        friendly_name=data.get("FriendlyName", data["FireId"]),
+        brand=data.get("Brand", ""),
+        product_type=data.get("ProductType", ""),
+        product_model=data.get("ProductModel", ""),
+        item_code=data.get("ItemCode", ""),
+        connection_state=ConnectionState(data.get("IoTConnectionState", 0)),
+        with_heat=data.get("WithHeat", False),
+        is_iot_fire=data.get("IsIotFire", False),
+        features=features,
+    )
+
+
 def _get_parameter_id(param: Parameter) -> int:
     """Return the wire ParameterId integer for a parameter dataclass."""
     if isinstance(param, ModeParam):
@@ -195,20 +218,7 @@ async def get_fires(self) -> list[Fire]:
 
         fires: list[Fire] = []
         for entry in data:
-            features = _parse_fire_features(entry.get("FireFeature", {}))
-            fire = Fire(
-                fire_id=entry["FireId"],
-                friendly_name=entry["FriendlyName"],
-                brand=entry["Brand"],
-                product_type=entry["ProductType"],
-                product_model=entry["ProductModel"],
-                item_code=entry["ItemCode"],
-                connection_state=ConnectionState(entry["IoTConnectionState"]),
-                with_heat=entry["WithHeat"],
-                is_iot_fire=entry["IsIotFire"],
-                features=features,
-            )
-            fires.append(fire)
+            fires.append(_parse_fire(entry))
 
         return fires
 
@@ -220,30 +230,41 @@ async def get_fire_overview(self, fire_id: str) -> FireOverview:
 
         Returns:
             A FireOverview containing the fire identity and decoded parameters.
+
+        Raises:
+            FireUnavailableError: If the API reports the fireplace as offline,
+                failed, no longer available, or updating firmware
+                (``ResultCode != 0``).  The exception carries the
+                ``result_code`` and, when available, the ``fire`` metadata.
         """
         url = f"{API_BASE}/api/Fires/GetFireOverview?FireId={quote(fire_id, safe='')}"
         data: dict[str, Any] = await self._request("GET", url)
 
+        # Check the result code before accessing nullable fields.
+        raw_code: int = data.get("ResultCode", 0)
+        try:
+            result_code = FireOverviewResultCode(raw_code)
+        except ValueError:
+            result_code = raw_code  # type: ignore[assignment]
+
+        if result_code != FireOverviewResultCode.SUCCESSFUL:
+            fire: Fire | None = None
+            fire_details: dict[str, Any] | None = data.get("FireDetails")
+            if fire_details is not None:
+                try:
+                    fire = _parse_fire(fire_details)
+                except Exception:
+                    _LOGGER.warning("Failed to parse FireDetails for fire %s", fire_id)
+            raise FireUnavailableError(result_code, fire)
+
         wifi: dict[str, Any] = data["WifiFireOverview"]
-        fire_data: dict[str, Any] = wifi
 
         feature_data = data.get("FireDetails", {}).get("FireFeature", {})
         if not feature_data:
             feature_data = wifi.get("FireFeature", {})
         features = _parse_fire_features(feature_data)
 
-        fire = Fire(
-            fire_id=fire_data["FireId"],
-            friendly_name=fire_data.get("FriendlyName", fire_data["FireId"]),
-            brand=fire_data.get("Brand", ""),
-            product_type=fire_data.get("ProductType", ""),
-            product_model=fire_data.get("ProductModel", ""),
-            item_code=fire_data.get("ItemCode", ""),
-            connection_state=ConnectionState(fire_data.get("IoTConnectionState", 0)),
-            with_heat=fire_data.get("WithHeat", False),
-            is_iot_fire=fire_data.get("IsIotFire", False),
-            features=features,
-        )
+        fire_obj = _parse_fire(wifi, features=features)
 
         raw_params: list[dict[str, Any]] = wifi.get("Parameters", [])
         parameters: list[Parameter] = []
@@ -258,7 +279,7 @@ async def get_fire_overview(self, fire_id: str) -> FireOverview:
                 continue
             parameters.append(param)
 
-        return FireOverview(fire=fire, parameters=parameters)
+        return FireOverview(fire=fire_obj, parameters=parameters)
 
     async def write_parameters(self, fire_id: str, params: list[Parameter]) -> None:
         """Write control parameters to a fireplace.

src/flameconnect/client.py

@@ -2,6 +2,13 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+from flameconnect.models import FireOverviewResultCode
+
+if TYPE_CHECKING:
+    from flameconnect.models import Fire
+
 
 class FlameConnectError(Exception):
     """Base exception for all flameconnect errors."""
@@ -21,3 +28,27 @@ def __init__(self, status: int, message: str) -> None:
 
 class ProtocolError(FlameConnectError):
     """Raised when wire protocol encoding/decoding fails."""
+
+
+class FireUnavailableError(FlameConnectError):
+    """Raised when the fireplace is offline, failed, or otherwise unavailable.
+
+    The ``result_code`` attribute contains the specific
+    :class:`~flameconnect.models.FireOverviewResultCode` returned by the API.
+    When the API includes ``FireDetails`` in the response, the ``fire``
+    attribute contains the parsed :class:`~flameconnect.models.Fire` metadata;
+    otherwise it is ``None``.
+    """
+
+    def __init__(
+        self,
+        result_code: FireOverviewResultCode | int,
+        fire: Fire | None = None,
+    ) -> None:
+        self.result_code = result_code
+        self.fire = fire
+        try:
+            label = FireOverviewResultCode(result_code).name
+        except ValueError:
+            label = f"UNKNOWN({result_code})"
+        super().__init__(f"Fire unavailable: {label}")

src/flameconnect/exceptions.py

@@ -126,6 +126,19 @@ class ConnectionState(IntEnum):
     UPDATING_FIRMWARE = 3
 
 
+class FireOverviewResultCode(IntEnum):
+    """Result code from the GetFireOverview API endpoint.
+
+    Maps to the C# ``EWifiFireOverviewResponseCode`` enum in the official app.
+    """
+
+    SUCCESSFUL = 0
+    FIRE_OFFLINE = 1
+    FAILED = 2
+    FIRE_NO_LONGER_AVAILABLE = 3
+    UPDATING_FIRMWARE = 4
+
+
 # ---------------------------------------------------------------------------
 # Value-object dataclasses
 # ---------------------------------------------------------------------------

src/flameconnect/models.py

@@ -1,4 +1,5 @@
 {
+  "ResultCode": 0,
   "WifiFireOverview": {
     "FireId": "test-fire-001",
     "FriendlyName": "Living Room",