feat(gateway): add gateway domain primitives

surfsense_backend/app/gateway/base/__init__.py

@@ -0,0 +1,2 @@
+"""Base gateway interfaces."""
+

surfsense_backend/app/gateway/base/adapter.py

@@ -0,0 +1,70 @@
+"""Platform adapter interfaces for messaging gateways."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ParsedInboundEvent:
+    platform: str
+    event_kind: str
+    external_peer_id: str | None
+    external_peer_kind: str
+    external_message_id: str | None
+    external_user_id: str | None
+    text: str | None
+    raw_payload: dict[str, Any]
+    display_name: str | None = None
+    username: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class PlatformSendResult:
+    external_message_id: str
+    raw_response: dict[str, Any] = field(default_factory=dict)
+
+
+class BasePlatformAdapter(ABC):
+    platform: str
+
+    @abstractmethod
+    def parse_inbound(self, raw_payload: dict[str, Any]) -> ParsedInboundEvent:
+        """Parse a provider webhook/update into the gateway's normalized shape."""
+
+    @abstractmethod
+    async def send_message(
+        self,
+        *,
+        external_peer_id: str,
+        text: str,
+        parse_mode: str | None = None,
+        reply_to_message_id: str | None = None,
+    ) -> PlatformSendResult:
+        """Send a new platform message."""
+
+    @abstractmethod
+    async def edit_message(
+        self,
+        *,
+        external_peer_id: str,
+        external_message_id: str,
+        text: str,
+        parse_mode: str | None = None,
+    ) -> PlatformSendResult:
+        """Edit an existing platform message."""
+
+    @abstractmethod
+    async def validate_credentials(self) -> dict[str, Any]:
+        """Validate configured credentials and return account metadata."""
+
+    async def fetch_updates(self, *, offset: int | None) -> AsyncIterator[dict[str, Any]]:
+        """Yield provider updates for long-polling adapters."""
+        if False:
+            yield {}  # pragma: no cover
+        raise NotImplementedError("This adapter does not support long-polling")
+

surfsense_backend/app/gateway/base/identity.py

@@ -0,0 +1,19 @@
+"""Gateway identity helpers."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def normalize_external_peer_id(value: str | int | None) -> str | None:
+    if value is None:
+        return None
+    return str(value).strip()
+
+
+def hash_external_id(value: str | int | None) -> str | None:
+    normalized = normalize_external_peer_id(value)
+    if not normalized:
+        return None
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+

surfsense_backend/app/gateway/base/translator.py

@@ -0,0 +1,28 @@
+"""Base stream translator for platform-specific outbound UX."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class GatewayStreamEvent:
+    """Small provider-neutral event shape consumed by translators.
+
+    The existing chat stack emits Vercel/assistant-ui events.  Gateway code
+    normalizes the subset it needs into this shape before handing it to the
+    platform translator.
+    """
+
+    type: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+class BaseStreamTranslator(ABC):
+    @abstractmethod
+    async def translate(self, events: AsyncIterator[GatewayStreamEvent]) -> None:
+        """Consume agent stream events and emit platform messages."""
+