wappa 0.1.0__py3-none-any.whl

wappa/messaging/whatsapp/models/__init__.py

@@ -0,0 +1,61 @@
+"""WhatsApp models package."""
+
+from .basic_models import BasicTextMessage, MessageResult, ReadStatusMessage
+from .interactive_models import ButtonMessage, CTAMessage, ListMessage
+from .media_models import (
+    AudioMessage,
+    DocumentMessage,
+    ImageMessage,
+    MediaType,
+    StickerMessage,
+    VideoMessage,
+)
+from .specialized_models import (
+    BusinessContact,
+    ContactCard,
+    ContactMessage,
+    ContactValidationResult,
+    LocationMessage,
+    LocationRequestMessage,
+    LocationValidationResult,
+    PersonalContact,
+)
+from .template_models import (
+    LocationTemplateMessage,
+    MediaTemplateMessage,
+    TemplateMessageStatus,
+    TemplateParameter,
+    TemplateType,
+    TemplateValidationResult,
+    TextTemplateMessage,
+)
+
+__all__ = [
+    "MessageResult",
+    "BasicTextMessage",
+    "ReadStatusMessage",
+    "ButtonMessage",
+    "CTAMessage",
+    "ListMessage",
+    "MediaType",
+    "ImageMessage",
+    "VideoMessage",
+    "AudioMessage",
+    "DocumentMessage",
+    "StickerMessage",
+    "ContactCard",
+    "ContactMessage",
+    "ContactValidationResult",
+    "LocationMessage",
+    "LocationRequestMessage",
+    "LocationValidationResult",
+    "BusinessContact",
+    "PersonalContact",
+    "TemplateType",
+    "TemplateParameter",
+    "TextTemplateMessage",
+    "MediaTemplateMessage",
+    "LocationTemplateMessage",
+    "TemplateMessageStatus",
+    "TemplateValidationResult",
+]

wappa/messaging/whatsapp/models/basic_models.py

