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

wappa/cli/examples/simple_echo_example/app/__init__.py

@@ -0,0 +1,7 @@
+"""
+Simple Echo Example - Clean Application Structure
+
+This package follows the successful pattern from redis_cache_example
+with a clean separation between infrastructure (project root) and
+application code (/app).
+"""

wappa/cli/examples/simple_echo_example/app/main.py

@@ -0,0 +1,183 @@
+"""
+Simple Echo Example - Clean Architecture Implementation
+
+This is a simplified version of the Redis cache example that demonstrates
+basic Wappa functionality without complex dependencies.
+
+Features:
+- Clean WappaEventHandler implementation
+- Simple message echoing for all message types
+- Proper dependency injection
+- Professional logging and error handling
+
+SETUP REQUIRED:
+1. Create a .env file with your WhatsApp Business API credentials:
+    WP_ACCESS_TOKEN=your_access_token_here
+    WP_PHONE_ID=your_phone_number_id_here
+    WP_BID=your_business_id_here
+
+USAGE:
+- Direct Python: python -m app.main (from project root)
+- FastAPI-style: uvicorn app.main:app --reload (from project root)
+- Wappa CLI: wappa run app/main.py (from project root)
+"""
+
+# Import core Wappa components
+from wappa import Wappa, __version__
+from wappa.core.config.settings import settings
+from wappa.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Import our simple echo handler
+from .master_event import SimpleEchoHandler
+
+
+def validate_configuration() -> bool:
+    """
+    Validate required configuration settings.
+    
+    Returns:
+        True if configuration is valid, False otherwise
+    """
+    
+    # Check required WhatsApp credentials
+    missing_configs = []
+    
+    if not settings.wp_access_token:
+        missing_configs.append("WP_ACCESS_TOKEN")
+    
+    if not settings.wp_phone_id:
+        missing_configs.append("WP_PHONE_ID")
+        
+    if not settings.wp_bid:
+        missing_configs.append("WP_BID")
+    
+    if missing_configs:
+        logger.error(f"❌ Missing required configuration: {', '.join(missing_configs)}")
+        logger.error("💡 Create a .env file with the required credentials")
+        return False
+    
+    logger.info("✅ Configuration validation passed")
+    return True
+
+
+def display_startup_information() -> None:
+    """
+    Display startup information and demo features.
+    """
+    print(f"🚀 Wappa v{__version__} - Simple Echo Example")
+    print("=" * 70)
+    print()
+    
+    print("📋 *CONFIGURATION STATUS:*")
+    print(f"  • Access Token: {'✅ Configured' if settings.wp_access_token else '❌ Missing'}")
+    print(f"  • Phone ID: {settings.wp_phone_id if settings.wp_phone_id else '❌ Missing'}")
+    print(f"  • Business ID: {'✅ Configured' if settings.wp_bid else '❌ Missing'}")
+    print(f"  • Environment: {'🛠️ Development' if settings.is_development else '🚀 Production'}")
+    print()
+    
+    print("🎯 *DEMO FEATURES:*")
+    print("  • Send any text message → Get echo response")
+    print("  • Send media files → Get acknowledgment")
+    print("  • Send location → Get location confirmation")
+    print("  • Send contacts → Get contact confirmation")
+    print("  • All messages are counted and logged")
+    print()
+    
+    print("🔧 *TECHNICAL FEATURES:*")
+    print("  • Clean WappaEventHandler implementation")
+    print("  • Proper dependency injection")
+    print("  • Multi-message-type support")
+    print("  • Professional error handling")
+    print("  • Structured logging")
+    print()
+
+
+def create_wappa_application() -> Wappa:
+    """
+    Create and configure the Wappa application.
+    
+    Returns:
+        Configured Wappa application instance
+    """
+    
+    try:
+        # Create Wappa instance with JSON cache (simple file-based cache for echo example)
+        logger.info("🏗️ Creating Wappa application with JSON cache...")
+        app = Wappa(cache="json")
+        
+        logger.info("✅ Wappa application created successfully")
+        return app
+        
+    except Exception as e:
+        logger.error(f"❌ Failed to create Wappa application: {e}")
+        raise
+
+
+def main() -> None:
+    """
+    Main application entry point.
+    """
+    
+    logger.info("🚀 Starting Simple Echo Example")
+    
+    try:
+        # Display startup information
+        display_startup_information()
+        
+        # Validate configuration before proceeding
+        if not validate_configuration():
+            logger.error("❌ Configuration validation failed - cannot start application")
+            return
+        
+        # Create Wappa application
+        app = create_wappa_application()
+        
+        # Create and set the simple echo handler
+        handler = SimpleEchoHandler()
+        app.set_event_handler(handler)
+        
+        logger.info("✅ Application initialization completed with SimpleEchoHandler")
+        
+        print("🌐 Starting simple echo server...")
+        print("💡 Press CTRL+C to stop the server")
+        print("=" * 70)
+        print()
+        
+        # Start the application
+        app.run()
+        
+    except KeyboardInterrupt:
+        logger.info("👋 Application stopped by user")
+        print("\\n👋 Simple echo server stopped by user")
+        
+    except Exception as e:
+        logger.error(f"❌ Application startup error: {e}", exc_info=True)
+        print(f"\\n❌ Server error: {e}")
+        
+    finally:
+        logger.info("🏁 Simple echo example completed")
+        print("🏁 Simple echo example completed")
+
+
+# Module-level app instance for uvicorn compatibility
+# This enables: uvicorn app.main:app --reload
+
+try:
+    logger.info("📦 Creating module-level Wappa application instance")
+    app = Wappa()
+    
+    # Create and set the simple echo handler
+    handler = SimpleEchoHandler()
+    app.set_event_handler(handler)
+    
+    logger.info("✅ Module-level application instance ready with SimpleEchoHandler")
+    
+except Exception as e:
+    logger.error(f"❌ Failed to create module-level app instance: {e}")
+    raise
+
+
+if __name__ == "__main__":
+    main()

