roomkit 0.1.0__py3-none-any.whl

roomkit/providers/rcs/mock.py

@@ -0,0 +1,78 @@
+"""Mock RCS provider for testing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from roomkit.models.event import RoomEvent
+from roomkit.providers.rcs.base import RCSDeliveryResult, RCSProvider
+
+
+class MockRCSProvider(RCSProvider):
+    """Mock RCS provider for testing."""
+
+    def __init__(
+        self,
+        sender_id: str = "mock_rcs_agent",
+        *,
+        simulate_fallback: bool = False,
+        simulate_failure: bool = False,
+    ) -> None:
+        """Initialize mock provider.
+
+        Args:
+            sender_id: Mock sender/agent ID.
+            simulate_fallback: If True, simulate SMS fallback on sends.
+            simulate_failure: If True, simulate send failures.
+        """
+        self._sender_id = sender_id
+        self._simulate_fallback = simulate_fallback
+        self._simulate_failure = simulate_failure
+        self.calls: list[dict[str, Any]] = []
+        self._message_counter = 0
+
+    @property
+    def sender_id(self) -> str:
+        return self._sender_id
+
+    async def send(
+        self,
+        event: RoomEvent,
+        to: str,
+        *,
+        fallback: bool = True,
+    ) -> RCSDeliveryResult:
+        self._message_counter += 1
+        self.calls.append(
+            {
+                "event": event,
+                "to": to,
+                "fallback": fallback,
+            }
+        )
+
+        if self._simulate_failure:
+            return RCSDeliveryResult(
+                success=False,
+                error="simulated_failure",
+            )
+
+        # Simulate fallback to SMS
+        if self._simulate_fallback and fallback:
+            return RCSDeliveryResult(
+                success=True,
+                provider_message_id=f"mock_sms_{self._message_counter}",
+                channel_used="sms",
+                fallback=True,
+            )
+
+        return RCSDeliveryResult(
+            success=True,
+            provider_message_id=f"mock_rcs_{self._message_counter}",
+            channel_used="rcs",
+            fallback=False,
+        )
+
+    async def check_capability(self, phone_number: str) -> bool:
+        """Mock capability check - returns opposite of simulate_fallback."""
+        return not self._simulate_fallback

roomkit/providers/sendgrid/__init__.py

@@ -0,0 +1,5 @@
+"""SendGrid provider."""
+
+from roomkit.providers.sendgrid.config import SendGridConfig
+
+__all__ = ["SendGridConfig"]

roomkit/providers/sendgrid/config.py

@@ -0,0 +1,13 @@
+"""SendGrid provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class SendGridConfig(BaseModel):
+    """SendGrid email provider configuration."""
+
+    api_key: SecretStr
+    from_email: str
+    from_name: str | None = None

roomkit/providers/sinch/__init__.py

@@ -0,0 +1,6 @@
+"""Sinch provider."""
+
+from roomkit.providers.sinch.config import SinchConfig
+from roomkit.providers.sinch.sms import SinchSMSProvider, parse_sinch_webhook
+
+__all__ = ["SinchConfig", "SinchSMSProvider", "parse_sinch_webhook"]

roomkit/providers/sinch/config.py

