python-missive 0.2.0__py3-none-any.whl

pymissive/archives/providers/smtp.py

@@ -0,0 +1,190 @@
+"""Generic SMTP provider without Django dependencies."""
+
+from __future__ import annotations
+
+import smtplib
+from contextlib import contextmanager
+from email.message import EmailMessage
+from typing import Any, Dict, List, Optional, Tuple
+
+from ..status import MissiveStatus
+from .base import BaseProvider
+from .base.email_message import build_email_message
+
+
+class SMTPProvider(BaseProvider):
+    """Simple SMTP provider supporting transactional and marketing emails."""
+
+    name = "smtp"
+    display_name = "SMTP"
+    supported_types = ["EMAIL", "EMAIL_MARKETING"]
+    config_keys = [
+        "SMTP_HOST",
+        "SMTP_PORT",
+        "SMTP_USERNAME",
+        "SMTP_PASSWORD",
+        "SMTP_USE_TLS",
+        "SMTP_USE_SSL",
+        "SMTP_TIMEOUT_SECONDS",
+        "DEFAULT_FROM_EMAIL",
+    ]
+    required_packages: List[str] = []
+    description_text = (
+        "Direct SMTP integration with optional TLS/SSL and inline attachment support."
+    )
+
+    # Geographic scopes + pricing baseline
+    email_geographic_coverage = ["*"]
+    email_geo = email_geographic_coverage
+    email_price = 0.0  # delegated to provider pricing
+    email_marketing_geographic_coverage = ["*"]
+    email_marketing_geo = email_marketing_geographic_coverage
+    email_marketing_price = 0.0
+
+    def validate(self) -> Tuple[bool, str]:
+        """Ensure mandatory connection settings exist."""
+        host = self._config.get("SMTP_HOST")
+        port = self._config.get("SMTP_PORT")
+        if not host or not port:
+            return False, "SMTP_HOST and SMTP_PORT must be configured"
+
+        if "DEFAULT_FROM_EMAIL" not in self._config:
+            sender_addr = self._get_missive_value(
+                "sender_email"
+            ) or self._get_missive_value("sender")
+            self._raw_config["DEFAULT_FROM_EMAIL"] = (
+                sender_addr if isinstance(sender_addr, str) else "noreply@example.com"
+            )
+            self._config = self._filter_config(self._raw_config)
+
+        return super().validate()
+
+    def send_email(self, **kwargs: Any) -> bool:
+        """Send an email via configured SMTP server."""
+        recipient = self._get_missive_value(
+            "get_recipient_email"
+        ) or self._get_missive_value("recipient_email")
+        if not recipient:
+            self._update_status(
+                MissiveStatus.FAILED, error_message="Recipient email missing"
+            )
+            return False
+
+        message = self._build_message(recipient)
+
+        try:
+            with self._smtp_connection() as smtp:
+                smtp.send_message(message)
+        except (OSError, smtplib.SMTPException) as exc:
+            return self._handle_send_error(exc)
+
+        external_id = f"smtp_{getattr(self.missive, 'id', 'unknown')}"
+        self._update_status(
+            MissiveStatus.SENT, provider=self.name, external_id=external_id
+        )
+        self._create_event("sent", "Email sent via SMTP")
+        return True
+
+    def send_email_marketing(self, **kwargs: Any) -> bool:
+        """Marketing campaigns reuse the same pipeline."""
+        return self.send_email(**kwargs)
+
+    def get_email_service_info(self) -> Dict[str, Any]:
+        info = super().get_email_service_info()
+        info["details"].update(
+            {
+                "host": self._config.get("SMTP_HOST"),
+                "port": self._config.get("SMTP_PORT"),
+                "use_tls": self._bool_config("SMTP_USE_TLS", False),
+                "use_ssl": self._bool_config("SMTP_USE_SSL", False),
+            }
+        )
+        info["warnings"] = []
+        return info
+
+    def get_email_marketing_service_info(self) -> Dict[str, Any]:
+        return self.get_email_service_info()
+
+    def get_service_status(self) -> Dict[str, Any]:
+        """Return lightweight availability info."""
+        service_info = self.get_email_service_info()
+        return self._build_generic_service_status(
+            status="operational",
+            is_available=True,
+            credits_type="unlimited",
+            rate_limits={},
+            warnings=service_info.get("warnings"),
+            details=service_info.get("details"),
+        )
+
+    def cancel_email(self, **kwargs: Any) -> bool:
+        """SMTP has no notion of cancel."""
+        return False
+
+    def cancel_email_marketing(self, **kwargs: Any) -> bool:
+        return False
+
+    def validate_email_webhook_signature(
+        self, payload: Any, headers: Dict[str, str]
+    ) -> Tuple[bool, str]:
+        """SMTP providers do not expose webhooks by default."""
+        return True, ""
+
+    validate_email_marketing_webhook_signature = validate_email_webhook_signature
+
+    def handle_email_webhook(
+        self, payload: Dict[str, Any], headers: Dict[str, str]
+    ) -> Tuple[bool, str, Optional[Any]]:
+        return False, "SMTP provider has no webhooks", None
+
+    handle_email_marketing_webhook = handle_email_webhook
+
+    def extract_email_missive_id(self, payload: Dict[str, Any]) -> Optional[str]:
+        return None
+
+    extract_email_marketing_missive_id = extract_email_missive_id
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def _build_message(self, recipient: str) -> EmailMessage:
+        from_email = self._config.get("DEFAULT_FROM_EMAIL", "noreply@example.com")
+        return build_email_message(self, recipient, from_email=from_email)
+
+    @contextmanager
+    def _smtp_connection(self):
+        host = str(self._config.get("SMTP_HOST"))
+        port = int(self._config.get("SMTP_PORT"))
+        timeout = float(self._config.get("SMTP_TIMEOUT_SECONDS", 10))
+        use_ssl = self._bool_config("SMTP_USE_SSL", False)
+        use_tls = self._bool_config("SMTP_USE_TLS", False)
+
+        if use_ssl:
+            smtp: smtplib.SMTP = smtplib.SMTP_SSL(host, port, timeout=timeout)
+        else:
+            smtp = smtplib.SMTP(host, port, timeout=timeout)
+            if use_tls:
+                smtp.starttls()
+
+        username = self._config.get("SMTP_USERNAME")
+        password = self._config.get("SMTP_PASSWORD")
+        if username and password:
+            smtp.login(username, password)
+
+        try:
+            yield smtp
+        finally:
+            try:
+                smtp.quit()
+            except Exception:
+                smtp.close()
+
+    def _bool_config(self, key: str, default: bool) -> bool:
+        """Convert config value to boolean."""
+        value = self._raw_config.get(key, default)
+        if isinstance(value, str):
+            return value.strip().lower() in {"1", "true", "yes", "on"}
+        return bool(value)
+
+
+__all__ = ["SMTPProvider"]