@@ -0,0 +1,65 @@
+"""
+Basic message models for WhatsApp messaging.
+
+Pydantic schemas for basic messaging operations: send_text and mark_as_read.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from wappa.schemas.core.types import PlatformType
+
+
+class MessageResult(BaseModel):
+    """Result of a messaging operation.
+
+    Standard response model for all messaging operations across platforms.
+    """
+
+    success: bool
+    platform: PlatformType = PlatformType.WHATSAPP
+    message_id: str | None = None
+    recipient: str | None = None
+    error: str | None = None
+    error_code: str | None = None
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    tenant_id: str | None = None  # phone_number_id in WhatsApp context
+
+    class Config:
+        use_enum_values = True
+
+
+class BasicTextMessage(BaseModel):
+    """Basic text message schema for send_text operations.
+
+    Schema for sending text messages with optional reply and preview control.
+    """
+
+    text: str = Field(
+        ..., min_length=1, max_length=4096, description="Text content of the message"
+    )
+    recipient: str = Field(
+        ..., min_length=1, description="Recipient phone number or user identifier"
+    )
+    reply_to_message_id: str | None = Field(
+        None, description="Message ID to reply to (creates a thread)"
+    )
+    disable_preview: bool = Field(
+        False, description="Disable URL preview for links in the message"
+    )
+
+
+class ReadStatusMessage(BaseModel):
+    """Read status message schema for mark_as_read operations.
+
+    Schema for marking messages as read with optional typing indicator.
+    Key requirement: typing boolean parameter for showing typing indicator.
+    """
+
+    message_id: str = Field(
+        ..., min_length=1, description="WhatsApp message ID to mark as read"
+    )
+    typing: bool = Field(
+        False, description="Show typing indicator when marking as read"
+    )

wappa/messaging/whatsapp/models/interactive_models.py

@@ -0,0 +1,287 @@
+"""
+Interactive message models for WhatsApp messaging.
+
+Pydantic schemas for interactive messaging operations based on WhatsApp Cloud API 2025
+specifications and existing interactive_message.py implementation patterns.
+
+Supports three types of interactive messages:
+1. Button Messages - Quick reply buttons (max 3)
+2. List Messages - Sectioned lists with rows (max 10 sections, 10 rows each)
+3. Call-to-Action Messages - URL buttons with external links
+"""
+
+from enum import Enum
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class InteractiveType(Enum):
+    """Supported interactive message types for WhatsApp."""
+
+    BUTTON = "button"
+    LIST = "list"
+    CTA_URL = "cta_url"
+
+
+class HeaderType(Enum):
+    """Supported header types for interactive messages."""
+
+    TEXT = "text"
+    IMAGE = "image"
+    VIDEO = "video"
+    DOCUMENT = "document"
+
+
+class InteractiveMessage(BaseModel):
+    """Base interactive message schema for interactive operations.
+
+    Common fields for all interactive message types based on existing
+    WhatsAppServiceInteractive implementation patterns.
+    """
+
+    recipient: str = Field(
+        ..., pattern=r"^\d{10,15}$", description="Recipient phone number"
+    )
+    body: str = Field(
+        ..., min_length=1, max_length=4096, description="Main message text"
+    )
+    reply_to_message_id: str | None = Field(
+        None, description="Optional message ID for replies"
+    )
+
+
+class ReplyButton(BaseModel):
+    """Reply button for button messages."""
+
+    id: str = Field(..., max_length=256, description="Unique button identifier")
+    title: str = Field(..., max_length=20, description="Button display text")
+
+
+class InteractiveHeader(BaseModel):
+    """Header for interactive messages with media support."""
+
+    type: HeaderType = Field(
+        ..., description="Header type (text, image, video, document)"
+    )
+    text: str | None = Field(
+        None, max_length=60, description="Header text (for text headers)"
+    )
+    image: dict[str, str] | None = Field(
+        None, description="Image header with 'id' or 'link' key"
+    )
+    video: dict[str, str] | None = Field(
+        None, description="Video header with 'id' or 'link' key"
+    )
+    document: dict[str, str] | None = Field(
+        None, description="Document header with 'id' or 'link' key"
+    )
+
+    @field_validator("text")
+    @classmethod
+    def validate_text_header(cls, v, info):
+        """Validate text header is provided for text type."""
+        if info.data and info.data.get("type") == HeaderType.TEXT and not v:
+            raise ValueError("Text header must include 'text' field")
+        return v
+
+    @field_validator("image", "video", "document")
+    @classmethod
+    def validate_media_header(cls, v, info):
+        """Validate media headers have id or link."""
+        if v and not (v.get("id") or v.get("link")):
+            raise ValueError("Media header must include either 'id' or 'link'")
+        return v
+
+
+class ButtonMessage(InteractiveMessage):
+    """Button message schema for send_button_message operations.
+
+    Supports up to 3 quick reply buttons with text headers and footers.
+    Based on existing send_buttons_menu() implementation.
+    """
+
+    interactive_type: Literal[InteractiveType.BUTTON] = Field(
+        default=InteractiveType.BUTTON
+    )
+    buttons: list[ReplyButton] = Field(
+        ..., min_length=1, max_length=3, description="List of reply buttons (max 3)"
+    )
+    header: InteractiveHeader | None = Field(
+        None, description="Optional header with text/media content"
+    )
+    footer: str | None = Field(None, max_length=60, description="Optional footer text")
+
+    @field_validator("buttons")
+    @classmethod
+    def validate_button_uniqueness(cls, v):
+        """Validate button IDs are unique."""
+        button_ids = [button.id for button in v]
+        if len(button_ids) != len(set(button_ids)):
+            raise ValueError("Button IDs must be unique")
+        return v
+
+
+class ListRow(BaseModel):
+    """Row within a list section."""
+
+    id: str = Field(..., max_length=200, description="Unique row identifier")
+    title: str = Field(..., max_length=24, description="Row title")
+    description: str | None = Field(
+        None, max_length=72, description="Optional row description"
+    )
+
+
+class ListSection(BaseModel):
+    """Section within a list message."""
+
+    title: str = Field(..., max_length=24, description="Section title")
+    rows: list[ListRow] = Field(
+        ...,
+        min_length=1,
+        max_length=10,
+        description="List of rows in this section (max 10)",
+    )
+
+    @field_validator("rows")
+    @classmethod
+    def validate_row_uniqueness(cls, v):
+        """Validate row IDs are unique within section."""
+        row_ids = [row.id for row in v]
+        if len(row_ids) != len(set(row_ids)):
+            raise ValueError("Row IDs must be unique within section")
+        return v
+
+
+class ListMessage(InteractiveMessage):
+    """List message schema for send_list_message operations.
+
+    Supports sectioned lists with up to 10 sections and 10 rows per section.
+    Based on existing send_list_menu() implementation.
+    """
+
+    interactive_type: Literal[InteractiveType.LIST] = Field(
+        default=InteractiveType.LIST
+    )
+    button_text: str = Field(
+        ..., max_length=20, description="Text for the button that opens the list"
+    )
+    sections: list[ListSection] = Field(
+        ..., min_length=1, max_length=10, description="List of sections (max 10)"
+    )
+    header: str | None = Field(
+        None, max_length=60, description="Optional header text (text only for lists)"
+    )
+    footer: str | None = Field(None, max_length=60, description="Optional footer text")
+
+    @field_validator("sections")
+    @classmethod
+    def validate_global_row_uniqueness(cls, v):
+        """Validate row IDs are unique across all sections."""
+        all_row_ids = []
+        for section in v:
+            for row in section.rows:
+                all_row_ids.append(row.id)
+
+        if len(all_row_ids) != len(set(all_row_ids)):
+            raise ValueError("Row IDs must be unique across all sections")
+        return v
+
+
+class CTAMessage(InteractiveMessage):
+    """Call-to-Action message schema for send_cta_message operations.
+
+    Supports URL buttons for external links.
+    Based on existing send_cta_button() implementation.
+    """
+
+    interactive_type: Literal[InteractiveType.CTA_URL] = Field(
+        default=InteractiveType.CTA_URL
+    )
+    button_text: str = Field(
+        ..., min_length=1, description="Text to display on the button"
+    )
+    button_url: str = Field(
+        ..., pattern=r"^https?://", description="URL to load when button is tapped"
+    )
+    header: str | None = Field(None, description="Optional header text")
+    footer: str | None = Field(None, description="Optional footer text")
+
+    @field_validator("button_url")
+    @classmethod
+    def validate_url_format(cls, v):
+        """Validate URL format is http:// or https://."""
+        if not (v.startswith("http://") or v.startswith("https://")):
+            raise ValueError("button_url must start with http:// or https://")
+        return v
+
+
+class InteractiveResponse(BaseModel):
+    """Response model for interactive message operations."""
+
+    success: bool = Field(..., description="Whether the operation succeeded")
+    message_id: str | None = Field(
+        None, description="WhatsApp message ID if successful"
+    )
+    interactive_type: InteractiveType = Field(
+        ..., description="Type of interactive message sent"
+    )
+    recipient: str = Field(..., description="Recipient phone number")
+    error: str | None = Field(None, description="Error message if failed")
+    error_code: str | None = Field(None, description="Error code for specific failures")
+
+
+# Validation utility functions for use in handlers
+def validate_buttons_menu_limits(buttons: list[ReplyButton]) -> None:
+    """Validate button menu constraints based on WhatsApp API limits."""
+    if len(buttons) > 3:
+        raise ValueError("Maximum of 3 buttons allowed")
+
+    for button in buttons:
+        if len(button.title) > 20:
+            raise ValueError(f"Button title '{button.title}' exceeds 20 characters")
+        if len(button.id) > 256:
+            raise ValueError(f"Button ID '{button.id}' exceeds 256 characters")
+
+
+def validate_list_menu_limits(sections: list[ListSection]) -> None:
+    """Validate list menu constraints based on WhatsApp API limits."""
+    if len(sections) > 10:
+        raise ValueError("Maximum of 10 sections allowed")
+
+    for section in sections:
+        if len(section.title) > 24:
+            raise ValueError(f"Section title '{section.title}' exceeds 24 characters")
+
+        if len(section.rows) > 10:
+            raise ValueError(f"Section '{section.title}' has more than 10 rows")
+
+        for row in section.rows:
+            if len(row.id) > 200:
+                raise ValueError(f"Row ID '{row.id}' exceeds 200 characters")
+            if len(row.title) > 24:
+                raise ValueError(f"Row title '{row.title}' exceeds 24 characters")
+            if row.description and len(row.description) > 72:
+                raise ValueError(
+                    f"Row description for '{row.title}' exceeds 72 characters"
+                )
+
+
+def validate_header_constraints(
+    header: InteractiveHeader | None, footer: str | None
+) -> None:
+    """Validate header and footer constraints."""
+    if header:
+        valid_header_types = {
+            HeaderType.TEXT,
+            HeaderType.IMAGE,
+            HeaderType.VIDEO,
+            HeaderType.DOCUMENT,
+        }
+        if header.type not in valid_header_types:
+            raise ValueError(
+                f"Header type must be one of {[t.value for t in valid_header_types]}"
+            )
+
+    if footer and len(footer) > 60:
+        raise ValueError("Footer text cannot exceed 60 characters")