@@ -0,0 +1,22 @@
+"""Sinch provider configuration."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, SecretStr
+
+
+class SinchConfig(BaseModel):
+    """Sinch SMS provider configuration."""
+
+    service_plan_id: str
+    api_token: SecretStr
+    from_number: str
+    region: Literal["us", "eu", "au", "br", "ca"] = "us"
+    webhook_secret: SecretStr | None = None
+    timeout: float = 10.0
+
+    @property
+    def api_url(self) -> str:
+        return f"https://{self.region}.sms.api.sinch.com/xms/v1/{self.service_plan_id}/batches"

roomkit/providers/sinch/sms.py

@@ -0,0 +1,192 @@
+"""Sinch SMS provider — sends SMS via the Sinch REST API."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from typing import TYPE_CHECKING, Any
+
+from roomkit.models.delivery import InboundMessage, ProviderResult
+from roomkit.models.event import RoomEvent
+from roomkit.providers.sinch.config import SinchConfig
+from roomkit.providers.sms.base import SMSProvider
+from roomkit.providers.sms.meta import (
+    build_inbound_content,
+    extract_media_urls,
+    extract_text_body,
+)
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class SinchSMSProvider(SMSProvider):
+    """SMS provider using the Sinch REST API."""
+
+    def __init__(self, config: SinchConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for SinchSMSProvider. "
+                "Install it with: pip install roomkit[httpx]"
+            ) from exc
+        self._config = config
+        self._httpx = _httpx
+        self._client: httpx.AsyncClient = _httpx.AsyncClient(timeout=config.timeout)
+
+    @property
+    def from_number(self) -> str:
+        return self._config.from_number
+
+    async def send(self, event: RoomEvent, to: str, from_: str | None = None) -> ProviderResult:
+        content = event.content
+        body = extract_text_body(content)
+        media_urls = extract_media_urls(content)
+
+        if not body and not media_urls:
+            return ProviderResult(success=False, error="empty_message")
+
+        from_number = from_ or self._config.from_number
+
+        headers = {
+            "Authorization": f"Bearer {self._config.api_token.get_secret_value()}",
+            "Content-Type": "application/json",
+        }
+
+        # Sinch expects 'to' as an array
+        payload: dict[str, Any] = {
+            "from": from_number,
+            "to": [to],
+        }
+
+        if media_urls:
+            # Sinch MMS: type mt_media, body contains url and optional message
+            payload["type"] = "mt_media"
+            media_body: dict[str, str] = {"url": media_urls[0]}
+            if body:
+                media_body["message"] = body
+            payload["body"] = media_body
+        else:
+            payload["body"] = body
+
+        try:
+            resp = await self._client.post(
+                self._config.api_url,
+                headers=headers,
+                json=payload,
+            )
+            resp.raise_for_status()
+            response_data = resp.json()
+        except self._httpx.TimeoutException:
+            return ProviderResult(success=False, error="timeout")
+        except self._httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                return ProviderResult(success=False, error="auth_error")
+            if status == 429:
+                return ProviderResult(success=False, error="rate_limit")
+            if status == 400:
+                try:
+                    error_data = exc.response.json()
+                    error_code = error_data.get("code", "invalid_request")
+                    return ProviderResult(
+                        success=False,
+                        error=f"sinch_{error_code}",
+                        metadata={"message": error_data.get("text", "")},
+                    )
+                except Exception:
+                    return ProviderResult(success=False, error="invalid_request")
+            return ProviderResult(success=False, error=f"http_{status}")
+        except self._httpx.HTTPError as exc:
+            return ProviderResult(success=False, error=str(exc))
+
+        return ProviderResult(
+            success=True,
+            provider_message_id=response_data.get("id"),
+        )
+
+    def verify_signature(
+        self,
+        payload: bytes,
+        signature: str,
+        timestamp: str | None = None,
+    ) -> bool:
+        """Verify a Sinch webhook signature using HMAC-SHA1.
+
+        Args:
+            payload: Raw request body bytes (JSON).
+            signature: Value of the ``X-Sinch-Signature`` header.
+            timestamp: Not used by Sinch (included for interface compatibility).
+
+        Returns:
+            True if the signature is valid, False otherwise.
+
+        Raises:
+            ValueError: If webhook_secret was not provided in config.
+        """
+        if not self._config.webhook_secret:
+            raise ValueError(
+                "webhook_secret must be provided in SinchConfig for signature verification"
+            )
+
+        try:
+            expected_sig = base64.b64encode(
+                hmac.new(
+                    self._config.webhook_secret.get_secret_value().encode(),
+                    payload,
+                    hashlib.sha1,
+                ).digest()
+            ).decode()
+            return hmac.compare_digest(expected_sig, signature)
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+def parse_sinch_webhook(
+    payload: dict[str, Any],
+    channel_id: str,
+) -> InboundMessage:
+    """Convert a Sinch SMS webhook POST body into an InboundMessage.
+
+    Sinch inbound SMS webhook structure:
+    {
+        "id": "message-id",
+        "from": "+15551234567",
+        "to": "12345",
+        "body": "Message text",
+        "received_at": "2026-01-28T12:00:00.000Z",
+        "operator_id": "...",
+        "media": [{"url": "...", "mimeType": "image/jpeg"}],
+        ...
+    }
+    """
+    body = payload.get("body", "")
+
+    media: list[dict[str, str | None]] = []
+    for m in payload.get("media", []):
+        if url := m.get("url"):
+            media.append(
+                {
+                    "url": url,
+                    "mime_type": m.get("mimeType"),
+                }
+            )
+
+    return InboundMessage(
+        channel_id=channel_id,
+        sender_id=payload.get("from", ""),
+        content=build_inbound_content(body, media),
+        external_id=payload.get("id"),
+        idempotency_key=payload.get("id"),
+        metadata={
+            "to": payload.get("to", ""),
+            "received_at": payload.get("received_at"),
+            "operator_id": payload.get("operator_id"),
+            "client_reference": payload.get("client_reference"),
+        },
+    )

roomkit/providers/sms/__init__.py

@@ -0,0 +1,15 @@
+"""SMS providers."""
+
+from roomkit.providers.sms.base import SMSProvider
+from roomkit.providers.sms.meta import WebhookMeta, extract_sms_meta
+from roomkit.providers.sms.mock import MockSMSProvider
+from roomkit.providers.sms.phone import is_valid_phone, normalize_phone
+
+__all__ = [
+    "MockSMSProvider",
+    "SMSProvider",
+    "WebhookMeta",
+    "extract_sms_meta",
+    "is_valid_phone",
+    "normalize_phone",
+]

roomkit/providers/sms/base.py

@@ -0,0 +1,67 @@
+"""Abstract base class for SMS providers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from roomkit.models.delivery import InboundMessage, ProviderResult
+from roomkit.models.event import RoomEvent
+
+
+class SMSProvider(ABC):
+    """SMS delivery provider."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. 'twilio', 'sinch')."""
+        return self.__class__.__name__
+
+    @property
+    @abstractmethod
+    def from_number(self) -> str:
+        """Default sender phone number."""
+        ...
+
+    @abstractmethod
+    async def send(self, event: RoomEvent, to: str, from_: str | None = None) -> ProviderResult:
+        """Send an SMS message.
+
+        Args:
+            event: The room event containing the message content.
+            to: Recipient phone number (E.164 format).
+            from_: Sender phone number override. Defaults to ``from_number``.
+
+        Returns:
+            Result with provider-specific delivery metadata.
+        """
+        ...
+
+    async def parse_webhook(self, payload: dict[str, Any]) -> InboundMessage:
+        """Parse an inbound webhook payload into an InboundMessage."""
+        raise NotImplementedError
+
+    def verify_signature(
+        self,
+        payload: bytes,
+        signature: str,
+        timestamp: str | None = None,
+    ) -> bool:
+        """Verify that a webhook payload was signed by the provider.
+
+        Args:
+            payload: Raw request body bytes.
+            signature: Signature header value from the webhook request.
+            timestamp: Timestamp header value (required by some providers).
+
+        Returns:
+            True if the signature is valid, False otherwise.
+
+        Raises:
+            NotImplementedError: If the provider does not support signature
+                verification.
+        """
+        raise NotImplementedError(f"{self.name} does not support webhook signature verification")
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses that hold connections."""