marqetive-lib 0.1.0__py3-none-any.whl

marqetive/platforms/twitter/exceptions.py

@@ -0,0 +1,311 @@
+"""Twitter-specific exception handling and error code mapping.
+
+This module provides comprehensive error handling for Twitter API errors including:
+- HTTP status code mapping
+- Twitter-specific error codes
+- Retry strategies
+- User-friendly error messages
+"""
+
+from typing import Any
+
+from marqetive.platforms.exceptions import (
+    MediaUploadError,
+    PlatformAuthError,
+    PlatformError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+# Twitter API error codes
+# Source: https://developer.x.com/en/support/twitter-api/error-troubleshooting
+class TwitterErrorCode:
+    """Twitter API error codes."""
+
+    # Authentication errors (200-299)
+    COULD_NOT_AUTHENTICATE = 32
+    INVALID_OR_EXPIRED_TOKEN = 89
+    UNABLE_TO_VERIFY_CREDENTIALS = 99
+    BAD_AUTHENTICATION_DATA = 215
+
+    # Authorization errors (300-399)
+    FORBIDDEN = 64
+    ACCOUNT_SUSPENDED = 63
+    API_ACCESS_REVOKED = 87
+
+    # Resource errors (400-499)
+    PAGE_NOT_EXIST = 34
+    USER_NOT_FOUND = 17
+    TWEET_NOT_FOUND = 144
+    NO_STATUS_FOUND = 34
+
+    # Rate limiting (500-599)
+    RATE_LIMIT_EXCEEDED = 88
+    TOO_MANY_REQUESTS = 429
+
+    # Validation errors (600-699)
+    STATUS_TOO_LONG = 186
+    DUPLICATE_STATUS = 187
+    INVALID_MEDIA = 324
+    MEDIA_ID_NOT_FOUND = 325
+
+    # Media upload errors
+    MEDIA_TYPE_UNSUPPORTED = 323
+    MEDIA_SIZE_TOO_LARGE = 324
+    VIDEO_DURATION_TOO_LONG = 324
+    MEDIA_PROCESSING_FAILED = 324
+
+
+# Mapping of error codes to user-friendly messages
+ERROR_MESSAGES: dict[int, str] = {
+    # Authentication
+    32: "Could not authenticate. Please check your API credentials.",
+    89: "Invalid or expired access token. Please re-authenticate.",
+    99: "Unable to verify your credentials. Please check your API keys.",
+    215: "Bad authentication data. Please verify your OAuth credentials.",
+    # Authorization
+    64: "Your account is not authorized to access this resource.",
+    63: "Your account is suspended and cannot be accessed.",
+    87: "API access has been revoked for this application.",
+    # Resources
+    34: "The requested page or resource does not exist.",
+    17: "User not found.",
+    144: "Tweet not found.",
+    # Rate limiting
+    88: "Rate limit exceeded. Please wait before making more requests.",
+    429: "Too many requests. You have hit a rate limit.",
+    # Validation
+    186: "Tweet is too long. Maximum length is 280 characters.",
+    187: "Duplicate tweet. You've already posted this content.",
+    324: "Invalid media for upload.",
+    325: "Media ID not found.",
+    323: "Media type not supported.",
+}
+
+
+# Retryable error codes
+RETRYABLE_ERROR_CODES = {
+    88,  # Rate limit exceeded
+    130,  # Over capacity
+    131,  # Internal error
+    429,  # Too many requests
+    500,  # Internal server error
+    502,  # Bad gateway
+    503,  # Service unavailable
+    504,  # Gateway timeout
+}
+
+# Non-retryable error codes
+NON_RETRYABLE_ERROR_CODES = {
+    32,  # Authentication failed
+    89,  # Invalid token
+    99,  # Unable to verify credentials
+    64,  # Forbidden
+    63,  # Account suspended
+    186,  # Status too long
+    187,  # Duplicate status
+    144,  # Tweet not found
+}
+
+
+def map_twitter_error(
+    status_code: int | None,
+    error_code: int | None = None,
+    error_message: str | None = None,
+    response_data: dict[str, Any] | None = None,
+) -> PlatformError:
+    """Map Twitter API error to appropriate exception.
+
+    Args:
+        status_code: HTTP status code.
+        error_code: Twitter-specific error code.
+        error_message: Error message from API.
+        response_data: Full response data from API.
+
+    Returns:
+        Appropriate PlatformError subclass.
+
+    Example:
+        >>> error = map_twitter_error(401, 32, "Could not authenticate")
+        >>> print(type(error).__name__)
+        PlatformAuthError
+    """
+    # Extract error details from response if provided
+    if response_data and "errors" in response_data:
+        errors = response_data["errors"]
+        if errors and isinstance(errors, list):
+            first_error = errors[0]
+            if not error_code:
+                error_code = first_error.get("code")
+            if not error_message:
+                error_message = first_error.get("message")
+
+    # Get user-friendly message
+    friendly_message = ERROR_MESSAGES.get(
+        error_code or 0, error_message or "Unknown error"
+    )
+
+    # Determine retry-after for rate limits
+    retry_after = None
+    if status_code == 429:
+        # Twitter typically uses 15-minute windows
+        retry_after = 900  # 15 minutes in seconds
+
+    # Map to appropriate exception type
+    # Authentication errors
+    if error_code in (32, 89, 99, 215) or status_code in (401, 403):
+        return PlatformAuthError(
+            friendly_message,
+            platform="twitter",
+            status_code=status_code,
+        )
+
+    # Rate limit errors
+    if error_code in (88, 429) or status_code == 429:
+        return RateLimitError(
+            friendly_message,
+            platform="twitter",
+            status_code=status_code or 429,
+            retry_after=retry_after,
+        )
+
+    # Validation errors
+    if error_code in (186, 187, 324, 325, 323):
+        return ValidationError(
+            friendly_message,
+            platform="twitter",
+        )
+
+    # Media upload errors
+    if error_code in (323, 324, 325):
+        return MediaUploadError(
+            friendly_message,
+            platform="twitter",
+            status_code=status_code,
+        )
+
+    # Generic platform error
+    return PlatformError(
+        friendly_message,
+        platform="twitter",
+        status_code=status_code,
+    )
+
+
+def is_retryable_twitter_error(
+    status_code: int | None,
+    error_code: int | None = None,
+) -> bool:
+    """Determine if a Twitter error is retryable.
+
+    Args:
+        status_code: HTTP status code.
+        error_code: Twitter-specific error code.
+
+    Returns:
+        True if error is retryable, False otherwise.
+
+    Example:
+        >>> is_retryable_twitter_error(503)
+        True
+        >>> is_retryable_twitter_error(401, 32)
+        False
+    """
+    # Check explicit non-retryable codes first
+    if error_code in NON_RETRYABLE_ERROR_CODES:
+        return False
+
+    # Check retryable codes
+    if error_code in RETRYABLE_ERROR_CODES:
+        return True
+
+    # Check HTTP status codes
+    if status_code:
+        # 5xx errors are generally retryable
+        if 500 <= status_code < 600:
+            return True
+        # 429 is retryable
+        if status_code == 429:
+            return True
+        # 4xx errors (except 429) are generally not retryable
+        if 400 <= status_code < 500:
+            return False
+
+    # Default to not retryable for safety
+    return False
+
+
+def get_retry_delay(
+    status_code: int | None,
+    error_code: int | None = None,
+    attempt: int = 1,
+) -> float:
+    """Get recommended retry delay for Twitter error.
+
+    Args:
+        status_code: HTTP status code.
+        error_code: Twitter-specific error code.
+        attempt: Current retry attempt number.
+
+    Returns:
+        Recommended delay in seconds.
+
+    Example:
+        >>> get_retry_delay(503, attempt=1)
+        5.0
+        >>> get_retry_delay(429)
+        900.0
+    """
+    # Rate limit errors - wait full window
+    if error_code in (88, 429) or status_code == 429:
+        return 900.0  # 15 minutes
+
+    # Server errors - exponential backoff
+    if status_code and 500 <= status_code < 600:
+        base_delay = 5.0
+        return min(base_delay * (2 ** (attempt - 1)), 60.0)
+
+    # Default delay
+    return 5.0
+
+
+class TwitterAPIError(PlatformError):
+    """Twitter API specific error with detailed information.
+
+    Attributes:
+        error_code: Twitter-specific error code.
+        is_retryable: Whether the error is retryable.
+        retry_delay: Recommended retry delay in seconds.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: int | None = None,
+        response_data: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize Twitter API error.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code.
+            error_code: Twitter-specific error code.
+            response_data: Full response data from API.
+        """
+        super().__init__(message, platform="twitter", status_code=status_code)
+        self.error_code = error_code
+        self.response_data = response_data
+        self.is_retryable = is_retryable_twitter_error(status_code, error_code)
+        self.retry_delay = get_retry_delay(status_code, error_code)
+
+    def __repr__(self) -> str:
+        """String representation of error."""
+        return (
+            f"TwitterAPIError(message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"error_code={self.error_code}, "
+            f"retryable={self.is_retryable})"
+        )

marqetive/platforms/twitter/factory.py

@@ -0,0 +1,151 @@
+"""Twitter account factory for managing credentials and client creation."""
+
+import logging
+import os
+from collections.abc import Callable
+
+from marqetive.core.account_factory import BaseAccountFactory
+from marqetive.platforms.exceptions import PlatformAuthError
+from marqetive.platforms.models import AccountStatus, AuthCredentials
+from marqetive.platforms.twitter.client import TwitterClient
+from marqetive.utils.oauth import refresh_twitter_token
+
+logger = logging.getLogger(__name__)
+
+
+class TwitterAccountFactory(BaseAccountFactory):
+    """Factory for creating and managing Twitter/X accounts and clients.
+
+    Example:
+        >>> factory = TwitterAccountFactory(
+        ...     client_id="your_client_id",
+        ...     client_secret="your_client_secret"
+        ... )
+        >>> credentials = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     refresh_token="refresh"
+        ... )
+        >>> client = await factory.create_authenticated_client(credentials)
+        >>> async with client:
+        ...     tweet = await client.create_post(request)
+    """
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        on_status_update: Callable[[str, AccountStatus], None] | None = None,
+    ) -> None:
+        """Initialize Twitter account factory.
+
+        Args:
+            client_id: Twitter OAuth client ID (uses TWITTER_CLIENT_ID env if None).
+            client_secret: Twitter OAuth client secret (uses TWITTER_CLIENT_SECRET env if None).
+            on_status_update: Optional callback when account status changes.
+        """
+        super().__init__(on_status_update=on_status_update)
+        self.client_id = client_id or os.getenv("TWITTER_CLIENT_ID")
+        self.client_secret = client_secret or os.getenv("TWITTER_CLIENT_SECRET")
+
+        if not self.client_id or not self.client_secret:
+            logger.warning(
+                "Twitter client_id/client_secret not provided. "
+                "Token refresh will not work."
+            )
+
+    @property
+    def platform_name(self) -> str:
+        """Get platform name."""
+        return "twitter"
+
+    async def refresh_token(self, credentials: AuthCredentials) -> AuthCredentials:
+        """Refresh Twitter OAuth2 access token.
+
+        Args:
+            credentials: Current credentials with refresh token.
+
+        Returns:
+            Updated credentials with new access token.
+
+        Raises:
+            PlatformAuthError: If refresh fails or credentials missing.
+        """
+        if not self.client_id or not self.client_secret:
+            raise PlatformAuthError(
+                "Twitter client_id and client_secret are required for token refresh",
+                platform=self.platform_name,
+            )
+
+        if not credentials.refresh_token:
+            raise PlatformAuthError(
+                "No refresh token available",
+                platform=self.platform_name,
+            )
+
+        logger.info("Refreshing Twitter access token...")
+        return await refresh_twitter_token(
+            credentials,
+            self.client_id,
+            self.client_secret,
+        )
+
+    async def create_client(self, credentials: AuthCredentials) -> TwitterClient:
+        """Create Twitter API client.
+
+        Args:
+            credentials: Valid Twitter credentials.
+
+        Returns:
+            TwitterClient instance.
+
+        Raises:
+            PlatformAuthError: If credentials are invalid.
+        """
+        if not credentials.access_token:
+            raise PlatformAuthError(
+                "Access token is required",
+                platform=self.platform_name,
+            )
+
+        # Get additional data for Twitter
+        additional_data = credentials.additional_data or {}
+
+        # Twitter needs API key/secret for some operations
+        api_key = additional_data.get("api_key") or os.getenv("TWITTER_API_KEY")
+        api_secret = additional_data.get("api_secret") or os.getenv(
+            "TWITTER_API_SECRET"
+        )
+        additional_data.get("access_secret")
+
+        # Update additional_data if we have env values
+        if api_key:
+            additional_data["api_key"] = api_key
+        if api_secret:
+            additional_data["api_secret"] = api_secret
+
+        credentials.additional_data = additional_data
+
+        return TwitterClient(credentials=credentials)
+
+    async def validate_credentials(self, credentials: AuthCredentials) -> bool:
+        """Validate Twitter credentials by making a test API call.
+
+        Args:
+            credentials: Credentials to validate.
+
+        Returns:
+            True if credentials are valid, False otherwise.
+        """
+        try:
+            client = await self.create_client(credentials)
+            async with client:
+                # Try to verify credentials by getting current user
+                # This is a lightweight call to test authentication
+                if client._tweepy_client:
+                    me = client._tweepy_client.get_me()
+                    return me is not None
+                return False
+        except Exception as e:
+            logger.error(f"Error validating Twitter credentials: {e}")
+            return False

