Skip to content

Self-improving AI Employees for everyone

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__.py
index 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_filter
from ._handlers import WS_HANDLERS
from ._option_loaders import load_channels, load_group_members, load_groups
diff --git a/server/nodes/whatsapp/_events.py b/server/nodes/whatsapp/_events.py
new file mode 100644
index 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.py
index 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_status
from ._service import get_client
client = 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: BLE001
span.record_exception(exc)
diff --git a/server/nodes/whatsapp/_service.py b/server/nodes/whatsapp/_service.py
index 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 failed
logger.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 cleared
logger.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 ban
logger.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 pairing
code = 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 set
if 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 event
device_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 method
diff --git a/server/services/status_broadcaster.py b/server/services/status_broadcaster.py
index 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 Updates
diff --git a/server/tests/test_status_broadcasts.py b/server/tests/test_status_broadcasts.py
index 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.