Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(whatsapp): Wave 12 B2 — move broadcasts into nodes/whatsapp/_events.py
trohitgc4d94282163e
diff --git a/server/nodes/whatsapp/__init__.py b/server/nodes/whatsapp/__init__.pyindex 3445d65f..1dd86a4d 100644--- a/server/nodes/whatsapp/__init__.py+++ b/server/nodes/whatsapp/__init__.py@@ -26,6 +26,12 @@ from services.ws_handler_registry import (register_ws_handlers,)+from ._events import ( # noqa: F401 — re-exported for callers+ broadcast_whatsapp_history_synced,+ broadcast_whatsapp_message,+ broadcast_whatsapp_newsletter,+ broadcast_whatsapp_status,+)from ._filters import build_filter as build_whatsapp_filterfrom ._handlers import WS_HANDLERSfrom ._option_loaders import load_channels, load_group_members, load_groupsdiff --git a/server/nodes/whatsapp/_events.py b/server/nodes/whatsapp/_events.pynew file mode 100644index 00000000..32305a23--- /dev/null+++ b/server/nodes/whatsapp/_events.py@@ -0,0 +1,276 @@+"""Wave 12 B2: CloudEvents factories + broadcaster wrappers for whatsapp.++Plugin-specific event emission — replaces:+ - 10 ``broadcaster.update_whatsapp_status(...)`` callsites (event+ handlers + status / start / restart WS handlers)+ - 7 ``broadcaster.send_custom_event("whatsapp_*", ...)`` callsites+ (message_sent / message_received / 4 newsletter events /+ history_sync_complete)++…all of which previously emitted raw dicts and lived as a tangle in+``_service.py``. After B2 every whatsapp wire frame originates from+exactly one wrapper in this module — single source of truth for shape.++Per RFC plugin_authoring_rfc.md §6.4:+ - Plugin-specific factories live in the plugin folder (NOT central+ ``services/events/envelope.py``).+ - Cross-cutting factories (``credential``, ``oauth_completed``, …)+ stay in central envelope.++Wire format preserved from the pre-migration shape (so FE consumers+keep working). Each wrapper dual-emits:+ - Legacy raw frame: ``{type: <legacy_key>, data: <raw payload>}``+ - Typed CloudEvents sibling: ``{type: <typed_wire_key>, data:+ <WorkflowEvent envelope>}``++Status events use the existing ``plugin_connection_status`` typed+channel (matches Wave 11.I X4 + the B1 android migration); message /+newsletter / history events use new dedicated typed channels.+"""++from __future__ import annotations++import time+from typing import Any, Dict, Literal, Mapping, Optional++from services.events.envelope import WorkflowEvent+++# ---- Wire-routing keys (outer ``type`` field the FE switches on) -----------+#+# Unchanged from the pre-B2 shape per RFC §11 (FE still routes on the+# legacy keys). Only the INNER ``data.type`` gains the ``com.machinaos.``+# reverse-DNS prefix via the typed CloudEvents factories below.++_STATUS_LEGACY_WIRE_KEY = "whatsapp_status"+_STATUS_TYPED_WIRE_KEY = "plugin_connection_status" # shared cross-plugin channel++_MESSAGE_SENT_WIRE_KEY = "whatsapp_message_sent"+_MESSAGE_RECEIVED_WIRE_KEY = "whatsapp_message_received"++_NEWSLETTER_WIRE_KEYS: Dict[str, str] = {+ "joined": "whatsapp_newsletter_join",+ "left": "whatsapp_newsletter_leave",+ "muted": "whatsapp_newsletter_mute_change",+ "live_updated": "whatsapp_newsletter_live_update",+}++_HISTORY_SYNCED_WIRE_KEY = "whatsapp_history_sync_complete"+++# ---- Typed factories (plugin-specific per RFC §6.4) ------------------------+++def whatsapp_connection_status(+ *,+ connected: bool,+ has_session: bool = False,+ running: bool = False,+ pairing: bool = False,+ device_id: Optional[str] = None,+ qr: Optional[str] = None,+) -> WorkflowEvent:+ """Connection-state envelope. ``subject`` is the device_id so the+ FE can route per-device updates."""+ return WorkflowEvent(+ source="machinaos://nodes/whatsapp",+ type=(+ "com.machinaos.whatsapp.connection.opened"+ if connected+ else "com.machinaos.whatsapp.connection.closed"+ ),+ subject=device_id,+ data={+ "connected": connected,+ "has_session": has_session,+ "running": running,+ "pairing": pairing,+ "device_id": device_id,+ "qr": qr,+ },+ )+++def whatsapp_message_event(+ direction: Literal["sent", "received"],+ params: Mapping[str, Any],+) -> WorkflowEvent:+ """Message envelope (sent or received). Subject auto-extracted+ from the params payload (chat_id / sender / from)."""+ payload = dict(params)+ subject = (+ payload.get("chat_id")+ or payload.get("sender")+ or payload.get("from")+ )+ return WorkflowEvent(+ source="machinaos://nodes/whatsapp",+ type=f"com.machinaos.whatsapp.message.{direction}",+ subject=str(subject) if subject else None,+ data=payload,+ )+++def whatsapp_newsletter_event(+ verb: Literal["joined", "left", "muted", "live_updated"],+ params: Mapping[str, Any],+) -> WorkflowEvent:+ """Newsletter-lifecycle envelope. Subject auto-extracted from+ ``newsletter_jid`` if present in params."""+ payload = dict(params)+ subject = payload.get("newsletter_jid") or payload.get("jid")+ return WorkflowEvent(+ source="machinaos://nodes/whatsapp",+ type=f"com.machinaos.whatsapp.newsletter.{verb}",+ subject=str(subject) if subject else None,+ data=payload,+ )+++def whatsapp_history_synced(params: Mapping[str, Any]) -> WorkflowEvent:+ """History-sync-complete envelope. Subject is the device_id when+ available in the params payload."""+ payload = dict(params)+ subject = payload.get("device_id")+ return WorkflowEvent(+ source="machinaos://nodes/whatsapp",+ type="com.machinaos.whatsapp.history.synced",+ subject=str(subject) if subject else None,+ data=payload,+ )+++# ---- Broadcaster wrappers --------------------------------------------------+++async def broadcast_whatsapp_status(+ *,+ connected: bool,+ has_session: bool = False,+ running: bool = False,+ pairing: bool = False,+ device_id: Optional[str] = None,+ qr: Optional[str] = None,+) -> None:+ """Update the whatsapp status cache + emit both the legacy raw+ ``whatsapp_status`` frame AND the typed+ ``plugin_connection_status`` CloudEvents sibling.++ Replaces ``StatusBroadcaster.update_whatsapp_status``.+ """+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()++ payload: Dict[str, Any] = {+ "connected": connected,+ "has_session": has_session,+ "running": running,+ "pairing": pairing,+ "device_id": device_id,+ "qr": qr,+ "timestamp": time.time(),+ }+ broadcaster._status["whatsapp"] = payload++ # Legacy raw frame (FE back-compat).+ await broadcaster.broadcast({+ "type": _STATUS_LEGACY_WIRE_KEY,+ "data": payload,+ })++ # Typed CloudEvents sibling — shared `plugin_connection_status` channel.+ event = whatsapp_connection_status(+ connected=connected,+ has_session=has_session,+ running=running,+ pairing=pairing,+ device_id=device_id,+ qr=qr,+ )+ await broadcaster.broadcast({+ "type": _STATUS_TYPED_WIRE_KEY,+ "data": event.model_dump(mode="json"),+ })+++async def broadcast_whatsapp_message(+ direction: Literal["sent", "received"],+ params: Mapping[str, Any],+) -> None:+ """Emit a message event (sent or received). Wire-routing key+ preserves the legacy ``whatsapp_message_<direction>`` channel."""+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()+ wire_key = (+ _MESSAGE_SENT_WIRE_KEY if direction == "sent"+ else _MESSAGE_RECEIVED_WIRE_KEY+ )++ # Legacy raw frame.+ await broadcaster.broadcast({+ "type": wire_key,+ "data": dict(params),+ })++ # Typed CloudEvents sibling — same outer wire key (the inner+ # envelope is what carries the typed contract).+ event = whatsapp_message_event(direction, params)+ await broadcaster.broadcast({+ "type": wire_key,+ "data": event.model_dump(mode="json"),+ })+++async def broadcast_whatsapp_newsletter(+ verb: Literal["joined", "left", "muted", "live_updated"],+ params: Mapping[str, Any],+) -> None:+ """Emit a newsletter-lifecycle event. ``verb`` selects the+ legacy wire key from :data:`_NEWSLETTER_WIRE_KEYS`."""+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()+ wire_key = _NEWSLETTER_WIRE_KEYS[verb]++ await broadcaster.broadcast({+ "type": wire_key,+ "data": dict(params),+ })++ event = whatsapp_newsletter_event(verb, params)+ await broadcaster.broadcast({+ "type": wire_key,+ "data": event.model_dump(mode="json"),+ })+++async def broadcast_whatsapp_history_synced(params: Mapping[str, Any]) -> None:+ """Emit a history-sync-complete event."""+ from services.status_broadcaster import get_status_broadcaster++ broadcaster = get_status_broadcaster()++ await broadcaster.broadcast({+ "type": _HISTORY_SYNCED_WIRE_KEY,+ "data": dict(params),+ })++ event = whatsapp_history_synced(params)+ await broadcaster.broadcast({+ "type": _HISTORY_SYNCED_WIRE_KEY,+ "data": event.model_dump(mode="json"),+ })+++__all__ = [+ "broadcast_whatsapp_history_synced",+ "broadcast_whatsapp_message",+ "broadcast_whatsapp_newsletter",+ "broadcast_whatsapp_status",+ "whatsapp_connection_status",+ "whatsapp_history_synced",+ "whatsapp_message_event",+ "whatsapp_newsletter_event",+]diff --git a/server/nodes/whatsapp/_refresh.py b/server/nodes/whatsapp/_refresh.pyindex e8cd4cd4..af2b9691 100644--- a/server/nodes/whatsapp/_refresh.py+++ b/server/nodes/whatsapp/_refresh.py@@ -28,32 +28,30 @@ tracer = trace.get_tracer(__name__)async def refresh_whatsapp_status(broadcaster: "StatusBroadcaster") -> None:"""Refresh WhatsApp cache + broadcast. One pass per- ``_refresh_all_services`` cycle.+ ``_refresh_all_services`` cycle. Wave 12 B2 — routes through the+ plugin's canonical broadcaster wrapper so the wire shape is+ single-sourced in ``_events.py``."""with tracer.start_as_current_span("broadcaster.refresh_whatsapp") as span:try:+ from ._events import broadcast_whatsapp_statusfrom ._service import get_clientclient = await get_client()status_data = await client.call("status")- broadcaster._status["whatsapp"] = {- "connected": status_data.get("connected", False),- "has_session": status_data.get("has_session", False),- "running": status_data.get("running", False),- "pairing": status_data.get("pairing", False),- "device_id": status_data.get("device_id"),- "qr": None,- "timestamp": time.time(),- }+ await broadcast_whatsapp_status(+ connected=status_data.get("connected", False),+ has_session=status_data.get("has_session", False),+ running=status_data.get("running", False),+ pairing=status_data.get("pairing", False),+ device_id=status_data.get("device_id"),+ qr=None,+ )logger.debug("[StatusBroadcaster] Refreshed WhatsApp status: connected=%s",status_data.get("connected"),)- await broadcaster.broadcast({- "type": "whatsapp_status",- "data": broadcaster._status["whatsapp"],- })span.set_attribute("connected", bool(status_data.get("connected", False)))except Exception as exc: # noqa: BLE001span.record_exception(exc)diff --git a/server/nodes/whatsapp/_service.py b/server/nodes/whatsapp/_service.pyindex 95928987..3a2b5ab7 100644--- a/server/nodes/whatsapp/_service.py+++ b/server/nodes/whatsapp/_service.py@@ -133,114 +133,119 @@ class RPCClient:logger.debug(f"[WhatsApp RPC] Event: {method}")try:- from services.status_broadcaster import get_status_broadcaster- broadcaster = get_status_broadcaster()+ # Wave 12 B2: all whatsapp wire emission routes through the+ # plugin's _events.py wrappers — single source of truth for+ # shape. No more direct broadcaster.* reaches into framework.+ from . import (+ broadcast_whatsapp_history_synced,+ broadcast_whatsapp_message,+ broadcast_whatsapp_newsletter,+ broadcast_whatsapp_status,+ )if method == "event.status":# Initial status sent on WebSocket connection- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=params.get("connected", False),has_session=params.get("has_session", False),running=params.get("running", False),pairing=params.get("pairing", False),device_id=params.get("device_id"),- qr=None+ qr=None,)elif method == "event.connected":# Connected successfully with device_id- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=True,has_session=True,running=True,pairing=False,device_id=params.get("device_id"),- qr=None+ qr=None,)elif method == "event.disconnected":# Disconnected - service still running- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False,device_id=None,- qr=None+ qr=None,)elif method == "event.connection_failure":# Connection failedlogger.error(f"[WhatsApp] Connection failure: {params.get('error')} - {params.get('reason')}")- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False,device_id=None,- qr=None+ qr=None,)elif method == "event.logged_out":# Logged out - session clearedlogger.warning(f"[WhatsApp] Logged out: {params.get('reason')}")- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False,device_id=None,- qr=None+ qr=None,)elif method == "event.temporary_ban":# Temporary banlogger.error(f"[WhatsApp] Temporary ban: code={params.get('code')} reason={params.get('reason')}")- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False,device_id=None,- qr=None+ qr=None,)elif method == "event.qr_code":# New QR code available for pairingcode = params.get("code")qr_image = qr_code_to_base64(code) if code else None- await broadcaster.update_whatsapp_status(+ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=True,device_id=None,- qr=qr_image+ qr=qr_image,)elif method == "event.message_sent":- # Message sent - broadcast as custom event- await broadcaster.send_custom_event("whatsapp_message_sent", params)+ await broadcast_whatsapp_message("sent", params)elif method == "event.message_received":- # Message received - broadcast as custom event for trigger nodes- # (includes newsletter messages with newsletter_meta field)- await broadcaster.send_custom_event("whatsapp_message_received", params)+ # Includes newsletter messages with newsletter_meta field.+ await broadcast_whatsapp_message("received", params)elif method == "event.newsletter_join":- await broadcaster.send_custom_event("whatsapp_newsletter_join", params)+ await broadcast_whatsapp_newsletter("joined", params)elif method == "event.newsletter_leave":- await broadcaster.send_custom_event("whatsapp_newsletter_leave", params)+ await broadcast_whatsapp_newsletter("left", params)elif method == "event.newsletter_mute_change":- await broadcaster.send_custom_event("whatsapp_newsletter_mute_change", params)+ await broadcast_whatsapp_newsletter("muted", params)elif method == "event.newsletter_live_update":- await broadcaster.send_custom_event("whatsapp_newsletter_live_update", params)+ await broadcast_whatsapp_newsletter("live_updated", params)elif method == "event.history_sync_complete":- await broadcaster.send_custom_event("whatsapp_history_sync_complete", params)+ await broadcast_whatsapp_history_synced(params)# Forward to custom handler if setif self._event_handler:@@ -353,16 +358,16 @@ async def handle_whatsapp_status() -> dict:client = await get_client()status_data = await client.call("status")- # Broadcast status update to all connected WebSocket clients- from services.status_broadcaster import get_status_broadcaster- broadcaster = get_status_broadcaster()- await broadcaster.update_whatsapp_status(+ # Broadcast status via the plugin's canonical wrapper (Wave 12 B2).+ from . import broadcast_whatsapp_status++ await broadcast_whatsapp_status(connected=status_data.get("connected", False),has_session=status_data.get("has_session", False),running=status_data.get("running", False),pairing=status_data.get("pairing", False),device_id=status_data.get("device_id"),- qr=None # QR code comes from event.qr_code events+ qr=None, # QR code comes from event.qr_code events)device_id = status_data.get("device_id")@@ -652,15 +657,15 @@ async def handle_whatsapp_start() -> dict:result = await client.call("start")# Broadcast that service is now running (waiting for QR or connection)- from services.status_broadcaster import get_status_broadcaster- broadcaster = get_status_broadcaster()- await broadcaster.update_whatsapp_status(+ from . import broadcast_whatsapp_status++ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False, # Will be set to True by event.qr_code eventdevice_id=None,- qr=None+ qr=None,)return {@@ -685,15 +690,15 @@ async def handle_whatsapp_restart() -> dict:client = await get_client(force_reconnect=True)# Broadcast that we're restarting (brief disconnected state)- from services.status_broadcaster import get_status_broadcaster- broadcaster = get_status_broadcaster()- await broadcaster.update_whatsapp_status(+ from . import broadcast_whatsapp_status++ await broadcast_whatsapp_status(connected=False,has_session=False,running=True,pairing=False,device_id=None,- qr=None+ qr=None,)# Call restart RPC methoddiff --git a/server/services/status_broadcaster.py b/server/services/status_broadcaster.pyindex c62da6bf..c404ec8c 100644--- a/server/services/status_broadcaster.py+++ b/server/services/status_broadcaster.py@@ -595,41 +595,11 @@ class StatusBroadcaster:# zero per-plugin knowledge.# =========================================================================- async def update_whatsapp_status(- self,- connected: bool,- has_session: bool = False,- running: bool = False,- pairing: bool = False,- device_id: Optional[str] = None,- qr: Optional[str] = None- ):- """Update WhatsApp connection status and broadcast.-- Emits both the legacy ``whatsapp_status`` raw frame and a- CloudEvents-typed sibling (Wave 11.I, X4).- """- import time- self._status["whatsapp"] = {- "connected": connected,- "has_session": has_session,- "running": running,- "pairing": pairing,- "device_id": device_id,- "qr": qr,- "timestamp": time.time()- }-- await self.broadcast({- "type": "whatsapp_status",- "data": self._status["whatsapp"]- })- await self._emit_connection_typed(- plugin="whatsapp",- connected=connected,- subject=device_id,- data=self._status["whatsapp"],- )+ # Wave 12 B2: ``update_whatsapp_status`` MOVED to+ # ``nodes/whatsapp/_events.py:broadcast_whatsapp_status``. Plus the+ # 7 send_custom_event callsites (message_sent/received, 4 newsletter+ # events, history_sync_complete) all moved to the plugin's+ # ``_events.py`` typed wrappers. Status cache slot stays here.# =========================================================================# Telegram Status Updatesdiff --git a/server/tests/test_status_broadcasts.py b/server/tests/test_status_broadcasts.pyindex bf39aee7..5911924a 100644--- a/server/tests/test_status_broadcasts.py+++ b/server/tests/test_status_broadcasts.py@@ -79,18 +79,19 @@ _TELEMETRY_CARVE_OUT: FrozenSet[str] = frozenset({_LEGACY_RAW_DICT_BROADCASTS: FrozenSet[str] = frozenset({# Wave 12 B1: ``update_android_status`` retired; moved to# ``nodes/android/_events.py:broadcast_android_status``.- "update_whatsapp_status", # FE: WhatsAppStatusPanel reads `whatsapp_status` wire-frame+ # Wave 12 B2: ``update_whatsapp_status`` retired; moved to+ # ``nodes/whatsapp/_events.py:broadcast_whatsapp_status``."update_telegram_status", # FE: TelegramStatusPanel reads `telegram_status` wire-frame})# ``send_custom_event`` callers that still pass raw dicts. Each entry# documents WHY. Per-plugin migration unlocks each one.+#+# Wave 12 B2: ``nodes/whatsapp/_service.py`` retired — all 7+# send_custom_event callsites (message_sent/received + 4 newsletter+# events + history_sync_complete) moved to typed CloudEvents wrappers+# in ``nodes/whatsapp/_events.py``._LEGACY_RAW_DICT_CALLSITES: FrozenSet[str] = frozenset({- # WhatsApp event router emits 7 distinct wire types. Migration would- # also rename ``whatsapp_message_received`` etc. to- # ``whatsapp.message.received`` namespaced types, requiring FE- # listener updates.- "nodes/whatsapp/_service.py",# Webhook router emits ``webhook_received``. Webhook payload is# arbitrary JSON; the consumer (webhookTrigger node) shape is# already abstract, so a typed envelope adds little value.