pymissive/archives/providers/teams.py

@@ -0,0 +1,91 @@
+"""Microsoft Teams provider."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..status import MissiveStatus
+from .base import BaseProvider
+
+
+class TeamsProvider(BaseProvider):
+    """
+    Microsoft Teams provider.
+
+    Required configuration:
+        TEAMS_CLIENT_ID: Azure AD app Client ID
+        TEAMS_CLIENT_SECRET: Client Secret
+        TEAMS_TENANT_ID: Tenant ID
+
+    Recipient must have:
+    - A Microsoft user_id (in metadata.teams_user_id)
+    - OR a Teams channel_id (in metadata.teams_channel_id)
+    """
+
+    name = "teams"
+    display_name = "Microsoft Teams"
+    supported_types = ["BRANDED"]  # Uses generic BRANDED type
+    services = ["teams", "messaging"]
+    brands = ["teams"]  # Microsoft Teams only
+    config_keys = ["TEAMS_CLIENT_ID", "TEAMS_CLIENT_SECRET", "TEAMS_TENANT_ID"]
+    required_packages = ["msgraph-core", "msal"]
+    site_url = "https://www.microsoft.com/microsoft-teams/"
+    status_url = "https://status.azure.com/en-us/status"
+    documentation_url = "https://learn.microsoft.com/en-us/microsoftteams/"
+    description_text = "Microsoft Teams - Enterprise communication (Microsoft 365)"
+    # Geographic scope
+    branded_geo = "*"
+
+    def validate(self) -> tuple[bool, str]:
+        """Validate that the recipient has a Teams user_id or channel_id"""
+        if not self.missive:
+            return False, "Missive not defined"
+
+        recipient = getattr(self.missive, "recipient", None)
+        if not recipient:
+            return False, "Recipient not defined"
+
+        metadata = getattr(recipient, "metadata", None) or {}
+        user_id = metadata.get("teams_user_id")
+        channel_id = metadata.get("teams_channel_id")
+
+        if not user_id and not channel_id:
+            return (
+                False,
+                "Recipient must have a teams_user_id or teams_channel_id in metadata",
+            )
+
+        return True, ""
+
+    def send_teams(self) -> bool:
+        """
+        Send a Teams message via Microsoft Graph API.
+
+        TODO: Implement actual sending via:
+        POST https://graph.microsoft.com/v1.0/chats/{chat-id}/messages
+        """
+        is_valid, error = self.validate()
+        if not is_valid:
+            self._update_status(MissiveStatus.FAILED, error_message=error)
+            return False
+
+        # TODO: Implement actual sending
+        # 1. Get an OAuth access token
+        # 2. Send the message via Graph API
+        # 3. Handle adaptive cards for rich content
+
+        external_id = f"teams_sim_{getattr(self.missive, 'id', 'unknown')}"
+        self._update_status(
+            MissiveStatus.SENT,
+            external_id=external_id,
+        )
+
+        return True
+
+    def check_status(self, external_id: Optional[str] = None) -> Optional[str]:
+        """Check status via Graph API"""
+        # TODO: Implement via Microsoft Graph API
+        return None
+
+
+__all__ = ["TeamsProvider"]

pymissive/archives/providers/telegram.py

@@ -0,0 +1,69 @@
+"""Telegram Bot API provider."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ..status import MissiveStatus
+from .base import BaseProvider
+
+
+class TelegramProvider(BaseProvider):
+    """Telegram provider."""
+
+    name = "telegram"
+    display_name = "Telegram"
+    supported_types = ["BRANDED"]
+    brands = ["telegram"]
+    config_keys = ["TELEGRAM_BOT_TOKEN"]
+    required_packages = ["python-telegram-bot"]
+    site_url = "https://telegram.org/"
+    description_text = "Secure instant messaging with bots"
+    # Geographic scope
+    branded_geo = "*"
+
+    def validate(self) -> tuple[bool, str]:
+        """Validates recipient has Telegram chat_id."""
+        if not self.missive:
+            return False, "Missive not defined"
+
+        recipient = getattr(self.missive, "recipient", None)
+        if not recipient:
+            return False, "Recipient not defined"
+
+        metadata = getattr(recipient, "metadata", None) or {}
+        chat_id = metadata.get("telegram_chat_id")
+        if not chat_id:
+            return False, "Recipient has no telegram_chat_id in metadata"
+
+        return True, ""
+
+    def send_branded(self, brand_name: Optional[str] = None, **kwargs) -> bool:
+        """Sends message via Telegram Bot API."""
+        is_valid, error = self.validate()
+        if not is_valid:
+            self._update_status(MissiveStatus.FAILED, error_message=error)
+            return False
+
+        # TODO: Implement actual sending
+        # For now, simulate sending
+        external_id = f"telegram_sim_{getattr(self.missive, 'id', 'unknown')}"
+        self._update_status(
+            MissiveStatus.SENT,
+            external_id=external_id,
+        )
+
+        return True
+
+    def check_status(self, external_id: Optional[str] = None) -> Optional[str]:
+        """
+        Check status of a Telegram message.
+
+        Note: Telegram does not provide automatic webhooks for delivery status.
+        Can only know if message was sent.
+        """
+        # TODO: Implement if needed
+        return None
+
+
+__all__ = ["TelegramProvider"]

