wappa 0.1.0__py3-none-any.whl

wappa/webhooks/core/base_status.py

@@ -0,0 +1,322 @@
+"""
+Base status abstractions for platform-agnostic status handling.
+
+This module defines the abstract base classes for message status updates
+that provide consistent interfaces regardless of the messaging platform.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .types import MessageStatus, PlatformType, UniversalMessageData
+
+
+class BaseMessageStatus(BaseModel, ABC):
+    """
+    Platform-agnostic message status base class.
+
+    Represents delivery status updates for sent messages across all platforms.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Universal fields
+    processed_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When the status update was processed by our system",
+    )
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this status update came from."""
+        pass
+
+    @property
+    @abstractmethod
+    def message_id(self) -> str:
+        """Get the ID of the message this status refers to."""
+        pass
+
+    @property
+    @abstractmethod
+    def status(self) -> MessageStatus:
+        """Get the universal message status."""
+        pass
+
+    @property
+    @abstractmethod
+    def recipient_id(self) -> str:
+        """Get the recipient's universal identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def timestamp(self) -> int:
+        """Get the status timestamp as Unix timestamp."""
+        pass
+
+    @property
+    @abstractmethod
+    def conversation_id(self) -> str:
+        """Get the conversation/chat identifier."""
+        pass
+
+    @abstractmethod
+    def is_delivered(self) -> bool:
+        """Check if the message was delivered."""
+        pass
+
+    @abstractmethod
+    def is_read(self) -> bool:
+        """Check if the message was read."""
+        pass
+
+    @abstractmethod
+    def is_failed(self) -> bool:
+        """Check if the message delivery failed."""
+        pass
+
+    @abstractmethod
+    def get_error_info(self) -> dict[str, Any] | None:
+        """
+        Get error information if the message failed.
+
+        Returns:
+            Dictionary with error details, or None if no error.
+        """
+        pass
+
+    @abstractmethod
+    def get_delivery_info(self) -> dict[str, Any]:
+        """
+        Get detailed delivery information.
+
+        Returns:
+            Dictionary with platform-specific delivery details.
+        """
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> UniversalMessageData:
+        """
+        Convert to platform-agnostic dictionary representation.
+
+        Returns:
+            Dictionary with standardized status data structure.
+        """
+        pass
+
+    @abstractmethod
+    def get_platform_data(self) -> dict[str, Any]:
+        """
+        Get platform-specific data for advanced processing.
+
+        Returns:
+            Dictionary with platform-specific status fields.
+        """
+        pass
+
+    def get_status_summary(self) -> dict[str, Any]:
+        """
+        Get a summary of the status update for logging and analytics.
+
+        Returns:
+            Dictionary with key status information.
+        """
+        return {
+            "message_id": self.message_id,
+            "platform": self.platform.value,
+            "status": self.status.value,
+            "recipient_id": self.recipient_id,
+            "conversation_id": self.conversation_id,
+            "timestamp": self.timestamp,
+            "processed_at": self.processed_at.isoformat(),
+            "is_delivered": self.is_delivered(),
+            "is_read": self.is_read(),
+            "is_failed": self.is_failed(),
+        }
+
+    @classmethod
+    @abstractmethod
+    def from_platform_data(cls, data: dict[str, Any], **kwargs) -> "BaseMessageStatus":
+        """
+        Create status instance from platform-specific data.
+
+        Args:
+            data: Raw status data from platform webhook
+            **kwargs: Additional platform-specific parameters
+
+        Returns:
+            Validated status instance
+        """
+        pass
+
+
+class BaseConversationInfo(BaseModel, ABC):
+    """
+    Platform-agnostic conversation information base class.
+
+    Contains metadata about the conversation where the message was sent.
+    """
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    @property
+    @abstractmethod
+    def conversation_id(self) -> str:
+        """Get the conversation identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def conversation_type(self) -> str:
+        """Get the conversation type (business, personal, etc.)."""
+        pass
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this conversation belongs to."""
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass
+
+
+class BasePricingInfo(BaseModel, ABC):
+    """
+    Platform-agnostic pricing information base class.
+
+    Contains cost information for sent messages where applicable.
+    """
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    @property
+    @abstractmethod
+    def billable(self) -> bool:
+        """Check if this message was billable."""
+        pass
+
+    @property
+    @abstractmethod
+    def pricing_model(self) -> str:
+        """Get the pricing model used."""
+        pass
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this pricing belongs to."""
+        pass
+
+    @abstractmethod
+    def get_cost_info(self) -> dict[str, Any]:
+        """
+        Get detailed cost information.
+
+        Returns:
+            Dictionary with cost details (amount, currency, etc.).
+        """
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass
+
+
+class BaseStatusWebhook(BaseModel, ABC):
+    """
+    Platform-agnostic status webhook base class.
+
+    Represents a webhook specifically containing status updates.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Universal fields
+    received_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When the status webhook was received",
+    )
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this webhook came from."""
+        pass
+
+    @property
+    @abstractmethod
+    def business_id(self) -> str:
+        """Get the business/account identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def source_id(self) -> str:
+        """Get the webhook source identifier."""
+        pass
+
+    @abstractmethod
+    def get_raw_statuses(self) -> list[dict[str, Any]]:
+        """
+        Get raw status data for parsing.
+
+        Returns:
+            List of raw status dictionaries.
+        """
+        pass
+
+    @abstractmethod
+    def get_status_count(self) -> int:
+        """Get the number of status updates in this webhook."""
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass
+
+    def get_webhook_summary(self) -> dict[str, Any]:
+        """
+        Get a summary of the status webhook for logging.
+
+        Returns:
+            Dictionary with key webhook information.
+        """
+        return {
+            "platform": self.platform.value,
+            "business_id": self.business_id,
+            "source_id": self.source_id,
+            "received_at": self.received_at.isoformat(),
+            "status_count": self.get_status_count(),
+        }
+
+    @classmethod
+    @abstractmethod
+    def from_platform_payload(
+        cls, payload: dict[str, Any], **kwargs
+    ) -> "BaseStatusWebhook":
+        """
+        Create status webhook instance from platform-specific payload.
+
+        Args:
+            payload: Raw webhook payload from the platform
+            **kwargs: Additional platform-specific parameters
+
+        Returns:
+            Validated status webhook instance
+        """
+        pass

