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

wappa/cli/examples/redis_cache_example/app/scores/score_user_management.py

@@ -0,0 +1,223 @@
+"""
+User Management Score - Single Responsibility: User profile and caching logic.
+
+This module handles all user-related operations including:
+- User profile creation and updates
+- User data caching with TTL management
+- User activity tracking
+"""
+
+from ..models.redis_demo_models import User
+from ..utils.cache_utils import create_user_profile_key, get_cache_ttl
+from ..utils.message_utils import extract_user_data
+from wappa.webhooks import IncomingMessageWebhook
+
+from .score_base import ScoreBase
+
+
+class UserManagementScore(ScoreBase):
+    """
+    Handles user profile management and caching operations.
+    
+    Follows Single Responsibility Principle by focusing only
+    on user-related business logic.
+    """
+    
+    async def can_handle(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        This score handles all webhooks since every message needs user management.
+        
+        Args:
+            webhook: Incoming message webhook
+            
+        Returns:
+            Always True since user management is needed for all messages
+        """
+        return True
+    
+    async def process(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        Process user data extraction and caching.
+        
+        Args:
+            webhook: Incoming message webhook
+            
+        Returns:
+            True if user processing was successful
+        """
+        if not await self.validate_dependencies():
+            return False
+        
+        try:
+            user_data = extract_user_data(webhook)
+            user_id = user_data['user_id']
+            user_name = user_data['user_name']
+            
+            # Get or create user profile
+            user = await self._get_or_create_user(user_id, user_name)
+            
+            if user:
+                # Update user activity
+                await self._update_user_activity(user, user_id)
+                
+                # Send welcome/acknowledgment message for regular messages
+                await self._send_welcome_message(webhook, user, user_id)
+                
+                self._record_processing(success=True)
+                
+                self.logger.info(
+                    f"👤 User profile updated: {user_id} "
+                    f"(messages: {user.message_count}, name: {user.user_name})"
+                )
+                return True
+            else:
+                self._record_processing(success=False)
+                return False
+                
+        except Exception as e:
+            await self._handle_error(e, "user_management_processing")
+            return False
+    
+    async def _get_or_create_user(self, user_id: str, user_name: str) -> User:
+        """
+        Get existing user or create new one.
+        
+        Args:
+            user_id: User's phone number ID
+            user_name: User's display name
+            
+        Returns:
+            User profile instance
+        """
+        try:
+            # Generate cache key using utility function
+            cache_key = create_user_profile_key(user_id)
+            
+            # Try to get existing user with BaseModel deserialization
+            user = await self.user_cache.get(cache_key, models=User)
+            
+            if user:
+                # User exists, update name if provided and different
+                if user_name and user_name != "Unknown User" and user.user_name != user_name:
+                    user.user_name = user_name
+                    self.logger.debug(f"Updated user name: {user_id} -> {user_name}")
+                
+                self.logger.debug(f"👤 User cache HIT: {user_id}")
+                return user
+            else:
+                # Create new user profile
+                user = User(
+                    phone_number=user_id,
+                    user_name=user_name if user_name != "Unknown User" else None,
+                    message_count=0  # Will be incremented by increment_message_count()
+                )
+                
+                self.logger.info(f"👤 User cache MISS: Creating new profile for {user_id}")
+                return user
+                
+        except Exception as e:
+            self.logger.error(f"Error getting/creating user {user_id}: {e}")
+            raise
+    
+    async def _update_user_activity(self, user: User, user_id: str) -> None:
+        """
+        Update user activity and save to cache.
+        
+        Args:
+            user: User profile to update
+            user_id: User's phone number ID
+        """
+        try:
+            # Update user activity
+            user.increment_message_count()
+            
+            # Save updated user data with TTL
+            cache_key = create_user_profile_key(user_id)
+            ttl = get_cache_ttl('user')
+            
+            await self.user_cache.set(cache_key, user, ttl=ttl)
+            
+            self.logger.debug(f"User activity updated: {user_id} (count: {user.message_count})")
+            
+        except Exception as e:
+            self.logger.error(f"Error updating user activity {user_id}: {e}")
+            raise
+    
+    async def get_user_profile(self, user_id: str) -> User:
+        """
+        Get user profile for other score modules.
+        
+        Args:
+            user_id: User's phone number ID
+            
+        Returns:
+            User profile or None if not found
+        """
+        try:
+            cache_key = create_user_profile_key(user_id)
+            return await self.user_cache.get(cache_key, models=User)
+        except Exception as e:
+            self.logger.error(f"Error getting user profile {user_id}: {e}")
+            return None
+    
+    async def _send_welcome_message(self, webhook: IncomingMessageWebhook, user: User, user_id: str) -> None:
+        """
+        Send welcome/acknowledgment message based on user's message count.
+        
+        Args:
+            webhook: Incoming message webhook
+            user: User profile data
+            user_id: User's phone number ID
+        """
+        try:
+            message_text = webhook.get_message_text() or ""
+            
+            # Don't send welcome for commands (let other scores handle them)
+            if message_text.strip().startswith('/'):
+                return
+            
+            # Step 1: Mark message as read with typing indicator
+            read_result = await self.messenger.mark_as_read(
+                message_id=webhook.message.message_id,
+                typing=True  # Show typing indicator
+            )
+            
+            if not read_result.success:
+                self.logger.warning(f"⚠️ Failed to mark message as read: {read_result.error}")
+            else:
+                self.logger.debug(f"✅ Message marked as read with typing indicator: {webhook.message.message_id}")
+            
+            # Create personalized welcome message based on message count
+            if user.message_count == 1:
+                # First message - welcome
+                welcome_text = (
+                    f"👋 Welcome to Wappa Redis Cache Demo, {user.user_name}!\n\n"
+                    f"🎯 Available commands:\n"
+                    f"• `/WAPPA` - Enter special state\n"
+                    f"• `/EXIT` - Leave special state\n"
+                    f"• `/HISTORY` - View message history\n"
+                    f"• `/STATS` - View cache statistics\n\n"
+                    f"💎 Your profile is cached in Redis!"
+                )
+            else:
+                # Regular acknowledgment
+                welcome_text = (
+                    f"✅ Message received, {user.user_name}!\n"
+                    f"📝 Total messages: {user.message_count}\n"
+                    f"💾 Profile cached in Redis"
+                )
+            
+            # Step 2: Send welcome/acknowledgment message
+            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 {user_id} (marked as read + typing)")
+            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}")