pymissive/archives/providers/twilio.py

@@ -0,0 +1,310 @@
+"""Twilio provider for SMS and WhatsApp."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional, Tuple
+
+from ..status import MissiveStatus
+from .base import BaseProvider
+
+
+class TwilioProvider(BaseProvider):
+    """Twilio provider (SMS and WhatsApp)."""
+
+    name = "twilio"
+    display_name = "Twilio"
+    supported_types = ["SMS", "BRANDED", "VOICE_CALL"]
+    services = ["sms", "whatsapp", "voice", "verify"]
+    brands = ["whatsapp"]
+    config_keys = ["TWILIO_ACCOUNT_SID", "TWILIO_AUTH_TOKEN", "TWILIO_PHONE_NUMBER"]
+    required_packages = ["twilio"]
+    site_url = "https://www.twilio.com/"
+    status_url = "https://status.twilio.com/"
+    documentation_url = "https://www.twilio.com/docs"
+    description_text = "Global multi-channel cloud platform (SMS, WhatsApp, Voice)"
+
+    def send_twilio(self) -> bool:
+        """Dispatches to WhatsApp for BRANDED type."""
+        return self.send_whatsapp()
+
+    def send_sms(self) -> bool:
+        """Sends SMS via Twilio."""
+        is_valid, error = self._validate_and_check_recipient(
+            "recipient_phone", "Phone missing"
+        )
+        if not is_valid:
+            self._update_status(MissiveStatus.FAILED, error_message=error)
+            return False
+
+        try:
+            # TODO: Implement actual Twilio SMS sending
+            # from twilio.rest import Client
+            #
+            # account_sid = self._config.get('TWILIO_ACCOUNT_SID')
+            # auth_token = self._config.get('TWILIO_AUTH_TOKEN')
+            # from_number = self._config.get('TWILIO_PHONE_NUMBER')
+            #
+            # client = Client(account_sid, auth_token)
+            # message = client.messages.create(
+            #     body=self.missive.body,
+            #     from_=from_number,
+            #     to=self.missive.recipient_phone
+            # )
+            #
+            # external_id = message.sid
+
+            # Simulation
+            external_id = f"tw_sms_{getattr(self.missive, 'id', 'unknown')}"
+
+            self._update_status(
+                MissiveStatus.SENT, provider=self.name, external_id=external_id
+            )
+            self._create_event("sent", "SMS sent via Twilio")
+
+            return True
+
+        except Exception as e:
+            return self._handle_send_error(e)
+
+    def send_whatsapp(self) -> bool:
+        """Send via WhatsApp via Twilio"""
+        is_valid, error = self._validate_and_check_recipient(
+            "recipient_phone", "Phone missing"
+        )
+        if not is_valid:
+            self._update_status(MissiveStatus.FAILED, error_message=error)
+            return False
+
+        try:
+            # TODO: Integrate with Twilio WhatsApp
+            # from twilio.rest import Client
+            #
+            # account_sid = self._config.get('TWILIO_ACCOUNT_SID')
+            # auth_token = self._config.get('TWILIO_AUTH_TOKEN')
+            #
+            # client = Client(account_sid, auth_token)
+            #
+            # from_number = f"whatsapp:{self._config.get('TWILIO_WHATSAPP_NUMBER')}"
+            # to_number = f"whatsapp:{self.missive.recipient_phone}"
+            #
+            # message = client.messages.create(
+            #     body=self.missive.body,
+            #     from_=from_number,
+            #     to=to_number,
+            #     status_callback=self._config.get('TWILIO_WEBHOOK_URL')
+            # )
+            #
+            # external_id = message.sid
+
+            # Simulation
+            external_id = f"tw_wa_{getattr(self.missive, 'id', 'unknown')}"
+
+            self._update_status(
+                MissiveStatus.SENT, provider=self.name, external_id=external_id
+            )
+            self._create_event("sent", "WhatsApp message sent via Twilio")
+
+            return True
+
+        except Exception as e:
+            self._update_status(MissiveStatus.FAILED, error_message=str(e))
+            self._create_event("failed", str(e))
+            return False
+
+    def send_voice_call(self) -> bool:
+        """Send voice call via Twilio."""
+        is_valid, error = self.validate()
+        if not is_valid:
+            self._update_status(MissiveStatus.FAILED, error_message=error)
+            return False
+
+        if not self._get_missive_value("recipient_phone"):
+            self._update_status(MissiveStatus.FAILED, error_message="Phone missing")
+            return False
+
+        try:
+            # TODO: Implement actual Twilio Voice call
+            # from twilio.rest import Client
+            #
+            # account_sid = self._config.get('TWILIO_ACCOUNT_SID')
+            # auth_token = self._config.get('TWILIO_AUTH_TOKEN')
+            #
+            # client = Client(account_sid, auth_token)
+            # call = client.calls.create(
+            #     to=self.missive.recipient_phone,
+            #     from_=self._config.get('TWILIO_PHONE_NUMBER'),
+            #     url=self._config.get('TWILIO_VOICE_URL'),  # TwiML URL
+            # )
+            #
+            # external_id = call.sid
+
+            # Simulation
+            external_id = f"tw_voice_{getattr(self.missive, 'id', 'unknown')}"
+
+            self._update_status(
+                MissiveStatus.SENT, provider=self.name, external_id=external_id
+            )
+            self._create_event("sent", "Voice call initiated via Twilio")
+
+            return True
+
+        except Exception as e:
+            self._update_status(MissiveStatus.FAILED, error_message=str(e))
+            self._create_event("failed", str(e))
+            return False
+
+    def validate_webhook_signature(
+        self, payload: Dict, headers: Dict
+    ) -> Tuple[bool, str]:
+        """Validate Twilio webhook signature."""
+        auth_token = self._config.get("TWILIO_AUTH_TOKEN")
+        if not auth_token:
+            return True, ""
+
+        signature = headers.get("HTTP_X_TWILIO_SIGNATURE", "")
+        if not signature:
+            return False, "Signature missing"
+
+        # Twilio validation requires the full URL
+        # For simplicity, validation can be disabled in dev
+        # In production, implement according to:
+        # https://www.twilio.com/docs/usage/webhooks/webhooks-security
+
+        return True, ""  # Simplified for now
+
+    def extract_sms_missive_id(self, payload: Dict) -> Optional[str]:
+        """Extract missive ID from Twilio webhook."""
+        # Twilio returns MessageSid, we must have stored it in external_id
+        return payload.get("MessageSid")
+
+    def extract_event_type(self, payload: Dict) -> str:
+        """Extract status from Twilio webhook."""
+        return payload.get("MessageStatus", "unknown")
+
+    def get_status_from_event(self, event_type: str) -> Optional[MissiveStatus]:
+        """Map Twilio statuses to MissiveStatus."""
+        status_mapping = {
+            "queued": MissiveStatus.PENDING,
+            "sending": MissiveStatus.PENDING,
+            "sent": MissiveStatus.SENT,
+            "delivered": MissiveStatus.DELIVERED,
+            "undelivered": MissiveStatus.FAILED,
+            "failed": MissiveStatus.FAILED,
+            "read": MissiveStatus.READ,
+        }
+        return status_mapping.get(event_type.lower())
+
+    def get_service_status(self) -> Dict:
+        """
+        Gets Twilio status and credits.
+
+        Twilio uses a prepaid system in USD.
+
+        Returns:
+            Dict with status, credits in USD, etc.
+        """
+        last_check = self._get_last_check_time()
+
+        return {
+            "status": "unknown",
+            "is_available": None,
+            "services": self._get_services(),
+            "credits": {
+                "type": "money",
+                "remaining": None,
+                "currency": "USD",
+                "limit": None,
+                "percentage": None,
+            },
+            "rate_limits": {
+                "per_second": 1,
+                "per_minute": 60,
+            },
+            "sla": {
+                "uptime_percentage": 99.95,
+            },
+            "last_check": last_check,
+            "warnings": ["Twilio API not implemented - uncomment the code"],
+            "details": {
+                "refill_url": "https://www.twilio.com/console/billing",
+                "status_page": "https://status.twilio.com/",
+                "api_docs": ("https://www.twilio.com/docs/usage/api/usage-record"),
+            },
+        }
+
+    def cancel_sms(self) -> bool:
+        """
+        Cancel SMS sending via Twilio.
+
+        Twilio allows canceling messages in 'queued' or 'scheduled' status.
+
+        Returns:
+            bool: True if cancellation succeeded, False otherwise
+        """
+        if not self.missive or not getattr(self.missive, "external_id", None):
+            return False
+
+        try:
+            # TODO: Implement actual cancellation
+            # from twilio.rest import Client
+            #
+            # account_sid = self._config.get("TWILIO_ACCOUNT_SID")
+            # auth_token = self._config.get("TWILIO_AUTH_TOKEN")
+            #
+            # if not account_sid or not auth_token:
+            #     return False
+            #
+            # client = Client(account_sid, auth_token)
+            # message = client.messages(self.missive.external_id).update(
+            #     status="canceled"
+            # )
+            #
+            # if message.status == "canceled":
+            #     self._create_event("cancelled", "SMS cancelled via Twilio")
+            #     return True
+            # else:
+            #     return False
+
+            return False
+
+        except Exception:
+            return False
+
+    def cancel_twilio(self) -> bool:
+        """
+        Cancel branded message (WhatsApp) sending via Twilio.
+
+        Called automatically by cancel_branded() via dispatch.
+        Works the same way as cancel_sms() because Twilio uses
+        the same API for SMS and WhatsApp.
+
+        Returns:
+            bool: True if cancellation succeeded, False otherwise
+        """
+        return self.cancel_sms()
+
+    def cancel_whatsapp(self) -> bool:
+        """
+        Cancels WhatsApp message sending via Twilio.
+
+        Called automatically by cancel_branded("whatsapp") via dispatch.
+
+        Returns:
+            bool: True if cancellation succeeded, False otherwise
+        """
+        return self.cancel_sms()
+
+    def get_whatsapp_service_info(self) -> Dict:
+        """
+        Gets WhatsApp service information via Twilio.
+
+        Called automatically by get_branded_service_info("whatsapp") via dispatch.
+
+        Returns:
+            Dict with status, credits, etc.
+        """
+        # WhatsApp via Twilio uses the same credit system as SMS
+        return self.get_service_status()
+
+
+__all__ = ["TwilioProvider"]