wappa/messaging/whatsapp/models/media_models.py

@@ -0,0 +1,215 @@
+"""
+Media message models for WhatsApp messaging.
+
+Pydantic schemas for media messaging operations based on WhatsApp Cloud API 2025
+specifications and existing handle_media.py implementation patterns.
+"""
+
+from enum import Enum
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class MediaType(Enum):
+    """Supported media types for WhatsApp messages.
+
+    Based on WhatsApp Cloud API 2025 specifications and existing
+    WhatsAppServiceMedia.MediaType implementation.
+    """
+
+    AUDIO = "audio"
+    DOCUMENT = "document"
+    IMAGE = "image"
+    STICKER = "sticker"
+    VIDEO = "video"
+
+    @classmethod
+    def get_supported_mime_types(cls, media_type: "MediaType") -> set[str]:
+        """
+        Returns set of supported MIME types for each media type.
+
+        Extracted from existing WhatsAppServiceMedia.MediaType.get_supported_mime_types()
+        and validated against WhatsApp Cloud API 2025 specifications.
+        """
+        SUPPORTED_TYPES = {
+            cls.AUDIO: {
+                "audio/aac",
+                "audio/mp4",
+                "audio/mpeg",
+                "audio/amr",
+                "audio/ogg",
+            },
+            cls.DOCUMENT: {
+                "text/plain",
+                "application/pdf",
+                "application/vnd.ms-powerpoint",
+                "application/msword",
+                "application/vnd.ms-excel",
+                "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+                "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            },
+            cls.IMAGE: {"image/jpeg", "image/png"},
+            cls.STICKER: {"image/webp"},
+            cls.VIDEO: {"video/3gp", "video/mp4"},
+        }
+        return SUPPORTED_TYPES[media_type]
+
+    @classmethod
+    def get_max_file_size(cls, media_type: "MediaType") -> int:
+        """
+        Returns maximum file size in bytes for each media type.
+
+        Based on WhatsApp Cloud API 2025 specifications and existing
+        validation logic from handle_media.py.
+        """
+        MAX_SIZES = {
+            cls.AUDIO: 16 * 1024 * 1024,  # 16MB
+            cls.DOCUMENT: 100 * 1024 * 1024,  # 100MB
+            cls.IMAGE: 5 * 1024 * 1024,  # 5MB
+            cls.STICKER: 500 * 1024,  # 500KB (animated), 100KB (static)
+            cls.VIDEO: 16 * 1024 * 1024,  # 16MB
+        }
+        return MAX_SIZES[media_type]
+
+
+class MediaMessage(BaseModel):
+    """Base media message schema for media operations.
+
+    Common fields for all media message types based on existing
+    send_media() method signature from handle_media.py.
+    """
+
+    recipient: str = Field(
+        ..., min_length=1, description="Recipient phone number or user identifier"
+    )
+    media_type: MediaType = Field(
+        ..., description="Type of media (audio, document, image, sticker, video)"
+    )
+    media_source: str | Path = Field(
+        ..., description="Either a URL string or a Path object to the local media file"
+    )
+    caption: str | None = Field(
+        None,
+        max_length=1024,
+        description="Optional caption for the media (not supported for audio and sticker)",
+    )
+    filename: str | None = Field(
+        None, description="Optional filename (used for documents)"
+    )
+    reply_to_message_id: str | None = Field(
+        None, description="Optional message ID for replies"
+    )
+
+    @field_validator("caption")
+    @classmethod
+    def validate_caption_for_media_type(cls, v, info):
+        """Validate caption is not used for audio and sticker media types."""
+        if v is not None and info.data and "media_type" in info.data:
+            media_type = info.data["media_type"]
+            if media_type in (MediaType.AUDIO, MediaType.STICKER):
+                raise ValueError(
+                    f"Caption not supported for {media_type.value} media type"
+                )
+        return v
+
+    @field_validator("filename")
+    @classmethod
+    def validate_filename_for_documents(cls, v, info):
+        """Validate filename is provided for document media types when needed."""
+        if v is not None and info.data and "media_type" in info.data:
+            media_type = info.data["media_type"]
+            if media_type != MediaType.DOCUMENT:
+                raise ValueError(
+                    f"Filename only supported for document media type, not {media_type.value}"
+                )
+        return v
+
+
+class ImageMessage(MediaMessage):
+    """Image message schema for send_image operations.
+
+    Supports JPEG and PNG images up to 5MB.
+    Images must be 8-bit, RGB or RGBA (WhatsApp Cloud API 2025).
+    """
+
+    media_type: Literal[MediaType.IMAGE] = Field(default=MediaType.IMAGE)
+    caption: str | None = Field(
+        None, max_length=1024, description="Optional caption for the image"
+    )
+
+
+class VideoMessage(MediaMessage):
+    """Video message schema for send_video operations.
+
+    Supports MP4 and 3GP videos up to 16MB.
+    Only H.264 video codec and AAC audio codec supported.
+    Single audio stream or no audio stream only (WhatsApp Cloud API 2025).
+    """
+
+    media_type: Literal[MediaType.VIDEO] = Field(default=MediaType.VIDEO)
+    caption: str | None = Field(
+        None, max_length=1024, description="Optional caption for the video"
+    )
+
+
+class AudioMessage(MediaMessage):
+    """Audio message schema for send_audio operations.
+
+    Supports AAC, AMR, MP3, M4A, and OGG audio up to 16MB.
+    OGG must use OPUS codecs only, mono input only (WhatsApp Cloud API 2025).
+    """
+
+    media_type: Literal[MediaType.AUDIO] = Field(default=MediaType.AUDIO)
+    caption: Literal[None] = Field(
+        default=None, description="Caption not supported for audio"
+    )
+
+
+class DocumentMessage(MediaMessage):
+    """Document message schema for send_document operations.
+
+    Supports TXT, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX up to 100MB.
+    """
+
+    media_type: Literal[MediaType.DOCUMENT] = Field(default=MediaType.DOCUMENT)
+    filename: str | None = Field(None, description="Optional filename for the document")
+
+
+class StickerMessage(MediaMessage):
+    """Sticker message schema for send_sticker operations.
+
+    Supports WebP images only.
+    Static stickers: 100KB max, Animated stickers: 500KB max.
+    """
+
+    media_type: Literal[MediaType.STICKER] = Field(default=MediaType.STICKER)
+    caption: Literal[None] = Field(
+        default=None, description="Caption not supported for stickers"
+    )
+
+
+class MediaUploadRequest(BaseModel):
+    """Request schema for media upload operations.
+
+    Used for direct media upload endpoints.
+    """
+
+    media_type: str = Field(..., description="MIME type of the media file")
+    filename: str | None = Field(None, description="Original filename of the media")
+
+    @field_validator("media_type")
+    @classmethod
+    def validate_mime_type(cls, v):
+        """Validate MIME type is supported by WhatsApp."""
+        supported_types = set()
+        for media_type in MediaType:
+            supported_types.update(MediaType.get_supported_mime_types(media_type))
+
+        if v not in supported_types:
+            raise ValueError(
+                f"Unsupported MIME type: {v}. Supported types: {sorted(supported_types)}"
+            )
+        return v