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

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

@@ -0,0 +1,445 @@
+"""
+Master Event Handler for Wappa Full Example Application
+
+This is the main WappaEventHandler implementation that demonstrates comprehensive
+WhatsApp Business API functionality including metadata extraction, interactive
+commands, state management, and all message type handling.
+"""
+
+import time
+from typing import Dict, Optional
+
+from wappa import WappaEventHandler
+from wappa.webhooks import ErrorWebhook, IncomingMessageWebhook, StatusWebhook
+
+from .handlers.command_handlers import (
+    CommandHandlers,
+    get_command_from_text,
+    is_special_command,
+)
+from .handlers.message_handlers import MessageHandlers, handle_message_by_type
+from .handlers.state_handlers import StateHandlers, handle_user_in_state
+from .models.state_models import StateType
+from .models.user_models import UserProfile
+from .utils.cache_utils import CacheHelper
+
+
+class WappaFullExampleHandler(WappaEventHandler):
+    """
+    Comprehensive WappaEventHandler implementation demonstrating all framework features.
+    
+    Features:
+    - Complete message type handling with metadata extraction
+    - Interactive commands (/button, /list, /cta, /location) with state management
+    - Media relay functionality using media_id
+    - User tracking and analytics with Redis cache
+    - Professional error handling and logging
+    - Welcome messages for first-time users
+    - State-based interactive workflows with TTL
+    """
+    
+    def __init__(self):
+        """Initialize the comprehensive Wappa example handler."""
+        super().__init__()
+        
+        # Handler instances (initialized per request)
+        self.cache_helper: Optional[CacheHelper] = None
+        self.message_handlers: Optional[MessageHandlers] = None
+        self.command_handlers: Optional[CommandHandlers] = None
+        self.state_handlers: Optional[StateHandlers] = None
+        
+        # Statistics
+        self._total_messages = 0
+        self._successful_processing = 0
+        self._failed_processing = 0
+        self._first_time_users = 0
+        self._commands_processed = 0
+        self._interactive_responses = 0
+        
+        self.logger.info("🚀 WappaFullExampleHandler initialized - comprehensive demo ready")
+    
+    async def process_message(self, webhook: IncomingMessageWebhook) -> None:
+        """
+        Main message processing method with comprehensive functionality.
+        
+        This method orchestrates:
+        1. Dependency validation and setup
+        2. User profile management and welcome messages
+        3. Message reading acknowledgment
+        4. Interactive state checking and processing
+        5. Special command handling
+        6. Regular message processing with metadata extraction
+        7. Statistics tracking and logging
+        
+        Args:
+            webhook: IncomingMessageWebhook containing message data
+        """
+        start_time = time.time()
+        self._total_messages += 1
+        
+        try:
+            # 1. Setup dependencies and validate
+            if not await self._setup_dependencies():
+                self._failed_processing += 1
+                return
+            
+            # 2. Handle user profile and first-time user welcome
+            user_profile = await self._handle_user_profile_and_welcome(webhook)
+            if not user_profile:
+                self.logger.warning("Failed to handle user profile, continuing without caching")
+                user_profile = UserProfile(phone_number=webhook.user.user_id)
+            
+            # 3. Mark message as read (as specified in requirements)
+            await self._mark_message_as_read(webhook)
+            
+            # Extract basic message info for routing
+            user_id = webhook.user.user_id
+            message_text = webhook.get_message_text().strip()
+            message_type = webhook.get_message_type_name()
+            
+            self.logger.info(
+                f"📨 Processing {message_type} from {user_id}: "
+                f"'{message_text[:50]}{'...' if len(message_text) > 50 else ''}'"
+            )
+            
+            # 4. Check for active interactive states first
+            state_result = await handle_user_in_state(
+                webhook, user_profile, self.messenger, self.cache_factory, self.logger
+            )
+            
+            if state_result is not None:
+                # User was in an interactive state - handle accordingly
+                if state_result["success"]:
+                    self._interactive_responses += 1
+                    self._successful_processing += 1
+                    self.logger.info(f"✅ Interactive state handled: {state_result.get('selection_type', 'unknown')}")
+                else:
+                    self.logger.info(f"🔄 Interactive state reminder sent: {state_result.get('error', 'unknown')}")
+                
+                await self._log_processing_stats(start_time)
+                return
+            
+            # 5. Check for special commands (only for text messages)
+            if message_type == "text" and is_special_command(message_text):
+                command = get_command_from_text(message_text)
+                await self._handle_special_command(webhook, user_profile, command)
+                self._commands_processed += 1
+                self._successful_processing += 1
+                await self._log_processing_stats(start_time)
+                return
+            
+            # 6. Handle regular message processing with metadata
+            result = await handle_message_by_type(
+                webhook, user_profile, self.messenger, self.cache_factory, self.logger
+            )
+            
+            if result["success"]:
+                self._successful_processing += 1
+                self.logger.info(f"✅ {message_type} message processed successfully")
+            else:
+                self._failed_processing += 1
+                self.logger.error(f"❌ {message_type} message processing failed: {result.get('error')}")
+                
+                # Send error response to user
+                await self._send_error_response(webhook, result.get('error', 'Processing failed'))
+            
+            await self._log_processing_stats(start_time)
+            
+        except Exception as e:
+            self._failed_processing += 1
+            self.logger.error(f"❌ Critical error in message processing: {e}", exc_info=True)
+            
+            # Send generic error response
+            try:
+                await self.messenger.send_text(
+                    recipient=webhook.user.user_id,
+                    text="❌ Sorry, something went wrong processing your message. Please try again.",
+                    reply_to_message_id=webhook.message.message_id
+                )
+            except Exception as send_error:
+                self.logger.error(f"❌ Failed to send error response: {send_error}")
+    
+    async def process_status(self, webhook: StatusWebhook) -> None:
+        """
+        Process status webhooks from WhatsApp Business API.
+        
+        Args:
+            webhook: StatusWebhook containing delivery status information
+        """
+        try:
+            status_value = webhook.status.value
+            recipient = webhook.recipient_id
+            message_id = webhook.message_id
+            
+            self.logger.info(f"📊 Message status: {status_value.upper()} for {recipient} (msg: {message_id[:20]}...)")
+            
+            # You can add custom status processing here
+            # For example: update delivery statistics, handle failed deliveries, etc.
+            
+        except Exception as e:
+            self.logger.error(f"❌ Error processing status webhook: {e}", exc_info=True)
+    
+    async def process_error(self, webhook: ErrorWebhook) -> None:
+        """
+        Process error webhooks from WhatsApp Business API.
+        
+        Args:
+            webhook: ErrorWebhook containing error information
+        """
+        try:
+            error_count = webhook.get_error_count()
+            primary_error = webhook.get_primary_error()
+            
+            self.logger.error(
+                f"🚨 WhatsApp API error: {error_count} errors, "
+                f"primary: {primary_error.error_code} - {primary_error.error_title}"
+            )
+            
+            # Record error in statistics
+            self._failed_processing += 1
+            
+            # You can add custom error handling logic here
+            # For example: alerting systems, retry mechanisms, etc.
+            
+        except Exception as e:
+            self.logger.error(f"❌ Error processing error webhook: {e}", exc_info=True)
+    
+    async def _setup_dependencies(self) -> bool:
+        """Setup handler dependencies and validate state."""
+        if not self.validate_dependencies():
+            self.logger.error("❌ Dependencies not properly injected")
+            return False
+        
+        if not self.cache_factory:
+            self.logger.error("❌ Cache factory not available - Redis caching unavailable")
+            return False
+        
+        try:
+            # Initialize helper instances
+            self.cache_helper = CacheHelper(self.cache_factory)
+            self.message_handlers = MessageHandlers(self.messenger, self.cache_factory, self.logger)
+            self.command_handlers = CommandHandlers(self.messenger, self.cache_factory, self.logger)
+            self.state_handlers = StateHandlers(self.messenger, self.cache_factory, self.logger)
+            
+            self.logger.debug("✅ Handler dependencies initialized successfully")
+            return True
+            
+        except Exception as e:
+            self.logger.error(f"❌ Failed to setup dependencies: {e}", exc_info=True)
+            return False
+    
+    async def _handle_user_profile_and_welcome(self, webhook: IncomingMessageWebhook) -> Optional[UserProfile]:
+        """Handle user profile caching and send welcome message to first-time users."""
+        try:
+            user_id = webhook.user.user_id
+            user_name = webhook.user.profile_name
+            
+            # Get or create user profile
+            user_profile = await self.cache_helper.get_or_create_user_profile(
+                user_id, user_name, user_name
+            )
+            
+            # Send welcome message to first-time users
+            if user_profile.is_first_time_user and not user_profile.has_received_welcome:
+                await self._send_welcome_message(webhook, user_profile)
+                user_profile.mark_welcome_sent()
+                await self.cache_helper.save_user_profile(user_profile)
+                self._first_time_users += 1
+            
+            return user_profile
+            
+        except Exception as e:
+            self.logger.error(f"❌ Error handling user profile: {e}", exc_info=True)
+            return None
+    
+    async def _send_welcome_message(self, webhook: IncomingMessageWebhook, user_profile: UserProfile) -> None:
+        """Send welcome message with instructions to first-time users."""
+        user_id = webhook.user.user_id
+        display_name = user_profile.get_display_name()
+        
+        welcome_text = (
+            f"🎉 *Welcome to Wappa Full Example, {display_name}!*\n\n"
+            f"This is a comprehensive demonstration of the Wappa framework capabilities.\n\n"
+            f"🚀 *What this example does:*\n"
+            f"• Echoes all message types with detailed metadata\n"
+            f"• Demonstrates interactive features (buttons, lists, CTA, locations)\n"
+            f"• Shows state management with TTL\n"
+            f"• Tracks user activity with Redis cache\n"
+            f"• Handles media relay using media_id\n\n"
+            f"🎯 *Try these special commands:*\n"
+            f"• `/button` - Interactive button demo with animal selection\n"
+            f"• `/list` - Interactive list demo with media files\n"
+            f"• `/cta` - Call-to-action button with external link\n"
+            f"• `/location` - Location sharing demonstration\n\n"
+            f"📨 *Send any message type to see it echoed with metadata:*\n"
+            f"• Text messages → Echo with metadata\n"
+            f"• Images/Videos/Audio/Documents → Relayed using media_id\n"
+            f"• Locations → Same location echoed back\n"
+            f"• Contacts → Contact information echoed back\n\n"
+            f"💡 *Pro tip*: This demo showcases production-ready patterns for building WhatsApp Business applications!"
+        )
+        
+        try:
+            result = await self.messenger.send_text(
+                recipient=user_id,
+                text=welcome_text,
+                reply_to_message_id=webhook.message.message_id
+            )
+            
+            if result.success:
+                self.logger.info(f"👋 Welcome message sent to {display_name} ({user_id})")
+            else:
+                self.logger.error(f"❌ Failed to send welcome message: {result.error}")
+                
+        except Exception as e:
+            self.logger.error(f"❌ Error sending welcome message: {e}")
+    
+    async def _mark_message_as_read(self, webhook: IncomingMessageWebhook) -> None:
+        """Mark incoming message as read (as specified in requirements)."""
+        try:
+            result = await self.messenger.mark_as_read(
+                message_id=webhook.message.message_id,
+                typing=False
+            )
+            
+            if result.success:
+                self.logger.debug(f"✅ Message marked as read: {webhook.message.message_id[:20]}...")
+            else:
+                self.logger.warning(f"⚠️ Failed to mark message as read: {result.error}")
+                
+        except Exception as e:
+            self.logger.warning(f"⚠️ Error marking message as read: {e}")
+    
+    async def _handle_special_command(self, webhook: IncomingMessageWebhook, 
+                                     user_profile: UserProfile, command: str) -> None:
+        """Handle special commands using command handlers."""
+        try:
+            if command == "/button":
+                result = await self.command_handlers.handle_button_command(webhook, user_profile)
+            elif command == "/list":
+                result = await self.command_handlers.handle_list_command(webhook, user_profile)
+            elif command == "/cta":
+                result = await self.command_handlers.handle_cta_command(webhook, user_profile)
+            elif command == "/location":
+                result = await self.command_handlers.handle_location_command(webhook, user_profile)
+            else:
+                self.logger.warning(f"Unsupported command: {command}")
+                return
+            
+            if result["success"]:
+                self.logger.info(f"✅ Command {command} processed successfully")
+            else:
+                self.logger.error(f"❌ Command {command} processing failed: {result.get('error')}")
+                
+        except Exception as e:
+            self.logger.error(f"❌ Error handling command {command}: {e}", exc_info=True)
+    
+    async def _send_error_response(self, webhook: IncomingMessageWebhook, error_details: str) -> None:
+        """Send user-friendly error response when processing fails."""
+        try:
+            user_id = webhook.user.user_id
+            message_id = webhook.message.message_id
+            
+            error_message = (
+                "🚨 *Wappa Full Example - Processing Error*\n\n"
+                "❌ An error occurred while processing your message.\n"
+                "Our comprehensive demo system encountered an issue.\n\n"
+                "🔄 *Please try again* or contact support if the problem persists.\n\n"
+                "💡 *Tip*: Try using one of our special commands:\n"
+                "`/button` • `/list` • `/cta` • `/location`"
+            )
+            
+            result = await self.messenger.send_text(
+                recipient=user_id,
+                text=error_message,
+                reply_to_message_id=message_id
+            )
+            
+            if result.success:
+                self.logger.info(f"🚨 Error response sent to {user_id}")
+            else:
+                self.logger.error(f"❌ Failed to send error response: {result.error}")
+                
+        except Exception as e:
+            self.logger.error(f"❌ Error sending error response: {e}")
+    
+    async def _log_processing_stats(self, start_time: float) -> None:
+        """Log processing statistics."""
+        processing_time = int((time.time() - start_time) * 1000)
+        success_rate = (self._successful_processing / max(1, self._total_messages)) * 100
+        
+        self.logger.info(
+            f"📊 Processing Stats: "
+            f"time={processing_time}ms, "
+            f"total={self._total_messages}, "
+            f"success={self._successful_processing}, "
+            f"failed={self._failed_processing}, "
+            f"rate={success_rate:.1f}%, "
+            f"new_users={self._first_time_users}, "
+            f"commands={self._commands_processed}, "
+            f"interactions={self._interactive_responses}"
+        )
+    
+    async def get_handler_statistics(self) -> Dict[str, any]:
+        """
+        Get comprehensive handler statistics.
+        
+        Returns:
+            Dictionary with processing statistics and handler metrics
+        """
+        try:
+            success_rate = (self._successful_processing / max(1, self._total_messages)) * 100
+            
+            stats = {
+                "handler_info": {
+                    "name": "WappaFullExampleHandler",
+                    "description": "Comprehensive WhatsApp Business API demo",
+                    "features": [
+                        "Complete message type handling",
+                        "Interactive commands with state management",
+                        "Media relay functionality",
+                        "User tracking and analytics",
+                        "Welcome messages for first-time users"
+                    ]
+                },
+                "processing_stats": {
+                    "total_messages": self._total_messages,
+                    "successful_processing": self._successful_processing,
+                    "failed_processing": self._failed_processing,
+                    "success_rate_percent": round(success_rate, 2)
+                },
+                "feature_usage": {
+                    "first_time_users": self._first_time_users,
+                    "commands_processed": self._commands_processed,
+                    "interactive_responses": self._interactive_responses
+                },
+                "supported_commands": ["/button", "/list", "/cta", "/location"],
+                "supported_message_types": [
+                    "text", "image", "video", "audio", "voice", "document", 
+                    "location", "contact", "contacts", "interactive"
+                ]
+            }
+            
+            # Add cache statistics if available
+            if self.cache_helper:
+                cache_stats = await self.cache_helper.get_cache_statistics()
+                stats["cache_stats"] = cache_stats
+            
+            return stats
+            
+        except Exception as e:
+            self.logger.error(f"❌ Error collecting handler statistics: {e}")
+            return {"error": f"Statistics collection failed: {str(e)}"}
+    
+    def __str__(self) -> str:
+        """String representation of the handler."""
+        success_rate = (self._successful_processing / max(1, self._total_messages)) * 100
+        return (
+            f"WappaFullExampleHandler("
+            f"messages={self._total_messages}, "
+            f"success_rate={success_rate:.1f}%, "
+            f"new_users={self._first_time_users}, "
+            f"commands={self._commands_processed}, "
+            f"interactions={self._interactive_responses}"
+            f")"
+        )

