wappa 0.1.0__py3-none-any.whl

wappa/messaging/whatsapp/models/specialized_models.py

@@ -0,0 +1,304 @@
+"""
+WhatsApp specialized message models.
+
+Provides Pydantic v2 validation models for WhatsApp specialized operations:
+- ContactMessage: Contact card sharing with comprehensive contact information
+- LocationMessage: Geographic location sharing with coordinates
+- LocationRequestMessage: Interactive location request from users
+
+Based on WhatsApp Cloud API 2025 specialized message specifications.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class AddressType(str, Enum):
+    """Contact address types."""
+
+    HOME = "HOME"
+    WORK = "WORK"
+
+
+class EmailType(str, Enum):
+    """Contact email types."""
+
+    HOME = "HOME"
+    WORK = "WORK"
+
+
+class PhoneType(str, Enum):
+    """Contact phone number types."""
+
+    HOME = "HOME"
+    WORK = "WORK"
+    CELL = "CELL"
+    MAIN = "MAIN"
+    IPHONE = "IPHONE"
+    WHATSAPP = "WHATSAPP"
+
+
+class UrlType(str, Enum):
+    """Contact URL types."""
+
+    HOME = "HOME"
+    WORK = "WORK"
+
+
+class ContactAddress(BaseModel):
+    """Contact address information."""
+
+    street: str | None = Field(None, max_length=500, description="Street address")
+    city: str | None = Field(None, max_length=100, description="City name")
+    state: str | None = Field(None, max_length=100, description="State or province")
+    zip: str | None = Field(None, max_length=20, description="ZIP or postal code")
+    country: str | None = Field(None, max_length=100, description="Country name")
+    country_code: str | None = Field(
+        None, pattern=r"^[A-Z]{2}$", description="ISO country code"
+    )
+    type: AddressType = Field(..., description="Address type")
+
+
+class ContactEmail(BaseModel):
+    """Contact email information."""
+
+    email: str = Field(
+        ..., pattern=r"^[^@]+@[^@]+\.[^@]+$", description="Email address"
+    )
+    type: EmailType = Field(..., description="Email type")
+
+
+class ContactName(BaseModel):
+    """Contact name information."""
+
+    formatted_name: str = Field(
+        ..., min_length=1, max_length=100, description="Full formatted name"
+    )
+    first_name: str | None = Field(None, max_length=50, description="First name")
+    last_name: str | None = Field(None, max_length=50, description="Last name")
+    middle_name: str | None = Field(None, max_length=50, description="Middle name")
+    suffix: str | None = Field(None, max_length=20, description="Name suffix")
+    prefix: str | None = Field(None, max_length=20, description="Name prefix")
+
+    @field_validator("formatted_name")
+    @classmethod
+    def validate_formatted_name_required(cls, v):
+        """Validate that formatted_name is not empty."""
+        if not v or not v.strip():
+            raise ValueError("formatted_name is required and cannot be empty")
+        return v.strip()
+
+
+class ContactOrganization(BaseModel):
+    """Contact organization information."""
+
+    company: str | None = Field(None, max_length=100, description="Company name")
+    department: str | None = Field(None, max_length=100, description="Department")
+    title: str | None = Field(None, max_length=100, description="Job title")
+
+
+class ContactPhone(BaseModel):
+    """Contact phone information."""
+
+    phone: str = Field(
+        ..., pattern=r"^\+?[\d\s\-\(\)]{7,20}$", description="Phone number"
+    )
+    type: PhoneType = Field(..., description="Phone type")
+    wa_id: str | None = Field(None, pattern=r"^\d{10,15}$", description="WhatsApp ID")
+
+
+class ContactUrl(BaseModel):
+    """Contact URL information."""
+
+    url: str = Field(..., pattern=r"^https?://", description="Website URL")
+    type: UrlType = Field(..., description="URL type")
+
+
+class ContactCard(BaseModel):
+    """Complete contact card information."""
+
+    addresses: list[ContactAddress] | None = Field(
+        None, max_length=5, description="Contact addresses"
+    )
+    birthday: str | None = Field(
+        None, pattern=r"^\d{4}-\d{2}-\d{2}$", description="Birthday (YYYY-MM-DD)"
+    )
+    emails: list[ContactEmail] | None = Field(
+        None, max_length=5, description="Email addresses"
+    )
+    name: ContactName = Field(..., description="Contact name information")
+    org: ContactOrganization | None = Field(
+        None, description="Organization information"
+    )
+    phones: list[ContactPhone] = Field(
+        ..., min_length=1, max_length=5, description="Phone numbers"
+    )
+    urls: list[ContactUrl] | None = Field(
+        None, max_length=5, description="Website URLs"
+    )
+
+    @field_validator("phones")
+    @classmethod
+    def validate_at_least_one_phone(cls, v):
+        """Validate that at least one phone number is provided."""
+        if not v or len(v) == 0:
+            raise ValueError("At least one phone number is required")
+        return v
+
+
+class ContactMessage(BaseModel):
+    """Contact card message request."""
+
+    recipient: str = Field(
+        ..., pattern=r"^\d{10,15}$", description="Recipient phone number"
+    )
+    contact: ContactCard = Field(..., description="Contact card information")
+    reply_to_message_id: str | None = Field(None, description="Message ID to reply to")
+
+
+class LocationMessage(BaseModel):
+    """Location sharing message request."""
+
+    recipient: str = Field(
+        ..., pattern=r"^\d{10,15}$", description="Recipient phone number"
+    )
+    latitude: float = Field(
+        ..., ge=-90, le=90, description="Location latitude (-90 to 90)"
+    )
+    longitude: float = Field(
+        ..., ge=-180, le=180, description="Location longitude (-180 to 180)"
+    )
+    name: str | None = Field(None, max_length=100, description="Location name")
+    address: str | None = Field(None, max_length=1000, description="Location address")
+    reply_to_message_id: str | None = Field(None, description="Message ID to reply to")
+
+    @field_validator("latitude")
+    @classmethod
+    def validate_latitude_range(cls, v):
+        """Validate latitude is within valid range."""
+        if not -90 <= v <= 90:
+            raise ValueError("Latitude must be between -90 and 90 degrees")
+        return v
+
+    @field_validator("longitude")
+    @classmethod
+    def validate_longitude_range(cls, v):
+        """Validate longitude is within valid range."""
+        if not -180 <= v <= 180:
+            raise ValueError("Longitude must be between -180 and 180 degrees")
+        return v
+
+
+class LocationRequestMessage(BaseModel):
+    """Location request message (asks user to share their location)."""
+
+    recipient: str = Field(
+        ..., pattern=r"^\d{10,15}$", description="Recipient phone number"
+    )
+    body: str = Field(
+        ..., min_length=1, max_length=1024, description="Request message text"
+    )
+    reply_to_message_id: str | None = Field(None, description="Message ID to reply to")
+
+    @field_validator("body")
+    @classmethod
+    def validate_body_length(cls, v):
+        """Validate body text length."""
+        if len(v) > 1024:
+            raise ValueError("Body text cannot exceed 1024 characters")
+        return v
+
+
+class ContactValidationResult(BaseModel):
+    """Contact validation result."""
+
+    valid: bool = Field(..., description="Whether contact is valid")
+    errors: list[str] | None = Field(None, description="Validation errors")
+    warnings: list[str] | None = Field(None, description="Validation warnings")
+
+
+class LocationValidationResult(BaseModel):
+    """Location validation result."""
+
+    valid: bool = Field(..., description="Whether location is valid")
+    latitude: float | None = Field(None, description="Validated latitude")
+    longitude: float | None = Field(None, description="Validated longitude")
+    errors: list[str] | None = Field(None, description="Validation errors")
+    address_suggestions: list[str] | None = Field(
+        None, description="Address suggestions"
+    )
+
+
+# Example contact structures for common use cases
+class BusinessContact(BaseModel):
+    """Simplified business contact model."""
+
+    business_name: str = Field(..., max_length=100, description="Business name")
+    phone: str = Field(
+        ..., pattern=r"^\+?[\d\s\-\(\)]{7,20}$", description="Business phone"
+    )
+    email: str | None = Field(
+        None, pattern=r"^[^@]+@[^@]+\.[^@]+$", description="Business email"
+    )
+    website: str | None = Field(
+        None, pattern=r"^https?://", description="Business website"
+    )
+    address: str | None = Field(None, max_length=500, description="Business address")
+
+    def to_contact_card(self) -> ContactCard:
+        """Convert to full ContactCard format."""
+        phones = [ContactPhone(phone=self.phone, type=PhoneType.WORK)]
+        emails = (
+            [ContactEmail(email=self.email, type=EmailType.WORK)]
+            if self.email
+            else None
+        )
+        urls = (
+            [ContactUrl(url=self.website, type=UrlType.WORK)] if self.website else None
+        )
+
+        return ContactCard(
+            name=ContactName(formatted_name=self.business_name),
+            phones=phones,
+            emails=emails,
+            urls=urls,
+            org=ContactOrganization(company=self.business_name),
+        )
+
+
+class PersonalContact(BaseModel):
+    """Simplified personal contact model."""
+
+    first_name: str = Field(..., max_length=50, description="First name")
+    last_name: str | None = Field(None, max_length=50, description="Last name")
+    phone: str = Field(
+        ..., pattern=r"^\+?[\d\s\-\(\)]{7,20}$", description="Phone number"
+    )
+    email: str | None = Field(
+        None, pattern=r"^[^@]+@[^@]+\.[^@]+$", description="Email address"
+    )
+
+    def to_contact_card(self) -> ContactCard:
+        """Convert to full ContactCard format."""
+        formatted_name = (
+            f"{self.first_name} {self.last_name}".strip()
+            if self.last_name
+            else self.first_name
+        )
+        phones = [ContactPhone(phone=self.phone, type=PhoneType.CELL)]
+        emails = (
+            [ContactEmail(email=self.email, type=EmailType.HOME)]
+            if self.email
+            else None
+        )
+
+        return ContactCard(
+            name=ContactName(
+                formatted_name=formatted_name,
+                first_name=self.first_name,
+                last_name=self.last_name,
+            ),
+            phones=phones,
+            emails=emails,
+        )

wappa/messaging/whatsapp/models/template_models.py

@@ -0,0 +1,261 @@
+"""
+WhatsApp template message models.
+
+Provides Pydantic v2 validation models for WhatsApp template operations:
+- TextTemplateMessage: Text-only template messages
+- MediaTemplateMessage: Template messages with media headers
+- LocationTemplateMessage: Template messages with location headers
+
+Based on WhatsApp Cloud API 2025 template message specifications.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class TemplateType(str, Enum):
+    """Template message types supported by WhatsApp."""
+
+    TEXT = "text"
+    MEDIA = "media"
+    LOCATION = "location"
+
+
+class MediaType(str, Enum):
+    """Media types supported in template headers."""
+
+    IMAGE = "image"
+    VIDEO = "video"
+    DOCUMENT = "document"
+
+
+class TemplateParameterType(str, Enum):
+    """Template parameter types."""
+
+    TEXT = "text"
+    CURRENCY = "currency"
+    DATE_TIME = "date_time"
+    IMAGE = "image"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    LOCATION = "location"
+
+
+class TemplateParameter(BaseModel):
+    """Template parameter for dynamic content replacement."""
+
+    type: TemplateParameterType = Field(..., description="Parameter type")
+    text: str | None = Field(
+        None, max_length=1024, description="Text content for text parameters"
+    )
+
+    @field_validator("text")
+    @classmethod
+    def validate_text_required_for_text_type(cls, v, info):
+        """Validate that text is provided for text type parameters."""
+        if info.data.get("type") == TemplateParameterType.TEXT and not v:
+            raise ValueError("Text content is required for text type parameters")
+        return v
+
+
+class TemplateComponent(BaseModel):
+    """Template component (header, body, footer, button)."""
+
+    type: str = Field(..., description="Component type (header, body, footer, button)")
+    parameters: list[TemplateParameter] | None = Field(
+        None, description="Component parameters"
+    )
+
+
+class TemplateLanguage(BaseModel):
+    """Template language configuration."""
+
+    code: str = Field(default="es", description="BCP-47 language code")
+
+    @field_validator("code")
+    @classmethod
+    def validate_language_code(cls, v):
+        """Validate BCP-47 language code format."""
+        # Basic validation for common language codes
+        common_codes = [
+            "es",
+            "en",
+            "en_US",
+            "pt_BR",
+            "fr",
+            "de",
+            "it",
+            "ja",
+            "ko",
+            "zh",
+            "ar",
+            "hi",
+            "ru",
+            "tr",
+            "nl",
+            "sv",
+            "da",
+            "no",
+            "pl",
+            "cs",
+            "hu",
+        ]
+
+        if v not in common_codes and not v.replace("_", "").replace("-", "").isalpha():
+            raise ValueError(f"Invalid language code format: {v}")
+        return v
+
+
+class BaseTemplateMessage(BaseModel):
+    """Base template message with common fields."""
+
+    recipient: str = Field(
+        ..., pattern=r"^\d{10,15}$", description="Recipient phone number"
+    )
+    template_name: str = Field(
+        ..., min_length=1, max_length=512, description="Template name"
+    )
+    language: TemplateLanguage = Field(
+        default_factory=lambda: TemplateLanguage(), description="Template language"
+    )
+    template_type: TemplateType = Field(..., description="Type of template message")
+
+
+class TextTemplateMessage(BaseTemplateMessage):
+    """Text-only template message."""
+
+    template_type: TemplateType = Field(
+        default=TemplateType.TEXT, description="Template type"
+    )
+    body_parameters: list[TemplateParameter] | None = Field(
+        None, max_length=10, description="Body parameters for text replacement"
+    )
+
+    @field_validator("body_parameters")
+    @classmethod
+    def validate_body_parameters(cls, v):
+        """Validate body parameters are text type."""
+        if v:
+            for param in v:
+                if param.type != TemplateParameterType.TEXT:
+                    raise ValueError(
+                        "Text template body parameters must be of type 'text'"
+                    )
+        return v
+
+
+class MediaTemplateMessage(BaseTemplateMessage):
+    """Template message with media header."""
+
+    template_type: TemplateType = Field(
+        default=TemplateType.MEDIA, description="Template type"
+    )
+    media_type: MediaType = Field(..., description="Media type for header")
+    media_id: str | None = Field(None, min_length=1, description="Uploaded media ID")
+    media_url: str | None = Field(None, pattern=r"^https?://", description="Media URL")
+    body_parameters: list[TemplateParameter] | None = Field(
+        None, max_length=10, description="Body parameters for text replacement"
+    )
+
+    @field_validator("media_id", "media_url")
+    @classmethod
+    def validate_media_source(cls, v, info):
+        """Validate that either media_id or media_url is provided, but not both."""
+        values = info.data
+        media_id = values.get("media_id")
+        media_url = values.get("media_url")
+
+        if (media_id and media_url) or (not media_id and not media_url):
+            raise ValueError(
+                "Either media_id or media_url must be provided, but not both"
+            )
+        return v
+
+    @field_validator("body_parameters")
+    @classmethod
+    def validate_body_parameters(cls, v):
+        """Validate body parameters are text type."""
+        if v:
+            for param in v:
+                if param.type != TemplateParameterType.TEXT:
+                    raise ValueError(
+                        "Media template body parameters must be of type 'text'"
+                    )
+        return v
+
+
+class LocationTemplateMessage(BaseTemplateMessage):
+    """Template message with location header."""
+
+    template_type: TemplateType = Field(
+        default=TemplateType.LOCATION, description="Template type"
+    )
+    latitude: str = Field(..., description="Location latitude as string")
+    longitude: str = Field(..., description="Location longitude as string")
+    name: str = Field(..., min_length=1, max_length=100, description="Location name")
+    address: str = Field(
+        ..., min_length=1, max_length=1000, description="Location address"
+    )
+    body_parameters: list[TemplateParameter] | None = Field(
+        None, max_length=10, description="Body parameters for text replacement"
+    )
+
+    @field_validator("latitude")
+    @classmethod
+    def validate_latitude(cls, v):
+        """Validate latitude range (-90 to 90)."""
+        try:
+            lat = float(v)
+            if not -90 <= lat <= 90:
+                raise ValueError("Latitude must be between -90 and 90 degrees")
+        except ValueError as e:
+            if "could not convert" in str(e):
+                raise ValueError("Latitude must be a valid number")
+            raise
+        return v
+
+    @field_validator("longitude")
+    @classmethod
+    def validate_longitude(cls, v):
+        """Validate longitude range (-180 to 180)."""
+        try:
+            lon = float(v)
+            if not -180 <= lon <= 180:
+                raise ValueError("Longitude must be between -180 and 180 degrees")
+        except ValueError as e:
+            if "could not convert" in str(e):
+                raise ValueError("Longitude must be a valid number")
+            raise
+        return v
+
+    @field_validator("body_parameters")
+    @classmethod
+    def validate_body_parameters(cls, v):
+        """Validate body parameters are text type."""
+        if v:
+            for param in v:
+                if param.type != TemplateParameterType.TEXT:
+                    raise ValueError(
+                        "Location template body parameters must be of type 'text'"
+                    )
+        return v
+
+
+class TemplateMessageStatus(BaseModel):
+    """Template message delivery status."""
+
+    template_name: str = Field(..., description="Template name")
+    status: str = Field(..., description="Template status")
+    language: str = Field(..., description="Template language")
+    category: str | None = Field(None, description="Template category")
+    components: list[dict] | None = Field(None, description="Template components")
+
+
+class TemplateValidationResult(BaseModel):
+    """Template validation result."""
+
+    valid: bool = Field(..., description="Whether template is valid")
+    template_name: str = Field(..., description="Template name")
+    errors: list[str] | None = Field(None, description="Validation errors")
+    warnings: list[str] | None = Field(None, description="Validation warnings")