wappa/cli/examples/redis_cache_example/app/utils/__init__.py

@@ -0,0 +1,26 @@
+"""
+Utility modules for Redis Cache Example.
+
+This package contains shared utility functions used across
+the score modules, following the Single Responsibility Principle.
+"""
+
+from .cache_utils import (
+    generate_cache_key,
+    get_cache_ttl,
+    validate_cache_key,
+)
+from .message_utils import (
+    extract_user_data,
+    format_timestamp,
+    sanitize_message_text,
+)
+
+__all__ = [
+    "generate_cache_key",
+    "get_cache_ttl", 
+    "validate_cache_key",
+    "extract_user_data",
+    "format_timestamp",
+    "sanitize_message_text",
+]

wappa/cli/examples/redis_cache_example/app/utils/cache_utils.py

@@ -0,0 +1,176 @@
+"""
+Cache utility functions following Single Responsibility Principle.
+
+This module provides cache-related helper functions used across 
+different score modules for consistent cache management.
+"""
+
+import re
+from datetime import datetime
+from typing import Optional
+
+
+def generate_cache_key(prefix: str, identifier: str, suffix: Optional[str] = None) -> str:
+    """
+    Generate a standardized cache key.
+    
+    Args:
+        prefix: Cache type prefix (e.g., 'user', 'state', 'msg_history')
+        identifier: Unique identifier (e.g., user_id, session_id)
+        suffix: Optional suffix for additional specificity
+        
+    Returns:
+        Properly formatted cache key
+        
+    Examples:
+        >>> generate_cache_key('user', '1234567890')
+        'user:1234567890'
+        >>> generate_cache_key('msg_history', '1234567890', 'recent')
+        'msg_history:1234567890:recent'
+    """
+    if not prefix or not identifier:
+        raise ValueError("Both prefix and identifier are required")
+    
+    # Sanitize inputs
+    prefix = sanitize_cache_component(prefix)
+    identifier = sanitize_cache_component(identifier)
+    
+    key = f"{prefix}:{identifier}"
+    
+    if suffix:
+        suffix = sanitize_cache_component(suffix)
+        key += f":{suffix}"
+    
+    return key
+
+
+def sanitize_cache_component(component: str) -> str:
+    """
+    Sanitize a cache key component by removing invalid characters.
+    
+    Args:
+        component: Component string to sanitize
+        
+    Returns:
+        Sanitized component safe for cache keys
+    """
+    # Remove spaces and special characters, keep alphanumeric, underscore, hyphen
+    sanitized = re.sub(r'[^\w\-]', '_', str(component).strip())
+    
+    # Remove multiple consecutive underscores
+    sanitized = re.sub(r'_+', '_', sanitized)
+    
+    # Remove leading/trailing underscores
+    return sanitized.strip('_')
+
+
+def get_cache_ttl(cache_type: str) -> int:
+    """
+    Get standard TTL (time-to-live) values for different cache types.
+    
+    Args:
+        cache_type: Type of cache ('user', 'state', 'message', 'statistics')
+        
+    Returns:
+        TTL in seconds
+        
+    Raises:
+        ValueError: If cache_type is not recognized
+    """
+    ttl_mapping = {
+        'user': 86400,      # 24 hours - User profiles
+        'state': 3600,      # 1 hour - Command states  
+        'message': 604800,  # 7 days - Message history
+        'statistics': 3600, # 1 hour - Cache statistics
+        'temporary': 600,   # 10 minutes - Temporary data
+    }
+    
+    if cache_type not in ttl_mapping:
+        raise ValueError(f"Unknown cache_type: {cache_type}. Valid types: {list(ttl_mapping.keys())}")
+    
+    return ttl_mapping[cache_type]
+
+
+def validate_cache_key(key: str) -> bool:
+    """
+    Validate if a cache key follows the expected format.
+    
+    Args:
+        key: Cache key to validate
+        
+    Returns:
+        True if valid, False otherwise
+    """
+    if not key or not isinstance(key, str):
+        return False
+    
+    # Basic format check: should contain at least one colon
+    if ':' not in key:
+        return False
+    
+    # Check for invalid characters (spaces, special chars except : _ -)
+    if re.search(r'[^\w:\-]', key):
+        return False
+    
+    # Should not start or end with colon
+    if key.startswith(':') or key.endswith(':'):
+        return False
+    
+    # Should not have consecutive colons
+    if '::' in key:
+        return False
+    
+    return True
+
+
+def create_user_profile_key(user_id: str) -> str:
+    """Create standardized user profile cache key."""
+    return generate_cache_key('user', user_id, 'profile')
+
+
+def create_message_history_key(user_id: str) -> str:
+    """Create standardized message history cache key.""" 
+    return generate_cache_key('msg_history', user_id)
+
+
+def create_state_key(user_id: str, state_type: str = 'wappa') -> str:
+    """Create standardized state cache key."""
+    return generate_cache_key('state', user_id, state_type)
+
+
+def create_statistics_key(scope: str = 'global') -> str:
+    """Create standardized cache statistics key."""
+    return generate_cache_key('stats', scope)
+
+
+def format_cache_error(operation: str, key: str, error: Exception) -> str:
+    """
+    Format cache operation error messages consistently.
+    
+    Args:
+        operation: Cache operation ('get', 'set', 'delete')
+        key: Cache key that failed
+        error: Exception that occurred
+        
+    Returns:
+        Formatted error message
+    """
+    return f"Cache {operation} failed for key '{key}': {str(error)}"
+
+
+def log_cache_operation(logger, operation: str, key: str, success: bool, 
+                       duration_ms: Optional[float] = None) -> None:
+    """
+    Log cache operations consistently across score modules.
+    
+    Args:
+        logger: Logger instance
+        operation: Cache operation performed
+        key: Cache key used
+        success: Whether operation succeeded
+        duration_ms: Optional operation duration in milliseconds
+    """
+    status = "✅" if success else "❌"
+    duration_str = f" ({duration_ms:.1f}ms)" if duration_ms else ""
+    
+    logger.debug(f"{status} Cache {operation}: {key}{duration_str}")

