feat: add Home Assistant Event entity for command errors

Closes #272. When a command to the vehicle fails, a JSON event is now
published to the command/error topic so Home Assistant users can build
automations around command failures.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nanomad

src/handlers/vehicle_command.py

@@ -2,7 +2,7 @@
 
 from dataclasses import dataclass
 import logging
-from typing import TYPE_CHECKING, Final
+from typing import TYPE_CHECKING, Any, Final
 
 from saic_ismart_client_ng.exceptions import SaicApiException, SaicLogoutException
 
@@ -69,6 +69,15 @@ async def handle_mqtt_command(self, *, topic: str, payload: str) -> None:
                 handler=handler, payload=payload, analyzed_topic=analyzed_topic
             )
 
+    def __publish_command_error(self, command: str, detail: str) -> None:
+        error_topic = self.vehicle_state.get_topic(mqtt_topics.COMMAND_ERROR)
+        event_payload: dict[str, Any] = {
+            "event_type": "command_error",
+            "command": command,
+            "detail": detail,
+        }
+        self.publisher.publish_json(error_topic, event_payload)
+
     async def __execute_mqtt_command_handler(
         self,
         *,
@@ -91,6 +100,7 @@ async def __execute_mqtt_command_handler(
                 self.publisher.clear_topic(topic_no_global)
         except MqttGatewayException as e:
             self.publisher.publish_str(result_topic, f"Failed: {e.message}")
+            self.__publish_command_error(topic, e.message)
             LOG.exception(e.message, exc_info=e)
         except SaicLogoutException:
             LOG.warning(
@@ -99,9 +109,11 @@ async def __execute_mqtt_command_handler(
             try:
                 await self.relogin_handler.force_login()
             except Exception as login_err:
+                detail = f"relogin failed ({login_err})"
                 self.publisher.publish_str(
-                    result_topic, f"Failed: relogin failed ({login_err})"
+                    result_topic, f"Failed: {detail}"
                 )
+                self.__publish_command_error(topic, detail)
                 LOG.error("Immediate relogin failed", exc_info=login_err)
                 return
             try:
@@ -115,17 +127,21 @@ async def __execute_mqtt_command_handler(
                 if execution_result.clear_command:
                     self.publisher.clear_topic(topic_no_global)
             except Exception as retry_err:
+                detail = str(retry_err)
                 self.publisher.publish_str(
-                    result_topic, f"Failed: {retry_err}"
+                    result_topic, f"Failed: {detail}"
                 )
+                self.__publish_command_error(topic, detail)
                 LOG.error(
                     "Command retry after relogin failed", exc_info=retry_err
                 )
         except SaicApiException as se:
             self.publisher.publish_str(result_topic, f"Failed: {se.message}")
+            self.__publish_command_error(topic, se.message)
             LOG.exception(se.message, exc_info=se)
         except Exception as se:
             self.publisher.publish_str(result_topic, "Failed unexpectedly")
+            self.__publish_command_error(topic, str(se))
             LOG.exception(
                 "handle_mqtt_command failed with an unexpected exception", exc_info=se
             )

src/integrations/home_assistant/base.py

@@ -230,6 +230,34 @@ def _publish_lock(
             "lock", name, payload, custom_availability
         )
 
+    def _publish_event(
+        self,
+        topic: str,
+        name: str,
+        event_types: list[str],
+        *,
+        enabled: bool = True,
+        entity_category: str | None = None,
+        device_class: str | None = None,
+        icon: str | None = None,
+        custom_availability: HaCustomAvailabilityConfig | None = None,
+    ) -> str:
+        payload: dict[str, Any] = {
+            "state_topic": self._get_state_topic(topic),
+            "event_types": event_types,
+            "enabled_by_default": enabled,
+        }
+        if entity_category is not None:
+            payload["entity_category"] = entity_category
+        if device_class is not None:
+            payload["device_class"] = device_class
+        if icon is not None:
+            payload["icon"] = icon
+
+        return self._publish_ha_discovery_message(
+            "event", name, payload, custom_availability
+        )
+
     def _publish_sensor(
         self,
         topic: str,

src/integrations/home_assistant/discovery.py

@@ -327,6 +327,15 @@ def __publish_ha_discovery_messages_real(self) -> None:
         )
         self.__publish_lights_sensors()
 
+        # Command error event
+        self._publish_event(
+            mqtt_topics.COMMAND_ERROR,
+            "Command error",
+            ["command_error"],
+            entity_category="diagnostic",
+            icon="mdi:alert-circle",
+        )
+
         LOG.debug("Completed publishing Home Assistant discovery messages")
 
     def __publish_drivetrain_charging_sensors(self) -> None:

src/mqtt_topics.py

@@ -179,4 +179,7 @@
 TYRES_REAR_LEFT_PRESSURE = TYRES + "/rearLeftPressure"
 TYRES_REAR_RIGHT_PRESSURE = TYRES + "/rearRightPressure"
 
+COMMAND = "command"
+COMMAND_ERROR = COMMAND + "/error"
+
 VEHICLES = "vehicles"