From f8e81aecd8739a68a2cf031c034538cf65a0daf4 Mon Sep 17 00:00:00 2001
From: Luke <conway220@gmail.com>
Date: Wed, 8 Jul 2026 22:03:40 -0400
Subject: [PATCH] fix: typing for message_handler

---
 harbor/mqtt.py     |  9 +++++++--
 tests/test_mqtt.py | 22 ++++++++++++++++++++++
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/harbor/mqtt.py b/harbor/mqtt.py
index 42377ef..18f539c 100644
--- a/harbor/mqtt.py
+++ b/harbor/mqtt.py
@@ -1,9 +1,11 @@
+from __future__ import annotations
+
 import asyncio
 import json
 import logging
 import sys
 from collections.abc import Awaitable, Callable
-from typing import Any
+from typing import TYPE_CHECKING, Any
 from uuid import uuid4
 
 from aiomqtt import Client, MqttError
@@ -12,6 +14,9 @@
 from .data.mqtt_models import GetCameraSettingsRequest, SettingsEvent
 from .utils import get_camera_host, get_ssl_cache_key, get_ssl_context
 
+if TYPE_CHECKING:
+    from .events import HarborEvent
+
 _LOGGER = logging.getLogger(__name__)
 
 DEFAULT_CONNECTION_GRACE_PERIOD = 90.0
@@ -26,7 +31,7 @@ def __init__(
         self,
         config: HarborCameraConfig,
         topics: list[str],
-        message_handler: Callable[[str, Any], Awaitable[None]],
+        message_handler: Callable[[str, Any], Awaitable[HarborEvent | None]],
         client_id: str | None = None,
         ssl_context_cache: dict | None = None,
         on_connection_change: Callable[[bool], Awaitable[None]] | None = None,
diff --git a/tests/test_mqtt.py b/tests/test_mqtt.py
index d746f23..a897b94 100644
--- a/tests/test_mqtt.py
+++ b/tests/test_mqtt.py
@@ -4,6 +4,7 @@
 import json
 
 from harbor.config import HarborCameraConfig
+from harbor.events import HarborEvent
 from harbor.mqtt import GET_SETTINGS_COMMAND, HarborMQTTClient
 
 
@@ -51,6 +52,27 @@ async def message_handler(topic: str, payload: object) -> None:
     assert messages == [("test/topic", {"test": "data"})]
 
 
+async def test_message_handler_may_return_event() -> None:
+    """MQTT handlers may return parsed events; the client ignores the value."""
+
+    called = False
+
+    async def message_handler(topic: str, payload: object) -> HarborEvent | None:
+        nonlocal called
+        called = True
+        return None
+
+    client = HarborMQTTClient(
+        config=_create_config(),
+        topics=[],
+        message_handler=message_handler,
+    )
+
+    await client._handle_message("test/topic", "{}")
+
+    assert called is True
+
+
 async def _noop_handler(topic: str, payload: object) -> None:
     pass