roomkit 0.1.0__py3-none-any.whl

roomkit/core/framework.py

@@ -0,0 +1,793 @@
+"""RoomKit - central orchestrator for multi-channel conversations."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from roomkit.models.delivery import InboundMessage, InboundResult
+    from roomkit.providers.sms.meta import WebhookMeta
+
+from roomkit.channels.base import Channel
+from roomkit.channels.websocket import SendFn, WebSocketChannel
+from roomkit.core._channel_ops import ChannelOpsMixin
+from roomkit.core._helpers import FrameworkEventHandler, HelpersMixin, IdentityHookFn
+from roomkit.core._inbound import InboundMixin
+from roomkit.core._room_lifecycle import RoomLifecycleMixin
+from roomkit.core.event_router import EventRouter
+from roomkit.core.hooks import (
+    AsyncHookFn,
+    HookEngine,
+    HookRegistration,
+    IdentityHookRegistration,
+    SyncHookFn,
+)
+from roomkit.core.inbound_router import DefaultInboundRoomRouter, InboundRoomRouter
+from roomkit.core.locks import InMemoryLockManager, RoomLockManager
+from roomkit.core.transcoder import DefaultContentTranscoder
+from roomkit.identity.base import IdentityResolver
+from roomkit.models.delivery import DeliveryStatus
+from roomkit.models.enums import (
+    ChannelDirection,
+    ChannelType,
+    EventStatus,
+    EventType,
+    HookExecution,
+    HookTrigger,
+)
+from roomkit.models.event import EventSource, RoomEvent
+from roomkit.models.task import Observation, Task
+from roomkit.realtime.base import (
+    EphemeralCallback,
+    EphemeralEvent,
+    EphemeralEventType,
+    RealtimeBackend,
+)
+from roomkit.realtime.memory import InMemoryRealtime
+from roomkit.sources.base import SourceHealth, SourceProvider, SourceStatus
+from roomkit.store.base import ConversationStore
+from roomkit.store.memory import InMemoryStore
+
+# Type alias for delivery status handlers
+DeliveryStatusHandler = Callable[[DeliveryStatus], Any]
+
+# Re-export type aliases so existing imports continue to work
+__all__ = [
+    "ChannelNotFoundError",
+    "ChannelNotRegisteredError",
+    "FrameworkEventHandler",
+    "IdentityHookFn",
+    "IdentityNotFoundError",
+    "ParticipantNotFoundError",
+    "RoomKit",
+    "RoomKitError",
+    "RoomNotFoundError",
+    "SourceAlreadyAttachedError",
+    "SourceNotFoundError",
+]
+
+
+class RoomKitError(Exception):
+    """Base exception for all RoomKit errors."""
+
+
+class RoomNotFoundError(RoomKitError):
+    """Room does not exist."""
+
+
+class ChannelNotFoundError(RoomKitError):
+    """Channel binding not found in room."""
+
+
+class ChannelNotRegisteredError(RoomKitError):
+    """Channel type not registered."""
+
+
+class ParticipantNotFoundError(RoomKitError):
+    """Participant not found in room."""
+
+
+class IdentityNotFoundError(RoomKitError):
+    """Identity not found."""
+
+
+class SourceAlreadyAttachedError(RoomKitError):
+    """Source already attached to channel."""
+
+
+class SourceNotFoundError(RoomKitError):
+    """Source not found for channel."""
+
+
+class RoomKit(InboundMixin, ChannelOpsMixin, RoomLifecycleMixin, HelpersMixin):
+    """Central orchestrator tying rooms, channels, hooks, and storage."""
+
+    def __init__(
+        self,
+        store: ConversationStore | None = None,
+        identity_resolver: IdentityResolver | None = None,
+        identity_channel_types: set[ChannelType] | None = None,
+        inbound_router: InboundRoomRouter | None = None,
+        lock_manager: RoomLockManager | None = None,
+        realtime: RealtimeBackend | None = None,
+        max_chain_depth: int = 5,
+        identity_timeout: float = 10.0,
+        process_timeout: float = 30.0,
+    ) -> None:
+        """Initialise the RoomKit orchestrator.
+
+        Args:
+            store: Persistent storage backend. Defaults to ``InMemoryStore``.
+            identity_resolver: Optional resolver for identifying inbound senders.
+            identity_channel_types: Restrict identity resolution to specific channel
+                types. If ``None`` (default), resolution runs for all channels.
+                Set to e.g. ``{ChannelType.SMS}`` to only resolve identity for SMS.
+            inbound_router: Strategy for routing inbound messages to rooms.
+                Defaults to ``DefaultInboundRoomRouter``.
+            lock_manager: Per-room locking backend. Defaults to
+                ``InMemoryLockManager``.  For multi-process deployments,
+                supply a distributed implementation (e.g. Redis-backed).
+            realtime: Realtime backend for ephemeral events (typing, presence).
+                Defaults to ``InMemoryRealtime``. For multi-process deployments,
+                supply a distributed implementation (e.g. Redis pub/sub).
+            max_chain_depth: Maximum reentry chain depth to prevent infinite loops.
+            identity_timeout: Timeout in seconds for identity resolution calls.
+            process_timeout: Timeout in seconds for the locked processing phase.
+        """
+        self._store = store or InMemoryStore()
+        self._identity_resolver = identity_resolver
+        self._identity_channel_types = identity_channel_types
+        self._max_chain_depth = max_chain_depth
+        self._identity_timeout = identity_timeout
+        self._process_timeout = process_timeout
+        self._channels: dict[str, Channel] = {}
+        self._hook_engine = HookEngine()
+        self._lock_manager = lock_manager or InMemoryLockManager()
+        self._realtime = realtime or InMemoryRealtime()
+        self._transcoder = DefaultContentTranscoder()
+        self._event_handlers: list[tuple[str, FrameworkEventHandler]] = []
+        self._identity_hooks: dict[HookTrigger, list[IdentityHookRegistration]] = {}
+        self._delivery_status_handlers: list[DeliveryStatusHandler] = []
+        self._inbound_router = inbound_router or DefaultInboundRoomRouter(self._store)
+        self._event_router: EventRouter | None = None
+        # Event-driven sources
+        self._sources: dict[str, SourceProvider] = {}
+        self._source_tasks: dict[str, asyncio.Task[None]] = {}
+
+    @property
+    def store(self) -> ConversationStore:
+        """The backing conversation store."""
+        return self._store
+
+    @property
+    def hook_engine(self) -> HookEngine:
+        """The hook engine used for sync/async hook pipelines."""
+        return self._hook_engine
+
+    @property
+    def realtime(self) -> RealtimeBackend:
+        """The realtime backend for ephemeral events."""
+        return self._realtime
+
+    def _get_router(self) -> EventRouter:
+        if self._event_router is None:
+            self._event_router = EventRouter(
+                channels=self._channels,
+                transcoder=self._transcoder,
+                max_chain_depth=self._max_chain_depth,
+            )
+        return self._event_router
+
+    async def close(self) -> None:
+        """Close all sources, channels, and the realtime backend."""
+        # Stop all event sources first
+        for channel_id in list(self._sources.keys()):
+            await self.detach_source(channel_id)
+        # Then close channels
+        for channel in self._channels.values():
+            await channel.close()
+        await self._realtime.close()
+
+    async def __aenter__(self) -> RoomKit:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    # -- Queries --
+
+    async def get_timeline(
+        self,
+        room_id: str,
+        offset: int = 0,
+        limit: int = 50,
+        visibility_filter: str | None = None,
+    ) -> list[RoomEvent]:
+        """Query the event timeline for a room."""
+        await self.get_room(room_id)
+        return await self._store.list_events(
+            room_id,
+            offset=offset,
+            limit=limit,
+            visibility_filter=visibility_filter,
+        )
+
+    async def list_tasks(self, room_id: str, status: str | None = None) -> list[Task]:
+        """List tasks for a room, optionally filtered by status."""
+        return await self._store.list_tasks(room_id, status=status)
+
+    async def list_observations(self, room_id: str) -> list[Observation]:
+        """List observations for a room."""
+        return await self._store.list_observations(room_id)
+
+    # -- Direct send --
+
+    async def send_event(
+        self,
+        room_id: str,
+        channel_id: str,
+        content: Any,
+        event_type: EventType = EventType.MESSAGE,
+        chain_depth: int = 0,
+        participant_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        visibility: str = "all",
+    ) -> RoomEvent:
+        """Send an event directly into a room from a channel.
+
+        Args:
+            room_id: Target room ID
+            channel_id: Source channel ID
+            content: Event content (TextContent, RichContent, etc.)
+            event_type: Type of event (default MESSAGE)
+            chain_depth: Depth in response chain (for loop prevention)
+            participant_id: Optional participant/sender ID for the event source
+            metadata: Optional event metadata
+            visibility: Event visibility ("all" or "internal")
+        """
+        await self.get_room(room_id)
+        binding = await self._get_binding(room_id, channel_id)
+
+        event = RoomEvent(
+            room_id=room_id,
+            type=event_type,
+            source=EventSource(
+                channel_id=channel_id,
+                channel_type=binding.channel_type,
+                participant_id=participant_id,
+            ),
+            content=content,
+            chain_depth=chain_depth,
+            status=EventStatus.DELIVERED,
+            metadata=metadata or {},
+            visibility=visibility,
+        )
+
+        async with self._lock_manager.locked(room_id):
+            count = await self._store.get_event_count(room_id)
+            event = event.model_copy(update={"index": count})
+            await self._store.add_event(event)
+
+            context = await self._build_context(room_id)
+            router = self._get_router()
+            await router.broadcast(event, binding, context)
+
+        return event
+
+    # -- WebSocket lifecycle --
+
+    async def connect_websocket(
+        self, channel_id: str, connection_id: str, send_fn: SendFn
+    ) -> None:
+        """Register a WebSocket connection and emit framework event."""
+        channel = self._channels.get(channel_id)
+        if not isinstance(channel, WebSocketChannel):
+            raise ChannelNotRegisteredError(
+                f"Channel {channel_id} is not a registered WebSocket channel"
+            )
+        channel.register_connection(connection_id, send_fn)
+        await self._emit_framework_event(
+            "channel_connected",
+            channel_id=channel_id,
+            data={"connection_id": connection_id},
+        )
+
+    async def disconnect_websocket(self, channel_id: str, connection_id: str) -> None:
+        """Unregister a WebSocket connection and emit framework event."""
+        channel = self._channels.get(channel_id)
+        if isinstance(channel, WebSocketChannel):
+            channel.unregister_connection(connection_id)
+        await self._emit_framework_event(
+            "channel_disconnected",
+            channel_id=channel_id,
+            data={"connection_id": connection_id},
+        )
+
+    # -- Read tracking --
+
+    async def mark_read(self, room_id: str, channel_id: str, event_id: str) -> None:
+        """Mark an event as read for a channel."""
+        await self._store.mark_read(room_id, channel_id, event_id)
+
+    async def mark_all_read(self, room_id: str, channel_id: str) -> None:
+        """Mark all events as read for a channel."""
+        await self._store.mark_all_read(room_id, channel_id)
+
+    # -- Realtime (ephemeral events) --
+
+    async def publish_typing(
+        self,
+        room_id: str,
+        user_id: str,
+        is_typing: bool = True,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """Publish a typing indicator for a user in a room.
+
+        Args:
+            room_id: The room to publish the typing event in.
+            user_id: The user who is typing.
+            is_typing: True for typing_start, False for typing_stop.
+            data: Optional additional data (e.g., {"name": "User Name"}).
+        """
+        event = EphemeralEvent(
+            room_id=room_id,
+            type=EphemeralEventType.TYPING_START if is_typing else EphemeralEventType.TYPING_STOP,
+            user_id=user_id,
+            data=data or {},
+        )
+        await self._realtime.publish_to_room(room_id, event)
+
+    async def publish_presence(self, room_id: str, user_id: str, status: str) -> None:
+        """Publish a presence update for a user in a room.
+
+        Args:
+            room_id: The room to publish the presence event in.
+            user_id: The user whose presence changed.
+            status: One of "online", "away", or "offline".
+        """
+        type_map = {
+            "online": EphemeralEventType.PRESENCE_ONLINE,
+            "away": EphemeralEventType.PRESENCE_AWAY,
+            "offline": EphemeralEventType.PRESENCE_OFFLINE,
+        }
+        event_type = type_map.get(status, EphemeralEventType.CUSTOM)
+        event = EphemeralEvent(
+            room_id=room_id,
+            type=event_type,
+            user_id=user_id,
+            data={"status": status} if event_type == EphemeralEventType.CUSTOM else {},
+        )
+        await self._realtime.publish_to_room(room_id, event)
+
+    async def publish_read_receipt(self, room_id: str, user_id: str, event_id: str) -> None:
+        """Publish a read receipt for a user in a room.
+
+        Args:
+            room_id: The room to publish the read receipt in.
+            user_id: The user who read the message.
+            event_id: The ID of the event that was read.
+        """
+        event = EphemeralEvent(
+            room_id=room_id,
+            type=EphemeralEventType.READ_RECEIPT,
+            user_id=user_id,
+            data={"event_id": event_id},
+        )
+        await self._realtime.publish_to_room(room_id, event)
+
+    async def subscribe_room(self, room_id: str, callback: EphemeralCallback) -> str:
+        """Subscribe to ephemeral events for a room.
+
+        Args:
+            room_id: The room to subscribe to.
+            callback: Async callback invoked for each ephemeral event.
+
+        Returns:
+            A subscription ID that can be used to unsubscribe.
+        """
+        return await self._realtime.subscribe_to_room(room_id, callback)
+
+    async def unsubscribe_room(self, subscription_id: str) -> bool:
+        """Unsubscribe from ephemeral events.
+
+        Args:
+            subscription_id: The subscription ID returned by subscribe_room.
+
+        Returns:
+            True if the subscription existed and was removed.
+        """
+        return await self._realtime.unsubscribe(subscription_id)
+
+    # -- Event-driven sources --
+
+    async def attach_source(
+        self,
+        channel_id: str,
+        source: SourceProvider,
+        *,
+        auto_restart: bool = True,
+        restart_delay: float = 5.0,
+        max_restart_delay: float = 300.0,
+        max_restart_attempts: int | None = None,
+        max_concurrent_emits: int | None = 10,
+    ) -> None:
+        """Attach an event-driven source to a channel.
+
+        The source will start listening for messages and emit them into
+        RoomKit's inbound pipeline via ``process_inbound()``.
+
+        Args:
+            channel_id: The channel ID to associate with this source.
+                Messages from this source will be tagged with this channel_id.
+            source: The source provider instance to attach.
+            auto_restart: If True (default), automatically restart the source
+                if it exits unexpectedly. Set to False for one-shot sources.
+            restart_delay: Initial delay in seconds before restarting after
+                failure. Doubles on each consecutive failure (exponential backoff).
+            max_restart_delay: Maximum delay between restart attempts in seconds.
+                Backoff is capped at this value. Defaults to 300 (5 minutes).
+            max_restart_attempts: Maximum number of consecutive restart attempts
+                before giving up. If None (default), retries indefinitely.
+                When exhausted, emits ``source_exhausted`` framework event.
+            max_concurrent_emits: Maximum number of concurrent ``emit()`` calls
+                to prevent backpressure buildup. Defaults to 10. Set to None
+                for unlimited concurrency (not recommended for high-volume sources).
+
+        Raises:
+            SourceAlreadyAttachedError: If a source is already attached to
+                this channel_id.
+
+        Example:
+            from roomkit.sources.neonize import NeonizeSource
+
+            source = NeonizeSource(session_path="~/.roomkit/wa.db")
+            await kit.attach_source(
+                "whatsapp-personal",
+                source,
+                max_restart_attempts=5,      # Give up after 5 failures
+                max_concurrent_emits=20,     # Allow 20 concurrent messages
+            )
+        """
+        if channel_id in self._sources:
+            raise SourceAlreadyAttachedError(f"Source already attached to channel {channel_id}")
+
+        logger = logging.getLogger("roomkit.sources")
+
+        # Create emit callback with optional backpressure control
+        if max_concurrent_emits is not None:
+            semaphore = asyncio.Semaphore(max_concurrent_emits)
+
+            async def emit(msg: InboundMessage) -> InboundResult:
+                async with semaphore:
+                    return await self.process_inbound(msg)
+        else:
+
+            async def emit(msg: InboundMessage) -> InboundResult:
+                return await self.process_inbound(msg)
+
+        self._sources[channel_id] = source
+        self._source_tasks[channel_id] = asyncio.create_task(
+            self._run_source(
+                channel_id,
+                source,
+                emit,
+                auto_restart,
+                restart_delay,
+                max_restart_delay,
+                max_restart_attempts,
+                logger,
+            ),
+            name=f"source:{channel_id}",
+        )
+
+        await self._emit_framework_event(
+            "source_attached",
+            channel_id=channel_id,
+            data={"source_name": source.name},
+        )
+
+    async def detach_source(self, channel_id: str) -> None:
+        """Detach and stop an event-driven source.
+
+        Args:
+            channel_id: The channel ID of the source to detach.
+
+        Raises:
+            SourceNotFoundError: If no source is attached to this channel_id.
+        """
+        if channel_id not in self._sources:
+            raise SourceNotFoundError(f"No source attached to channel {channel_id}")
+
+        source = self._sources.pop(channel_id)
+        task = self._source_tasks.pop(channel_id)
+
+        # Stop the source
+        await source.stop()
+
+        # Cancel the runner task and await its completion
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError, Exception):
+            await task
+
+        await self._emit_framework_event(
+            "source_detached",
+            channel_id=channel_id,
+            data={"source_name": source.name},
+        )
+
+    async def _run_source(
+        self,
+        channel_id: str,
+        source: SourceProvider,
+        emit: Callable[[InboundMessage], Awaitable[InboundResult]],
+        auto_restart: bool,
+        restart_delay: float,
+        max_restart_delay: float,
+        max_restart_attempts: int | None,
+        logger: logging.Logger,
+    ) -> None:
+        """Run a source with optional auto-restart on failure.
+
+        Uses exponential backoff: delay doubles on each failure, capped at
+        max_restart_delay. Delay resets after a successful start.
+        """
+
+        attempt = 0
+        current_delay = restart_delay
+
+        while True:
+            try:
+                logger.info("Starting source %s for channel %s", source.name, channel_id)
+                await source.start(emit)
+                # Clean exit - source stopped normally
+                logger.info("Source %s stopped cleanly", source.name)
+                break
+            except asyncio.CancelledError:
+                logger.debug("Source %s cancelled", source.name)
+                raise
+            except Exception as e:
+                attempt += 1
+                logger.exception("Source %s failed (attempt %d): %s", source.name, attempt, e)
+                await self._emit_framework_event(
+                    "source_error",
+                    channel_id=channel_id,
+                    data={"source_name": source.name, "error": str(e), "attempt": attempt},
+                )
+
+                if not auto_restart:
+                    raise
+
+                # Check if max attempts exceeded
+                if max_restart_attempts is not None and attempt >= max_restart_attempts:
+                    logger.error(
+                        "Source %s exhausted after %d attempts, giving up",
+                        source.name,
+                        attempt,
+                    )
+                    await self._emit_framework_event(
+                        "source_exhausted",
+                        channel_id=channel_id,
+                        data={
+                            "source_name": source.name,
+                            "attempts": attempt,
+                            "last_error": str(e),
+                        },
+                    )
+                    break
+
+                logger.info(
+                    "Restarting source %s in %.1f seconds (attempt %d%s)",
+                    source.name,
+                    current_delay,
+                    attempt,
+                    f"/{max_restart_attempts}" if max_restart_attempts else "",
+                )
+                await asyncio.sleep(current_delay)
+
+                # Exponential backoff: double delay, cap at max
+                current_delay = min(current_delay * 2, max_restart_delay)
+
+    async def source_health(self, channel_id: str) -> SourceHealth | None:
+        """Get health information for an attached source.
+
+        Args:
+            channel_id: The channel ID of the source.
+
+        Returns:
+            SourceHealth if a source is attached, None otherwise.
+        """
+        source = self._sources.get(channel_id)
+        if source is None:
+            return None
+        return await source.healthcheck()
+
+    def list_sources(self) -> dict[str, SourceStatus]:
+        """List all attached sources and their status.
+
+        Returns:
+            Dict mapping channel_id to current SourceStatus.
+        """
+        return {cid: source.status for cid, source in self._sources.items()}
+
+    # -- Hook decorators --
+
+    def hook(
+        self,
+        trigger: HookTrigger,
+        execution: HookExecution = HookExecution.SYNC,
+        priority: int = 0,
+        name: str = "",
+        timeout: float = 30.0,
+        channel_types: set[ChannelType] | None = None,
+        channel_ids: set[str] | None = None,
+        directions: set[ChannelDirection] | None = None,
+    ) -> Callable[..., Any]:
+        """Decorator to register a global hook.
+
+        Args:
+            trigger: When the hook fires (BEFORE_BROADCAST, AFTER_BROADCAST, etc.)
+            execution: SYNC (can block/modify) or ASYNC (fire-and-forget)
+            priority: Lower numbers run first (default: 0)
+            name: Optional name for logging and removal
+            timeout: Max execution time in seconds (default: 30.0)
+            channel_types: Only run for events from these channel types (None = all)
+            channel_ids: Only run for events from these channel IDs (None = all)
+            directions: Only run for events with these directions (None = all)
+        """
+
+        def decorator(fn: SyncHookFn | AsyncHookFn) -> SyncHookFn | AsyncHookFn:
+            self._hook_engine.register(
+                HookRegistration(
+                    trigger=trigger,
+                    execution=execution,
+                    fn=fn,
+                    priority=priority,
+                    name=name or fn.__name__,
+                    timeout=timeout,
+                    channel_types=channel_types,
+                    channel_ids=channel_ids,
+                    directions=directions,
+                )
+            )
+            return fn
+
+        return decorator
+
+    def on(self, event_type: str) -> Callable[..., Any]:
+        """Decorator to register a framework event handler filtered by type."""
+
+        def decorator(fn: FrameworkEventHandler) -> FrameworkEventHandler:
+            self._event_handlers.append((event_type, fn))
+            return fn
+
+        return decorator
+
+    def identity_hook(
+        self,
+        trigger: HookTrigger,
+        channel_types: set[ChannelType] | None = None,
+        channel_ids: set[str] | None = None,
+        directions: set[ChannelDirection] | None = None,
+    ) -> Callable[..., Any]:
+        """Decorator to register an identity-resolution hook.
+
+        The decorated function receives ``(event, context, id_result)`` and
+        returns an ``IdentityHookResult`` or ``None``.
+
+        Args:
+            trigger: When the hook fires (ON_IDENTITY_AMBIGUOUS, ON_IDENTITY_UNKNOWN).
+            channel_types: Only run for events from these channel types (None = all).
+            channel_ids: Only run for events from these channel IDs (None = all).
+            directions: Only run for events with these directions (None = all).
+        """
+
+        def decorator(fn: IdentityHookFn) -> IdentityHookFn:
+            registration = IdentityHookRegistration(
+                trigger=trigger,
+                fn=fn,
+                channel_types=channel_types,
+                channel_ids=channel_ids,
+                directions=directions,
+            )
+            self._identity_hooks.setdefault(trigger, []).append(registration)
+            return fn
+
+        return decorator
+
+    def on_delivery_status(self, fn: DeliveryStatusHandler) -> DeliveryStatusHandler:
+        """Decorator to register a delivery status handler.
+
+        The decorated function is called when ``process_delivery_status()`` is
+        invoked with a ``DeliveryStatus`` from a provider webhook.
+
+        Example:
+            @kit.on_delivery_status
+            async def track_delivery(status: DeliveryStatus):
+                if status.status == "delivered":
+                    logger.info("Message %s delivered to %s", status.message_id, status.recipient)
+                elif status.status == "failed":
+                    logger.error("Message %s failed: %s", status.message_id, status.error_message)
+        """
+        self._delivery_status_handlers.append(fn)
+        return fn
+
+    async def process_webhook(
+        self,
+        meta: WebhookMeta,
+        channel_id: str,
+    ) -> None:
+        """Process any SMS provider webhook automatically.
+
+        This is the simplest integration method. It handles:
+        - Inbound messages → process_inbound() with all hooks
+        - Delivery status → process_delivery_status() with ON_DELIVERY_STATUS hooks
+        - Unknown webhooks → silently ignored (acknowledged)
+
+        Args:
+            meta: WebhookMeta from extract_sms_meta().
+            channel_id: The channel ID for inbound messages.
+
+        Example:
+            @app.post("/webhooks/sms/{provider}/inbound")
+            async def sms_webhook(provider: str, payload: dict):
+                meta = extract_sms_meta(provider, payload)
+                await kit.process_webhook(meta, channel_id=f"sms-{provider}")
+                return {"ok": True}
+        """
+        if meta.is_inbound:
+            inbound = meta.to_inbound(channel_id)
+            await self.process_inbound(inbound)
+        elif meta.is_status:
+            status = meta.to_status()
+            await self.process_delivery_status(status)
+        # else: unknown webhook type, silently acknowledge
+
+    async def process_delivery_status(self, status: DeliveryStatus) -> None:
+        """Process a delivery status through registered ON_DELIVERY_STATUS handlers.
+
+        Args:
+            status: The DeliveryStatus from meta.to_status().
+        """
+        logger = logging.getLogger("roomkit.framework")
+        for handler in self._delivery_status_handlers:
+            try:
+                result = handler(status)
+                if inspect.iscoroutine(result):
+                    await result
+            except Exception:
+                logger.exception(
+                    "Delivery status handler %s failed for message %s",
+                    getattr(handler, "__name__", "unknown"),
+                    status.message_id,
+                )
+
+    def add_room_hook(
+        self,
+        room_id: str,
+        trigger: HookTrigger,
+        execution: HookExecution,
+        fn: SyncHookFn | AsyncHookFn,
+        priority: int = 0,
+        name: str = "",
+    ) -> None:
+        """Add a hook for a specific room."""
+        self._hook_engine.add_room_hook(
+            room_id,
+            HookRegistration(
+                trigger=trigger,
+                execution=execution,
+                fn=fn,
+                priority=priority,
+                name=name,
+            ),
+        )
+
+    def remove_room_hook(self, room_id: str, name: str) -> bool:
+        """Remove a room hook by name."""
+        return self._hook_engine.remove_room_hook(room_id, name)