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

django_cfg/__init__.py

@@ -38,7 +38,7 @@ default_app_config = "django_cfg.apps.DjangoCfgConfig"
 from typing import TYPE_CHECKING
 
 # Version information
-__version__ = "1.1.81"
+__version__ = "1.1.82"
 __author__ = "Unrealos Team"
 __email__ = "info@unrealos.com"
 __license__ = "MIT"

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-1.1.81.dist-info → django_cfg-1.1.82.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-cfg
-Version: 1.1.81
+Version: 1.1.82
 Summary: 🚀 Production-ready Django configuration framework with type-safe settings, smart automation, and modern developer experience
 Project-URL: Homepage, https://github.com/markolofsen/django-cfg
 Project-URL: Documentation, https://django-cfg.readthedocs.io

{django_cfg-1.1.81.dist-info → django_cfg-1.1.82.dist-info}/RECORD

@@ -1,5 +1,5 @@
 django_cfg/README.md,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_cfg/__init__.py,sha256=izT5u3ve-q3owo5utgpw1QifrTw9GqjixkzygUpny8M,14288
+django_cfg/__init__.py,sha256=gIUc-yUHEQRkNikh05rk2BOOBZtm8-Dx3cm_rTbfY5g,14288
 django_cfg/apps.py,sha256=k84brkeXJI7EgKZLEpTkM9YFZofKI4PzhFOn1cl9Msc,1656
 django_cfg/exceptions.py,sha256=RTQEoU3PfR8lqqNNv5ayd_HY2yJLs3eioqUy8VM6AG4,10378
 django_cfg/integration.py,sha256=jUO-uZXLmBXy9iugqgsl_xnYA_xoH3LZg5RxZbobVrc,4988
@@ -127,7 +127,6 @@ django_cfg/apps/tasks/apps.py,sha256=WXQvQjFVBuiO7s1ikd4Sf15YKRTvruVzMTo82uNXY08
 django_cfg/apps/tasks/serializers.py,sha256=o323j6bmeNAVCu-FA3Jrve2tLuFOHMgkfXgZUdsTuS8,2751
 django_cfg/apps/tasks/urls.py,sha256=NwEk6Vjq_ETEzzbx6R-9Qv3EbCxmX31xfzLICrlQ6cw,587
 django_cfg/apps/tasks/views.py,sha256=HO4fSHyYALOKmLiLsm2Ir-G2DgCsZGHuoncq8FVRp5s,18048
-django_cfg/apps/tasks/@docs/README.md,sha256=A1A4e56ed1Dh6R5XHEgInOkHv25fUQfJGVIs9f_G1ZM,6363
 django_cfg/apps/tasks/static/tasks/css/dashboard.css,sha256=mDtAwFWzNrWEJkbkQFewmzFSYRXgTfGIXVkfWkbcUW0,4765
 django_cfg/apps/tasks/static/tasks/js/api.js,sha256=01OL5P0AO4fg9vCjVNx5s1mGgh6Ate69rucfA27CS3c,4048
 django_cfg/apps/tasks/static/tasks/js/dashboard.js,sha256=iBizGudFpzkX29cJbYv7Zim2xHx94uoBtmPCJ7t6TzE,23496
@@ -233,6 +232,7 @@ django_cfg/modules/django_twilio/sendgrid_service.py,sha256=VKRjQ4iw6IQ_slde8TK3
 django_cfg/modules/django_twilio/service.py,sha256=oLhnL0emT05AGY6uAos5tjAaEN-hGKXwHKtaV94K-w8,34866
 django_cfg/modules/django_twilio/simple_service.py,sha256=pcXI28z2siyH4-8dwTbbjFpIYzLpam5c6LmJfJVYsk0,10035
 django_cfg/modules/django_twilio/twilio_service.py,sha256=BTUiInH1XKft6_nMZtySJbrUh8rAR1wYVZgRB5Oc264,20138
+django_cfg/modules/django_twilio/templates/guide.md,sha256=nZfwx-sgWyK5NApm93zOeeMTfLPOa8HK0IIYKdMLCzE,7799
 django_cfg/modules/django_twilio/templates/sendgrid_otp_email.html,sha256=sXR6_D9hmOFfk9CrfPizpLddVhkRirBWpZd_ioEsxVk,6671
 django_cfg/modules/django_twilio/templates/sendgrid_test_data.json,sha256=fh1VyuSiDELHsS_CIz9gp7tlsMAEjaDOoqbAPSZ3yyo,339
 django_cfg/modules/unfold/__init__.py,sha256=iy9-M0cXMouipP7iHPJbKnQuuVJxkB8VlkBx9WJMCsc,724
