machinaos 0.0.78 → 0.0.80

package/server/nodes/whatsapp/_credentials.py

@@ -0,0 +1,44 @@
+"""WhatsApp Personal credential stub.
+
+WhatsApp's "personal" connection is QR-paired session-based — the bot
+binary (``edgymeow``) handles the WebSocket session lifecycle and there's
+no API key / OAuth token to store. The credential class exists only so
+``CREDENTIAL_REGISTRY`` can resolve the ``whatsapp`` provider
+key (for catalogue icon lookup via
+:meth:`services.plugin.credential.Credential.get_icon_path`). It does
+NOT implement ``resolve()`` — connection-state queries go through the
+``whatsapp_status`` WebSocket flow + the QR-pairing UI, not through
+``auth_service.get_*``.
+
+See ``server/config/credential_providers.json`` (entry
+``whatsapp``) for the catalogue-level declaration of the QR
+pairing UI / status rows / actions. This module's only job is to make
+the icon endpoint find ``credential_whatsapp.svg`` co-located
+in this folder.
+"""
+
+from __future__ import annotations
+
+from services.plugin.credential import Credential
+
+
+class WhatsAppCredential(Credential):
+    """Catalogue stub for the QR-paired WhatsApp Personal connection.
+
+    Not an :class:`ApiKeyCredential` / :class:`OAuth2Credential` —
+    WhatsApp's pairing is session-based and managed entirely by the
+    :class:`~nodes.whatsapp._runtime.WhatsAppRuntime` supervisor +
+    WebSocket handlers. The class is registered into
+    ``CREDENTIAL_REGISTRY`` purely to give the catalogue icon endpoint
+    (``GET /api/schemas/credentials/whatsapp/icon``) a class
+    to call :meth:`get_icon_path` on. ``resolve()`` is never called
+    because no node plugin declares this credential in its
+    ``credentials`` tuple — the connection is implicit, mediated by
+    ``services.whatsapp_service`` and the runtime supervisor.
+    """
+
+    id = "whatsapp"
+    display_name = "WhatsApp Personal"
+    auth = "custom"
+    category = "Social"
+    docs_url = "https://faq.whatsapp.com/general/about-linked-devices"

package/server/nodes/whatsapp/_events.py

@@ -0,0 +1,277 @@
+"""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: still dual-emit on their legacy
+    wire keys until the matching FE handlers migrate to envelope-aware
+    readers (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.machinaos.``
+# reverse-DNS prefix via the typed CloudEvents factories below.
+
+_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 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 broadcast_whatsapp_message(
+    direction: Literal["sent", "received"],
+    params: Mapping[str, Any],
+) -> None:
+    """Emit a message event (sent or received).
+
+    Inbound (``received``) routes via :func:`services.events.dispatch.emit`
+    — the canary CloudEvents path Signals running
+    :class:`TriggerListenerWorkflow` consumers AND broadcasts the
+    envelope on the ``whatsapp_message_received`` wire key.
+
+    Outbound (``sent``) is observation-only: no trigger consumer
+    exists, so it bypasses ``dispatch.emit`` and goes out as a raw
+    legacy frame on ``whatsapp_message_sent`` for the FE message-list
+    UI.
+    """
+    from services.status_broadcaster import get_status_broadcaster
+
+    broadcaster = get_status_broadcaster()
+    payload = dict(params)
+
+    if direction == "received":
+        # Canary path — single ``emit`` call delivers to Temporal
+        # listeners + FE WS. The FE message-list handler at
+        # WebSocketContext.tsx still reads ``data.*`` for back-compat,
+        # so we also broadcast the legacy raw frame until that handler
+        # migrates to envelope-shape (Wave 12 D4 follow-up).
+        from services.events.dispatch import emit
+
+        await broadcaster.broadcast(
+            {
+                "type": _MESSAGE_RECEIVED_WIRE_KEY,
+                "data": payload,
+            }
+        )
+        await emit(
+            whatsapp_message_event("received", payload),
+            wire_routing_key=_MESSAGE_RECEIVED_WIRE_KEY,
+        )
+    else:
+        # Outbound observation only — direct legacy raw broadcast.
+        await broadcaster.broadcast(
+            {
+                "type": _MESSAGE_SENT_WIRE_KEY,
+                "data": payload,
+            }
+        )
+
+
+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, at which point this becomes a ``dispatch.emit``
+    call like :func:`broadcast_whatsapp_message`.
+    """
+    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_message",
+    "broadcast_whatsapp_newsletter",
+    "broadcast_whatsapp_status",
+    "whatsapp_connection_status",
+    "whatsapp_history_synced",
+    "whatsapp_message_event",
+    "whatsapp_newsletter_event",
+]