wappa/persistence/cache_factory.py

@@ -0,0 +1,93 @@
+"""
+Main cache factory selector for Wappa framework.
+
+Provides factory selector based on cache type configuration.
+"""
+
+
+from ..domain.interfaces.cache_factory import ICacheFactory
+
+
+def create_cache_factory(cache_type: str) -> type[ICacheFactory]:
+    """
+    Create cache factory class based on cache type.
+
+    Returns factory classes that can be instantiated with context parameters.
+    This supports the new context-aware cache factory pattern where context
+    (tenant_id, user_id) is injected at construction time.
+
+    Args:
+        cache_type: Type of cache to create ("redis", "json", "memory")
+
+    Returns:
+        Cache factory class for the specified type
+
+    Raises:
+        ValueError: If cache_type is not supported
+        ImportError: If required dependencies are not available
+    """
+    if cache_type == "redis":
+        try:
+            from .redis.redis_cache_factory import RedisCacheFactory
+
+            return RedisCacheFactory
+        except ImportError as e:
+            raise ImportError(
+                f"Redis dependencies not available for cache_type='redis': {e}"
+            ) from e
+
+    elif cache_type == "json":
+        try:
+            from .json.json_cache_factory import JSONCacheFactory
+
+            return JSONCacheFactory
+        except ImportError as e:
+            raise ImportError(
+                f"JSON cache dependencies not available for cache_type='json': {e}"
+            ) from e
+
+    elif cache_type == "memory":
+        try:
+            from .memory.memory_cache_factory import MemoryCacheFactory
+
+            return MemoryCacheFactory
+        except ImportError as e:
+            raise ImportError(
+                f"Memory cache dependencies not available for cache_type='memory': {e}"
+            ) from e
+
+    else:
+        raise ValueError(
+            f"Unsupported cache_type: {cache_type}. "
+            f"Supported types: 'redis', 'json', 'memory'"
+        )
+
+
+# Convenience function for getting cache factory with validation
+def get_cache_factory(
+    cache_type: str, *, validate_redis_url: bool = True
+) -> type[ICacheFactory]:
+    """
+    Get cache factory class with validation.
+
+    Args:
+        cache_type: Type of cache to create
+        validate_redis_url: Whether to validate Redis URL for redis cache type
+
+    Returns:
+        Configured cache factory class
+
+    Raises:
+        ValueError: If configuration is invalid
+        ImportError: If required dependencies are not available
+    """
+    if cache_type == "redis" and validate_redis_url:
+        from ..core.config.settings import settings
+
+        if not settings.has_redis:
+            raise ValueError(
+                "Redis URL not configured. Set REDIS_URL environment variable "
+                "or use a different cache_type"
+            )
+
+    return create_cache_factory(cache_type)

wappa/persistence/json/__init__.py

@@ -0,0 +1,14 @@
+"""
+JSON-based cache implementation for Wappa framework.
+
+Provides persistent cache storage using JSON files on disk.
+Suitable for development, debugging, and single-process deployments.
+
+Usage:
+    wappa = Wappa(cache="json")
+    # Cache files will be created in {project_root}/cache/
+"""
+
+from .json_cache_factory import JSONCacheFactory
+
+__all__ = ["JSONCacheFactory"]