@@ -271,8 +271,8 @@ django_cfg/templates/emails/base_email.html,sha256=TWcvYa2IHShlF_E8jf1bWZStRO0v8
 django_cfg/utils/__init__.py,sha256=64wwXJuXytvwt8Ze_erSR2HmV07nGWJ6DV5wloRBvYE,435
 django_cfg/utils/path_resolution.py,sha256=eML-6-RIGTs5TePktIQN8nxfDUEFJ3JA0AzWBcihAbs,13894
 django_cfg/utils/smart_defaults.py,sha256=-qaoiOQ1HKDOzwK2uxoNlmrOX6l8zgGlVPgqtdj3y4g,22319
-django_cfg-1.1.81.dist-info/METADATA,sha256=2KREhhUvAVtIBlHCR1cbbCDMQlm3zxGblxMTIfByn-s,45783
-django_cfg-1.1.81.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-django_cfg-1.1.81.dist-info/entry_points.txt,sha256=Ucmde4Z2wEzgb4AggxxZ0zaYDb9HpyE5blM3uJ0_VNg,56
-django_cfg-1.1.81.dist-info/licenses/LICENSE,sha256=xHuytiUkSZCRG3N11nk1X6q1_EGQtv6aL5O9cqNRhKE,1071
-django_cfg-1.1.81.dist-info/RECORD,,
+django_cfg-1.1.82.dist-info/METADATA,sha256=PSBG-0MIsRKeHjR9U3XE6paEumN9nOx56v86SSeJWXM,45783
+django_cfg-1.1.82.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+django_cfg-1.1.82.dist-info/entry_points.txt,sha256=Ucmde4Z2wEzgb4AggxxZ0zaYDb9HpyE5blM3uJ0_VNg,56
+django_cfg-1.1.82.dist-info/licenses/LICENSE,sha256=xHuytiUkSZCRG3N11nk1X6q1_EGQtv6aL5O9cqNRhKE,1071
+django_cfg-1.1.82.dist-info/RECORD,,

django_cfg/apps/tasks/@docs/README.md