wappa/cli/examples/simple_echo_example/app/master_event.py

@@ -0,0 +1,209 @@
+"""
+Simple Echo Master Event Handler
+
+A simplified, clean event handler that demonstrates basic echo functionality
+following the same patterns as the redis_cache_example but without the complexity.
+
+This handler shows:
+- Clean WappaEventHandler implementation
+- Simple message echoing
+- Multi-message-type support
+- Proper logging and error handling
+"""
+
+import asyncio
+from datetime import datetime
+
+from wappa import WappaEventHandler
+from wappa.core.logging import get_logger
+from wappa.webhooks import ErrorWebhook, IncomingMessageWebhook, StatusWebhook
+
+logger = get_logger(__name__)
+
+
+class SimpleEchoHandler(WappaEventHandler):
+    """
+    Simple echo handler that replies to all messages.
+    
+    This demonstrates the basic WappaEventHandler pattern without
+    the complexity of score modules or caching systems.
+    """
+
+    def __init__(self):
+        """Initialize the simple echo handler."""
+        super().__init__()
+        self._message_count = 0
+        logger.info("🔄 SimpleEchoHandler initialized - ready to echo messages")
+
+    async def process_message(self, webhook: IncomingMessageWebhook) -> None:
+        """
+        Process incoming messages with simple echo functionality.
+        
+        Args:
+            webhook: Incoming message webhook to process
+        """
+        
+        # Validate dependencies are properly injected
+        if not self.validate_dependencies():
+            logger.error("❌ Dependencies not properly injected - cannot process message")
+            return
+
+        self._message_count += 1
+        
+        user_id = webhook.user.user_id
+        message_text = webhook.get_message_text()
+        message_type = webhook.get_message_type_name()
+        message_id = webhook.message.message_id
+
+        logger.info(f"📝 Message #{self._message_count}: {message_type} from {user_id}")
+
+        try:
+            # Mark message as read with typing indicator
+            await self.messenger.mark_as_read(message_id=message_id, typing=True)
+            
+            # Handle different message types
+            await self._handle_message_by_type(webhook, user_id, message_text, message_type)
+            
+        except Exception as e:
+            logger.error(f"❌ Error processing message: {e}", exc_info=True)
+
+    async def _handle_message_by_type(
+        self, 
+        webhook: IncomingMessageWebhook, 
+        user_id: str, 
+        message_text: str, 
+        message_type: str
+    ) -> None:
+        """Handle message based on its type."""
+        
+        try:
+            if message_type.lower() == "text":
+                await self._handle_text_message(webhook, user_id, message_text)
+            elif message_type.lower() in ["image", "video", "audio", "document", "sticker"]:
+                await self._handle_media_message(webhook, user_id, message_type)
+            elif message_type.lower() == "location":
+                await self._handle_location_message(webhook, user_id)
+            elif message_type.lower() == "contacts":
+                await self._handle_contact_message(webhook, user_id)
+            else:
+                await self._handle_other_message(webhook, user_id, message_type)
+                
+        except Exception as e:
+            logger.error(f"❌ Error handling {message_type} message: {e}")
+
+    async def _handle_text_message(self, webhook: IncomingMessageWebhook, user_id: str, message_text: str) -> None:
+        """Handle text messages with simple echo."""
+        
+        logger.info(f"💬 Echoing text: '{message_text}'")
+        
+        # Create echo response
+        echo_response = f"🔄 Echo: {message_text}"
+        
+        # Add some metadata for the first few messages
+        if self._message_count <= 3:
+            echo_response += f"\n\n📊 Message #{self._message_count} processed successfully!"
+            if self._message_count == 1:
+                echo_response += "\n👋 Welcome to the Simple Echo Example!"
+        
+        # Send echo response
+        result = await self.messenger.send_text(
+            recipient=user_id,
+            text=echo_response,
+            reply_to_message_id=webhook.message.message_id
+        )
+        
+        if result.success:
+            logger.info(f"✅ Text echo sent successfully: {result.message_id}")
+        else:
+            logger.error(f"❌ Text echo failed: {result.error}")
+
+    async def _handle_media_message(self, webhook: IncomingMessageWebhook, user_id: str, message_type: str) -> None:
+        """Handle media messages."""
+        
+        logger.info(f"🎬 Processing {message_type} message")
+        
+        response = f"📁 {message_type.title()} received! Simple echo doesn't download media, but message was processed successfully.\n\n📊 Total messages: {self._message_count}"
+        
+        result = await self.messenger.send_text(
+            recipient=user_id,
+            text=response,
+            reply_to_message_id=webhook.message.message_id
+        )
+        
+        if result.success:
+            logger.info(f"✅ {message_type} response sent: {result.message_id}")
+        else:
+            logger.error(f"❌ {message_type} response failed: {result.error}")
+
+    async def _handle_location_message(self, webhook: IncomingMessageWebhook, user_id: str) -> None:
+        """Handle location messages."""
+        
+        logger.info("📍 Processing location message")
+        
+        response = f"📍 Location received! Thanks for sharing your location.\n\n📊 Total messages: {self._message_count}"
+        
+        result = await self.messenger.send_text(
+            recipient=user_id,
+            text=response,
+            reply_to_message_id=webhook.message.message_id
+        )
+        
+        if result.success:
+            logger.info(f"✅ Location response sent: {result.message_id}")
+        else:
+            logger.error(f"❌ Location response failed: {result.error}")
+
+    async def _handle_contact_message(self, webhook: IncomingMessageWebhook, user_id: str) -> None:
+        """Handle contact messages."""
+        
+        logger.info("👥 Processing contact message")
+        
+        response = f"👥 Contact shared! Thanks for the contact information.\n\n📊 Total messages: {self._message_count}"
+        
+        result = await self.messenger.send_text(
+            recipient=user_id,
+            text=response,
+            reply_to_message_id=webhook.message.message_id
+        )
+        
+        if result.success:
+            logger.info(f"✅ Contact response sent: {result.message_id}")
+        else:
+            logger.error(f"❌ Contact response failed: {result.error}")
+
+    async def _handle_other_message(self, webhook: IncomingMessageWebhook, user_id: str, message_type: str) -> None:
+        """Handle other message types."""
+        
+        logger.info(f"❓ Processing unsupported message type: {message_type}")
+        
+        response = f"📨 {message_type.title()} message received! This message type is not fully supported yet, but was processed successfully.\n\n📊 Total messages: {self._message_count}"
+        
+        result = await self.messenger.send_text(
+            recipient=user_id,
+            text=response,
+            reply_to_message_id=webhook.message.message_id
+        )
+        
+        if result.success:
+            logger.info(f"✅ {message_type} response sent: {result.message_id}")
+        else:
+            logger.error(f"❌ {message_type} response failed: {result.error}")
+
+    async def process_status(self, webhook: StatusWebhook) -> None:
+        """Process status webhooks with simple logging."""
+        
+        status_value = webhook.status.value
+        recipient = webhook.recipient_id
+        
+        logger.info(f"📊 Status update: {status_value.upper()} for recipient {recipient}")
+
+    async def process_error(self, webhook: ErrorWebhook) -> None:
+        """Process error webhooks with simple logging."""
+        
+        error_count = webhook.get_error_count()
+        primary_error = webhook.get_primary_error()
+        
+        logger.error(
+            f"🚨 Platform error: {error_count} errors, "
+            f"primary: {primary_error.error_code} - {primary_error.error_title}"
+        )