marqetive/platforms/twitter/manager.py

@@ -0,0 +1,121 @@
+"""Twitter post manager for handling post operations."""
+
+import logging
+from typing import Any
+
+from marqetive.core.base_manager import BasePostManager
+from marqetive.platforms.models import AuthCredentials, Post, PostCreateRequest
+from marqetive.platforms.twitter.client import TwitterClient
+from marqetive.platforms.twitter.factory import TwitterAccountFactory
+
+logger = logging.getLogger(__name__)
+
+
+class TwitterPostManager(BasePostManager):
+    """Manager for Twitter/X post operations.
+
+    Coordinates post creation, media uploads, and progress tracking for Twitter.
+
+    Example:
+        >>> manager = TwitterPostManager()
+        >>> credentials = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     refresh_token="refresh"
+        ... )
+        >>> request = PostCreateRequest(content="Hello Twitter!")
+        >>> post = await manager.execute_post(credentials, request)
+        >>> print(f"Tweet ID: {post.post_id}")
+    """
+
+    def __init__(
+        self,
+        account_factory: TwitterAccountFactory | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+    ) -> None:
+        """Initialize Twitter post manager.
+
+        Args:
+            account_factory: Twitter account factory (creates default if None).
+            client_id: Twitter OAuth client ID (for default factory).
+            client_secret: Twitter OAuth client secret (for default factory).
+        """
+        if account_factory is None:
+            account_factory = TwitterAccountFactory(
+                client_id=client_id,
+                client_secret=client_secret,
+            )
+
+        super().__init__(account_factory=account_factory)
+
+    @property
+    def platform_name(self) -> str:
+        """Get platform name."""
+        return "twitter"
+
+    async def _execute_post_impl(
+        self,
+        client: Any,
+        request: PostCreateRequest,
+        credentials: AuthCredentials,  # noqa: ARG002
+    ) -> Post:
+        """Execute Twitter post creation.
+
+        Args:
+            client: TwitterClient instance.
+            request: Post creation request.
+            credentials: Twitter credentials.
+
+        Returns:
+            Created Post object.
+        """
+        if not isinstance(client, TwitterClient):
+            raise TypeError(f"Expected TwitterClient, got {type(client)}")
+
+        # Handle media uploads with progress tracking
+        media_ids: list[str] = []
+        if request.media_urls:
+            self._progress_tracker.emit_start(
+                "upload_media",
+                total=len(request.media_urls),
+                message=f"Uploading {len(request.media_urls)} media files...",
+            )
+
+            for idx, media_url in enumerate(request.media_urls):
+                if self.is_cancelled():
+                    raise InterruptedError("Post creation was cancelled")
+
+                self._progress_tracker.emit_progress(
+                    "upload_media",
+                    progress=idx,
+                    total=len(request.media_urls),
+                    message=f"Uploading media {idx + 1}/{len(request.media_urls)}...",
+                )
+
+                # Twitter media upload is simplified in the client
+                # In production, this would use tweepy's media upload
+                media_attachment = await client.upload_media(
+                    media_url=media_url,
+                    media_type="image",  # Default to image
+                    alt_text=None,
+                )
+                media_ids.append(media_attachment.media_id)
+
+            self._progress_tracker.emit_complete(
+                "upload_media",
+                message="All media uploaded successfully",
+            )
+
+        # Create post with progress tracking
+        self._progress_tracker.emit_progress(
+            "execute_post",
+            progress=50,
+            total=100,
+            message="Creating tweet...",
+        )
+
+        # Use the client to create the post
+        post = await client.create_post(request)
+
+        return post