@@ -1,195 +0,0 @@
-# 📚 Django-CFG Tasks Documentation
-
-## 🎯 Overview
-
-This directory contains comprehensive documentation for Django-CFG task system, covering all aspects of background task processing with Dramatiq.
-
-**Documentation follows the DOCS_MODULE.md methodology** for LLM-optimized, token-efficient documentation.
-
----
-
-## 📖 Documentation Files
-
-### [TASKS_QUEUES.md](./TASKS_QUEUES.md) %%PRIORITY:HIGH%%
-**Main documentation covering**:
-- Architecture and core components
-- Queue configuration and usage patterns  
-- Worker management (manual startup)
-- Task processing flows
-- Common issues and solutions
-- Development workflow
-- Production deployment
-
-**Use this for**: Understanding the system, configuration, and general usage.
-
-### [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) %%PRIORITY:HIGH%%
-**Comprehensive troubleshooting guide covering**:
-- Critical issues (tasks stuck, Redis DB mismatch, worker failures)
-- Diagnostic tools and commands
-- Recovery procedures
-- Performance issues
-- Emergency procedures
-- Prevention tips
-
-**Use this for**: Debugging problems, performance issues, and system recovery.
-
-### [CONFIGURATION.md](./CONFIGURATION.md)
-**Complete configuration reference covering**:
-- Configuration models (TaskConfig, DramatiqConfig)
-- Environment-specific configurations
-- Docker and container setup
-- Process management (systemd, supervisor)
-- Security configuration
-- Monitoring and health checks
-- Advanced configuration options
-
-**Use this for**: Setting up environments, deployment, and advanced configuration.
-
----
-
-## 🚀 Quick Start
-
-### 1. Basic Setup
-```python
-# In your Django-CFG config
-from django_cfg.models.tasks import TaskConfig, DramatiqConfig
-
-config = SampleProjectConfig(
-    tasks=TaskConfig(
-        enabled=True,
-        dramatiq=DramatiqConfig(
-            redis_db=2,  # Important: Use separate Redis DB
-            processes=2,
-            threads=4,
-            queues=["default", "knowledge", "high", "low"]
-        )
-    )
-)
-```
-
-### 2. Start Workers
-```bash
-# Manual startup (recommended)
-poetry run python manage.py rundramatiq --processes 2 --threads 4
-
-# Development mode
-poetry run python manage.py rundramatiq --processes 1 --threads 2
-```
-
-### 3. Create Tasks
-```python
-import dramatiq
-
-@dramatiq.actor(queue_name="knowledge")
-def process_document(document_id: str):
-    # Your task logic here
-    pass
-
-# Enqueue task
-process_document.send("doc-123")
-```
-
----
-
-## 🔧 Key Changes %%BREAKING_CHANGE%%
-
-### Removed in v1.1.54
-- **Auto-start functionality**: No more automatic worker startup
-- **`auto_start_worker` field**: Removed from TaskConfig model
-- **Subprocess worker management**: Eliminated due to reliability issues
-
-### Why the Change?
-1. **Subprocess Issues**: Workers couldn't find Django commands properly
-2. **Environment Problems**: `DJANGO_SETTINGS_MODULE` not inherited correctly  
-3. **Process Management**: Better handled by systemd/supervisor in production
-4. **Reliability**: Manual startup is more predictable and debuggable
-
----
-
-## 🚨 Common Issues Quick Reference
-
-| Issue | Quick Fix |
-|-------|-----------|
-| Tasks stuck in pending | Start workers: `poetry run python manage.py rundramatiq` |
-| Redis DB mismatch | Check `redis_db=2` in config, verify Redis URL |
-| Worker subprocess fails | Use manual startup, not auto-start |
-| Database routing errors | Verify `app_label` matches database routing |
-| Message decoding errors | Clear DLQ: `redis-cli -n 2 DEL dramatiq:queue:knowledge.DQ` |
-
----
-
-## 🎯 Documentation Philosophy
-
-This documentation follows these principles:
-
-### LLM-Optimized %%AI_HINT%%
-- **Token-efficient**: Concise but comprehensive
-- **Structured**: Clear headings and sections for easy parsing
-- **Searchable**: Tagged with relevant keywords
-- **Contextual**: Includes AI hints and priority markers
-
-### Problem-Focused
-- **Real Issues**: Documents actual problems encountered
-- **Tested Solutions**: All solutions have been verified
-- **Prevention**: Includes anti-patterns and best practices
-- **Recovery**: Emergency procedures for critical issues
-
-### Production-Ready
-- **Deployment**: Covers systemd, supervisor, Docker
-- **Monitoring**: Health checks, logging, metrics
-- **Security**: Redis security, environment variables
-- **Scaling**: Resource planning and performance tuning
-
----
-
-## 🔍 Finding Information
-
-### By Use Case
-- **Setting up tasks**: Start with [TASKS_QUEUES.md](./TASKS_QUEUES.md) → Architecture section
-- **Deployment**: Go to [CONFIGURATION.md](./CONFIGURATION.md) → Process Management
-- **Debugging**: Check [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) → Diagnostic Tools
-- **Performance**: See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) → Performance Issues
-
-### By Component
-- **Redis**: All files cover Redis, see Configuration for security
-- **Workers**: TASKS_QUEUES.md for management, TROUBLESHOOTING.md for issues
-- **Queues**: TASKS_QUEUES.md for configuration, TROUBLESHOOTING.md for monitoring
-- **Tasks**: TASKS_QUEUES.md for flows, TROUBLESHOOTING.md for debugging
-
-### By Environment
-- **Development**: TASKS_QUEUES.md → Development Workflow
-- **Production**: CONFIGURATION.md → Production Deployment
-- **Testing**: CONFIGURATION.md → Testing Configuration
-- **Docker**: CONFIGURATION.md → Docker Configuration
-
----
-
-## 📊 Documentation Metrics
-
-- **Total Lines**: ~2,400 lines across 4 files
-- **Max File Size**: <1,000 lines per file (DOCS_MODULE.md compliant)
-- **Coverage**: 100% of task system functionality
-- **Examples**: 50+ code examples and commands
-- **Issues Covered**: 15+ common problems with solutions
-
----
-
-## 🧠 Contributing
-
-When updating this documentation:
-
-1. **Follow DOCS_MODULE.md format**: Use proper headings, tags, and markers
-2. **Keep files under 1,000 lines**: Split if necessary
-3. **Test all examples**: Ensure code examples work
-4. **Update version history**: Mark changes with version numbers
-5. **Add AI hints**: Use `%%AI_HINT%%` for important context
-
-### Documentation Standards
-- **Concise**: Every line adds value
-- **Accurate**: All information verified
-- **Current**: Regular updates with system changes
-- **Searchable**: Proper tagging and keywords
-
-**TAGS**: `documentation, tasks, queues, dramatiq, django-cfg`
-**DEPENDS_ON**: Django-CFG task system, Dramatiq, Redis
-**USED_BY**: Developers, DevOps, System administrators, AI assistants