wappa 0.1.0__py3-none-any.whl

wappa/domain/factories/messenger_factory.py

@@ -0,0 +1,244 @@
+"""
+Messenger factory for creating platform-specific IMessenger implementations.
+
+This factory implements the Strategy Pattern to create appropriate IMessenger
+instances based on platform type, handling all dependency injection and
+configuration for each platform-specific messenger.
+"""
+
+from typing import TYPE_CHECKING
+
+from wappa.core.logging.logger import get_logger
+from wappa.domain.interfaces.messaging_interface import IMessenger
+from wappa.domain.services.tenant_credentials_service import TenantCredentialsService
+from wappa.messaging.whatsapp.client.whatsapp_client import WhatsAppClient
+from wappa.messaging.whatsapp.handlers.whatsapp_interactive_handler import (
+    WhatsAppInteractiveHandler,
+)
+from wappa.messaging.whatsapp.handlers.whatsapp_media_handler import (
+    WhatsAppMediaHandler,
+)
+from wappa.messaging.whatsapp.handlers.whatsapp_specialized_handler import (
+    WhatsAppSpecializedHandler,
+)
+from wappa.messaging.whatsapp.handlers.whatsapp_template_handler import (
+    WhatsAppTemplateHandler,
+)
+from wappa.messaging.whatsapp.messenger.whatsapp_messenger import WhatsAppMessenger
+from wappa.schemas.core.types import PlatformType
+
+if TYPE_CHECKING:
+    import aiohttp
+
+
+class MessengerFactory:
+    """
+    Factory for creating platform-specific messenger implementations.
+
+    Uses Strategy Pattern to provide appropriate IMessenger implementations
+    based on platform type. Handles dependency injection and configuration
+    for each platform-specific messenger.
+
+    Currently supported platforms:
+    - WhatsApp Business API
+
+    Future platforms:
+    - Telegram Bot API
+    - Microsoft Teams
+    - Discord
+    """
+
+    def __init__(self, http_session: "aiohttp.ClientSession" = None):
+        """
+        Initialize the messenger factory.
+
+        Args:
+            http_session: Shared HTTP session for efficient connection pooling
+        """
+        self._http_session = http_session
+        self.logger = get_logger(__name__)
+
+        # Cache for created messengers to avoid recreating for same tenant/platform
+        self._messenger_cache: dict[str, IMessenger] = {}
+
+    async def create_messenger(
+        self, platform: PlatformType, tenant_id: str, force_recreate: bool = False
+    ) -> IMessenger:
+        """
+        Create platform-specific messenger implementation.
+
+        Args:
+            platform: Platform type (WHATSAPP, TELEGRAM, etc.)
+            tenant_id: Tenant-specific identifier
+            force_recreate: Force creation of new instance even if cached
+
+        Returns:
+            Configured IMessenger implementation for the specified platform
+
+        Raises:
+            ValueError: If platform is not supported
+            RuntimeError: If messenger creation fails
+        """
+        cache_key = f"{platform.value}:{tenant_id}"
+
+        # Return cached instance if available and not forcing recreation
+        if not force_recreate and cache_key in self._messenger_cache:
+            self.logger.debug(f"Using cached messenger for {cache_key}")
+            return self._messenger_cache[cache_key]
+
+        self.logger.debug(
+            f"Creating new messenger for platform: {platform.value}, tenant: {tenant_id}"
+        )
+
+        try:
+            if platform == PlatformType.WHATSAPP:
+                messenger = await self._create_whatsapp_messenger(tenant_id)
+
+            # Future platform implementations:
+            # elif platform == PlatformType.TELEGRAM:
+            #     messenger = await self._create_telegram_messenger(tenant_id)
+            # elif platform == PlatformType.TEAMS:
+            #     messenger = await self._create_teams_messenger(tenant_id)
+
+            else:
+                raise ValueError(f"Unsupported platform: {platform.value}")
+
+            # Cache the created messenger
+            self._messenger_cache[cache_key] = messenger
+
+            return messenger
+
+        except Exception as e:
+            self.logger.error(
+                f"Failed to create messenger for platform {platform.value}: {e}"
+            )
+            raise RuntimeError(f"Messenger creation failed: {e}") from e
+
+    async def _create_whatsapp_messenger(self, tenant_id: str) -> WhatsAppMessenger:
+        """
+        Create configured WhatsApp messenger with all dependencies.
+
+        Reuses the existing dependency injection chain from whatsapp_dependencies.py
+        to maintain consistency and avoid code duplication.
+
+        Args:
+            tenant_id: WhatsApp phone_number_id (tenant identifier)
+
+        Returns:
+            Fully configured WhatsAppMessenger instance
+
+        Raises:
+            ValueError: If tenant credentials are invalid
+        """
+        self.logger.debug(f"Creating WhatsApp messenger for tenant: {tenant_id}")
+
+        # Validate tenant credentials
+        if not TenantCredentialsService.validate_tenant(tenant_id):
+            raise ValueError(f"Invalid or inactive tenant: {tenant_id}")
+
+        # Get tenant-specific access token
+        access_token = TenantCredentialsService.get_whatsapp_access_token(tenant_id)
+
+        # Create WhatsApp client (core dependency)
+        client = WhatsAppClient(
+            session=self._http_session,
+            access_token=access_token,
+            phone_number_id=tenant_id,
+            logger=self.logger,
+        )
+
+        # Create all WhatsApp handlers (following dependency injection pattern)
+        media_handler = WhatsAppMediaHandler(client=client, tenant_id=tenant_id)
+        interactive_handler = WhatsAppInteractiveHandler(
+            client=client, tenant_id=tenant_id
+        )
+        template_handler = WhatsAppTemplateHandler(client=client, tenant_id=tenant_id)
+        specialized_handler = WhatsAppSpecializedHandler(
+            client=client, tenant_id=tenant_id
+        )
+
+        # Create unified WhatsApp messenger with all handlers
+        messenger = WhatsAppMessenger(
+            client=client,
+            media_handler=media_handler,
+            interactive_handler=interactive_handler,
+            template_handler=template_handler,
+            specialized_handler=specialized_handler,
+            tenant_id=tenant_id,
+        )
+
+        self.logger.info(
+            f"✅ WhatsApp messenger created successfully for tenant: {tenant_id}"
+        )
+        return messenger
+
+    def get_supported_platforms(self) -> list[PlatformType]:
+        """
+        Get list of currently supported platforms.
+
+        Returns:
+            List of supported platform types
+        """
+        return [PlatformType.WHATSAPP]
+
+    def is_platform_supported(self, platform: PlatformType) -> bool:
+        """
+        Check if platform is supported by this factory.
+
+        Args:
+            platform: Platform type to check
+
+        Returns:
+            True if platform is supported, False otherwise
+        """
+        return platform in self.get_supported_platforms()
+
+    def clear_cache(self, platform: PlatformType = None, tenant_id: str = None):
+        """
+        Clear messenger cache.
+
+        Args:
+            platform: Optional platform to clear (clear all if None)
+            tenant_id: Optional tenant to clear (clear all if None)
+        """
+        if platform and tenant_id:
+            # Clear specific platform/tenant combination
+            cache_key = f"{platform.value}:{tenant_id}"
+            self._messenger_cache.pop(cache_key, None)
+            self.logger.debug(f"Cleared messenger cache for {cache_key}")
+        elif platform:
+            # Clear all messengers for a platform
+            to_remove = [
+                key
+                for key in self._messenger_cache.keys()
+                if key.startswith(f"{platform.value}:")
+            ]
+            for key in to_remove:
+                del self._messenger_cache[key]
+            self.logger.debug(f"Cleared messenger cache for platform: {platform.value}")
+        elif tenant_id:
+            # Clear all messengers for a tenant
+            to_remove = [
+                key
+                for key in self._messenger_cache.keys()
+                if key.endswith(f":{tenant_id}")
+            ]
+            for key in to_remove:
+                del self._messenger_cache[key]
+            self.logger.debug(f"Cleared messenger cache for tenant: {tenant_id}")
+        else:
+            # Clear entire cache
+            self._messenger_cache.clear()
+            self.logger.debug("Cleared entire messenger cache")
+
+    # Future platform implementations:
+
+    # async def _create_telegram_messenger(self, tenant_id: str) -> IMessenger:
+    #     """Create configured Telegram messenger (future implementation)."""
+    #     # TODO: Implement Telegram Bot API messenger
+    #     raise NotImplementedError("Telegram messenger not yet implemented")
+
+    # async def _create_teams_messenger(self, tenant_id: str) -> IMessenger:
+    #     """Create configured Teams messenger (future implementation)."""
+    #     # TODO: Implement Microsoft Teams messenger
+    #     raise NotImplementedError("Teams messenger not yet implemented")

