Add optional Home Assistant integration for battery percentage tracking

ha_client.py

@@ -0,0 +1,40 @@
+import logging
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+class HomeAssistantClient:
+    """Thin wrapper around the Home Assistant REST API.
+
+    Instantiating with url=None or api_key=None produces a disabled client;
+    all methods become no-ops that return None.
+    """
+
+    def __init__(self, url: str | None, api_key: str | None):
+        self._enabled = bool(url and api_key)
+        self._base_url = (url or "").rstrip("/")
+        self._headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+
+    @property
+    def enabled(self) -> bool:
+        return self._enabled
+
+    def get_state(self, entity_id: str) -> int | None:
+        """Fetch the current state of a HA entity and return it as an integer.
+
+        Returns None if HA is not configured, the entity is not found,
+        the state is non-numeric, or any network/HTTP error occurs.
+        """
+        if not self._enabled:
+            return None
+        url = f"{self._base_url}/api/states/{entity_id}"
+        try:
+            resp = requests.get(url, headers=self._headers, timeout=10)
+            resp.raise_for_status()
+            state = resp.json().get("state")
+            return int(float(state))
+        except (requests.RequestException, ValueError, TypeError, KeyError) as exc:
+            logger.warning("HA API error for %s: %s", entity_id, exc)
+            return None