Relax over-strict validation models to fields api.py actually uses (fixes #359)

custom_components/zaptec/__init__.py

@@ -26,16 +26,39 @@
 from .manager import ZaptecConfigEntry, ZaptecManager
 from .services import async_setup_services, async_unload_services
 from .zaptec import (
+    RETRYABLE_HTTP_STATUSES,
     AuthenticationError,
     Installation,
     RequestConnectionError,
+    RequestError,
     RequestTimeoutError,
     Zaptec,
     ZaptecApiError,
 )
 
 _LOGGER = logging.getLogger(__name__)
 
+
+def _config_entry_error(
+    err: ZaptecApiError,
+) -> ConfigEntryAuthFailed | ConfigEntryNotReady | ConfigEntryError:
+    """Map a Zaptec API error from setup login to a HA config-entry error.
+
+    Authentication failures are non-recoverable (trigger re-auth). Connection
+    and timeout errors, and transient server statuses (429/502/503/504), are
+    recoverable, so we raise ConfigEntryNotReady to let Home Assistant retry
+    setup automatically instead of failing permanently (issue #392). All other
+    API errors remain permanent ConfigEntryError failures.
+    """
+    if isinstance(err, AuthenticationError):
+        return ConfigEntryAuthFailed(str(err))
+    if isinstance(err, (RequestTimeoutError, RequestConnectionError)):
+        return ConfigEntryNotReady(str(err))
+    if isinstance(err, RequestError) and err.error_code in RETRYABLE_HTTP_STATUSES:
+        return ConfigEntryNotReady(str(err))
+    return ConfigEntryError(str(err))
+
+
 PLATFORMS = [
     Platform.BINARY_SENSOR,
     Platform.BUTTON,
@@ -80,15 +103,9 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     # Login to the Zaptec account
     try:
         await zaptec.login()
-    except AuthenticationError as err:
-        _LOGGER.error("Authentication failed: %s", err)
-        raise ConfigEntryAuthFailed from err
-    except (RequestTimeoutError, RequestConnectionError) as err:
-        _LOGGER.error("Connection error: %s", err)
-        raise ConfigEntryNotReady from err
     except ZaptecApiError as err:
-        _LOGGER.error("Zaptec API error: %s", err)
-        raise ConfigEntryError from err
+        _LOGGER.error("Zaptec login failed: %s", err)
+        raise _config_entry_error(err) from err
 
     # Get the structure of devices from Zaptec and determine the zaptec objects to track
     tracked_devices = await ZaptecManager.first_time_setup(

custom_components/zaptec/services.yaml

@@ -73,7 +73,7 @@ restart_charger:
       description: Charger identifier
       example: 00000000-1111-2222-3333-444444444444
 
-update_firmware:
+upgrade_firmware:
   name: Update firmware
   description: >-
     Send update firmware request to the charger. Select charger

custom_components/zaptec/zaptec/__init__.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 from .api import Charger, Installation, Zaptec, ZaptecBase
-from .const import MISSING, Missing
+from .const import MISSING, RETRYABLE_HTTP_STATUSES, Missing
 from .exceptions import (
     AuthenticationError,
     RequestConnectionError,
     RequestDataError,
+    RequestError,
     RequestRetryError,
     RequestTimeoutError,
     ZaptecApiError,
@@ -18,6 +19,7 @@
 
 __all__ = [
     "MISSING",
+    "RETRYABLE_HTTP_STATUSES",
     "ZCONST",
     "AuthenticationError",
     "Charger",
@@ -26,6 +28,7 @@
     "Redactor",
     "RequestConnectionError",
     "RequestDataError",
+    "RequestError",
     "RequestRetryError",
     "RequestTimeoutError",
     "Zaptec",

custom_components/zaptec/zaptec/api.py

@@ -35,6 +35,7 @@
     DEFAULT_MAX_CURRENT,
     MAX_DEBUG_TEXT_LEN_ON_500,
     MISSING,
+    RETRYABLE_HTTP_STATUSES,
     TOKEN_URL,
     TRUTHY,
 )
@@ -273,14 +274,15 @@ async def build(self) -> None:
             redact.add_uid(ctid, "Circuit")
             _LOGGER.debug("    Circuit %s", redact(ctid))
 
-            for charger_item in circuit["Chargers"]:
+            # Chargers and Name are nullable per the Zaptec API docs.
+            for charger_item in circuit.get("Chargers") or []:
                 chgid = charger_item["Id"]
                 redact.add_uid(chgid, "Charger")
 
                 # Inject additional attributes
                 charger_item["InstallationId"] = self.id
                 charger_item["CircuitId"] = ctid
-                charger_item["CircuitName"] = circuit["Name"]
+                charger_item["CircuitName"] = circuit.get("Name")
                 charger_item["CircuitMaxCurrent"] = circuit["MaxCurrent"]
 
                 # Add or update the charger
@@ -958,6 +960,19 @@ async def _response_log(resp: aiohttp.ClientResponse) -> AsyncGenerator[str]:
         except Exception:
             _LOGGER.exception("Failed to log response (ignored exception)")
 
+    @staticmethod
+    def _parse_retry_after(value: str | None) -> float | None:
+        """Parse a Retry-After header value into seconds.
+
+        Only the integer delta-seconds form is supported; the HTTP-date form
+        returns None so the caller falls back to the exponential backoff."""
+        if not value:
+            return None
+        try:
+            return max(0.0, float(value))
+        except (TypeError, ValueError):
+            return None
+
     async def _request_worker(
         self, url: str, method: str = "get", retries: int = API_RETRIES, **kwargs: Any
     ) -> AsyncGenerator[tuple[aiohttp.ClientResponse, TLogExc]]:
@@ -971,6 +986,7 @@ async def _request_worker(
         error: Exception | None = None
         delay: float = API_RETRY_INIT_DELAY
         sleep_delay: float = 0.0
+        retry_after: float | None = None
         start_time: float = time.perf_counter()
         iteration = 0
         for iteration in range(1, retries + 1):
@@ -1016,6 +1032,22 @@ def log_exc(
                             _LOGGER.error(str(exc), exc_info=exc)
                         return exc
 
+                    # Retry transient, infrastructure-level server errors
+                    # (429/502/503/504) regardless of method. These indicate
+                    # the request likely never reached the application, so a
+                    # retry is safe even for POST/PUT -- unlike 500, which is
+                    # handled per-method by the caller. On the final iteration
+                    # we fall through to yield so the caller raises the error.
+                    if response.status in RETRYABLE_HTTP_STATUSES and iteration < retries:
+                        if DEBUG_API_CALLS:
+                            _LOGGER.debug(
+                                "@@@  RETRYABLE STATUS %s, retrying (attempt %s)",
+                                response.status,
+                                iteration,
+                            )
+                        retry_after = self._parse_retry_after(response.headers.get("Retry-After"))
+                        continue  # Retry after backoff (or the Retry-After delay)
+
                     # Let the caller handle the response. If the caller
                     # calls __next__ on the generator the request will be
                     # retried.
@@ -1043,6 +1075,12 @@ def log_exc(
                 # longer than the calculated delay, so we don't need to sleep.
                 sleep_delay = delay - time.perf_counter() + start_time
 
+                # A Retry-After header from a transient response overrides the
+                # computed backoff for the next attempt.
+                if retry_after is not None:
+                    sleep_delay = min(retry_after, self._max_time)
+                    retry_after = None
+
         if isinstance(error, TimeoutError):
             raise RequestTimeoutError(
                 f"Request to {url} timed out after {iteration} retries"

custom_components/zaptec/zaptec/const.py

@@ -18,6 +18,15 @@ class Missing:
 API_RETRIES = 8  # Corresponds to median ~100 seconds of retries before giving up
 """Number of retries for API requests."""
 
+RETRYABLE_HTTP_STATUSES = frozenset({429, 502, 503, 504})
+"""Transient HTTP statuses that are retried with backoff regardless of method.
+
+Too Many Requests, Bad Gateway, Service Unavailable and Gateway Timeout are
+infrastructure-level "try again shortly" errors where the request typically
+never reached the application, so retrying is safe even for POST/PUT. This is
+distinct from 500 (Internal Server Error), which Zaptec returns in various
+application-level cases and is only retried for GET (see ``Zaptec.request``)."""
+
 API_RETRY_INIT_DELAY = 0.3
 """Initial delay for the first API retry."""
 

custom_components/zaptec/zaptec/validate.py

@@ -16,27 +16,43 @@ class Installation(BaseModel):
 
     model_config = ConfigDict(extra="allow")
     Id: str
-    Active: bool
-    CurrentUserRoles: int
-    InstallationType: int
-    NetworkType: int
+    Active: bool | None = None
+    CurrentUserRoles: int | None = None
+    InstallationType: int | None = None
+    NetworkType: int | None = None
 
 
 class Installations(BaseModel):
     """Pydantic model for a list of Zaptec installations."""
 
     model_config = ConfigDict(extra="allow")
     Data: list[Installation]
-    Pages: int
+    Pages: int | None = None
 
 
 class Charger(BaseModel):
-    """Pydantic model for a Zaptec charger."""
+    """Pydantic model for a Zaptec charger, as returned by /chargers and /chargers/{id}."""
+
+    model_config = ConfigDict(extra="allow")
+    Id: str
+    Name: str | None = None
+    Active: bool | None = None
+    DeviceType: int
+
+
+class HierarchyCharger(BaseModel):
+    """Pydantic model for the minimal charger stub embedded in a hierarchy Circuit.
+
+    This is a distinct, smaller shape than Charger: at parse time in
+    Installation.build() only Id is read from it. But Zaptec.build()'s
+    standalone-charger merge loop skips re-merging any charger already found
+    via the installation hierarchy, so a hierarchy-sourced charger's
+    attributes come only from this stub -- including DeviceType, which is
+    later hard-subscripted for every registered charger.
+    """
 
     model_config = ConfigDict(extra="allow")
     Id: str
-    Name: str
-    Active: bool
     DeviceType: int
 
 
@@ -61,17 +77,20 @@ class Circuit(BaseModel):
 
     model_config = ConfigDict(extra="allow")
     Id: str
-    Name: str
-    Chargers: list[Charger]
+    Name: str | None = (
+        None  # Nullable per the Zaptec API docs; api.py reads it defensively via .get().
+    )
+    MaxCurrent: float
+    Chargers: list[HierarchyCharger] | None = None
 
 
 class Hierarchy(BaseModel):
     """Pydantic model for the hierarchy of Zaptec objects in an installation."""
 
     model_config = ConfigDict(extra="allow")
-    Id: str
-    Name: str
-    NetworkType: int
+    Id: str | None = None
+    Name: str | None = None
+    NetworkType: int | None = None
     Circuits: list[Circuit]
 
 
@@ -80,11 +99,11 @@ class ChargerFirmware(BaseModel):
 
     model_config = ConfigDict(extra="allow")
     ChargerId: str
-    DeviceType: int
-    IsOnline: bool
-    CurrentVersion: str
-    AvailableVersion: str
-    IsUpToDate: bool
+    DeviceType: int | None = None
+    IsOnline: bool | None = None
+    CurrentVersion: str | None = None
+    AvailableVersion: str | None = None
+    IsUpToDate: bool | None = None
 
 
 class InstallationConnectionDetails(BaseModel):

tests/conftest.py

@@ -2,12 +2,63 @@
 
 import asyncio
 import os
+from typing import Any
+from unittest.mock import MagicMock
 
 import pytest
 
 from custom_components.zaptec.zaptec.api import Zaptec
 
 
+class FakeConfigEntry:
+    """Minimal stand-in for HA's ConfigEntry.
+
+    Exposes only what coordinator.py and entity.py actually touch
+    (`pref_disable_polling`, `async_on_unload`,
+    `async_create_background_task`). A real ConfigEntry pulls in HA's full
+    test-harness machinery, which cannot run on native Windows in this dev
+    environment - see CLAUDE.md's environment notes.
+    """
+
+    pref_disable_polling = False
+    title = "Mock Title"
+
+    def async_on_unload(self, func: Any) -> None:
+        """No-op stand-in for HA's unload-callback registration. Never invoked by these tests."""
+
+    def async_create_background_task(
+        self, hass: Any, target: Any, name: str, eager_start: bool = True
+    ) -> asyncio.Task:
+        """Schedule target as a real asyncio Task.
+
+        This ensures trigger_poll()'s cancel-and-replace logic is genuinely
+        exercised by tests.
+        """
+        return asyncio.ensure_future(target)
+
+
+@pytest.fixture
+def config_entry() -> FakeConfigEntry:
+    """A fake config entry for coordinator/entity tests."""
+    return FakeConfigEntry()
+
+
+@pytest.fixture
+async def hass() -> MagicMock:
+    """A minimal fake HomeAssistant object exposing a real running event loop.
+
+    DataUpdateCoordinator only reads `hass.loop` (to schedule refreshes via
+    `loop.call_at()`/`loop.time()`); coordinator.py and entity.py never touch
+    any other HomeAssistant functionality (config, states, services, etc.).
+    `is_stopping` is pinned False to match a real (non-shutting-down)
+    HomeAssistant instance, since a bare MagicMock would otherwise be truthy.
+    """
+    fake_hass = MagicMock()
+    fake_hass.loop = asyncio.get_running_loop()
+    fake_hass.is_stopping = False
+    return fake_hass
+
+
 @pytest.fixture(scope="session")
 def skip_if_in_github_actions() -> None:
     """Check if we are running in Github actions and skip any dependant tests if true."""