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

wappa/cli/examples/json_cache_example/app/scores/score_state_commands.py

@@ -0,0 +1,260 @@
+"""
+State Commands Score - Single Responsibility: /WAPPA and /EXIT command processing.
+
+This module handles all state-related commands including:
+- /WAPPA command activation and state management
+- /EXIT command deactivation and cleanup
+- WAPPA state message processing
+"""
+
+from ..models.json_demo_models import StateHandler
+from ..utils.cache_utils import create_state_key, get_cache_ttl
+from ..utils.message_utils import extract_command_from_message, extract_user_data
+from wappa.webhooks import IncomingMessageWebhook
+
+from .score_base import ScoreBase
+
+
+class StateCommandsScore(ScoreBase):
+    """
+    Handles state-related command processing.
+    
+    Follows Single Responsibility Principle by focusing only
+    on state management and command processing.
+    """
+    
+    async def can_handle(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        This score handles /WAPPA, /EXIT commands and messages in WAPPA state.
+        
+        Args:
+            webhook: Incoming message webhook
+            
+        Returns:
+            True if this is a state command or user is in WAPPA state
+        """
+        message_text = webhook.get_message_text()
+        if not message_text:
+            return False
+        
+        # Check for state commands
+        command, _ = extract_command_from_message(message_text.strip())
+        if command in ['/WAPPA', '/EXIT']:
+            return True
+        
+        # Check if user is in WAPPA state (need to handle regular messages in state)
+        user_data = extract_user_data(webhook)
+        user_id = user_data['user_id']
+        
+        try:
+            state_key = create_state_key(user_id)
+            state = await self.state_cache.get(state_key, models=StateHandler)
+            return state is not None and state.is_wappa
+        except:
+            return False
+    
+    async def process(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        Process state commands and WAPPA state messages.
+        
+        Args:
+            webhook: Incoming message webhook
+            
+        Returns:
+            True if processing was successful
+        """
+        if not await self.validate_dependencies():
+            return False
+        
+        try:
+            message_text = webhook.get_message_text()
+            if not message_text:
+                return False
+            
+            command, remaining_text = extract_command_from_message(message_text.strip())
+            user_data = extract_user_data(webhook)
+            user_id = user_data['user_id']
+            
+            if command == "/WAPPA":
+                await self._handle_wappa_activation(webhook, user_id)
+            elif command == "/EXIT":
+                await self._handle_wappa_exit(webhook, user_id)
+            else:
+                # Handle regular message in WAPPA state
+                await self._handle_wappa_state_message(webhook, user_id, message_text)
+            
+            self._record_processing(success=True)
+            return True
+            
+        except Exception as e:
+            await self._handle_error(e, "state_command_processing")
+            return False
+    
+    async def _handle_wappa_activation(self, webhook: IncomingMessageWebhook, user_id: str) -> None:
+        """
+        Handle /WAPPA command activation.
+        
+        Args:
+            webhook: Incoming message webhook
+            user_id: User's phone number ID
+        """
+        try:
+            # Create and save WAPPA state
+            state = StateHandler()
+            state.activate_wappa()
+            
+            # Store state with TTL
+            state_key = create_state_key(user_id)
+            ttl = get_cache_ttl('state')
+            await self.state_cache.set(state_key, state, ttl=ttl)
+            
+            # Mark message as read with typing indicator first
+            await self.messenger.mark_as_read(
+                message_id=webhook.message.message_id,
+                typing=True
+            )
+            
+            # Send activation message
+            activation_message = (
+                "🎉 You are in wappa state, to exit wappa state write /EXIT\n\n"
+                "✨ While in WAPPA state:\n"
+                "• I'll respond with 'Hola Wapp@ ;)' to all your messages\n"
+                "• Your state is cached in JSON files\n"
+                "• Write /EXIT to leave WAPPA state"
+            )
+            
+            result = await self.messenger.send_text(
+                recipient=user_id,
+                text=activation_message,
+                reply_to_message_id=webhook.message.message_id
+            )
+            
+            if result.success:
+                self.logger.info(f"✅ WAPPA state activated for {user_id}")
+            else:
+                self.logger.error(f"❌ Failed to send WAPPA activation message: {result.error}")
+                
+        except Exception as e:
+            self.logger.error(f"Error in WAPPA activation: {e}")
+            raise
+    
+    async def _handle_wappa_exit(self, webhook: IncomingMessageWebhook, user_id: str) -> None:
+        """
+        Handle /EXIT command deactivation.
+        
+        Args:
+            webhook: Incoming message webhook
+            user_id: User's phone number ID
+        """
+        try:
+            state_key = create_state_key(user_id)
+            
+            # Check if user has WAPPA state
+            state = await self.state_cache.get(state_key, models=StateHandler)
+            
+            if state and state.is_wappa:
+                # Calculate session stats
+                duration = state.get_state_duration() or 0
+                command_count = state.command_count
+                
+                # Deactivate and delete state
+                await self.state_cache.delete(state_key)
+                
+                # Mark message as read with typing indicator first
+                await self.messenger.mark_as_read(
+                    message_id=webhook.message.message_id,
+                    typing=True
+                )
+                
+                # Send exit message
+                exit_message = (
+                    "👋 You are no longer in wappa state!\n\n"
+                    f"📊 Session Summary:\n"
+                    f"• Duration: {duration} seconds\n"
+                    f"• Commands processed: {command_count}\n"
+                    f"• State cleared from JSON cache"
+                )
+                
+                result = await self.messenger.send_text(
+                    recipient=user_id,
+                    text=exit_message,
+                    reply_to_message_id=webhook.message.message_id
+                )
+                
+                if result.success:
+                    self.logger.info(f"✅ WAPPA state deactivated for {user_id} (duration: {duration}s)")
+                else:
+                    self.logger.error(f"❌ Failed to send WAPPA exit message: {result.error}")
+            else:
+                # No active state found
+                await self.messenger.send_text(
+                    recipient=user_id,
+                    text="❓ You are not currently in WAPPA state. Send /WAPPA to activate it.",
+                    reply_to_message_id=webhook.message.message_id
+                )
+                
+        except Exception as e:
+            self.logger.error(f"Error in WAPPA exit: {e}")
+            raise
+    
+    async def _handle_wappa_state_message(self, webhook: IncomingMessageWebhook, 
+                                        user_id: str, message_text: str) -> None:
+        """
+        Handle regular messages when user is in WAPPA state.
+        
+        Args:
+            webhook: Incoming message webhook
+            user_id: User's phone number ID
+            message_text: Message content
+        """
+        try:
+            state_key = create_state_key(user_id)
+            state = await self.state_cache.get(state_key, models=StateHandler)
+            
+            if state and state.is_wappa:
+                # Update state with command processing
+                state.process_command(message_text)
+                
+                # Save updated state
+                ttl = get_cache_ttl('state')
+                await self.state_cache.set(state_key, state, ttl=ttl)
+                
+                # Mark message as read with typing indicator first
+                await self.messenger.mark_as_read(
+                    message_id=webhook.message.message_id,
+                    typing=True
+                )
+                
+                # Send WAPPA response
+                result = await self.messenger.send_text(
+                    recipient=user_id,
+                    text="Hola Wapp@ ;)",
+                    reply_to_message_id=webhook.message.message_id
+                )
+                
+                if result.success:
+                    self.logger.info(f"✅ WAPPA response sent to {user_id} (command #{state.command_count})")
+                else:
+                    self.logger.error(f"❌ Failed to send WAPPA response: {result.error}")
+            
+        except Exception as e:
+            self.logger.error(f"Error handling WAPPA state message: {e}")
+            raise
+    
+    async def is_user_in_wappa_state(self, user_id: str) -> bool:
+        """
+        Check if user is currently in WAPPA state (for other score modules).
+        
+        Args:
+            user_id: User's phone number ID
+            
+        Returns:
+            True if user is in WAPPA state
+        """
+        try:
+            state_key = create_state_key(user_id)
+            state = await self.state_cache.get(state_key, models=StateHandler)
+            return state is not None and state.is_wappa
+        except Exception as e:
+            self.logger.error(f"Error checking WAPPA state for {user_id}: {e}")
+            return False

wappa/cli/examples/json_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.json_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 JSON 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 JSON files!"
+                )
+            else:
+                # Regular acknowledgment
+                welcome_text = (
+                    f"✅ Message received, {user.user_name}!\n"
+                    f"📝 Total messages: {user.message_count}\n"
+                    f"💾 Profile cached in JSON files"
+                )
+            
+            # 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/json_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/json_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}")