django-cfg 1.3.13__py3-none-any.whl → 1.4.0__py3-none-any.whl

django_cfg/modules/django_twilio/_imports.py

@@ -0,0 +1,30 @@
+"""
+Optional Twilio imports.
+
+Makes twilio and sendgrid imports optional for testing and when not using Twilio functionality.
+"""
+
+# Third-party imports (optional - only required when using Twilio functionality)
+try:
+    from twilio.rest import Client
+    from twilio.base.exceptions import TwilioException
+    TWILIO_AVAILABLE = True
+except ImportError:
+    Client = None  # type: ignore
+    TwilioException = Exception  # Fallback to base exception
+    TWILIO_AVAILABLE = False
+
+try:
+    from sendgrid import SendGridAPIClient
+    SENDGRID_AVAILABLE = True
+except ImportError:
+    SendGridAPIClient = None  # type: ignore
+    SENDGRID_AVAILABLE = False
+
+__all__ = [
+    'Client',
+    'TwilioException',
+    'SendGridAPIClient',
+    'TWILIO_AVAILABLE',
+    'SENDGRID_AVAILABLE',
+]

django_cfg/modules/django_twilio/base.py

@@ -0,0 +1,192 @@
+"""
+Base service class for all Twilio operations.
+
+Provides auto-configuration from DjangoConfig and common utilities
+for all Twilio services including error handling and logging.
+"""
+
+import asyncio
+import logging
+import random
+import string
+from typing import Optional, Dict, Any
+from datetime import datetime, timedelta
+
+# Third-party imports (optional)
+from ._imports import Client, TwilioException, SendGridAPIClient, TWILIO_AVAILABLE, SENDGRID_AVAILABLE
+
+# Django CFG imports
+from django_cfg.modules.base import BaseCfgModule
+from django_cfg.modules.django_twilio.models import TwilioConfig
+from django_cfg.modules.django_twilio.exceptions import (
+    TwilioConfigurationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def is_async_context() -> bool:
+    """Detect if running in async context."""
+    try:
+        asyncio.get_running_loop()
+        return True
+    except RuntimeError:
+        return False
+
+
+class BaseTwilioService(BaseCfgModule):
+    """
+    Base service class for all Twilio operations.
+
+    Provides auto-configuration from DjangoConfig and common utilities
+    for all Twilio services including error handling and logging.
+    """
+
+    def __init__(self):
+        """Initialize with auto-discovered configuration."""
+        super().__init__()
+        self._config: Optional[TwilioConfig] = None
+        self._twilio_client: Optional[Client] = None
+        self._sendgrid_client: Optional[SendGridAPIClient] = None
+        self._otp_storage: Dict[str, Dict[str, Any]] = {}  # In-memory storage for development
+
+    def get_twilio_config(self) -> TwilioConfig:
+        """
+        Get Twilio configuration from DjangoConfig.
+
+        Returns:
+            TwilioConfig instance
+
+        Raises:
+            TwilioConfigurationError: If configuration is missing or invalid
+        """
+        if self._config is None:
+            django_config = self.get_config()
+            if not django_config:
+                raise TwilioConfigurationError(
+                    "DjangoConfig instance not found",
+                    suggestions=["Ensure DjangoConfig is properly initialized"]
+                )
+
+            twilio_config = getattr(django_config, 'twilio', None)
+            if not twilio_config:
+                raise TwilioConfigurationError(
+                    "Twilio configuration not found in DjangoConfig",
+                    missing_fields=["twilio"],
+                    suggestions=["Add TwilioConfig to your DjangoConfig class"]
+                )
+
+            self._config = twilio_config
+
+        return self._config
+
+    def get_twilio_client(self) -> Client:
+        """
+        Get initialized Twilio client.
+
+        Returns:
+            Twilio Client instance
+
+        Raises:
+            TwilioConfigurationError: If client cannot be initialized
+        """
+        if self._twilio_client is None:
+            config = self.get_twilio_config()
+
+            try:
+                client_config = config.get_client_config()
+                self._twilio_client = Client(
+                    client_config["username"],
+                    client_config["password"],
+                    region=client_config.get("region")
+                )
+
+                # Test connection with a simple API call
+                try:
+                    self._twilio_client.api.v2010.accounts(config.account_sid).fetch()
+                except TwilioException as e:
+                    raise TwilioConfigurationError(
+                        f"Failed to authenticate with Twilio: {e}",
+                        error_code=getattr(e, 'code', None),
+                        suggestions=[
+                            "Verify TWILIO_ACCOUNT_SID is correct",
+                            "Verify TWILIO_AUTH_TOKEN is correct",
+                            "Check Twilio account status"
+                        ]
+                    ) from e
+
+            except Exception as e:
+                raise TwilioConfigurationError(
+                    f"Failed to initialize Twilio client: {e}",
+                    suggestions=["Check Twilio configuration parameters"]
+                ) from e
+
+        return self._twilio_client
+
+    def get_sendgrid_client(self) -> Optional[SendGridAPIClient]:
+        """
+        Get initialized SendGrid client.
+
+        Returns:
+            SendGrid client instance or None if not configured
+
+        Raises:
+            TwilioConfigurationError: If client cannot be initialized
+        """
+        config = self.get_twilio_config()
+
+        if not config.sendgrid:
+            return None
+
+        if self._sendgrid_client is None:
+            try:
+                sendgrid_config = config.get_sendgrid_config()
+                if sendgrid_config:
+                    self._sendgrid_client = SendGridAPIClient(
+                        api_key=sendgrid_config["api_key"]
+                    )
+
+            except Exception as e:
+                raise TwilioConfigurationError(
+                    f"Failed to initialize SendGrid client: {e}",
+                    suggestions=["Check SendGrid API key configuration"]
+                ) from e
+
+        return self._sendgrid_client
+
+    def _generate_otp(self, length: int = 6) -> str:
+        """Generate numeric OTP code."""
+        return ''.join(random.choices(string.digits, k=length))
+
+    def _store_otp(self, identifier: str, code: str, ttl_seconds: int = 600) -> None:
+        """Store OTP code with expiration (in-memory for development)."""
+        self._otp_storage[identifier] = {
+            'code': code,
+            'created_at': datetime.now(),
+            'expires_at': datetime.now() + timedelta(seconds=ttl_seconds),
+            'attempts': 0,
+        }
+
+    def _get_stored_otp(self, identifier: str) -> Optional[Dict[str, Any]]:
+        """Get stored OTP data."""
+        return self._otp_storage.get(identifier)
+
+    def _remove_otp(self, identifier: str) -> None:
+        """Remove OTP from storage."""
+        self._otp_storage.pop(identifier, None)
+
+    def _mask_identifier(self, identifier: str) -> str:
+        """Mask identifier for security in logs."""
+        if "@" in identifier:  # Email
+            parts = identifier.split("@")
+            if len(parts) == 2:
+                return f"{parts[0][:2]}***@{parts[1]}"
+        else:  # Phone number
+            return f"***{identifier[-4:]}" if len(identifier) > 4 else "***"
+        return "***"
+
+
+__all__ = [
+    "is_async_context",
+    "BaseTwilioService",
+]

django_cfg/modules/django_twilio/email_otp.py

@@ -0,0 +1,227 @@
+"""
+Email OTP service using SendGrid.
+
+Provides OTP delivery via email with template support and
+comprehensive deliverability optimization.
+"""
+
+import logging
+from typing import Optional, Tuple, Dict, Any
+from django_cfg.modules.django_twilio._imports import SendGridAPIClient, SENDGRID_AVAILABLE
+
+# Import Mail helper conditionally
+try:
+    from sendgrid.helpers.mail import Mail
+except ImportError:
+    Mail = None  # type: ignore
+
+from asgiref.sync import sync_to_async
+
+from .base import BaseTwilioService
+from .models import SendGridConfig
+from .exceptions import (
+    TwilioConfigurationError,
+    TwilioSendError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class EmailOTPService(BaseTwilioService):
+    """
+    Email OTP service using SendGrid.
+
+    Provides OTP delivery via email with template support and
+    comprehensive deliverability optimization.
+    """
+
+    def send_otp(
+        self,
+        email: str,
+        subject: Optional[str] = None,
+        template_data: Optional[Dict[str, Any]] = None
+    ) -> Tuple[bool, str, str]:
+        """
+        Send OTP via email.
+
+        Args:
+            email: Recipient email address
+            subject: Custom email subject (uses default if not provided)
+            template_data: Additional data for email template
+
+        Returns:
+            Tuple[bool, str, str]: (success, message, otp_code)
+
+        Raises:
+            TwilioConfigurationError: If SendGrid is not configured
+            TwilioSendError: If email sending fails
+        """
+        config = self.get_twilio_config()
+
+        if not config.sendgrid:
+            raise TwilioConfigurationError(
+                "SendGrid configuration not found",
+                missing_fields=["sendgrid"],
+                suggestions=["Configure SendGridConfig in your Twilio settings"]
+            )
+
+        sendgrid_client = self.get_sendgrid_client()
+        if not sendgrid_client:
+            raise TwilioConfigurationError("SendGrid client not initialized")
+
+        try:
+            # Generate OTP code
+            otp_code = self._generate_otp(6)
+
+            # Store OTP for verification
+            self._store_otp(email, otp_code, config.verify.ttl_seconds if config.verify else 600)
+
+            # Prepare email content
+            if config.sendgrid.otp_template_id:
+                # Use dynamic template
+                success, message = self._send_template_email(
+                    sendgrid_client, config.sendgrid, email, otp_code, template_data
+                )
+            else:
+                # Use simple HTML email
+                success, message = self._send_simple_email(
+                    sendgrid_client, config.sendgrid, email, otp_code, subject
+                )
+
+            if success:
+                logger.info(f"Email OTP sent successfully to {self._mask_identifier(email)}")
+                return True, message, otp_code
+            else:
+                raise TwilioSendError(message, channel="email", recipient=email)
+
+        except Exception as e:
+            if isinstance(e, TwilioSendError):
+                raise
+            raise TwilioSendError(
+                f"Failed to send email OTP: {e}",
+                channel="email",
+                recipient=email
+            ) from e
+
+    async def asend_otp(
+        self,
+        email: str,
+        subject: Optional[str] = None,
+        template_data: Optional[Dict[str, Any]] = None
+    ) -> Tuple[bool, str, str]:
+        """Async version of send_otp."""
+        return await sync_to_async(self.send_otp)(email, subject, template_data)
+
+    def _send_template_email(
+        self,
+        client: SendGridAPIClient,
+        config: SendGridConfig,
+        email: str,
+        otp_code: str,
+        template_data: Optional[Dict[str, Any]] = None
+    ) -> Tuple[bool, str]:
+        """Send email using SendGrid dynamic template."""
+        try:
+            # Prepare template data
+            dynamic_data = {
+                'verification_code': otp_code,
+                'user_email': email,
+                'expiry_minutes': 10,
+                'company_name': config.from_name,
+                **config.custom_template_data,
+                **(template_data or {})
+            }
+
+            message = Mail(
+                from_email=(config.from_email, config.from_name),
+                to_emails=email
+            )
+
+            message.template_id = config.otp_template_id
+            message.dynamic_template_data = dynamic_data
+
+            if config.reply_to_email:
+                message.reply_to = config.reply_to_email
+
+            response = client.send(message)
+
+            if response.status_code in [200, 201, 202]:
+                return True, f"OTP sent via email template to {self._mask_identifier(email)}"
+            else:
+                return False, f"SendGrid API error: {response.status_code}"
+
+        except Exception as e:
+            return False, f"Template email error: {e}"
+
+    def _send_simple_email(
+        self,
+        client: SendGridAPIClient,
+        config: SendGridConfig,
+        email: str,
+        otp_code: str,
+        subject: Optional[str] = None
+    ) -> Tuple[bool, str]:
+        """Send simple HTML email without template."""
+        try:
+            html_content = self._generate_html_content(otp_code, config.from_name)
+            plain_content = self._generate_plain_content(otp_code)
+
+            message = Mail(
+                from_email=(config.from_email, config.from_name),
+                to_emails=email,
+                subject=subject or config.default_subject,
+                html_content=html_content,
+                plain_text_content=plain_content
+            )
+
+            if config.reply_to_email:
+                message.reply_to = config.reply_to_email
+
+            response = client.send(message)
+
+            if response.status_code in [200, 201, 202]:
+                return True, f"OTP sent via email to {self._mask_identifier(email)}"
+            else:
+                return False, f"SendGrid API error: {response.status_code}"
+
+        except Exception as e:
+            return False, f"Simple email error: {e}"
+
+    def _generate_html_content(self, otp_code: str, company_name: str) -> str:
+        """Generate HTML email content."""
+        return f"""
+        <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+            <div style="background-color: #f8f9fa; padding: 30px; border-radius: 10px; text-align: center;">
+                <h1 style="color: #333; margin-bottom: 20px;">Verification Code</h1>
+                <p style="color: #666; font-size: 16px; margin-bottom: 30px;">
+                    Your verification code is:
+                </p>
+                <div style="background-color: #007bff; color: white; font-size: 32px; font-weight: bold;
+                     padding: 20px; border-radius: 8px; letter-spacing: 5px; margin: 30px 0;">
+                    {otp_code}
+                </div>
+                <p style="color: #999; font-size: 14px;">
+                    This code expires in 10 minutes<br>
+                    If you didn't request this code, please ignore this email
+                </p>
+                <hr style="border: none; border-top: 1px solid #eee; margin: 30px 0;">
+                <p style="color: #999; font-size: 12px;">
+                    Sent by {company_name}
+                </p>
+            </div>
+        </div>
+        """
+
+    def _generate_plain_content(self, otp_code: str) -> str:
+        """Generate plain text email content."""
+        return f"""
+Your verification code: {otp_code}
+
+This code expires in 10 minutes.
+If you didn't request this code, please ignore this email.
+        """.strip()
+
+
+__all__ = [
+    "EmailOTPService",
+]

django_cfg/modules/django_twilio/sendgrid_service.py

@@ -359,7 +359,7 @@ class SendGridService(BaseCfgModule):
         """Send simple HTML email using Django templates."""
         try:
             # Get current config for template context
-            from django_cfg.core.config import get_current_config
+            from django_cfg.core.state import get_current_config
             current_config = get_current_config()
             
             # Prepare context for unified template

django_cfg/modules/django_twilio/simple_service.py

@@ -7,8 +7,7 @@ without the complexity of the OTP system.
 
 import logging
 from typing import Optional, Dict, Any
-from twilio.rest import Client
-from twilio.base.exceptions import TwilioException
+from ._imports import Client, TwilioException
 
 from django_cfg.modules.base import BaseCfgModule
 from django_cfg.modules.django_twilio.models import TwilioConfig

django_cfg/modules/django_twilio/sms.py

@@ -0,0 +1,94 @@
+"""
+SMS OTP service using Twilio Verify API.
+
+Provides reliable SMS OTP delivery with comprehensive
+error handling and international support.
+"""
+
+import logging
+from typing import Tuple
+from asgiref.sync import sync_to_async
+
+from .base import BaseTwilioService
+from .exceptions import (
+    TwilioConfigurationError,
+    TwilioSendError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SMSOTPService(BaseTwilioService):
+    """
+    SMS OTP service using Twilio Verify API.
+
+    Provides reliable SMS OTP delivery with comprehensive
+    error handling and international support.
+    """
+
+    def send_otp(self, phone_number: str) -> Tuple[bool, str]:
+        """
+        Send OTP via SMS.
+
+        Args:
+            phone_number: Phone number in E.164 format
+
+        Returns:
+            Tuple[bool, str]: (success, message)
+
+        Raises:
+            TwilioConfigurationError: If Verify service not configured
+            TwilioSendError: If SMS sending fails
+        """
+        config = self.get_twilio_config()
+
+        if not config.verify:
+            raise TwilioConfigurationError(
+                "Twilio Verify service not configured",
+                missing_fields=["verify"],
+                suggestions=["Configure TwilioVerifyConfig in your Twilio settings"]
+            )
+
+        client = self.get_twilio_client()
+
+        try:
+            verification = client.verify.v2.services(
+                config.verify.service_sid
+            ).verifications.create(
+                to=phone_number,
+                channel='sms'
+            )
+
+            if verification.status == 'pending':
+                logger.info(f"SMS OTP sent successfully to {self._mask_identifier(phone_number)}")
+                return True, f"OTP sent via SMS to {self._mask_identifier(phone_number)}"
+            else:
+                raise TwilioSendError(
+                    f"SMS OTP failed with status: {verification.status}",
+                    channel="sms",
+                    recipient=phone_number
+                )
+
+        except TwilioException as e:
+            raise TwilioSendError(
+                f"SMS OTP failed: {e}",
+                channel="sms",
+                recipient=phone_number,
+                twilio_error_code=getattr(e, 'code', None),
+                twilio_error_message=str(e)
+            ) from e
+        except Exception as e:
+            raise TwilioSendError(
+                f"Unexpected error sending SMS OTP: {e}",
+                channel="sms",
+                recipient=phone_number
+            ) from e
+
+    async def asend_otp(self, phone_number: str) -> Tuple[bool, str]:
+        """Async version of send_otp."""
+        return await sync_to_async(self.send_otp)(phone_number)
+
+
+__all__ = [
+    "SMSOTPService",
+]

django_cfg/modules/django_twilio/twilio_service.py

@@ -13,8 +13,7 @@ import string
 from typing import Optional, Dict, Any, Tuple
 from datetime import datetime, timedelta
 
-from twilio.rest import Client
-from twilio.base.exceptions import TwilioException
+from ._imports import Client, TwilioException
 from asgiref.sync import sync_to_async
 
 from django_cfg.modules.base import BaseCfgModule
@@ -256,7 +255,7 @@ class TwilioService(BaseCfgModule):
         
         # STEP 1: Try Direct WhatsApp with custom OTP
         try:
-            from django_cfg.core.config import get_current_config
+            from django_cfg.core.state import get_current_config
             django_config = get_current_config()
             site_name = django_config.project_name if django_config else "Django CFG"