wappa 0.1.0__py3-none-any.whl

wappa/webhooks/core/types.py

@@ -0,0 +1,253 @@
+"""
+Unified data types and enums for cross-platform messaging compatibility.
+
+This module defines the common types used across all messaging platforms
+to ensure consistent data handling regardless of the underlying platform.
+"""
+
+from enum import Enum
+from typing import Any
+
+
+class PlatformType(str, Enum):
+    """Supported messaging platforms in the Mimeia platform."""
+
+    WHATSAPP = "whatsapp"
+    TELEGRAM = "telegram"
+    TEAMS = "teams"
+    INSTAGRAM = "instagram"
+
+
+class MessageType(str, Enum):
+    """Universal message types across all platforms."""
+
+    TEXT = "text"
+    INTERACTIVE = "interactive"
+    BUTTON = "button"  # Button reply messages (WhatsApp quick reply buttons)
+    IMAGE = "image"
+    AUDIO = "audio"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    CONTACT = "contact"
+    LOCATION = "location"
+    ORDER = "order"  # Order/catalog messages
+    STICKER = "sticker"
+    REACTION = "reaction"
+    SYSTEM = "system"  # System notifications, member joins, etc.
+    UNSUPPORTED = "unsupported"  # Unsupported message types
+
+
+class WebhookType(str, Enum):
+    """Types of webhook events that platforms can send."""
+
+    INCOMING_MESSAGES = "incoming_messages"
+    STATUS_UPDATES = "status_updates"
+    ERRORS = "errors"
+    MEMBER_UPDATES = "member_updates"  # For group/channel management
+    SYSTEM_EVENTS = "system_events"
+
+
+class MessageStatus(str, Enum):
+    """Universal message delivery status across platforms."""
+
+    SENT = "sent"
+    DELIVERED = "delivered"
+    READ = "read"
+    FAILED = "failed"
+    DELETED = "deleted"
+    PENDING = "pending"
+
+
+class InteractiveType(str, Enum):
+    """Types of interactive elements across platforms."""
+
+    BUTTON_REPLY = "button_reply"
+    LIST_REPLY = "list_reply"
+    QUICK_REPLY = "quick_reply"
+    INLINE_KEYBOARD = "inline_keyboard"  # Telegram inline keyboards
+    CAROUSEL = "carousel"
+    MENU = "menu"
+
+
+class MediaType(str, Enum):
+    """Media content types with MIME type mapping."""
+
+    IMAGE_JPEG = "image/jpeg"
+    IMAGE_PNG = "image/png"
+    IMAGE_GIF = "image/gif"
+    IMAGE_WEBP = "image/webp"
+
+    AUDIO_AAC = "audio/aac"
+    AUDIO_MP3 = "audio/mp3"
+    AUDIO_OGG = "audio/ogg"
+    AUDIO_WAV = "audio/wav"
+
+    VIDEO_MP4 = "video/mp4"
+    VIDEO_AVI = "video/avi"
+    VIDEO_MOV = "video/mov"
+    VIDEO_WEBM = "video/webm"
+
+    DOCUMENT_PDF = "application/pdf"
+    DOCUMENT_DOC = "application/msword"
+    DOCUMENT_DOCX = (
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+    )
+    DOCUMENT_TXT = "text/plain"
+    DOCUMENT_CSV = "text/csv"
+
+
+class ConversationType(str, Enum):
+    """Types of conversations across platforms."""
+
+    PRIVATE = "private"  # 1-on-1 conversation
+    GROUP = "group"  # Group chat
+    CHANNEL = "channel"  # Broadcast channel
+    BUSINESS = "business"  # Business conversation (WhatsApp Business)
+
+
+class UserRole(str, Enum):
+    """User roles in conversations."""
+
+    MEMBER = "member"
+    ADMIN = "admin"
+    OWNER = "owner"
+    MODERATOR = "moderator"
+    BOT = "bot"
+
+
+# Type aliases for complex types
+PlatformData = dict[str, Any]
+MessageMetadata = dict[str, Any]
+UniversalMessageData = dict[str, str | int | bool | None | dict | list]
+
+
+class ErrorCode(str, Enum):
+    """Universal error codes for webhook processing."""
+
+    VALIDATION_ERROR = "validation_error"
+    AUTHENTICATION_ERROR = "authentication_error"
+    RATE_LIMIT_ERROR = "rate_limit_error"
+    PLATFORM_ERROR = "platform_error"
+    NETWORK_ERROR = "network_error"
+    PROCESSING_ERROR = "processing_error"
+    UNKNOWN_MESSAGE_TYPE = "unknown_message_type"
+    SIGNATURE_VALIDATION_FAILED = "signature_validation_failed"
+
+
+class ProcessingPriority(str, Enum):
+    """Priority levels for message processing."""
+
+    LOW = "low"
+    NORMAL = "normal"
+    HIGH = "high"
+    URGENT = "urgent"
+
+
+# Platform capability mapping
+PLATFORM_CAPABILITIES = {
+    PlatformType.WHATSAPP: {
+        "message_types": {
+            MessageType.TEXT,
+            MessageType.INTERACTIVE,
+            MessageType.BUTTON,
+            MessageType.IMAGE,
+            MessageType.AUDIO,
+            MessageType.VIDEO,
+            MessageType.DOCUMENT,
+            MessageType.CONTACT,
+            MessageType.LOCATION,
+            MessageType.ORDER,
+            MessageType.STICKER,
+            MessageType.REACTION,
+            MessageType.SYSTEM,
+            MessageType.UNSUPPORTED,
+        },
+        "interactive_types": {InteractiveType.BUTTON_REPLY, InteractiveType.LIST_REPLY},
+        "max_text_length": 4096,
+        "max_media_size": 16 * 1024 * 1024,  # 16MB
+        "supports_threads": False,
+        "supports_reactions": True,
+        "supports_editing": False,
+    },
+    PlatformType.TELEGRAM: {
+        "message_types": {
+            MessageType.TEXT,
+            MessageType.INTERACTIVE,
+            MessageType.IMAGE,
+            MessageType.AUDIO,
+            MessageType.VIDEO,
+            MessageType.DOCUMENT,
+            MessageType.CONTACT,
+            MessageType.LOCATION,
+            MessageType.STICKER,
+        },
+        "interactive_types": {
+            InteractiveType.INLINE_KEYBOARD,
+            InteractiveType.QUICK_REPLY,
+        },
+        "max_text_length": 4096,
+        "max_media_size": 50 * 1024 * 1024,  # 50MB
+        "supports_threads": True,
+        "supports_reactions": True,
+        "supports_editing": True,
+    },
+    PlatformType.TEAMS: {
+        "message_types": {MessageType.TEXT, MessageType.IMAGE, MessageType.DOCUMENT},
+        "interactive_types": {InteractiveType.BUTTON_REPLY, InteractiveType.CAROUSEL},
+        "max_text_length": 28000,
+        "max_media_size": 100 * 1024 * 1024,  # 100MB
+        "supports_threads": True,
+        "supports_reactions": True,
+        "supports_editing": True,
+    },
+    PlatformType.INSTAGRAM: {
+        "message_types": {
+            MessageType.TEXT,
+            MessageType.IMAGE,
+            MessageType.VIDEO,
+            MessageType.STICKER,
+        },
+        "interactive_types": {
+            InteractiveType.QUICK_REPLY,
+            InteractiveType.BUTTON_REPLY,
+        },
+        "max_text_length": 1000,
+        "max_media_size": 8 * 1024 * 1024,  # 8MB
+        "supports_threads": False,
+        "supports_reactions": True,
+        "supports_editing": False,
+    },
+}
+
+
+def get_platform_capabilities(platform: PlatformType) -> dict[str, Any]:
+    """Get capabilities for a specific platform."""
+    return PLATFORM_CAPABILITIES.get(platform, {})
+
+
+def is_message_type_supported(
+    platform: PlatformType, message_type: MessageType
+) -> bool:
+    """Check if a message type is supported by a platform."""
+    capabilities = get_platform_capabilities(platform)
+    return message_type in capabilities.get("message_types", set())
+
+
+def is_interactive_type_supported(
+    platform: PlatformType, interactive_type: InteractiveType
+) -> bool:
+    """Check if an interactive type is supported by a platform."""
+    capabilities = get_platform_capabilities(platform)
+    return interactive_type in capabilities.get("interactive_types", set())
+
+
+def get_max_text_length(platform: PlatformType) -> int:
+    """Get maximum text length for a platform."""
+    capabilities = get_platform_capabilities(platform)
+    return capabilities.get("max_text_length", 4096)
+
+
+def get_max_media_size(platform: PlatformType) -> int:
+    """Get maximum media file size for a platform."""
+    capabilities = get_platform_capabilities(platform)
+    return capabilities.get("max_media_size", 16 * 1024 * 1024)