wappa/domain/interfaces/__init__.py

@@ -0,0 +1,32 @@
+"""
+Domain interfaces.
+
+Defines the contracts that infrastructure layer must implement.
+"""
+
+from .base_repository import IBaseRepository
+from .cache_factory import ICacheFactory
+from .cache_interface import ICache
+from .expiry_repository import IExpiryRepository
+from .media_interface import IMediaHandler
+from .messaging_interface import IMessenger
+from .pubsub_repository import IPubSubRepository
+from .repository_factory import IRepositoryFactory
+from .shared_state_repository import ISharedStateRepository
+from .state_repository import IStateRepository
+from .user_repository import IUserRepository
+
+__all__ = [
+    "IBaseRepository",
+    "IUserRepository",
+    "IStateRepository",
+    "ISharedStateRepository",
+    "IExpiryRepository",
+    "IPubSubRepository",
+    "IRepositoryFactory",
+    "IMessenger",
+    "IMediaHandler",
+    # Cache interfaces
+    "ICache",
+    "ICacheFactory",
+]

wappa/domain/interfaces/base_repository.py

@@ -0,0 +1,94 @@
+"""
+Base repository interface.
+
+Defines common contract for all Redis-based repositories.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import timedelta
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class IBaseRepository(ABC):
+    """
+    Base interface for all Redis repositories.
+
+    Provides common contract for key-value operations, TTL management,
+    and context-aware operations.
+    """
+
+    @abstractmethod
+    async def get(self, key: str) -> Any | None:
+        """Get value by key."""
+        pass
+
+    @abstractmethod
+    async def set(self, key: str, value: Any, ttl: timedelta | None = None) -> bool:
+        """Set value with optional TTL."""
+        pass
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """Delete key."""
+        pass
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check if key exists."""
+        pass
+
+    @abstractmethod
+    async def get_ttl(self, key: str) -> int | None:
+        """Get TTL for key in seconds."""
+        pass
+
+    @abstractmethod
+    async def set_ttl(self, key: str, ttl: timedelta) -> bool:
+        """Set TTL for existing key."""
+        pass
+
+    @abstractmethod
+    async def get_hash(
+        self, key: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Get hash value with optional BaseModel deserialization.
+
+        Args:
+            key: Redis key
+            models: Optional BaseModel class for full object reconstruction
+                   e.g., User (will automatically handle nested UserContact, UserLocation)
+
+        Returns:
+            Hash data dictionary or None if not found
+        """
+        pass
+
+    @abstractmethod
+    async def set_hash(
+        self, key: str, data: dict[str, Any], ttl: timedelta | None = None
+    ) -> bool:
+        """Set hash value with optional TTL."""
+        pass
+
+    @abstractmethod
+    async def get_hash_field(self, key: str, field: str) -> Any | None:
+        """Get single field from hash."""
+        pass
+
+    @abstractmethod
+    async def set_hash_field(self, key: str, field: str, value: Any) -> bool:
+        """Set single field in hash."""
+        pass
+
+    @abstractmethod
+    async def delete_hash_field(self, key: str, field: str) -> bool:
+        """Delete field from hash."""
+        pass
+
+    @abstractmethod
+    async def get_keys_pattern(self, pattern: str) -> list[str]:
+        """Get keys matching pattern."""
+        pass

wappa/domain/interfaces/cache_factory.py

@@ -0,0 +1,85 @@
+"""
+Cache factory interface definition for Wappa framework.
+
+Defines the contract for creating context-aware cache instances.
+"""
+
+from abc import ABC, abstractmethod
+
+from .cache_interface import ICache
+
+
+class ICacheFactory(ABC):
+    """
+    Interface for creating context-aware cache instances.
+
+    Cache factories create cache instances bound to specific tenants and users,
+    ensuring proper data isolation and context management.
+
+    Context (tenant_id, user_id) is injected at construction time, eliminating
+    the need for manual parameter passing in cache creation methods.
+    """
+
+    def __init__(self, tenant_id: str, user_id: str):
+        """
+        Initialize cache factory with request context.
+
+        This eliminates the need for manual parameter passing in cache methods.
+        Context is injected once at construction and used throughout the factory lifetime.
+
+        Args:
+            tenant_id: Tenant identifier for namespace isolation
+            user_id: User identifier for user-specific caches
+
+        Raises:
+            ValueError: If tenant_id or user_id is None or empty
+        """
+        self.tenant_id = tenant_id
+        self.user_id = user_id
+        self._validate_context()
+
+    def _validate_context(self):
+        """Validate that required context is available."""
+        if not self.tenant_id or not self.user_id:
+            raise ValueError(
+                f"Missing required context: tenant_id={self.tenant_id}, user_id={self.user_id}"
+            )
+
+    @abstractmethod
+    def create_state_cache(self) -> ICache:
+        """
+        Create state cache instance with context binding.
+
+        Used for handler state management and conversation state tracking.
+        Context (tenant_id, user_id) is automatically injected from constructor.
+
+        Returns:
+            Context-bound state cache instance
+        """
+        pass
+
+    @abstractmethod
+    def create_user_cache(self) -> ICache:
+        """
+        Create user cache instance with context binding.
+
+        Used for user profile data, preferences, and user-specific information.
+        Context (tenant_id, user_id) is automatically injected from constructor.
+
+        Returns:
+            Context-bound user cache instance
+        """
+        pass
+
+    @abstractmethod
+    def create_table_cache(self) -> ICache:
+        """
+        Create table cache instance with context binding.
+
+        Used for shared data, lookup tables, and tenant-wide information.
+        Context (tenant_id) is automatically injected from constructor.
+
+        Returns:
+            Context-bound table cache instance
+        """
+        pass

wappa/domain/interfaces/cache_interface.py

@@ -0,0 +1,199 @@
+"""
+Cache interface definition for Wappa framework.
+
+Defines the contract for cache implementations (Redis, Memory, JSON).
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ICache(ABC):
+    """
+    Interface for cache implementations in the Wappa framework.
+
+    Provides basic cache operations with context awareness for tenant and user isolation.
+    All cache implementations must support these core operations.
+    """
+
+    @abstractmethod
+    async def get(
+        self, key: str, models: type[BaseModel] | None = None
+    ) -> dict[str, Any] | None:
+        """
+        Get cached data by key.
+
+        Args:
+            key: Cache key
+            models: Optional BaseModel class for deserialization
+
+        Returns:
+            Cached data or None if not found
+        """
+        pass
+
+    @abstractmethod
+    async def set(self, key: str, data: dict[str, Any], ttl: int | None = None) -> bool:
+        """
+        Set cached data with optional TTL.
+
+        Args:
+            key: Cache key
+            data: Data to cache
+            ttl: Time to live in seconds
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def delete(self, key: str) -> bool:
+        """
+        Delete cached data by key.
+
+        Args:
+            key: Cache key to delete
+
+        Returns:
+            True if deleted, False if not found
+        """
+        pass
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """
+        Check if key exists in cache.
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            True if exists, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def get_field(self, key: str, field: str) -> Any | None:
+        """
+        Get a specific field from cached hash data.
+
+        Args:
+            key: Cache key
+            field: Field name
+
+        Returns:
+            Field value or None if not found
+        """
+        pass
+
+    @abstractmethod
+    async def set_field(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """
+        Set a specific field in cached hash data.
+
+        Args:
+            key: Cache key
+            field: Field name
+            value: Field value
+            ttl: Time to live in seconds
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def increment_field(
+        self, key: str, field: str, increment: int = 1, ttl: int | None = None
+    ) -> int | None:
+        """
+        Atomically increment an integer field.
+
+        Args:
+            key: Cache key
+            field: Field name
+            increment: Amount to increment by
+            ttl: Time to live in seconds
+
+        Returns:
+            New value after increment or None on error
+        """
+        pass
+
+    @abstractmethod
+    async def append_to_list(
+        self, key: str, field: str, value: Any, ttl: int | None = None
+    ) -> bool:
+        """
+        Append value to a list field.
+
+        Args:
+            key: Cache key
+            field: Field name containing list
+            value: Value to append
+            ttl: Time to live in seconds
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    async def get_ttl(self, key: str) -> int:
+        """
+        Get remaining time to live for a key.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Remaining TTL in seconds, -1 if no expiry, -2 if key doesn't exist
+        """
+        pass
+
+    @abstractmethod
+    async def set_ttl(self, key: str, ttl: int) -> bool:
+        """
+        Set time to live for a key.
+
+        Args:
+            key: Cache key
+            ttl: Time to live in seconds
+
+        Returns:
+            True if successful, False otherwise
+        """
+        pass
+    
+    @staticmethod
+    def create_table_key(table_name: str, pkid: str) -> str:
+        """
+        Create a properly formatted table cache key.
+        
+        This is a static utility method available on all cache implementations
+        to ensure consistent key formatting across cache backends.
+        
+        Args:
+            table_name: Name of the table (e.g., "user_profiles", "message_logs")
+            pkid: Primary key ID (e.g., user_id, message_id)
+            
+        Returns:
+            Formatted key string for use with cache methods
+            
+        Example:
+            key = ICache.create_table_key("user_profiles", "12345")
+            # Returns: "user_profiles:12345"
+        """
+        if not table_name or not pkid:
+            raise ValueError("Both table_name and pkid must be provided and non-empty")
+        
+        # Sanitize inputs to avoid conflicts
+        safe_table_name = str(table_name).replace(":", "_")
+        safe_pkid = str(pkid).replace(":", "_")
+        
+        return f"{safe_table_name}:{safe_pkid}"