wappa/cli/examples/wappa_full_example/app/media/README.md

@@ -0,0 +1,54 @@
+# Media Files Directory
+
+This directory contains media files used by the Wappa Full Example application for interactive demonstrations.
+
+## Directory Structure
+
+```
+media/
+├── buttons/          # Media files for button command responses
+│   ├── kitty.png     # Image sent when user selects "Kitty" button
+│   └── puppy.png     # Image sent when user selects "Puppy" button
+└── list/             # Media files for list command responses
+    ├── image.png     # Sample image file for list selection
+    ├── video.mp4     # Sample video file for list selection
+    ├── audio.mp3     # Sample audio file for list selection
+    └── document.pdf  # Sample document file for list selection
+```
+
+## Usage
+
+The application automatically serves these files when users interact with:
+
+1. **Button Command** (`/button`):
+   - User selects "🐱 Kitty" → sends `buttons/kitty.png`
+   - User selects "🐶 Puppy" → sends `buttons/puppy.png`
+
+2. **List Command** (`/list`):
+   - User selects "🖼️ Image" → sends `list/image.png`
+   - User selects "🎬 Video" → sends `list/video.mp4`
+   - User selects "🎵 Audio" → sends `list/audio.mp3`
+   - User selects "📄 Document" → sends `list/document.pdf`
+
+## File Requirements
+
+- **Images**: PNG, JPG formats (max 5MB)
+- **Videos**: MP4 format (max 16MB)
+- **Audio**: MP3, OGG formats (max 16MB)
+- **Documents**: PDF format (max 100MB)
+
+## Adding Your Own Files
+
+Replace the placeholder files with your own media:
+
+1. Add your files to the appropriate subdirectories
+2. Use the exact filenames as listed above
+3. Ensure files meet WhatsApp Business API size limits
+4. Test with the interactive commands to verify functionality
+
+## Notes
+
+- Files are loaded from the local filesystem
+- The media handler automatically detects file types
+- If files are missing, fallback text messages are sent instead
+- This is a demonstration setup - in production, you might use cloud storage or CDN

