django-cfg 1.1.81__py3-none-any.whl → 1.2.0__py3-none-any.whl

django_cfg/modules/django_twilio/templates/guide.md

@@ -0,0 +1,266 @@
+# 🚀 Django CFG Twilio Integration - Complete Setup Guide
+
+## 📋 Overview
+
+Django CFG Twilio provides seamless integration for:
+- 📱 **WhatsApp OTP** via Twilio Verify API
+- 📱 **SMS OTP** via Twilio Verify API  
+- 📧 **Email OTP** via SendGrid
+- 🔧 **Testing Suite** with management commands
+- 📧 **HTML Email Templates** with customization
+
+## 🛠️ Quick Setup (5 minutes)
+
+### 1. Install Dependencies
+```bash
+pip install django-cfg[twilio]
+# or
+poetry add django-cfg[twilio]
+```
+
+### 2. Configure Twilio Services
+
+#### A. Create Twilio Verify Service
+1. Go to [Twilio Console > Verify > Services](https://console.twilio.com/us1/develop/verify/services)
+2. Click **Create new Service**
+3. Name: `YourApp OTP Service`
+4. **Enable channels**: WhatsApp ✅, SMS ✅
+5. Copy the **Service SID** (starts with `VA...`)
+
+#### B. Get SendGrid API Key (Optional)
+1. Go to [SendGrid Console > API Keys](https://app.sendgrid.com/settings/api_keys)
+2. Create new API key with **Mail Send** permissions
+3. Copy the API key (starts with `SG.`)
+
+### 3. Update Configuration Files
+
+#### `config.dev.yaml`
+```yaml
+twilio:
+  account_sid: "AC_YOUR_ACCOUNT_SID"
+  auth_token: "YOUR_AUTH_TOKEN"
+  whatsapp_from: "+14155238886"  # Twilio sandbox
+  sms_from: "+YOUR_SMS_NUMBER"
+  sendgrid_api_key: "SG.YOUR_SENDGRID_API_KEY"
+  verify_service_sid: "VA_YOUR_VERIFY_SERVICE_SID"
+```
+
+#### `config.py`
+```python
+from django_cfg.modules.django_twilio.models import SendGridConfig, TwilioVerifyConfig, TwilioChannelType
+
+class YourProjectConfig(DjangoConfig):
+    # Admin emails for testing
+    admin_emails: List[str] = ["admin@yourdomain.com"]
+    
+    # Twilio configuration
+    twilio: Optional[TwilioConfig] = TwilioConfig(
+        account_sid=env.twilio.account_sid,
+        auth_token=SecretStr(env.twilio.auth_token),
+        
+        # Verify API for OTP
+        verify=TwilioVerifyConfig(
+            service_sid=env.twilio.verify_service_sid,
+            service_name=env.app.name,
+            default_channel=TwilioChannelType.WHATSAPP,
+            fallback_channels=[TwilioChannelType.SMS],
+            code_length=6,
+            ttl_seconds=600,  # 10 minutes
+            max_attempts=5,
+        ) if env.twilio.verify_service_sid else None,
+        
+        # SendGrid for email
+        sendgrid=SendGridConfig(
+            api_key=SecretStr(env.twilio.sendgrid_api_key),
+            from_email="noreply@yourdomain.com",
+            from_name=env.app.name,
+            default_subject=f"Your {env.app.name} verification code",
+        ) if env.twilio.sendgrid_api_key else None,
+    ) if env.twilio.account_sid and env.twilio.auth_token else None
+```
+
+## 🧪 Testing Everything
+
+### Quick Test Command
+```bash
+# Test all services
+python manage.py test_twilio --mode=all
+
+# Test OTP only
+python manage.py test_twilio --mode=test-otp --phone="+1234567890"
+
+# Interactive mode
+python manage.py test_twilio --interactive
+
+# Check configuration
+python manage.py test_twilio --mode=setup
+```
+
+### Expected Output
+```
+🚀 Django CFG Twilio Test Suite
+==================================================
+📧 Using admin email from config: admin@yourdomain.com
+
+🔧 Configuration Check
+------------------------------
+✅ Admin emails configured
+✅ Twilio configuration found
+✅ Verify API configured
+✅ SendGrid configured
+✅ Email configuration found
+
+🔐 Testing OTP Functionality
+------------------------------
+📱 Testing WhatsApp OTP to +1234567890...
+✅ OTP sent via WhatsApp to ***7890
+
+📧 Testing Email OTP to admin@yourdomain.com...
+✅ Email OTP sent (code: 123456)
+
+🎉 All tests completed!
+```
+
+## 🔌 API Usage
+
+### Basic OTP Request
+```python
+from django_cfg.modules.django_twilio import send_whatsapp_otp, verify_otp
+
+# Send WhatsApp OTP
+success, message = send_whatsapp_otp("+1234567890")
+
+# Verify OTP
+is_valid, message = verify_otp("+1234567890", "123456")
+```
+
+### Email OTP
+```python
+from django_cfg.modules.django_twilio import send_otp_email
+
+# Send email OTP
+success, message, otp_code = send_otp_email("user@example.com")
+```
+
+### REST API Endpoints
+```bash
+# Request OTP
+curl -X POST http://localhost:8000/api/accounts/otp/request/ \
+  -H "Content-Type: application/json" \
+  -d '{"identifier": "+1234567890", "channel": "phone"}'
+
+# Verify OTP
+curl -X POST http://localhost:8000/api/accounts/otp/verify/ \
+  -H "Content-Type: application/json" \
+  -d '{"identifier": "+1234567890", "otp": "123456", "channel": "phone"}'
+```
+
+## 📧 Email Templates
+
+### Template Structure
+```
+django_cfg/modules/django_twilio/templates/
+├── email_otp_template.html      # Main HTML template
+├── email_otp_test_data.json     # Test data
+└── email_otp_rendered.html      # Generated preview
+```
+
+### Template Variables
+- `{{app_name}}` - Your app name
+- `{{user_name}}` - User's name
+- `{{otp_code}}` - 6-digit OTP code
+- `{{otp_link}}` - Verification link
+- `{{expires_minutes}}` - Expiry time
+
+### Generate Templates
+```bash
+python manage.py test_twilio --mode=generate-templates
+```
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+#### 1. WhatsApp Not Working
+```
+❌ Error: Unable to create record: Delivery channel disabled: WHATSAPP
+```
+**Solution**: Enable WhatsApp channel in [Twilio Console > Verify > Services](https://console.twilio.com/us1/develop/verify/services)
+
+#### 2. SMS to International Numbers
+```
+❌ Error: Message cannot be sent with current 'To' and 'From' parameters
+```
+**Solution**: Use Verify API (automatic) or upgrade Twilio account for international SMS
+
+#### 3. SendGrid Not Working
+```
+❌ Error: SendGrid configuration not found
+```
+**Solution**: Add `sendgrid_api_key` to your YAML config and enable in `config.py`
+
+#### 4. Email Not Sending
+```
+❌ Error: Email backend not configured
+```
+**Solution**: Check email configuration in `config.py` and ensure SMTP settings are correct
+
+### Debug Mode
+```python
+# Enable detailed logging
+twilio: TwilioConfig = TwilioConfig(
+    debug_logging=True,  # Shows all API requests/responses
+    test_mode=True,      # Uses test credentials
+)
+```
+
+## 📱 Production Checklist
+
+### Before Going Live:
+
+#### Twilio Setup
+- [ ] **Account verified** and upgraded from trial
+- [ ] **Phone numbers verified** for SMS
+- [ ] **WhatsApp Business approved** (if using production WhatsApp)
+- [ ] **Verify Service** created and channels enabled
+- [ ] **Webhook URLs** configured (optional)
+
+#### SendGrid Setup  
+- [ ] **Domain authentication** completed
+- [ ] **Sender identity** verified
+- [ ] **API key** with proper permissions
+- [ ] **Email templates** tested and approved
+
+#### Security
+- [ ] **Environment variables** for sensitive data
+- [ ] **Rate limiting** configured
+- [ ] **Admin emails** updated for production
+- [ ] **Error monitoring** setup (Sentry, etc.)
+
+#### Testing
+- [ ] **All OTP channels** tested with real numbers
+- [ ] **Email delivery** tested with real addresses  
+- [ ] **Error handling** tested with invalid inputs
+- [ ] **Load testing** completed for expected volume
+
+## 🔗 Useful Links
+
+- [Twilio Console](https://console.twilio.com/)
+- [Twilio Verify API Docs](https://www.twilio.com/docs/verify/api)
+- [SendGrid Console](https://app.sendgrid.com/)
+- [Django CFG Documentation](https://github.com/your-repo/django-cfg)
+
+## 💡 Pro Tips
+
+1. **Use Verify API** for professional OTP instead of custom solutions
+2. **Enable both WhatsApp and SMS** for better delivery rates
+3. **Test with real numbers** in different countries
+4. **Monitor delivery rates** in Twilio Console
+5. **Use admin_emails** for easy testing configuration
+6. **Keep templates simple** for better email client compatibility
+
+---
+
+🎉 **You're all set!** Your Django CFG Twilio integration is ready for production use.
+
+For support, check the troubleshooting section or create an issue on GitHub.

django_cfg/modules/django_twilio/twilio_service.py

@@ -17,7 +17,7 @@ from twilio.rest import Client
 from twilio.base.exceptions import TwilioException
 from asgiref.sync import sync_to_async
 
-from django_cfg.modules.base import BaseModule
+from django_cfg.modules.base import BaseCfgModule
 from django_cfg.modules.django_twilio.models import TwilioConfig, TwilioVerifyConfig
 from django_cfg.modules.django_twilio.exceptions import (
     TwilioConfigurationError,
@@ -27,7 +27,7 @@ from django_cfg.modules.django_twilio.exceptions import (
 logger = logging.getLogger(__name__)
 
 
-class TwilioService(BaseModule):
+class TwilioService(BaseCfgModule):
     """
     Unified Twilio service for WhatsApp, SMS, and OTP.
     

django_cfg/modules/django_unfold/__init__.py

@@ -0,0 +1,69 @@
+"""
+Django CFG Unfold Module
+
+Provides complete Unfold admin interface integration with dashboard,
+navigation, theming, and callback support.
+"""
+
+from .dashboard import DashboardManager, get_dashboard_manager
+from .callbacks import UnfoldCallbacks
+from .system_monitor import SystemMonitor
+from .tailwind import get_unfold_colors, get_css_variables
+from .models import *
+
+# Lazy initialization functions to avoid circular imports
+def get_system_monitor() -> SystemMonitor:
+    """Get the global system monitor instance."""
+    global _system_monitor
+    if '_system_monitor' not in globals():
+        globals()['_system_monitor'] = SystemMonitor()
+    return globals()['_system_monitor']
+
+def get_unfold_callbacks() -> UnfoldCallbacks:
+    """Get the global unfold callbacks instance."""
+    global _unfold_callbacks
+    if '_unfold_callbacks' not in globals():
+        globals()['_unfold_callbacks'] = UnfoldCallbacks()
+    return globals()['_unfold_callbacks']
+
+# Export main components
+__all__ = [
+    'DashboardManager',
+    'get_dashboard_manager',
+    'UnfoldCallbacks', 
+    'get_unfold_callbacks',
+    'SystemMonitor',
+    'get_system_monitor',
+    'get_unfold_colors',
+    'get_css_variables',
+    # Models
+    'UnfoldConfig',
+    'UnfoldTheme', 
+    'UnfoldColors',
+    'UnfoldSidebar',
+    'UnfoldThemeConfig',
+    'UnfoldDashboardConfig',
+    'NavigationItem',
+    'NavigationSection',
+    'NavigationItemType',
+    'SiteDropdownItem',
+    'StatCard',
+    'SystemHealthItem',
+    'QuickAction',
+    'DashboardWidget',
+    'DashboardData',
+    'ChartDataset',
+    'ChartData',
+    'TabConfiguration',
+    'TabItem',
+]
+
+# Version info
+__version__ = '1.0.0'
+__author__ = 'Django CFG Team'
+__email__ = 'team@djangocfg.com'
+
+# Module metadata
+__title__ = 'Django CFG Unfold'
+__description__ = 'Complete Unfold admin interface integration'
+__url__ = 'https://github.com/djangocfg/django-cfg'

django_cfg/modules/{unfold → django_unfold}/callbacks.py

@@ -21,8 +21,9 @@ from django.db import connection
 from django.core.cache import cache
 from django.apps import apps
 
-from ..base import BaseModule
-from .models import DashboardData, StatCard, SystemHealthItem, QuickAction
+from ..base import BaseCfgModule
+from .models.dashboard import DashboardData, StatCard, SystemHealthItem, QuickAction
+from .icons import Icons
 
 logger = logging.getLogger(__name__)
 
@@ -119,7 +120,7 @@ def get_user_admin_urls():
         }
 
 
-class UnfoldCallbacks(BaseModule):
+class UnfoldCallbacks(BaseCfgModule):
     """
     Base Unfold dashboard callbacks with full system monitoring.
     
@@ -148,7 +149,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Total Users",
                     value=f"{total_users:,}",
-                    icon="people",
+                    icon=Icons.PEOPLE,
                     change=f"+{new_users_7d}" if new_users_7d > 0 else None,
                     change_type="positive" if new_users_7d > 0 else "neutral",
                     description="Registered users",
@@ -156,7 +157,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Active Users",
                     value=f"{active_users:,}",
-                    icon="person",
+                    icon=Icons.PERSON,
                     change=(
                         f"{(active_users/total_users*100):.1f}%"
                         if total_users > 0
@@ -170,14 +171,14 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="New This Week",
                     value=f"{new_users_7d:,}",
-                    icon="person_add",
+                    icon=Icons.PERSON_ADD,
                     change_type="positive" if new_users_7d > 0 else "neutral",
                     description="Last 7 days",
                 ),
                 StatCard(
                     title="Staff Members",
                     value=f"{staff_users:,}",
-                    icon="admin_panel_settings",
+                    icon=Icons.ADMIN_PANEL_SETTINGS,
                     change=(
                         f"{(staff_users/total_users*100):.1f}%" if total_users > 0 else "0%"
                     ),
@@ -191,7 +192,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Users",
                     value="N/A",
-                    icon="people",
+                    icon=Icons.PEOPLE,
                     description="Data unavailable",
                 )
             ]
@@ -316,7 +317,7 @@ class UnfoldCallbacks(BaseModule):
             QuickAction(
                 title="Add User",
                 description="Create new user account",
-                icon="person_add",
+                icon=Icons.PERSON_ADD,
                 link=user_admin_urls["add"],
                 color="primary",
                 category="admin",
@@ -324,16 +325,16 @@ class UnfoldCallbacks(BaseModule):
             QuickAction(
                 title="Support Tickets",
                 description="Manage support tickets",
-                icon="support_agent",
+                icon=Icons.SUPPORT_AGENT,
                 link="admin:django_cfg_support_ticket_changelist",
-                color="info",
+                color="primary",
                 category="support",
             ),
             QuickAction(
                 title="Health Check",
                 description="System health status",
-                icon="health_and_safety",
-                link="django_cfg_health",
+                icon=Icons.HEALTH_AND_SAFETY,
+                link="/cfg/health/",
                 color="success",
                 category="system",
             ),
@@ -382,7 +383,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Total Tickets",
                     value=f"{total_tickets:,}",
-                    icon="support_agent",
+                    icon=Icons.SUPPORT_AGENT,
                     change=f"+{new_tickets_7d}" if new_tickets_7d > 0 else None,
                     change_type="positive" if new_tickets_7d > 0 else "neutral",
                     description="All support tickets",
@@ -390,7 +391,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Open Tickets",
                     value=f"{open_tickets:,}",
-                    icon="pending",
+                    icon=Icons.PENDING,
                     change=(
                         f"{(open_tickets/total_tickets*100):.1f}%"
                         if total_tickets > 0
@@ -406,7 +407,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Resolved",
                     value=f"{resolved_tickets:,}",
-                    icon="check_circle",
+                    icon=Icons.CHECK_CIRCLE,
                     change=(
                         f"{(resolved_tickets/total_tickets*100):.1f}%"
                         if total_tickets > 0
@@ -418,7 +419,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="New This Week",
                     value=f"{new_tickets_7d:,}",
-                    icon="new_releases",
+                    icon=Icons.NEW_RELEASES,
                     change_type="positive" if new_tickets_7d > 0 else "neutral",
                     description="Last 7 days",
                 ),
@@ -429,7 +430,7 @@ class UnfoldCallbacks(BaseModule):
                 StatCard(
                     title="Support",
                     value="N/A",
-                    icon="support_agent",
+                    icon=Icons.SUPPORT_AGENT,
                     description="Data unavailable",
                 )
             ]
@@ -707,14 +708,14 @@ class UnfoldCallbacks(BaseModule):
                 environment=getattr(settings, "ENVIRONMENT", "development"),
             )
 
-            # Convert to template context (keeping Pydantic validation)
-            cards_data = [card.model_dump() for card in dashboard_data.stat_cards]
+            # Convert to template context (using to_dict for Unfold compatibility)
+            cards_data = [card.to_dict() for card in dashboard_data.stat_cards]
 
             context.update({
                 # Statistics cards
                 "cards": cards_data,
-                "user_stats": [card.model_dump() for card in user_stats],
-                "support_stats": [card.model_dump() for card in support_stats],
+                "user_stats": [card.to_dict() for card in user_stats],
+                "support_stats": [card.to_dict() for card in support_stats],
                 # System health (convert to dict for template)
                 "system_health": {
                     item.component + "_status": item.status