roomkit 0.1.0__py3-none-any.whl

roomkit/providers/twilio/rcs.py

@@ -0,0 +1,183 @@
+"""Twilio RCS provider — sends RCS messages via the Twilio REST API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, SecretStr
+
+from roomkit.models.delivery import InboundMessage
+from roomkit.models.event import RoomEvent
+from roomkit.providers.rcs.base import RCSDeliveryResult, RCSProvider
+from roomkit.providers.sms.meta import (
+    build_inbound_content,
+    extract_media_urls,
+    extract_text_body,
+)
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class TwilioRCSConfig(BaseModel):
+    """Twilio RCS provider configuration."""
+
+    account_sid: str
+    auth_token: SecretStr
+    messaging_service_sid: str  # Required for RCS (must be RCS-enabled)
+    timeout: float = 10.0
+
+    @property
+    def api_url(self) -> str:
+        return f"https://api.twilio.com/2010-04-01/Accounts/{self.account_sid}/Messages.json"
+
+
+class TwilioRCSProvider(RCSProvider):
+    """RCS provider using the Twilio REST API.
+
+    Twilio RCS uses the same Messages API as SMS, but requires an RCS-enabled
+    Messaging Service. When the recipient doesn't support RCS, Twilio can
+    automatically fall back to SMS (unless disabled via fallback=False).
+    """
+
+    def __init__(self, config: TwilioRCSConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for TwilioRCSProvider. "
+                "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 sender_id(self) -> str:
+        return self._config.messaging_service_sid
+
+    async def send(
+        self,
+        event: RoomEvent,
+        to: str,
+        *,
+        fallback: bool = True,
+    ) -> RCSDeliveryResult:
+        """Send an RCS message via Twilio.
+
+        Args:
+            event: The room event containing the message content.
+            to: Recipient phone number (E.164 format).
+            fallback: If True, allow SMS fallback. If False, RCS only.
+
+        Returns:
+            Result with delivery info including channel used.
+        """
+        content = event.content
+        body = extract_text_body(content)
+        media_urls = extract_media_urls(content)
+
+        if not body and not media_urls:
+            return RCSDeliveryResult(success=False, error="empty_message")
+
+        auth = (self._config.account_sid, self._config.auth_token.get_secret_value())
+
+        # Twilio expects form-encoded data
+        data: dict[str, str] = {
+            "MessagingServiceSid": self._config.messaging_service_sid,
+        }
+
+        # For RCS-only (no fallback), prefix "to" with "rcs:"
+        if fallback:
+            data["To"] = to
+        else:
+            data["To"] = f"rcs:{to}"
+
+        if body:
+            data["Body"] = body
+
+        # Add media URLs (Twilio supports up to 10)
+        for i, url in enumerate(media_urls[:10]):
+            data[f"MediaUrl{i}"] = url
+
+        try:
+            resp = await self._client.post(
+                self._config.api_url,
+                auth=auth,
+                data=data,
+            )
+            resp.raise_for_status()
+            response_data = resp.json()
+        except self._httpx.TimeoutException:
+            return RCSDeliveryResult(success=False, error="timeout")
+        except self._httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            if status == 401:
+                return RCSDeliveryResult(success=False, error="auth_error")
+            if status == 429:
+                return RCSDeliveryResult(success=False, error="rate_limit")
+            if status == 400:
+                try:
+                    error_data = exc.response.json()
+                    error_code = error_data.get("code", "invalid_request")
+                    return RCSDeliveryResult(
+                        success=False,
+                        error=f"twilio_{error_code}",
+                        metadata={"message": error_data.get("message", "")},
+                    )
+                except Exception:
+                    return RCSDeliveryResult(success=False, error="invalid_request")
+            return RCSDeliveryResult(success=False, error=f"http_{status}")
+        except self._httpx.HTTPError as exc:
+            return RCSDeliveryResult(success=False, error=str(exc))
+
+        # Twilio returns the channel used in the response
+        # For now, we assume RCS unless we detect fallback from status callback
+        return RCSDeliveryResult(
+            success=True,
+            provider_message_id=response_data.get("sid"),
+            channel_used="rcs",
+            fallback=False,
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+def parse_twilio_rcs_webhook(
+    payload: dict[str, Any],
+    channel_id: str,
+) -> InboundMessage:
+    """Convert a Twilio RCS webhook POST body into an InboundMessage.
+
+    Note: Twilio sends webhooks as form-encoded data. Convert to dict first:
+        payload = dict(await request.form())
+    """
+    body = payload.get("Body", "")
+
+    media: list[dict[str, str | None]] = []
+    num_media = int(payload.get("NumMedia", "0"))
+    for i in range(num_media):
+        url = payload.get(f"MediaUrl{i}")
+        if url:
+            media.append(
+                {
+                    "url": url,
+                    "mime_type": payload.get(f"MediaContentType{i}"),
+                }
+            )
+
+    return InboundMessage(
+        channel_id=channel_id,
+        sender_id=payload.get("From", ""),
+        content=build_inbound_content(body, media),
+        external_id=payload.get("MessageSid"),
+        idempotency_key=payload.get("MessageSid"),
+        metadata={
+            "to": payload.get("To", ""),
+            "account_sid": payload.get("AccountSid", ""),
+            "num_media": payload.get("NumMedia", "0"),
+            "channel": payload.get("Channel", "rcs"),  # RCS-specific
+            "messaging_service_sid": payload.get("MessagingServiceSid", ""),
+        },
+    )

roomkit/providers/twilio/sms.py

@@ -0,0 +1,200 @@
+"""Twilio SMS provider — sends SMS via the Twilio 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.sms.base import SMSProvider
+from roomkit.providers.sms.meta import (
+    build_inbound_content,
+    extract_media_urls,
+    extract_text_body,
+)
+from roomkit.providers.twilio.config import TwilioConfig
+
+if TYPE_CHECKING:
+    import httpx
+
+
+class TwilioSMSProvider(SMSProvider):
+    """SMS provider using the Twilio REST API."""
+
+    def __init__(self, config: TwilioConfig) -> None:
+        try:
+            import httpx as _httpx
+        except ImportError as exc:
+            raise ImportError(
+                "httpx is required for TwilioSMSProvider. "
+                "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
+
+        # Twilio uses HTTP Basic auth
+        auth = (self._config.account_sid, self._config.auth_token.get_secret_value())
+
+        # Twilio expects form-encoded data
+        data: dict[str, str] = {
+            "To": to,
+        }
+
+        if body:
+            data["Body"] = body
+
+        # Add media URLs (Twilio supports up to 10)
+        for i, url in enumerate(media_urls[:10]):
+            data[f"MediaUrl{i}"] = url
+
+        # Use MessagingServiceSid if provided, otherwise use From number
+        if self._config.messaging_service_sid:
+            data["MessagingServiceSid"] = self._config.messaging_service_sid
+        else:
+            data["From"] = from_number
+
+        try:
+            resp = await self._client.post(
+                self._config.api_url,
+                auth=auth,
+                data=data,
+            )
+            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 to extract Twilio error code
+                try:
+                    error_data = exc.response.json()
+                    error_code = error_data.get("code", "invalid_request")
+                    return ProviderResult(
+                        success=False,
+                        error=f"twilio_{error_code}",
+                        metadata={"message": error_data.get("message", "")},
+                    )
+                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("sid"),
+        )
+
+    def verify_signature(
+        self,
+        payload: bytes,
+        signature: str,
+        timestamp: str | None = None,
+        url: str | None = None,
+    ) -> bool:
+        """Verify a Twilio webhook signature using HMAC-SHA1.
+
+        Args:
+            payload: Raw request body bytes (form-encoded).
+            signature: Value of the ``X-Twilio-Signature`` header.
+            timestamp: Not used by Twilio (included for interface compatibility).
+            url: The full URL that Twilio called (required for verification).
+
+        Returns:
+            True if the signature is valid, False otherwise.
+        """
+        if not url:
+            return False
+
+        # Parse form-encoded payload and sort parameters
+        try:
+            from urllib.parse import unquote_plus
+
+            pairs = payload.decode().split("&")
+            params = dict(pair.split("=", 1) for pair in pairs if "=" in pair)
+            # URL decode the values
+            params = {k: unquote_plus(v) for k, v in params.items()}
+        except Exception:
+            return False
+
+        # Build the validation string: URL + sorted params
+        validation_string = url
+        for key in sorted(params.keys()):
+            validation_string += key + params[key]
+
+        # Compute HMAC-SHA1
+        expected_sig = base64.b64encode(
+            hmac.new(
+                self._config.auth_token.get_secret_value().encode(),
+                validation_string.encode(),
+                hashlib.sha1,
+            ).digest()
+        ).decode()
+
+        return hmac.compare_digest(expected_sig, signature)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+def parse_twilio_webhook(
+    payload: dict[str, Any],
+    channel_id: str,
+) -> InboundMessage:
+    """Convert a Twilio webhook POST body into an InboundMessage.
+
+    Note: Twilio sends webhooks as form-encoded data. Convert to dict first:
+        payload = dict(await request.form())
+    """
+    body = payload.get("Body", "")
+
+    media: list[dict[str, str | None]] = []
+    num_media = int(payload.get("NumMedia", "0"))
+    for i in range(num_media):
+        url = payload.get(f"MediaUrl{i}")
+        if url:
+            media.append(
+                {
+                    "url": url,
+                    "mime_type": payload.get(f"MediaContentType{i}"),
+                }
+            )
+
+    return InboundMessage(
+        channel_id=channel_id,
+        sender_id=payload.get("From", ""),
+        content=build_inbound_content(body, media),
+        external_id=payload.get("MessageSid"),
+        idempotency_key=payload.get("MessageSid"),
+        metadata={
+            "to": payload.get("To", ""),
+            "account_sid": payload.get("AccountSid", ""),
+            "num_media": payload.get("NumMedia", "0"),
+            "from_city": payload.get("FromCity"),
+            "from_state": payload.get("FromState"),
+            "from_country": payload.get("FromCountry"),
+        },
+    )

roomkit/providers/voicemeup/__init__.py

@@ -0,0 +1,15 @@
+"""VoiceMeUp provider."""
+
+from roomkit.providers.voicemeup.config import VoiceMeUpConfig
+from roomkit.providers.voicemeup.sms import (
+    VoiceMeUpSMSProvider,
+    configure_voicemeup_mms,
+    parse_voicemeup_webhook,
+)
+
+__all__ = [
+    "VoiceMeUpConfig",
+    "VoiceMeUpSMSProvider",
+    "configure_voicemeup_mms",
+    "parse_voicemeup_webhook",
+]

roomkit/providers/voicemeup/config.py

@@ -0,0 +1,21 @@
+"""VoiceMeUp provider configuration."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, SecretStr
+
+
+class VoiceMeUpConfig(BaseModel):
+    """VoiceMeUp SMS provider configuration."""
+
+    username: str
+    auth_token: SecretStr
+    from_number: str
+    environment: str = "production"
+    timeout: float = 10.0
+
+    @property
+    def base_url(self) -> str:
+        if self.environment == "sandbox":
+            return "https://dev-clients.voicemeup.com/api/v1.1/json/"
+        return "https://clients.voicemeup.com/api/v1.1/json/"