wappa/cli/examples/wappa_full_example/app/media/buttons/README.md

@@ -0,0 +1,62 @@
+# Button Command Media Files
+
+This directory contains media files sent in response to button selections in the `/button` command demo.
+
+## Required Files
+
+Place these files in this directory:
+
+### `kitty.png`
+- **Purpose**: Sent when user clicks the "🐱 Kitty" button
+- **Format**: PNG or JPG image
+- **Size limit**: 5MB maximum
+- **Dimensions**: Recommended 500x500px or similar
+- **Content**: Image of a cute kitten
+
+### `puppy.png`
+- **Purpose**: Sent when user clicks the "🐶 Puppy" button
+- **Format**: PNG or JPG image
+- **Size limit**: 5MB maximum
+- **Dimensions**: Recommended 500x500px or similar
+- **Content**: Image of a cute puppy
+
+## How It Works
+
+1. User sends `/button` command
+2. App creates interactive button message with "Kitty" and "Puppy" options
+3. User clicks one of the buttons
+4. App sends the corresponding image file from this directory
+5. User receives the image with a caption
+
+## File Sources
+
+You can add your own images:
+- Download free images from Unsplash, Pixabay, or similar
+- Use your own photos
+- Ensure you have rights to use the images
+- Keep file sizes reasonable for WhatsApp
+
+## Fallback Behavior
+
+If files are missing:
+- App will send a text message instead
+- Message will indicate the file is missing
+- Button functionality will still work, but without media
+
+## Example Implementation
+
+```python
+# In state_handlers.py
+if selection_id == "kitty":
+    media_file = "kitty.png"
+elif selection_id == "puppy":
+    media_file = "puppy.png"
+
+media_result = await send_local_media_file(
+    messenger=self.messenger,
+    recipient=user_id,
+    filename=media_file,
+    media_subdir="buttons",
+    caption=f"Here's your {selection_id}! 🎉"
+)
+```