wappa/webhooks/core/webhook_interfaces/__init__.py

@@ -0,0 +1,48 @@
+"""
+Universal Webhook Interface system for platform-agnostic webhook handling.
+
+This module provides universal webhook interfaces that all messaging platforms
+must adapt to, using WhatsApp as the comprehensive template. The system uses
+3 universal webhook types that work across all platforms:
+
+1. IncomingMessageWebhook - All incoming messages from users
+2. StatusWebhook - Message delivery status updates (includes "outgoing" status)
+3. ErrorWebhook - System, app, and account-level errors
+
+Note: "Outgoing message" webhooks are actually status updates that use StatusWebhook.
+
+All platforms (WhatsApp, Teams, Telegram, Instagram) must transform their
+platform-specific webhooks into these universal interfaces via processor adapters.
+"""
+
+from .base_components import (
+    AdReferralBase,
+    BusinessContextBase,
+    ConversationBase,
+    ErrorDetailBase,
+    ForwardContextBase,
+    TenantBase,
+    UserBase,
+)
+from .universal_webhooks import (
+    ErrorWebhook,
+    IncomingMessageWebhook,
+    StatusWebhook,
+    UniversalWebhook,
+)
+
+__all__ = [
+    # Base components
+    "TenantBase",
+    "UserBase",
+    "BusinessContextBase",
+    "ForwardContextBase",
+    "AdReferralBase",
+    "ConversationBase",
+    "ErrorDetailBase",
+    # Universal webhook interfaces
+    "IncomingMessageWebhook",
+    "StatusWebhook",
+    "ErrorWebhook",
+    "UniversalWebhook",
+]

