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

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

@@ -0,0 +1,174 @@
+"""
+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
+
+
+def generate_cache_key(prefix: str, identifier: str, suffix: str | None = 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
+    return "::" not in key
+
+
+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: float | None = 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,251 @@
+"""
+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 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[str | None, 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: str | None, 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 = [
+        "👤 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')}",
+        "",
+        "🎯 Special Commands:",
+        "• Send '/WAPPA' to enter special state",
+        "• Send '/EXIT' to leave special state",
+        "• Send '/HISTORY' to see your message history",
+        "",
+        "📊 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}",
+        "",
+        "💾 This demo showcases Redis caching:",
+        "• User data cached in user_cache",
+        "• Message history stored in table_cache per user",
+        "• 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=
+

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,191 @@
+"""
+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()