wappa/cli/examples/wappa_full_example/.env.example

@@ -0,0 +1,33 @@
+# ================================================================
+# WAPPA WHATSAPP FRAMEWORK CONFIGURATION
+# ================================================================
+
+# General Configuration
+PORT=8000
+TIME_ZONE=America/Bogota
+
+# DEBUG or INFO or WARNING or ERROR or CRITICAL
+LOG_LEVEL=DEBUG
+LOG_DIR=./logs
+## Environment DEV or PROD
+ENVIRONMENT=DEV  
+
+# WhatsApp Graph API
+BASE_URL=https://graph.facebook.com/
+API_VERSION=v23.0
+
+# WhatsApp Business API Credentials
+WP_ACCESS_TOKEN=
+WP_PHONE_ID=
+WP_BID=
+
+# Webhook Configuration
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=
+
+# Redis Configuration (Optional - uncomment to enable Redis persistence)
+REDIS_URL=redis://localhost:6379/
+REDIS_MAX_CONNECTIONS=64
+
+# Optional: AI Tools
+# OPENAI_API_KEY=
+

wappa/cli/examples/wappa_full_example/.gitignore

@@ -1,10 +1,69 @@
-# Python-generated files
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
 __pycache__/
-*.py[oc]
+*.py[cod]
+*$py.class
+*.so
+.Python
 build/
+develop-eggs/
 dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
 wheels/
-*.egg-info
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
 
 # Virtual environments
-.venv
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/wappa_full_example/app/__init__.py

@@ -0,0 +1,6 @@
+"""
+Wappa Full Example Application Package
+
+A comprehensive wappa framework example demonstrating all messaging features
+with proper metadata extraction, interactive commands, and state management.
+"""

wappa/cli/examples/wappa_full_example/app/handlers/__init__.py

@@ -0,0 +1,5 @@
+"""
+Message and command handlers for the Wappa Full Example application.
+
+Contains handlers for different message types, special commands, and interactive states.
+"""