feat(websocket): expose heartbeat events and consolidate examples

Author: 0xferit

README.md

@@ -238,6 +238,27 @@ The same can be done without using decorators:
 bfx.wss.on("candles_update", callback=on_candles_update)
 ```
 
+### Heartbeat events
+
+The WebSocket server sends periodic heartbeat messages to keep connections alive. 
+These are now exposed as `heartbeat` events that users can listen to:
+
+```python
+@bfx.wss.on("heartbeat")
+def on_heartbeat(subscription=None):
+    if subscription:
+        # Heartbeat for a specific subscription (public channels)
+        print(f"Heartbeat for {subscription['channel']}")
+    else:
+        # Heartbeat for authenticated connection
+        print("Heartbeat on authenticated channel")
+```
+
+For public channel subscriptions, the heartbeat event includes the subscription information. 
+For authenticated connections, heartbeats are sent without subscription data.
+
+---
+
 # Advanced features
 
 ## Using custom notifications

bfxapi/websocket/_client/bfx_websocket_bucket.py

@@ -66,9 +66,11 @@ async def start(self) -> None:
                     if (
                         (chan_id := cast(int, message[0]))
                         and (subscription := self.__subscriptions.get(chan_id))
-                        and (message[1] != Connection._HEARTBEAT)
                     ):
-                        self.__handler.handle(subscription, message[1:])
+                        if message[1] == Connection._HEARTBEAT:
+                            self.__event_emitter.emit("heartbeat", subscription)
+                        else:
+                            self.__handler.handle(subscription, message[1:])
 
     def __on_subscribed(self, message: Dict[str, Any]) -> None:
         chan_id = cast(int, message["chan_id"])

bfxapi/websocket/_client/bfx_websocket_client.py

@@ -266,9 +266,11 @@ async def __connect(self) -> None:
                 if (
                     isinstance(message, list)
                     and message[0] == 0
-                    and message[1] != Connection._HEARTBEAT
                 ):
-                    self.__handler.handle(message[1], message[2])
+                    if message[1] == Connection._HEARTBEAT:
+                        self.__event_emitter.emit("heartbeat", None)
+                    else:
+                        self.__handler.handle(message[1], message[2])
 
     async def __new_bucket(self) -> BfxWebSocketBucket:
         bucket = BfxWebSocketBucket(self._host, self.__event_emitter)

bfxapi/websocket/_event_emitter/bfx_event_emitter.py

@@ -32,6 +32,7 @@
 
 _COMMON = [
     "disconnected",
+    "heartbeat",
     "t_ticker_update",
     "f_ticker_update",
     "t_trade_execution",

examples/websocket/heartbeat.py

@@ -0,0 +1,48 @@
+"""
+python -c "import examples.websocket.heartbeat"
+
+Single example demonstrating heartbeat handling for both public and authenticated flows.
+
+If BFX_API_KEY and BFX_API_SECRET are set in the environment, the client will
+authenticate and you will see heartbeats on the authenticated (chan 0) path
+as well. Otherwise, only public channel heartbeats are shown.
+"""
+
+import os
+from typing import Optional
+
+from bfxapi import Client
+from bfxapi.websocket.subscriptions import Subscription
+
+
+bfx = Client(
+    api_key=os.getenv("BFX_API_KEY"),
+    api_secret=os.getenv("BFX_API_SECRET"),
+)
+
+
+@bfx.wss.on("heartbeat")
+def on_heartbeat(subscription: Optional[Subscription] = None):
+    if subscription:
+        channel = subscription["channel"]
+        label = subscription.get("symbol", subscription.get("key", "N/A"))
+        print(f"Heartbeat for {channel}: {label}")
+    else:
+        print("Heartbeat on authenticated connection")
+
+
+@bfx.wss.on("authenticated")
+async def on_authenticated(event):
+    print(f"Authenticated: userId={event.get('userId')}")
+
+
+@bfx.wss.on("open")
+async def on_open():
+    # Subscribe to a public channel to observe subscription heartbeats
+    await bfx.wss.subscribe("ticker", symbol="tBTCUSD")
+
+
+print("Starting WebSocket client... Press Ctrl+C to stop.")
+bfx.wss.run()
+
+