wappa 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

wappa/cli/examples/wappa_full_example/README.md

@@ -0,0 +1,322 @@
+# Wappa Full Example
+
+A comprehensive demonstration of the **Wappa Framework** showcasing all WhatsApp Business API features including message handling, interactive commands, state management, and media processing.
+
+## 🌟 Overview
+
+This example demonstrates a production-ready WhatsApp Business application that showcases:
+
+- ✅ **Complete message type handling** with metadata extraction
+- 🔘 **Interactive commands** with button and list demonstrations
+- 🗃️ **State management** with TTL and Redis caching
+- 📎 **Media relay functionality** using media_id
+- 👥 **User tracking and analytics** with comprehensive profiles
+- 🎉 **Welcome messages** for first-time users
+- 🏗️ **Professional architecture** with clean code patterns
+- 📊 **Performance monitoring** and statistics tracking
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- Redis server running locally or remotely
+- WhatsApp Business API access token and phone number ID
+
+### Installation
+
+1. **Clone or navigate to the project:**
+   ```bash
+   cd wappa_examples/wappa_full_example
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   uv sync
+   ```
+
+3. **Create environment file:**
+   ```bash
+   cp .env.example .env
+   ```
+
+4. **Configure your WhatsApp Business API credentials in `.env`:**
+   ```env
+   WP_ACCESS_TOKEN=your_access_token_here
+   WP_PHONE_ID=your_phone_number_id_here
+   WP_BID=your_business_id_here
+   REDIS_URL=redis://localhost:6379
+   ```
+
+5. **Add media files (optional):**
+   - Add `kitty.png` and `puppy.png` to `app/media/buttons/`
+   - Add sample files to `app/media/list/` (image.png, video.mp4, audio.mp3, document.pdf)
+
+6. **Run the application:**
+   ```bash
+   uv run python -m app.main
+   ```
+
+## 🎮 Interactive Features
+
+### Special Commands
+
+Send these commands to your WhatsApp number to try the interactive features:
+
+#### `/button` - Interactive Button Demo
+- Creates buttons for "🐱 Kitty" and "🐶 Puppy"
+- 10-minute TTL with state management
+- Sends corresponding animal image on selection
+- Demonstrates comprehensive metadata extraction
+
+#### `/list` - Interactive List Demo
+- List with Image, Video, Audio, Document options
+- Sends actual media files based on selection
+- Demonstrates list interaction patterns
+
+#### `/cta` - Call-to-Action Button
+- External link to Wappa documentation
+- Shows CTA button implementation
+
+#### `/location` - Location Sharing Demo
+- Shares predefined location (Bogotá, Colombia)
+- Demonstrates location message handling
+
+### Message Type Handling
+
+The application automatically handles and echoes all WhatsApp message types:
+
+| Message Type | Response | Features |
+|--------------|----------|----------|
+| **Text** | Echo with "Echo - {content}" + metadata | URL detection, mention parsing |
+| **Images/Videos/Audio/Documents** | Relay same media using media_id + metadata | File size, dimensions, duration |
+| **Location** | Echo same coordinates + metadata | Name, address, coordinates |
+| **Contacts** | Echo contact information + metadata | Names, phones, emails |
+| **Interactive** | Process button/list selections + metadata | Selection IDs, titles |
+
+## 🏗️ Architecture
+
+### Project Structure
+
+```
+wappa_full_example/
+├── app/
+│   ├── handlers/           # Message, command, and state handlers
+│   │   ├── message_handlers.py    # Handle different message types
+│   │   ├── command_handlers.py    # Handle special commands
+│   │   └── state_handlers.py      # Handle interactive states
+│   ├── models/             # Pydantic data models
+│   │   ├── webhook_metadata.py    # Metadata models per message type
+│   │   ├── user_models.py         # User profile and session models
+│   │   └── state_models.py        # Interactive state models
+│   ├── utils/              # Utility modules
+│   │   ├── metadata_extractor.py  # Extract webhook metadata
+│   │   ├── media_handler.py       # Media download/upload
+│   │   └── cache_utils.py         # Redis cache operations
+│   ├── media/              # Media files for demos
+│   │   ├── buttons/        # Button response images
+│   │   └── list/          # List response media files
+│   ├── master_event.py     # Main WappaEventHandler
+│   └── main.py            # FastAPI application
+├── logs/                  # Application logs
+├── pyproject.toml        # Project configuration
+└── README.md            # This file
+```
+
+### Key Components
+
+#### 1. **Master Event Handler** (`master_event.py`)
+- Main `WappaEventHandler` implementation
+- Orchestrates all message processing
+- Handles user profiles and welcome messages
+- Manages statistics and logging
+
+#### 2. **Message Handlers** (`handlers/message_handlers.py`)
+- Type-specific message processing
+- Metadata extraction and formatting
+- Media relay functionality
+- User activity tracking
+
+#### 3. **Command Handlers** (`handlers/command_handlers.py`)
+- Special command processing (`/button`, `/list`, `/cta`, `/location`)
+- Interactive message creation
+- State initialization with TTL
+
+#### 4. **State Handlers** (`handlers/state_handlers.py`)
+- Interactive state management
+- Button and list response processing
+- State validation and cleanup
+- Media file serving
+
+#### 5. **Utilities**
+- **Metadata Extractor**: Comprehensive webhook metadata extraction
+- **Media Handler**: Media download/upload and relay functionality
+- **Cache Utils**: Redis operations and user management
+
+## 📊 Features Demonstrated
+
+### User Management
+- **First-time user detection** with welcome messages
+- **User profile caching** with activity tracking  
+- **Message count statistics** and interaction analytics
+- **Command usage tracking** and behavioral insights
+
+### State Management
+- **TTL-based states** (10-minute expiration for interactive commands)
+- **State validation** and error handling
+- **Automatic cleanup** of expired states
+- **Multi-state support** (buttons, lists, custom states)
+
+### Message Processing
+- **Comprehensive metadata extraction** for all message types
+- **Media relay using media_id** for efficient bandwidth usage
+- **Professional error handling** with user-friendly messages
+- **Performance monitoring** with processing time tracking
+
+### Interactive Features
+- **Button workflows** with media responses
+- **List interactions** with file serving
+- **CTA buttons** linking to external resources
+- **Location sharing** with predefined coordinates
+
+## 🛠️ Development
+
+### Running in Development
+
+```bash
+# Start with auto-reload
+uvicorn app.main:app --reload
+
+# Or use uv run
+uv run python -m app.main
+
+# With specific host/port
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### Code Quality
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint code
+uv run ruff check .
+
+# Type checking
+uv run mypy app/
+```
+
+### Testing
+
+```bash
+# Run tests (when test suite is added)
+uv run pytest
+
+# With coverage
+uv run pytest --cov=app tests/
+```
+
+## 📈 Monitoring and Analytics
+
+The application provides comprehensive statistics:
+
+### Handler Statistics
+- Total messages processed
+- Success/failure rates
+- Processing time metrics
+- Feature usage analytics
+
+### User Analytics
+- New user registrations
+- Message type distribution
+- Command usage patterns
+- Interactive feature engagement
+
+### Cache Statistics
+- Redis operation metrics
+- User profile hit rates
+- State management efficiency
+- Memory usage patterns
+
+## 🔧 Configuration
+
+### Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `WP_ACCESS_TOKEN` | WhatsApp Business API access token | Yes | - |
+| `WP_PHONE_ID` | WhatsApp phone number ID | Yes | - |
+| `WP_BID` | WhatsApp Business ID | Yes | - |
+| `REDIS_URL` | Redis connection URL | Yes | `redis://localhost:6379` |
+| `LOG_LEVEL` | Application log level | No | `INFO` |
+| `ENVIRONMENT` | Environment (dev/prod) | No | `development` |
+
+### Redis Configuration
+
+The application uses Redis for:
+- **User profiles** (24-hour TTL)
+- **Interactive states** (10-minute TTL)
+- **Message history** (7-day TTL)
+- **Application statistics** (persistent)
+
+## 🎯 Use Cases
+
+This example demonstrates patterns useful for:
+
+### Business Applications
+- **Customer support** with interactive menus
+- **Order management** with button workflows
+- **Appointment booking** with list selections
+- **Product catalogs** with media sharing
+
+### Educational Applications
+- **Interactive tutorials** with step-by-step guidance
+- **Quiz systems** with button-based answers
+- **File sharing** for educational resources
+- **Location sharing** for campus navigation
+
+### E-commerce Applications
+- **Product browsing** with media catalogs
+- **Order confirmation** with interactive buttons
+- **Payment flows** with CTA buttons
+- **Delivery tracking** with location updates
+
+## 📚 Learning Resources
+
+### Wappa Framework
+- [Documentation](https://wappa.mimeia.com/docs)
+- [GitHub Repository](https://github.com/mimeia/wappa)
+- [API Reference](https://wappa.mimeia.com/docs/api)
+
+### WhatsApp Business API
+- [Official Documentation](https://developers.facebook.com/docs/whatsapp)
+- [Message Types](https://developers.facebook.com/docs/whatsapp/cloud-api/messages)
+- [Interactive Messages](https://developers.facebook.com/docs/whatsapp/cloud-api/messages/interactive-messages)
+
+## 🤝 Contributing
+
+This example is part of the Wappa framework project. To contribute:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙋‍♀️ Support
+
+- **Documentation**: [wappa.mimeia.com](https://wappa.mimeia.com)
+- **Issues**: [GitHub Issues](https://github.com/mimeia/wappa/issues)
+- **Community**: [Discord](https://discord.gg/wappa)
+- **Email**: support@mimeia.com
+
+---
+
+**Built with ❤️ using the Wappa Framework**
+
+**This comprehensive example showcases production-ready patterns for building sophisticated WhatsApp Business applications. Use it as a foundation for your own projects and explore the full potential of conversational interfaces.**

wappa/cli/examples/wappa_full_example/docker-compose.yml

@@ -0,0 +1,170 @@
+# ================================================================
+# WAPPA FULL EXAMPLE - DOCKER COMPOSE CONFIGURATION
+# ================================================================
+# Production-ready deployment with Redis, health checks, and scaling
+# ================================================================
+
+version: '3.8'
+
+services:
+  # ================================================================
+  # Redis Cache Service
+  # ================================================================
+  redis:
+    image: redis:7.2-alpine
+    container_name: wappa-redis
+    restart: unless-stopped
+    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru
+    ports:
+      - "6379:6379"
+    volumes:
+      - redis_data:/data
+      - ./redis.conf:/etc/redis/redis.conf:ro
+    networks:
+      - wappa-network
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+      start_period: 10s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+  # ================================================================
+  # Wappa Application Service
+  # ================================================================
+  wappa-app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        BUILD_DATE: ${BUILD_DATE:-2024-01-01}
+        VCS_REF: ${VCS_REF:-dev}
+    image: wappa-full-example:latest
+    container_name: wappa-app
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      # Production environment variables
+      ENVIRONMENT: PROD
+      LOG_LEVEL: INFO
+      PORT: 8000
+      
+      # Redis configuration
+      REDIS_URL: redis://redis:6379/
+      REDIS_MAX_CONNECTIONS: 64
+      
+      # WhatsApp API credentials (from .env file)
+      WP_ACCESS_TOKEN: ${WP_ACCESS_TOKEN}
+      WP_PHONE_ID: ${WP_PHONE_ID}
+      WP_BID: ${WP_BID}
+      WHATSAPP_WEBHOOK_VERIFY_TOKEN: ${WHATSAPP_WEBHOOK_VERIFY_TOKEN}
+      
+      # Optional AI tools
+      OPENAI_API_KEY: ${OPENAI_API_KEY:-}
+      
+      # Framework configuration
+      BASE_URL: https://graph.facebook.com/
+      API_VERSION: v23.0
+      TIME_ZONE: America/Bogota
+    volumes:
+      # Persistent logs
+      - app_logs:/app/logs
+      # Media files (if you want to persist them)
+      - app_media:/app/media
+    networks:
+      - wappa-network
+    depends_on:
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "50m"
+        max-file: "5"
+
+  # ================================================================
+  # Nginx Reverse Proxy (Optional - for SSL termination)
+  # ================================================================
+  nginx:
+    image: nginx:alpine
+    container_name: wappa-nginx
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./ssl:/etc/ssl/certs:ro
+      - nginx_logs:/var/log/nginx
+    networks:
+      - wappa-network
+    depends_on:
+      - wappa-app
+    profiles:
+      - nginx
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
+
+# ================================================================
+# Networks
+# ================================================================
+networks:
+  wappa-network:
+    driver: bridge
+    name: wappa-network
+
+# ================================================================
+# Persistent Volumes
+# ================================================================
+volumes:
+  redis_data:
+    driver: local
+    name: wappa-redis-data
+  app_logs:
+    driver: local
+    name: wappa-app-logs
+  app_media:
+    driver: local
+    name: wappa-app-media
+  nginx_logs:
+    driver: local
+    name: wappa-nginx-logs
+
+# ================================================================
+# DEPLOYMENT COMMANDS:
+# ================================================================
+# Development:
+#   docker-compose up -d
+#
+# Production:
+#   docker-compose --profile nginx up -d
+#
+# Scaling:
+#   docker-compose up --scale wappa-app=3 -d
+#
+# Monitoring:
+#   docker-compose logs -f wappa-app
+#   docker-compose ps
+#
+# Health Checks:
+#   curl http://localhost:8000/health
+#   docker-compose exec wappa-app curl http://localhost:8000/health/detailed
+#
+# Cleanup:
+#   docker-compose down -v
+# ================================================================

wappa/cli/examples/wappa_full_example/nginx.conf

@@ -0,0 +1,177 @@
+# ================================================================
+# NGINX REVERSE PROXY CONFIGURATION FOR WAPPA FULL EXAMPLE
+# ================================================================
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+    
+    # Logging
+    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
+                    '$status $body_bytes_sent "$http_referer" '
+                    '"$http_user_agent" "$http_x_forwarded_for"';
+    
+    access_log /var/log/nginx/access.log main;
+    error_log /var/log/nginx/error.log warn;
+    
+    # Basic settings
+    sendfile on;
+    tcp_nopush on;
+    tcp_nodelay on;
+    keepalive_timeout 65;
+    types_hash_max_size 2048;
+    client_max_body_size 10M;
+    
+    # Gzip compression
+    gzip on;
+    gzip_vary on;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
+    
+    # Rate limiting
+    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+    limit_req_zone $binary_remote_addr zone=webhook:10m rate=50r/s;
+    
+    # Upstream backend
+    upstream wappa_backend {
+        server wappa-app:8000 max_fails=3 fail_timeout=30s;
+        # Add more servers for load balancing:
+        # server wappa-app-2:8000 max_fails=3 fail_timeout=30s;
+        # server wappa-app-3:8000 max_fails=3 fail_timeout=30s;
+    }
+    
+    # HTTP server (redirect to HTTPS)
+    server {
+        listen 80;
+        server_name _;
+        
+        # Health check endpoint
+        location /nginx-health {
+            access_log off;
+            return 200 "healthy\n";
+            add_header Content-Type text/plain;
+        }
+        
+        # Redirect all HTTP traffic to HTTPS
+        location / {
+            return 301 https://$host$request_uri;
+        }
+    }
+    
+    # HTTPS server
+    server {
+        listen 443 ssl http2;
+        server_name your-domain.com;  # Replace with your domain
+        
+        # SSL configuration
+        ssl_certificate /etc/ssl/certs/cert.pem;
+        ssl_certificate_key /etc/ssl/certs/key.pem;
+        ssl_session_timeout 1d;
+        ssl_session_cache shared:MozTLS:10m;
+        ssl_session_tickets off;
+        
+        # Modern SSL configuration
+        ssl_protocols TLSv1.2 TLSv1.3;
+        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+        ssl_prefer_server_ciphers off;
+        
+        # Security headers
+        add_header Strict-Transport-Security "max-age=63072000" always;
+        add_header X-Frame-Options DENY;
+        add_header X-Content-Type-Options nosniff;
+        add_header X-XSS-Protection "1; mode=block";
+        add_header Referrer-Policy "no-referrer-when-downgrade";
+        
+        # WhatsApp webhook endpoint (high rate limit)
+        location /webhook {
+            limit_req zone=webhook burst=100 nodelay;
+            
+            proxy_pass http://wappa_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection 'upgrade';
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_cache_bypass $http_upgrade;
+            proxy_read_timeout 90;
+            proxy_send_timeout 90;
+            proxy_connect_timeout 30;
+        }
+        
+        # API endpoints (standard rate limit)
+        location /api {
+            limit_req zone=api burst=20 nodelay;
+            
+            proxy_pass http://wappa_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_read_timeout 90;
+            proxy_send_timeout 90;
+            proxy_connect_timeout 30;
+        }
+        
+        # Health check endpoint
+        location /health {
+            proxy_pass http://wappa_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            access_log off;
+        }
+        
+        # Documentation and static files
+        location /docs {
+            proxy_pass http://wappa_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+        
+        # Default location
+        location / {
+            limit_req zone=api burst=10 nodelay;
+            
+            proxy_pass http://wappa_backend;
+            proxy_http_version 1.1;
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_read_timeout 90;
+            proxy_send_timeout 90;
+            proxy_connect_timeout 30;
+        }
+        
+        # Block common bot requests
+        location ~ /\.(git|svn|hg) {
+            deny all;
+            return 404;
+        }
+        
+        location ~ /\.(env|log)$ {
+            deny all;
+            return 404;
+        }
+    }
+}
+
+# ================================================================
+# CONFIGURATION NOTES:
+# ================================================================
+# 1. Replace 'your-domain.com' with your actual domain
+# 2. Add SSL certificates to ./ssl/cert.pem and ./ssl/key.pem
+# 3. For Let's Encrypt: use certbot with nginx plugin
+# 4. Scale backend servers by adding more upstream entries
+# 5. Adjust rate limits based on your WhatsApp API quotas
+# 6. Monitor nginx logs for performance tuning
+# ================================================================

wappa/cli/examples/wappa_full_example/railway.toml

@@ -0,0 +1,30 @@
+# ================================================================
+# RAILWAY CONFIGURATION FOR WAPPA FULL EXAMPLE
+# ================================================================
+
+[build]
+builder = "dockerfile"
+dockerfilePath = "Dockerfile"
+
+[deploy]
+healthcheckPath = "/health"
+healthcheckTimeout = 300
+restartPolicyType = "on_failure"
+restartPolicyMaxRetries = 10
+
+# ================================================================
+# RAILWAY ENVIRONMENT VARIABLES (Set via Railway Dashboard)
+# ================================================================
+# Required variables to set in Railway:
+#
+# WP_ACCESS_TOKEN=your_whatsapp_access_token
+# WP_PHONE_ID=your_phone_number_id  
+# WP_BID=your_business_id
+# WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_webhook_token
+# REDIS_URL=redis://redis.railway.internal:6379
+# OPENAI_API_KEY=your_openai_key (optional)
+#
+# Railway automatically sets:
+# PORT (dynamic port assignment)
+# RAILWAY_ENVIRONMENT (production/staging)
+# ================================================================