wappa/cli/examples/wappa_full_example/app/media/list/README.md

@@ -0,0 +1,110 @@
+# List Command Media Files
+
+This directory contains media files sent in response to list selections in the `/list` command demo.
+
+## Required Files
+
+Place these files in this directory:
+
+### `image.png`
+- **Purpose**: Sent when user selects "🖼️ Image" from the list
+- **Format**: PNG or JPG image
+- **Size limit**: 5MB maximum
+- **Content**: Sample image to demonstrate image sending
+- **Suggested**: Colorful demo image, infographic, or screenshot
+
+### `video.mp4`
+- **Purpose**: Sent when user selects "🎬 Video" from the list
+- **Format**: MP4 video file
+- **Size limit**: 16MB maximum
+- **Duration**: Keep under 60 seconds for demo purposes
+- **Content**: Sample video demonstrating video messaging
+- **Suggested**: Short demo video, animation, or screen recording
+
+### `audio.mp3`
+- **Purpose**: Sent when user selects "🎵 Audio" from the list
+- **Format**: MP3, OGG, or AAC audio file
+- **Size limit**: 16MB maximum
+- **Duration**: Keep under 2 minutes for demo purposes
+- **Content**: Sample audio demonstrating audio messaging
+- **Suggested**: Music clip, voice recording, or sound effect
+
+### `document.pdf`
+- **Purpose**: Sent when user selects "📄 Document" from the list
+- **Format**: PDF document
+- **Size limit**: 100MB maximum
+- **Content**: Sample document demonstrating document sharing
+- **Suggested**: User guide, specification sheet, or informational PDF
+
+## How It Works
+
+1. User sends `/list` command
+2. App creates interactive list message with 4 media type options
+3. User selects one option from the list
+4. App sends the corresponding media file from this directory
+5. User receives the media file with a caption
+
+## Interactive List Structure
+
+```json
+{
+  "title": "📁 Media Files",
+  "rows": [
+    {"id": "image_file", "title": "🖼️ Image", "description": "Get a sample image file"},
+    {"id": "video_file", "title": "🎬 Video", "description": "Get a sample video file"},
+    {"id": "audio_file", "title": "🎵 Audio", "description": "Get a sample audio file"},
+    {"id": "document_file", "title": "📄 Document", "description": "Get a sample document file"}
+  ]
+}
+```
+
+## File Recommendations
+
+### For Demo/Testing:
+- **Image**: Screenshots of the app, logos, or demo graphics
+- **Video**: App walkthrough, feature demonstration, or intro video
+- **Audio**: Welcome message, jingle, or app sounds
+- **Document**: User manual, API documentation, or feature list
+
+### For Production:
+- **Image**: Product catalogs, infographics, charts
+- **Video**: Product demos, tutorials, testimonials
+- **Audio**: Voice messages, audio guides, music
+- **Document**: Contracts, invoices, manuals, reports
+
+## WhatsApp Business API Limits
+
+- **Images**: JPEG, PNG up to 5MB, 8-bit RGB or RGBA
+- **Videos**: MP4, 3GP up to 16MB, H.264 codec, AAC audio
+- **Audio**: AAC, AMR, MP3, M4A, OGG up to 16MB
+- **Documents**: TXT, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX up to 100MB
+
+## Fallback Behavior
+
+If files are missing:
+- App will send a text message instead
+- Message will indicate the selected media type
+- List functionality will still work, but without actual media
+
+## Example Implementation
+
+```python
+# In state_handlers.py
+media_mapping = {
+    "image_file": ("image.png", "image"),
+    "video_file": ("video.mp4", "video"),
+    "audio_file": ("audio.mp3", "audio"),
+    "document_file": ("document.pdf", "document")
+}
+
+media_file, media_type = media_mapping.get(selection_id, (None, None))
+
+if media_file:
+    await send_local_media_file(
+        messenger=self.messenger,
+        recipient=user_id,
+        filename=media_file,
+        media_subdir="list",
+        caption=f"Here's your {media_type} file! 🎉"
+    )
+```