wappa/cli/examples/redis_cache_example/app/utils/message_utils.py

@@ -0,0 +1,246 @@
+"""
+Message processing utility functions following Single Responsibility Principle.
+
+This module provides message-related helper functions used across
+different score modules for consistent message handling.
+"""
+
+from datetime import datetime
+from typing import Dict, Optional, Tuple
+
+from wappa.webhooks import IncomingMessageWebhook
+
+
+def extract_user_data(webhook: IncomingMessageWebhook) -> Dict[str, str]:
+    """
+    Extract user data from webhook in a standardized format.
+    
+    Args:
+        webhook: Incoming message webhook
+        
+    Returns:
+        Dictionary with standardized user data
+    """
+    return {
+        'user_id': webhook.user.user_id,
+        'user_name': webhook.user.profile_name or "Unknown User",
+        'tenant_id': webhook.tenant.get_tenant_key(),
+        'message_id': webhook.message.message_id,
+    }
+
+
+def sanitize_message_text(text: str, max_length: int = 500) -> str:
+    """
+    Sanitize message text for safe storage and processing.
+    
+    Args:
+        text: Raw message text
+        max_length: Maximum allowed length
+        
+    Returns:
+        Sanitized message text
+    """
+    if not text:
+        return ""
+    
+    # Convert to string and strip whitespace
+    sanitized = str(text).strip()
+    
+    # Truncate if too long
+    if len(sanitized) > max_length:
+        sanitized = sanitized[:max_length-3] + "..."
+    
+    # Replace problematic characters
+    sanitized = sanitized.replace('\x00', '').replace('\r\n', '\n')
+    
+    return sanitized
+
+
+def format_timestamp(dt: datetime, format_type: str = 'display') -> str:
+    """
+    Format timestamps consistently across the application.
+    
+    Args:
+        dt: Datetime to format
+        format_type: Format type ('display', 'compact', 'iso')
+        
+    Returns:
+        Formatted timestamp string
+    """
+    if format_type == 'display':
+        return dt.strftime("%Y-%m-%d %H:%M:%S")
+    elif format_type == 'compact':
+        return dt.strftime("%m/%d %H:%M")
+    elif format_type == 'iso':
+        return dt.isoformat()
+    else:
+        raise ValueError(f"Unknown format_type: {format_type}")
+
+
+def extract_command_from_message(text: str) -> Tuple[Optional[str], str]:
+    """
+    Extract command and remaining text from message.
+    
+    Args:
+        text: Message text
+        
+    Returns:
+        Tuple of (command, remaining_text)
+        Command is None if no command found
+        
+    Examples:
+        >>> extract_command_from_message("/WAPPA hello")
+        ("/WAPPA", "hello")
+        >>> extract_command_from_message("regular message")
+        (None, "regular message")
+    """
+    if not text:
+        return None, ""
+    
+    text = text.strip()
+    
+    # Check if it starts with a command
+    if text.startswith('/'):
+        parts = text.split(' ', 1)
+        command = parts[0].upper()
+        remaining = parts[1] if len(parts) > 1 else ""
+        return command, remaining
+    
+    return None, text
+
+
+def is_special_command(text: str) -> bool:
+    """
+    Check if message text contains a special command.
+    
+    Args:
+        text: Message text to check
+        
+    Returns:
+        True if text contains a recognized command
+    """
+    command, _ = extract_command_from_message(text)
+    
+    if not command:
+        return False
+    
+    # List of recognized commands
+    special_commands = ['/WAPPA', '/EXIT', '/HISTORY', '/HELP', '/STATUS']
+    
+    return command in special_commands
+
+
+def get_message_type_display_name(message_type: str) -> str:
+    """
+    Get human-readable display name for message types.
+    
+    Args:
+        message_type: Technical message type
+        
+    Returns:
+        Human-readable display name
+    """
+    type_mapping = {
+        'text': 'Text',
+        'image': 'Image',
+        'audio': 'Audio',
+        'video': 'Video',
+        'document': 'Document',
+        'location': 'Location',
+        'contacts': 'Contact',
+        'interactive': 'Interactive',
+        'button': 'Button Response',
+        'list': 'List Response',
+        'sticker': 'Sticker',
+    }
+    
+    return type_mapping.get(message_type.lower(), message_type.title())
+
+
+def create_user_greeting(user_name: Optional[str], message_count: int) -> str:
+    """
+    Create personalized user greeting message.
+    
+    Args:
+        user_name: User's display name (can be None)
+        message_count: Number of messages from user
+        
+    Returns:
+        Personalized greeting text
+    """
+    name = user_name or "there"
+    
+    if message_count == 1:
+        return f"👋 Hello {name}! Welcome to the Redis Cache Demo!"
+    elif message_count < 5:
+        return f"👋 Hello {name}! Nice to see you again!"
+    else:
+        return f"👋 Hello {name}! You're becoming a regular here! ({message_count} messages)"
+
+
+def format_message_history_display(messages, total_count: int, display_count: int = 20) -> str:
+    """
+    Format message history for display to user.
+    
+    Args:
+        messages: List of MessageHistory objects
+        total_count: Total number of messages in history
+        display_count: Number of messages being displayed
+        
+    Returns:
+        Formatted history text
+    """
+    if not messages:
+        return "📚 Your message history is empty. Start chatting to build your history!"
+    
+    history_text = f"📚 Your Message History ({total_count} total messages):\n\n"
+    
+    for i, msg_history in enumerate(messages, 1):
+        timestamp_str = format_timestamp(msg_history.timestamp, 'compact')
+        msg_type = f"[{get_message_type_display_name(msg_history.message_type)}]" if msg_history.message_type != "text" else ""
+        
+        # Truncate long messages for display
+        display_message = sanitize_message_text(msg_history.message, 50)
+        
+        history_text += f"{i:2d}. {timestamp_str} {msg_type} {display_message}\n"
+    
+    if total_count > display_count:
+        history_text += f"\n... showing last {display_count} of {total_count} messages"
+    
+    return history_text
+
+
+def create_cache_info_message(user_profile, cache_stats) -> str:
+    """
+    Create informational message about cache status.
+    
+    Args:
+        user_profile: User profile data
+        cache_stats: Cache statistics data
+        
+    Returns:
+        Formatted cache information message
+    """
+    info_lines = [
+        f"👤 Your Profile:",
+        f"• Messages sent: {user_profile.message_count}",
+        f"• First seen: {format_timestamp(user_profile.first_seen, 'compact')}",
+        f"• Last seen: {format_timestamp(user_profile.last_seen, 'compact')}",
+        "",
+        f"🎯 Special Commands:",
+        f"• Send '/WAPPA' to enter special state",
+        f"• Send '/EXIT' to leave special state", 
+        f"• Send '/HISTORY' to see your message history",
+        "",
+        f"📊 Cache Statistics:",
+        f"• Total operations: {cache_stats.total_operations}",
+        f"• User cache hit rate: {cache_stats.get_user_hit_rate():.1%}",
+        f"• Active states: {cache_stats.state_cache_active}",
+        "",
+        f"💾 This demo showcases Redis caching:",
+        f"• User data cached in user_cache",
+        f"• Message history stored in table_cache per user",
+        f"• Commands tracked in state_cache"
+    ]
+    
+    return "\n".join(info_lines)

wappa/cli/examples/simple_echo_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=
+