package/server/nodes/whatsapp/_filters.py

@@ -40,66 +40,65 @@ def build_filter(params: Dict) -> Callable[[Dict], bool]:
     - ``group_info`` -- present for group messages, with ``group_jid``
       / ``sender_jid`` / ``sender_phone`` / ``sender_name``
     """
-    msg_type = params.get('message_type_filter', 'all')
-    sender_filter = params.get('filter', 'all')
-    contact_phone = params.get('phone_number', '')
-    group_id = params.get('group_id', '')
-    sender_number = params.get('sender_number', '')
-    keywords = [
-        k.strip().lower()
-        for k in params.get('keywords', '').split(',')
-        if k.strip()
-    ]
-    ignore_own = params.get('ignore_own_messages', True)
-    forwarded_filter = params.get('forwarded_filter', 'all')
+    msg_type = params.get("message_type_filter", "all")
+    sender_filter = params.get("filter", "all")
+    contact_phone = params.get("phone_number", "")
+    group_id = params.get("group_id", "")
+    sender_number = params.get("sender_number", "")
+    keywords = [k.strip().lower() for k in params.get("keywords", "").split(",") if k.strip()]
+    ignore_own = params.get("ignore_own_messages", True)
+    forwarded_filter = params.get("forwarded_filter", "all")
 
     logger.debug(
         "[WhatsAppFilter] Built: type=%s, filter=%s, group_id=%r, forwarded=%s",
-        msg_type, sender_filter, group_id, forwarded_filter,
+        msg_type,
+        sender_filter,
+        group_id,
+        forwarded_filter,
     )
 
     def matches(m: Dict) -> bool:
-        msg_chat_id = m.get('chat_id', '')
-        is_group = m.get('is_group', False)
-        group_info = m.get('group_info', {})
+        msg_chat_id = m.get("chat_id", "")
+        is_group = m.get("is_group", False)
+        group_info = m.get("group_info", {})
 
         # Use sender_phone directly -- Go RPC already resolves LIDs.
         # For group messages, prefer group_info.sender_phone, fall back
         # to root sender_phone.
         if is_group:
-            sender_phone = group_info.get('sender_phone', '') or m.get('sender_phone', '')
+            sender_phone = group_info.get("sender_phone", "") or m.get("sender_phone", "")
         else:
-            sender_phone = m.get('sender_phone', '')
+            sender_phone = m.get("sender_phone", "")
 
         # Fallback: extract phone from sender JID if sender_phone absent.
         if not sender_phone:
-            sender = m.get('sender', '')
-            sender_phone = sender.split('@')[0] if '@' in sender else sender
+            sender = m.get("sender", "")
+            sender_phone = sender.split("@")[0] if "@" in sender else sender
 
         # Message type filter (schema field: message_type).
-        if msg_type != 'all' and m.get('message_type') != msg_type:
+        if msg_type != "all" and m.get("message_type") != msg_type:
             return False
 
         # Sender filter -- for ``contact`` filter, use actual phone.
-        if sender_filter == 'self':
+        if sender_filter == "self":
             # Self-chat (notes-to-self) only -- must be from me AND in
             # a chat with myself.
-            if not m.get('is_from_me'):
+            if not m.get("is_from_me"):
                 return False
-            chat_id = m.get('chat_id', '')
-            sender = m.get('sender', '')
+            chat_id = m.get("chat_id", "")
+            sender = m.get("sender", "")
             if chat_id != sender:
                 return False
 
-        if sender_filter == 'any_contact':
+        if sender_filter == "any_contact":
             if is_group:
                 return False
 
-        if sender_filter == 'contact':
+        if sender_filter == "contact":
             if contact_phone not in sender_phone:
                 return False
 
-        if sender_filter == 'group':
+        if sender_filter == "group":
             if not is_group:
                 return False
             if msg_chat_id != group_id:
@@ -109,26 +108,26 @@ def build_filter(params: Dict) -> Callable[[Dict], bool]:
                 if sender_number not in sender_phone:
                     return False
 
-        if sender_filter == 'channel':
-            if not msg_chat_id.endswith('@newsletter'):
+        if sender_filter == "channel":
+            if not msg_chat_id.endswith("@newsletter"):
                 return False
-            channel_jid = params.get('channel_jid', '')
+            channel_jid = params.get("channel_jid", "")
             if channel_jid and msg_chat_id != channel_jid:
                 return False
 
-        if sender_filter == 'keywords':
-            text = (m.get('text') or '').lower()
+        if sender_filter == "keywords":
+            text = (m.get("text") or "").lower()
             if not any(kw in text for kw in keywords):
                 return False
 
         # Ignore own messages -- but not when filtering for ``self``.
-        if ignore_own and sender_filter != 'self' and m.get('is_from_me'):
+        if ignore_own and sender_filter != "self" and m.get("is_from_me"):
             return False
 
-        is_forwarded = m.get('is_forwarded', False)
-        if forwarded_filter == 'only_forwarded' and not is_forwarded:
+        is_forwarded = m.get("is_forwarded", False)
+        if forwarded_filter == "only_forwarded" and not is_forwarded:
             return False
-        if forwarded_filter == 'ignore_forwarded' and is_forwarded:
+        if forwarded_filter == "ignore_forwarded" and is_forwarded:
             return False
 
         logger.debug("[WhatsAppFilter] Matched message from %s", sender_phone)

package/server/nodes/whatsapp/_handlers.py

@@ -80,6 +80,7 @@ async def handle_whatsapp_chat_history(data: Dict[str, Any], websocket: WebSocke
 
 # ---- Rate-limit RPC passthroughs ----
 
+
 async def handle_whatsapp_rate_limit_get(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
     """Get rate-limit config and current stats."""
     return await _wa_rpc_call("rate_limit_get", {})
@@ -102,6 +103,7 @@ async def handle_whatsapp_rate_limit_unpause(data: Dict[str, Any], websocket: We
 
 # ---- Lightweight RPC passthroughs ----
 
+
 async def handle_whatsapp_mark_read(data: Dict[str, Any], websocket: WebSocket) -> Dict[str, Any]:
     """Mark messages as read. Schema: mark_read({message_ids, chat_jid, sender_jid?})."""
     message_ids = data.get("message_ids", [])

package/server/nodes/whatsapp/_option_loaders.py

@@ -56,9 +56,7 @@ async def load_group_members(params: Dict[str, Any]) -> List[Dict[str, Any]]:
     if not group_id:
         return []
     response = await handle_whatsapp_group_info(group_id)
-    participants = (
-        response.get("participants", []) if isinstance(response, dict) else []
-    )
+    participants = response.get("participants", []) if isinstance(response, dict) else []
     return [
         {
             "value": p.get("phone") or p.get("jid") or "",

package/server/nodes/whatsapp/_refresh.py

@@ -14,7 +14,6 @@ pre-migration behaviour.
 from __future__ import annotations
 
 import logging
-import time
 from typing import TYPE_CHECKING
 
 from opentelemetry import trace
@@ -28,35 +27,31 @@ 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)
-            logger.debug(
-                "[StatusBroadcaster] Could not refresh WhatsApp status: %s", exc
-            )
+            logger.debug("[StatusBroadcaster] Could not refresh WhatsApp status: %s", exc)

package/server/nodes/whatsapp/_runtime.py

@@ -36,6 +36,7 @@ class WhatsAppRuntime(BaseProcessSupervisor):
         super().__init__()
         if settings is None:
             from core.config import Settings
+
             settings = Settings()
         self.settings = settings
 
@@ -43,11 +44,12 @@ class WhatsAppRuntime(BaseProcessSupervisor):
 
     @property
     def data_root(self) -> Path:
-        sub = getattr(self.settings, "whatsapp_data_subdir", "whatsapp")
-        base = Path(self.settings.data_dir)
-        if not base.is_absolute():
-            base = _PROJECT_ROOT / "server" / base
-        return (base / sub).resolve()
+        # Routes through ``Settings._resolve_under_data`` so dev mode's
+        # ``DATA_DIR=.machina`` lands the WhatsApp tree at
+        # ``<repo>/.machina/whatsapp/`` (not ``<repo>/server/.machina/...``,
+        # which the old ad-hoc ``_PROJECT_ROOT / "server" / data_dir``
+        # logic produced when ``DATA_DIR`` was relative).
+        return Path(self.settings._resolve_under_data(self.settings.whatsapp_data_subdir))
 
     @property
     def port(self) -> int:
@@ -107,7 +109,8 @@ class WhatsAppRuntime(BaseProcessSupervisor):
         config["server"]["port"] = self.port
         config["server"]["host"] = self.bind_host
         (self.data_root / "configs" / "config.yaml").write_text(
-            yaml.safe_dump(config, sort_keys=False), encoding="utf-8",
+            yaml.safe_dump(config, sort_keys=False),
+            encoding="utf-8",
         )