wappa/webhooks/core/base_webhook.py

@@ -0,0 +1,312 @@
+"""
+Base webhook abstraction for platform-agnostic webhook handling.
+
+This module defines the abstract base classes that all platform-specific
+webhook implementations must inherit from to ensure consistent interfaces.
+"""
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .types import PlatformType, WebhookType
+
+
+class BaseContact(BaseModel, ABC):
+    """
+    Platform-agnostic contact information base class.
+
+    All platform-specific contact models must inherit from this class
+    to provide a consistent interface for contact data.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    @property
+    @abstractmethod
+    def user_id(self) -> str:
+        """Get the universal user identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def display_name(self) -> str | None:
+        """Get the user's display name if available."""
+        pass
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this contact belongs to."""
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass
+
+
+class BaseWebhookMetadata(BaseModel, ABC):
+    """
+    Platform-agnostic webhook metadata base class.
+
+    Contains platform-specific metadata about the webhook source.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    @property
+    @abstractmethod
+    def business_id(self) -> str:
+        """Get the business/bot identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def webhook_source_id(self) -> str:
+        """Get the webhook source identifier (phone number, bot token, etc.)."""
+        pass
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform type."""
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass
+
+
+class BaseWebhook(BaseModel, ABC):
+    """
+    Platform-agnostic webhook base class.
+
+    All platform-specific webhook models must inherit from this class
+    to provide a consistent interface for webhook processing.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid", str_strip_whitespace=True, validate_assignment=True
+    )
+
+    # Universal fields that all webhooks should have
+    received_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When the webhook was received by our system",
+    )
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform type this webhook came from."""
+        pass
+
+    @property
+    @abstractmethod
+    def webhook_type(self) -> WebhookType:
+        """Get the type of webhook (messages, status updates, errors, etc.)."""
+        pass
+
+    @property
+    @abstractmethod
+    def business_id(self) -> str:
+        """Get the business/account identifier."""
+        pass
+
+    @property
+    @abstractmethod
+    def source_id(self) -> str:
+        """Get the webhook source identifier (phone number ID, bot token, etc.)."""
+        pass
+
+    @abstractmethod
+    def is_incoming_message(self) -> bool:
+        """Check if this webhook contains incoming messages."""
+        pass
+
+    @abstractmethod
+    def is_status_update(self) -> bool:
+        """Check if this webhook contains message status updates."""
+        pass
+
+    @abstractmethod
+    def has_errors(self) -> bool:
+        """Check if this webhook contains error information."""
+        pass
+
+    @abstractmethod
+    def get_raw_messages(self) -> list[dict[str, Any]]:
+        """
+        Get raw message data for parsing with platform-specific schemas.
+
+        Returns:
+            List of raw message dictionaries ready for platform-specific parsing.
+        """
+        pass
+
+    @abstractmethod
+    def get_raw_statuses(self) -> list[dict[str, Any]]:
+        """
+        Get raw status data for parsing with platform-specific schemas.
+
+        Returns:
+            List of raw status dictionaries ready for platform-specific parsing.
+        """
+        pass
+
+    @abstractmethod
+    def get_contacts(self) -> list[BaseContact]:
+        """
+        Get contact information from the webhook.
+
+        Returns:
+            List of contact objects with universal interface.
+        """
+        pass
+
+    @abstractmethod
+    def get_metadata(self) -> BaseWebhookMetadata:
+        """
+        Get webhook metadata with universal interface.
+
+        Returns:
+            Metadata object with platform-agnostic interface.
+        """
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """
+        Convert webhook to platform-agnostic dictionary representation.
+
+        This method should return a dictionary with standardized keys
+        that can be used across all platforms for logging, analytics, etc.
+
+        Returns:
+            Dictionary with universal webhook data structure.
+        """
+        pass
+
+    @abstractmethod
+    def get_processing_context(self) -> dict[str, Any]:
+        """
+        Get context information needed for message processing.
+
+        This includes tenant information, routing data, and other
+        metadata required for Symphony AI integration.
+
+        Returns:
+            Dictionary with processing context data.
+        """
+        pass
+
+    def get_webhook_id(self) -> str:
+        """
+        Generate a unique identifier for this webhook.
+
+        This can be used for deduplication, logging, and tracking.
+        """
+        import hashlib
+        import json
+
+        # Create deterministic ID based on platform, business_id, and timestamp
+        data = {
+            "platform": self.platform.value,
+            "business_id": self.business_id,
+            "source_id": self.source_id,
+            "received_at": self.received_at.isoformat(),
+            "webhook_type": self.webhook_type.value,
+        }
+
+        content = json.dumps(data, sort_keys=True)
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def get_summary(self) -> dict[str, Any]:
+        """
+        Get a summary of the webhook for logging and monitoring.
+
+        Returns:
+            Dictionary with key webhook information for structured logging.
+        """
+        return {
+            "webhook_id": self.get_webhook_id(),
+            "platform": self.platform.value,
+            "webhook_type": self.webhook_type.value,
+            "business_id": self.business_id,
+            "source_id": self.source_id,
+            "received_at": self.received_at.isoformat(),
+            "has_messages": self.is_incoming_message(),
+            "has_statuses": self.is_status_update(),
+            "has_errors": self.has_errors(),
+            "message_count": len(self.get_raw_messages()),
+            "status_count": len(self.get_raw_statuses()),
+            "contact_count": len(self.get_contacts()),
+        }
+
+    @classmethod
+    @abstractmethod
+    def from_platform_payload(cls, payload: dict[str, Any], **kwargs) -> "BaseWebhook":
+        """
+        Create webhook instance from platform-specific payload.
+
+        This factory method should handle platform-specific validation
+        and transformation of the raw webhook payload.
+
+        Args:
+            payload: Raw webhook payload from the platform
+            **kwargs: Additional platform-specific parameters
+
+        Returns:
+            Validated webhook instance
+
+        Raises:
+            ValidationError: If payload is invalid
+            PlatformError: If platform-specific validation fails
+        """
+        pass
+
+
+class BaseWebhookError(BaseModel, ABC):
+    """
+    Platform-agnostic webhook error base class.
+
+    Represents errors that occur during webhook processing.
+    """
+
+    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
+
+    @property
+    @abstractmethod
+    def error_code(self) -> str:
+        """Get the platform-specific error code."""
+        pass
+
+    @property
+    @abstractmethod
+    def error_message(self) -> str:
+        """Get the human-readable error message."""
+        pass
+
+    @property
+    @abstractmethod
+    def platform(self) -> PlatformType:
+        """Get the platform this error originated from."""
+        pass
+
+    @abstractmethod
+    def is_retryable(self) -> bool:
+        """Check if this error condition is retryable."""
+        pass
+
+    @abstractmethod
+    def to_universal_dict(self) -> dict[str, Any]:
+        """Convert to platform-agnostic dictionary representation."""
+        pass