wappa/webhooks/core/webhook_interfaces/base_components.py

@@ -0,0 +1,293 @@
+"""
+Universal base components for platform-agnostic webhook interfaces.
+
+These components provide the building blocks for all universal webhook types.
+They are designed based on WhatsApp's comprehensive webhook structure and
+represent the "standard" that all messaging platforms should adapt to.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TenantBase(BaseModel):
+    """
+    Universal business/tenant identification component.
+
+    Represents the business account that messages are sent to/from.
+    Based on WhatsApp's metadata structure but platform-agnostic.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Core tenant identification
+    business_phone_number_id: str = Field(description="Unique business phone number ID")
+    display_phone_number: str = Field(description="Business display phone number")
+
+    # Platform-specific tenant ID (WhatsApp Business Account ID, Teams tenant ID, etc.)
+    platform_tenant_id: str = Field(description="Platform-specific tenant identifier")
+
+    def get_tenant_key(self) -> str:
+        """Get unique tenant key for this business account."""
+        # For WhatsApp, the business_phone_number_id IS the tenant identifier
+        # For other platforms, they might use platform_tenant_id, but for consistency
+        # we use business_phone_number_id as the primary tenant key
+        return self.business_phone_number_id
+
+
+class UserBase(BaseModel):
+    """
+    Universal user/contact identification component.
+
+    Represents the end user sending messages to the business.
+    Based on WhatsApp's contact structure but platform-agnostic.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Core user identification
+    user_id: str = Field(
+        description="Platform-specific user ID (WhatsApp wa_id, Teams user ID, etc.)"
+    )
+    phone_number: str = Field(description="User's phone number")
+
+    # User profile information
+    profile_name: str | None = Field(default=None, description="User's display name")
+
+    # Security and identity
+    identity_key_hash: str | None = Field(
+        default=None,
+        description="Identity key hash for security validation (WhatsApp feature)",
+    )
+
+    def get_display_name(self) -> str:
+        """Get user's display name or fallback to phone number."""
+        return self.profile_name or self.phone_number
+
+    def get_user_key(self) -> str:
+        """Get unique user key for this contact."""
+        return f"{self.user_id}:{self.phone_number}"
+
+
+class BusinessContextBase(BaseModel):
+    """
+    Universal business interaction context component.
+
+    Represents context when users interact with business features like
+    product catalogs, business buttons, etc. Based on WhatsApp's business
+    features but designed to be universal.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Business message context
+    contextual_message_id: str = Field(
+        description="ID of the business message that triggered this interaction"
+    )
+    business_phone_number: str = Field(description="Business phone number from context")
+
+    # Product catalog context (for e-commerce interactions)
+    catalog_id: str | None = Field(default=None, description="Product catalog ID")
+    product_retailer_id: str | None = Field(
+        default=None, description="Product ID from catalog"
+    )
+
+    def has_product_context(self) -> bool:
+        """Check if this interaction involves a product catalog."""
+        return self.catalog_id is not None and self.product_retailer_id is not None
+
+
+class ForwardContextBase(BaseModel):
+    """
+    Universal message forwarding context component.
+
+    Represents information about forwarded messages. Based on WhatsApp's
+    forwarding detection but designed to be universal.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Forwarding indicators
+    is_forwarded: bool = Field(
+        default=False, description="Whether the message was forwarded"
+    )
+    is_frequently_forwarded: bool = Field(
+        default=False,
+        description="Whether the message has been forwarded multiple times (>5)",
+    )
+
+    # Optional forwarding metadata
+    forward_count: int | None = Field(
+        default=None, description="Number of times forwarded (if known)"
+    )
+    original_sender: str | None = Field(
+        default=None, description="Original sender ID (if available)"
+    )
+
+
+class AdReferralBase(BaseModel):
+    """
+    Universal advertisement referral context component.
+
+    Represents information when users interact via advertisements.
+    Based on WhatsApp's Click-to-WhatsApp ads but designed to be universal
+    for all advertising platforms.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Core ad identification
+    source_type: str = Field(
+        description="Type of ad source (e.g., 'ad', 'social', 'search')"
+    )
+    source_id: str = Field(description="Advertisement ID")
+    source_url: str = Field(description="Advertisement URL")
+
+    # Ad content
+    ad_body: str | None = Field(default=None, description="Advertisement primary text")
+    ad_headline: str | None = Field(default=None, description="Advertisement headline")
+
+    # Media content
+    media_type: str | None = Field(
+        default=None, description="Ad media type (image, video)"
+    )
+    image_url: str | None = Field(default=None, description="Ad image URL")
+    video_url: str | None = Field(default=None, description="Ad video URL")
+    thumbnail_url: str | None = Field(
+        default=None, description="Ad video thumbnail URL"
+    )
+
+    # Tracking and attribution
+    click_id: str | None = Field(default=None, description="Click tracking ID")
+
+    # Welcome message (for chat ads)
+    welcome_message_text: str | None = Field(
+        default=None, description="Predefined welcome message from the ad"
+    )
+
+    def has_media(self) -> bool:
+        """Check if this ad referral includes media content."""
+        return self.image_url is not None or self.video_url is not None
+
+    def is_video_ad(self) -> bool:
+        """Check if this is a video advertisement."""
+        return self.media_type == "video" and self.video_url is not None
+
+
+class ConversationBase(BaseModel):
+    """
+    Universal conversation and billing context component.
+
+    Represents conversation state and billing information. Based on WhatsApp's
+    conversation-based pricing but designed to be universal for all platforms
+    that may implement conversation tracking.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Conversation identification
+    conversation_id: str = Field(description="Unique conversation identifier")
+    expiration_timestamp: datetime | None = Field(
+        default=None, description="When this conversation window expires"
+    )
+
+    # Conversation categorization
+    category: str | None = Field(
+        default=None,
+        description="Conversation category (service, marketing, authentication, etc.)",
+    )
+    origin_type: str | None = Field(
+        default=None,
+        description="How this conversation was initiated (user, business, service, etc.)",
+    )
+
+    # Billing information
+    is_billable: bool | None = Field(
+        default=None, description="Whether this conversation is billable"
+    )
+    pricing_model: str | None = Field(
+        default=None,
+        description="Pricing model (CBP=conversation-based, PMP=per-message)",
+    )
+    pricing_category: str | None = Field(
+        default=None,
+        description="Pricing category/rate (service, marketing, authentication, etc.)",
+    )
+    pricing_type: str | None = Field(
+        default=None,
+        description="Pricing type (regular, free_customer_service, free_entry_point)",
+    )
+
+    def is_free_conversation(self) -> bool:
+        """Check if this conversation is free (not billable)."""
+        return self.is_billable is False or self.pricing_type in [
+            "free_customer_service",
+            "free_entry_point",
+        ]
+
+    def is_expired(self) -> bool:
+        """Check if this conversation has expired."""
+        if self.expiration_timestamp is None:
+            return False
+        return datetime.utcnow() > self.expiration_timestamp
+
+
+class ErrorDetailBase(BaseModel):
+    """
+    Universal error detail component.
+
+    Represents structured error information from messaging platforms.
+    Based on WhatsApp's error structure but designed to be universal.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Core error identification
+    error_code: int = Field(description="Numeric error code")
+    error_title: str = Field(description="Human-readable error title")
+    error_message: str = Field(description="Detailed error message")
+
+    # Additional error context
+    error_details: str | None = Field(
+        default=None, description="Extended error details"
+    )
+    documentation_url: str | None = Field(
+        default=None, description="URL to error code documentation"
+    )
+
+    # Error categorization
+    error_type: str | None = Field(
+        default=None, description="Type of error (system, validation, rate_limit, etc.)"
+    )
+    is_retryable: bool | None = Field(
+        default=None, description="Whether this error condition can be retried"
+    )
+
+    # Timestamp
+    occurred_at: datetime | None = Field(
+        default=None, description="When this error occurred"
+    )
+
+    def is_temporary_error(self) -> bool:
+        """Check if this is likely a temporary error that could be retried."""
+        temporary_codes = [429, 500, 502, 503, 504]  # Rate limits and server errors
+        return self.error_code in temporary_codes or self.is_retryable is True
+
+    def get_error_summary(self) -> str:
+        """Get a concise error summary for logging."""
+        return f"Error {self.error_code}: {self.error_title}"