refactor: replace SETUP_DRIVER_ABORT event with callback

Use the setup handler with the new AbortDriverSetup class to notify a
driver about an aborted setup flow.

ucapi/__init__.py

@@ -10,6 +10,7 @@
 import logging  # isort:skip
 
 from .api_definitions import (  # isort:skip # noqa: F401
+    AbortDriverSetup,
     DeviceStates,
     DriverSetupRequest,
     Events,

ucapi/api.py

@@ -308,7 +308,7 @@ async def _process_ws_message(self, websocket, message) -> None:
             else:
                 await self._handle_ws_request_msg(websocket, msg, req_id, msg_data)
         elif kind == "event":
-            self._handle_ws_event_msg(msg, msg_data)
+            await self._handle_ws_event_msg(msg, msg_data)
 
     async def _handle_ws_request_msg(
         self, websocket, msg: str, req_id: int, msg_data: dict[str, Any] | None
@@ -365,7 +365,9 @@ async def _handle_ws_request_msg(
                 await asyncio.sleep(0.5)
                 await self.driver_setup_error(websocket)
 
-    def _handle_ws_event_msg(self, msg: str, _msg_data: dict[str, Any] | None) -> None:
+    async def _handle_ws_event_msg(
+        self, msg: str, msg_data: dict[str, Any] | None
+    ) -> None:
         if msg == uc.WsMsgEvents.CONNECT:
             self._events.emit(uc.Events.CONNECT)
         elif msg == uc.WsMsgEvents.DISCONNECT:
@@ -375,7 +377,22 @@ def _handle_ws_event_msg(self, msg: str, _msg_data: dict[str, Any] | None) -> No
         elif msg == uc.WsMsgEvents.EXIT_STANDBY:
             self._events.emit(uc.Events.EXIT_STANDBY)
         elif msg == uc.WsMsgEvents.ABORT_DRIVER_SETUP:
-            self._events.emit(uc.Events.SETUP_DRIVER_ABORT)
+            if not self._setup_handler:
+                _LOG.warning(
+                    "Received abort_driver_setup event, but no setup handler provided by the driver!"  # noqa
+                )
+                return
+
+            if "error" in msg_data:
+                try:
+                    error = uc.IntegrationSetupError[msg_data["error"]]
+                except KeyError:
+                    error = uc.IntegrationSetupError.OTHER
+                await self._setup_handler(uc.AbortDriverSetup(error))
+            else:
+                _LOG.warning(
+                    "Unsupported abort_driver_setup payload received: %s", msg_data
+                )
 
     async def _authenticate(self, websocket, success: bool) -> None:
         await self._send_ws_response(

ucapi/api_definitions.py

@@ -84,7 +84,6 @@ class Events(str, Enum):
     ENTITY_ATTRIBUTES_UPDATED = "entity_attributes_updated"
     SUBSCRIBE_ENTITIES = "subscribe_entities"
     UNSUBSCRIBE_ENTITIES = "unsubscribe_entities"
-    SETUP_DRIVER_ABORT = "setup_driver_abort"
     CONNECT = "connect"
     DISCONNECT = "disconnect"
     ENTER_STANDBY = "enter_standby"
@@ -147,6 +146,18 @@ class UserConfirmationResponse(SetupDriver):
     confirm: bool
 
 
+@dataclass
+class AbortDriverSetup(SetupDriver):
+    """
+    Abort notification.
+
+    - ``error == OTHER``: the user cancelled the setup flow.
+    - ``error == TIMEOUT``: timeout occurred, most likely because of no user input.
+    """
+
+    error: IntegrationSetupError
+
+
 class SetupAction:
     """Setup action response base class."""