Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""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 (Wave 12 D4 — legacy ``whatsapp_status`` raw frame retired):
- Status: typed CloudEvents envelope on ``plugin_connection_status``
(FE routes by ``envelope.source``).
- Message / newsletter / history: one-way legacy WS frames on their
``whatsapp_*`` wire keys (no envelope twin). The FE handlers still
route on those keys; migrating them to envelope-aware readers is a
follow-up D4 round.
"""
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.opencompany.``
# reverse-DNS prefix via the typed CloudEvents factories below.
_STATUS_TYPED_WIRE_KEY = "plugin_connection_status" # shared cross-plugin channel
_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="opencompany://nodes/whatsapp",
type=("com.opencompany.whatsapp.connection.opened" if connected else "com.opencompany.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")
message_id = payload.get("message_id")
fields = {"id": f"whatsapp:{direction}:{subject}:{message_id}"} if subject and message_id else {}
return WorkflowEvent(
**fields,
source="opencompany://nodes/whatsapp",
type=f"com.opencompany.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="opencompany://nodes/whatsapp",
type=f"com.opencompany.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="opencompany://nodes/whatsapp",
type="com.opencompany.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 the typed
``plugin_connection_status`` CloudEvents envelope.
Replaces ``StatusBroadcaster.update_whatsapp_status``. Legacy raw
``whatsapp_status`` frame retired in Wave 12 D4 — FE consumes via
the envelope-aware ``plugin_connection_status`` case.
"""
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
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 emit_whatsapp_message_received(params: Mapping[str, Any]) -> None:
"""Deliver an inbound message to the deployed ``whatsappReceive``
triggers through :func:`services.events.dispatch.emit`.
Not broadcast: the message is a customer's content, and every
connected socket would receive it, while no client reads it.
"""
from services.events.dispatch import emit
await emit(
whatsapp_message_event("received", dict(params)),
wire_routing_key=_MESSAGE_RECEIVED_WIRE_KEY,
broadcast=False,
)
async def broadcast_whatsapp_newsletter(
verb: Literal["joined", "left", "muted", "live_updated"],
params: Mapping[str, Any],
) -> None:
"""Emit a newsletter-lifecycle event for FE observation.
Not a trigger event — no canary consumer. Direct raw broadcast on
the legacy wire key until the FE newsletter UI migrates to read
the envelope shape.
"""
from services.status_broadcaster import get_status_broadcaster
broadcaster = get_status_broadcaster()
await broadcaster.broadcast(
{
"type": _NEWSLETTER_WIRE_KEYS[verb],
"data": dict(params),
}
)
async def broadcast_whatsapp_history_synced(params: Mapping[str, Any]) -> None:
"""Emit a history-sync-complete event for FE observation.
Not a trigger event — no canary consumer. Direct raw broadcast.
"""
from services.status_broadcaster import get_status_broadcaster
broadcaster = get_status_broadcaster()
await broadcaster.broadcast(
{
"type": _HISTORY_SYNCED_WIRE_KEY,
"data": dict(params),
}
)
__all__ = [
"broadcast_whatsapp_history_synced",
"broadcast_whatsapp_newsletter",
"broadcast_whatsapp_status",
"emit_whatsapp_message_received",
"whatsapp_connection_status",
"whatsapp_history_synced",
"whatsapp_message_event",
"whatsapp_newsletter_event",
]