marqetive-lib 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

marqetive/platforms/tiktok/exceptions.py

@@ -0,0 +1,284 @@
+"""TikTok-specific exception handling and error code mapping.
+
+This module provides error handling for the TikTok API, including HTTP status
+code mapping, TikTok-specific error codes, and user-friendly messages.
+
+TikTok API uses string error codes in the response format:
+{"error": {"code": "error_code_string", "message": "...", "log_id": "..."}}
+"""
+
+from typing import Any
+
+from marqetive.platforms.exceptions import (
+    MediaUploadError,
+    PlatformAuthError,
+    PlatformError,
+    PostNotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
+
+class TikTokErrorCode:
+    """TikTok API error codes (string-based).
+
+    Reference: https://developers.tiktok.com/doc/content-posting-api-reference-direct-post
+    """
+
+    # Success
+    OK = "ok"
+
+    # Authentication & Authorization
+    ACCESS_TOKEN_INVALID = "access_token_invalid"
+    ACCESS_TOKEN_EXPIRED = "access_token_expired"
+    SCOPE_NOT_AUTHORIZED = "scope_not_authorized"
+    TOKEN_NOT_AUTHORIZED_FOR_OPEN_ID = "token_not_authorized_for_this_open_id"
+
+    # Rate Limiting & Spam
+    RATE_LIMIT_EXCEEDED = "rate_limit_exceeded"
+    SPAM_RISK_TOO_MANY_POSTS = "spam_risk_too_many_posts"
+    SPAM_RISK_USER_BANNED = "spam_risk_user_banned_from_posting"
+
+    # Resource Not Found
+    VIDEO_NOT_FOUND = "video_not_found"
+    USER_NOT_FOUND = "user_not_found"
+    PUBLISH_ID_NOT_FOUND = "publish_id_not_found"
+
+    # Validation & Privacy Errors
+    INVALID_PARAMS = "invalid_params"
+    INVALID_FILE_FORMAT = "invalid_file_format"
+    VIDEO_DURATION_TOO_LONG = "video_duration_too_long"
+    VIDEO_DURATION_TOO_SHORT = "video_duration_too_short"
+    PICTURE_NUMBER_EXCEEDS_LIMIT = "picture_number_exceeds_limit"
+    PRIVACY_LEVEL_OPTION_MISMATCH = "privacy_level_option_mismatch"
+    TITLE_LENGTH_EXCEEDS_LIMIT = "title_length_exceeds_limit"
+
+    # Upload & Processing
+    FILE_FORMAT_CHECK_FAILED = "file_format_check_failed"
+    UPLOAD_FAILED = "upload_failed"
+    PROCESSING_FAILED = "processing_failed"
+
+    # Unaudited Client Restrictions
+    UNAUDITED_CLIENT_PRIVATE_ONLY = "unaudited_client_can_only_post_to_private_accounts"
+
+    # Publish Status Values (not errors, but statuses)
+    STATUS_PROCESSING_UPLOAD = "PROCESSING_UPLOAD"
+    STATUS_PROCESSING_DOWNLOAD = "PROCESSING_DOWNLOAD"
+    STATUS_PUBLISH_COMPLETE = "PUBLISH_COMPLETE"
+    STATUS_FAILED = "FAILED"
+
+
+# Mapping of error codes to user-friendly messages
+ERROR_MESSAGES: dict[str, str] = {
+    # Success
+    TikTokErrorCode.OK: "Request completed successfully.",
+    # Authentication
+    TikTokErrorCode.ACCESS_TOKEN_INVALID: "Invalid access token. Please re-authenticate.",
+    TikTokErrorCode.ACCESS_TOKEN_EXPIRED: "Access token has expired. Please refresh the token.",
+    TikTokErrorCode.SCOPE_NOT_AUTHORIZED: "The application is not authorized for the requested scope.",
+    TikTokErrorCode.TOKEN_NOT_AUTHORIZED_FOR_OPEN_ID: "Token is not authorized for this user.",
+    # Rate Limiting
+    TikTokErrorCode.RATE_LIMIT_EXCEEDED: "Rate limit exceeded. Please wait before making more requests.",
+    TikTokErrorCode.SPAM_RISK_TOO_MANY_POSTS: "Daily posting limit reached (~15 posts/day).",
+    TikTokErrorCode.SPAM_RISK_USER_BANNED: "User has been temporarily banned from posting.",
+    # Resource Not Found
+    TikTokErrorCode.VIDEO_NOT_FOUND: "The requested video could not be found.",
+    TikTokErrorCode.USER_NOT_FOUND: "The specified user does not exist.",
+    TikTokErrorCode.PUBLISH_ID_NOT_FOUND: "The publish ID was not found.",
+    # Validation
+    TikTokErrorCode.INVALID_PARAMS: "Invalid parameter in request.",
+    TikTokErrorCode.INVALID_FILE_FORMAT: "Invalid file format. Use MP4 or MOV.",
+    TikTokErrorCode.VIDEO_DURATION_TOO_LONG: "Video duration exceeds the maximum allowed.",
+    TikTokErrorCode.VIDEO_DURATION_TOO_SHORT: "Video duration is below the minimum (3 seconds).",
+    TikTokErrorCode.PICTURE_NUMBER_EXCEEDS_LIMIT: "Too many images in photo post.",
+    TikTokErrorCode.PRIVACY_LEVEL_OPTION_MISMATCH: "Privacy level not available for this creator.",
+    TikTokErrorCode.TITLE_LENGTH_EXCEEDS_LIMIT: "Video title/description is too long.",
+    # Upload
+    TikTokErrorCode.FILE_FORMAT_CHECK_FAILED: "File format validation failed.",
+    TikTokErrorCode.UPLOAD_FAILED: "Media upload failed.",
+    TikTokErrorCode.PROCESSING_FAILED: "Media processing failed after upload.",
+    # Unaudited
+    TikTokErrorCode.UNAUDITED_CLIENT_PRIVATE_ONLY: "Unaudited apps can only post to private accounts.",
+}
+
+
+def map_tiktok_error(
+    status_code: int | None,
+    error_code: str | None = None,
+    error_message: str | None = None,
+    response_data: dict[str, Any] | None = None,
+) -> PlatformError:
+    """Map TikTok API error to the appropriate exception class.
+
+    TikTok API returns errors in the format:
+    {"error": {"code": "error_code_string", "message": "...", "log_id": "..."}}
+
+    Args:
+        status_code: HTTP status code.
+        error_code: TikTok-specific error code string from the response body.
+        error_message: Error message from the API.
+        response_data: Full response data from the API.
+
+    Returns:
+        An appropriate subclass of PlatformError.
+    """
+    if response_data and "error" in response_data:
+        error_data = response_data["error"]
+        if not error_code:
+            error_code = error_data.get("code")
+        if not error_message:
+            error_message = error_data.get("message")
+
+    friendly_message = ERROR_MESSAGES.get(
+        error_code or "", error_message or "An unknown TikTok API error occurred"
+    )
+
+    # Authentication errors
+    auth_error_codes = {
+        TikTokErrorCode.ACCESS_TOKEN_INVALID,
+        TikTokErrorCode.ACCESS_TOKEN_EXPIRED,
+        TikTokErrorCode.SCOPE_NOT_AUTHORIZED,
+        TikTokErrorCode.TOKEN_NOT_AUTHORIZED_FOR_OPEN_ID,
+    }
+    if error_code in auth_error_codes or status_code in (401, 403):
+        return PlatformAuthError(
+            friendly_message,
+            platform="tiktok",
+            status_code=status_code,
+        )
+
+    # Rate limiting errors
+    rate_limit_codes = {
+        TikTokErrorCode.RATE_LIMIT_EXCEEDED,
+        TikTokErrorCode.SPAM_RISK_TOO_MANY_POSTS,
+        TikTokErrorCode.SPAM_RISK_USER_BANNED,
+    }
+    if error_code in rate_limit_codes or status_code == 429:
+        return RateLimitError(
+            friendly_message,
+            platform="tiktok",
+            status_code=status_code or 429,
+            retry_after=None,
+        )
+
+    # Not found errors
+    not_found_codes = {
+        TikTokErrorCode.VIDEO_NOT_FOUND,
+        TikTokErrorCode.USER_NOT_FOUND,
+        TikTokErrorCode.PUBLISH_ID_NOT_FOUND,
+    }
+    if error_code in not_found_codes or status_code == 404:
+        return PostNotFoundError(
+            post_id="",
+            platform="tiktok",
+            status_code=status_code,
+            message=friendly_message,
+        )
+
+    # Validation errors
+    validation_codes = {
+        TikTokErrorCode.INVALID_PARAMS,
+        TikTokErrorCode.INVALID_FILE_FORMAT,
+        TikTokErrorCode.VIDEO_DURATION_TOO_LONG,
+        TikTokErrorCode.VIDEO_DURATION_TOO_SHORT,
+        TikTokErrorCode.PICTURE_NUMBER_EXCEEDS_LIMIT,
+        TikTokErrorCode.PRIVACY_LEVEL_OPTION_MISMATCH,
+        TikTokErrorCode.TITLE_LENGTH_EXCEEDS_LIMIT,
+        TikTokErrorCode.UNAUDITED_CLIENT_PRIVATE_ONLY,
+    }
+    if error_code in validation_codes:
+        return ValidationError(
+            friendly_message,
+            platform="tiktok",
+        )
+
+    # Media upload errors
+    media_error_codes = {
+        TikTokErrorCode.FILE_FORMAT_CHECK_FAILED,
+        TikTokErrorCode.UPLOAD_FAILED,
+        TikTokErrorCode.PROCESSING_FAILED,
+    }
+    if error_code in media_error_codes:
+        return MediaUploadError(
+            friendly_message,
+            platform="tiktok",
+            status_code=status_code,
+        )
+
+    # Generic platform error for everything else
+    return PlatformError(
+        friendly_message,
+        platform="tiktok",
+        status_code=status_code,
+    )
+
+
+class TikTokAPIError(PlatformError):
+    """TikTok API specific error with detailed information."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        log_id: str | None = None,
+        response_data: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, platform="tiktok", status_code=status_code)
+        self.error_code = error_code
+        self.log_id = log_id
+        self.response_data = response_data
+
+    def __repr__(self) -> str:
+        return (
+            f"TikTokAPIError(message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"error_code={self.error_code!r}, "
+            f"log_id={self.log_id!r})"
+        )
+
+
+def is_retryable_error(error_code: str | None, status_code: int | None = None) -> bool:
+    """Check if an error is retryable.
+
+    Args:
+        error_code: TikTok error code string.
+        status_code: HTTP status code.
+
+    Returns:
+        True if the error should be retried, False otherwise.
+    """
+    # Server errors are retryable
+    if status_code and 500 <= status_code < 600:
+        return True
+
+    # Rate limits should wait and retry
+    if error_code == TikTokErrorCode.RATE_LIMIT_EXCEEDED:
+        return True
+
+    # Upload failures may be transient
+    return error_code == TikTokErrorCode.UPLOAD_FAILED
+
+
+def get_retry_delay(error_code: str | None, attempt: int = 1) -> float:
+    """Get recommended retry delay for an error.
+
+    Args:
+        error_code: TikTok error code string.
+        attempt: Current attempt number (1-based).
+
+    Returns:
+        Recommended delay in seconds before retry.
+    """
+    # Rate limits - wait longer
+    if error_code == TikTokErrorCode.RATE_LIMIT_EXCEEDED:
+        return 60.0  # 1 minute
+
+    # Daily post limit - wait much longer
+    if error_code == TikTokErrorCode.SPAM_RISK_TOO_MANY_POSTS:
+        return 3600.0  # 1 hour (user should wait until next day)
+
+    # Default exponential backoff: 5s, 10s, 20s, max 60s
+    delay = min(5 * (2 ** (attempt - 1)), 60)
+    return float(delay)

marqetive/platforms/tiktok/factory.py

@@ -0,0 +1,188 @@
+"""TikTok account factory for managing credentials and client creation."""
+
+import logging
+import os
+from collections.abc import Callable
+from datetime import datetime, timedelta
+
+from marqetive.core.account_factory import BaseAccountFactory
+from marqetive.platforms.exceptions import PlatformAuthError
+from marqetive.platforms.models import AccountStatus, AuthCredentials
+from marqetive.platforms.tiktok.client import TikTokClient
+from marqetive.utils.oauth import fetch_tiktok_token, refresh_tiktok_token
+
+logger = logging.getLogger(__name__)
+
+
+class TikTokAccountFactory(BaseAccountFactory):
+    """Factory for creating and managing TikTok accounts and clients.
+
+    This factory handles the instantiation of TikTokClients, manages OAuth
+    credentials, and provides a mechanism for token refreshing.
+    """
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        on_status_update: Callable[[str, AccountStatus], None] | None = None,
+    ) -> None:
+        """Initialize TikTok account factory.
+
+        Args:
+            client_id: TikTok App client ID (uses TIKTOK_CLIENT_ID env if None).
+            client_secret: TikTok App client secret (uses TIKTOK_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("TIKTOK_CLIENT_ID")
+        self.client_secret = client_secret or os.getenv("TIKTOK_CLIENT_SECRET")
+
+        if not self.client_id or not self.client_secret:
+            logger.warning(
+                "TikTok client_id/client_secret not provided. "
+                "Token refresh may not work."
+            )
+
+    @property
+    def platform_name(self) -> str:
+        """Get the platform name."""
+        return "tiktok"
+
+    async def get_credentials_from_auth_code(
+        self,
+        auth_code: str,
+        redirect_uri: str,
+        code_verifier: str | None = None,
+    ) -> AuthCredentials:
+        """Get credentials from an authorization code.
+
+        This method exchanges an authorization code for an access token and
+        formats it into the standard AuthCredentials object.
+
+        Args:
+            auth_code: The authorization code received from TikTok.
+            redirect_uri: The redirect URI used in the initial auth request.
+            code_verifier: The PKCE code verifier, if used.
+
+        Returns:
+            An AuthCredentials object for the user.
+
+        Raises:
+            PlatformAuthError: If the token exchange fails.
+        """
+        if not self.client_id or not self.client_secret:
+            raise PlatformAuthError(
+                "TikTok client_id and client_secret are required.",
+                platform=self.platform_name,
+            )
+
+        token_data = await fetch_tiktok_token(
+            code=auth_code,
+            client_id=self.client_id,
+            client_secret=self.client_secret,
+            redirect_uri=redirect_uri,
+            code_verifier=code_verifier,
+        )
+
+        expires_at = None
+        if "expires_in" in token_data:
+            expires_at = datetime.now() + timedelta(seconds=token_data["expires_in"])
+
+        refresh_expires_at = None
+        if "refresh_expires_in" in token_data:
+            refresh_expires_at = datetime.now() + timedelta(
+                seconds=token_data["refresh_expires_in"]
+            )
+
+        credentials = AuthCredentials(
+            platform=self.platform_name,
+            access_token=token_data["access_token"],
+            refresh_token=token_data.get("refresh_token"),
+            expires_at=expires_at,
+            scope=token_data.get("scope", []),
+            additional_data={
+                "open_id": token_data["open_id"],
+                "token_type": token_data.get("token_type"),
+                "refresh_expires_at": refresh_expires_at,
+            },
+        )
+        return credentials
+
+    async def refresh_token(self, credentials: AuthCredentials) -> AuthCredentials:
+        """Refresh a TikTok OAuth2 access token.
+
+        Args:
+            credentials: The current credentials containing the refresh token.
+
+        Returns:
+            Updated credentials with a new access token.
+
+        Raises:
+            PlatformAuthError: If refresh fails or credentials are missing.
+        """
+        if not self.client_id or not self.client_secret:
+            raise PlatformAuthError(
+                "TikTok 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 for TikTok.", platform=self.platform_name
+            )
+
+        logger.info("Refreshing TikTok access token...")
+        # This function would call the actual TikTok token refresh endpoint
+        return await refresh_tiktok_token(
+            credentials, self.client_id, self.client_secret
+        )
+
+    async def create_client(self, credentials: AuthCredentials) -> TikTokClient:
+        """Create a TikTok API client.
+
+        Args:
+            credentials: Valid TikTok authentication credentials.
+
+        Returns:
+            An instance of TikTokClient.
+
+        Raises:
+            PlatformAuthError: If credentials are incomplete or invalid.
+        """
+        if not credentials.access_token:
+            raise PlatformAuthError(
+                "Access token is required for TikTok.", platform=self.platform_name
+            )
+        if (
+            not credentials.additional_data
+            or "open_id" not in credentials.additional_data
+        ):
+            raise PlatformAuthError(
+                "'open_id' must be provided in additional_data for TikTok.",
+                platform=self.platform_name,
+            )
+
+        return TikTokClient(credentials=credentials)
+
+    async def validate_credentials(self, credentials: AuthCredentials) -> bool:
+        """Validate TikTok credentials by making a test API call.
+
+        Args:
+            credentials: The credentials to validate.
+
+        Returns:
+            True if the credentials are valid, False otherwise.
+        """
+        try:
+            client = await self.create_client(credentials)
+            async with client:
+                return await client.is_authenticated()
+        except PlatformAuthError as e:
+            logger.warning(f"TikTok credential validation failed: {e}")
+            return False
+        except Exception as e:
+            logger.error(
+                f"An unexpected error occurred during TikTok credential validation: {e}"
+            )
+            return False

marqetive/platforms/tiktok/manager.py

@@ -0,0 +1,115 @@
+"""TikTok post manager for handling video 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.tiktok.client import TikTokClient
+from marqetive.platforms.tiktok.factory import TikTokAccountFactory
+
+logger = logging.getLogger(__name__)
+
+
+class TikTokPostManager(BasePostManager):
+    """Manager for TikTok video post operations.
+
+    This manager coordinates the multi-step process of posting a video to
+    TikTok, including media upload, processing, and the final publishing step.
+    It provides progress tracking throughout the operation.
+    """
+
+    def __init__(
+        self,
+        account_factory: TikTokAccountFactory | None = None,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+    ) -> None:
+        """Initialize the TikTok post manager.
+
+        Args:
+            account_factory: An instance of TikTokAccountFactory. If not provided,
+                             a default one will be created.
+            client_id: TikTok App client ID (for the default factory).
+            client_secret: TikTok App client secret (for the default factory).
+        """
+        if account_factory is None:
+            account_factory = TikTokAccountFactory(
+                client_id=client_id,
+                client_secret=client_secret,
+            )
+        super().__init__(account_factory=account_factory)
+
+    @property
+    def platform_name(self) -> str:
+        """Get the platform name."""
+        return "tiktok"
+
+    async def _execute_post_impl(
+        self,
+        client: Any,
+        request: PostCreateRequest,
+        credentials: AuthCredentials,  # noqa: ARG002
+    ) -> Post:
+        """Execute the TikTok video post creation process.
+
+        Args:
+            client: An authenticated TikTokClient instance.
+            request: The post creation request.
+            credentials: The credentials used for authentication.
+
+        Returns:
+            The created Post object representing the TikTok video.
+
+        Raises:
+            TypeError: If the provided client is not a TikTokClient.
+            InterruptedError: If the operation is cancelled.
+        """
+        if not isinstance(client, TikTokClient):
+            raise TypeError(f"Expected TikTokClient, got {type(client)}")
+
+        # The TikTok posting process is primarily about the video upload.
+        # The client's create_post method handles the upload and publish steps.
+        # We can wrap it here to provide progress updates.
+
+        self._progress_tracker.emit_start(
+            "execute_post", total=100, message="Starting TikTok post..."
+        )
+
+        if self.is_cancelled():
+            raise InterruptedError("Post creation was cancelled before start.")
+
+        # Media upload progress can be tracked inside the client, but for simplicity,
+        # we'll emit high-level progress here.
+        self._progress_tracker.emit_progress(
+            "execute_post",
+            progress=10,
+            total=100,
+            message="Uploading video to TikTok...",
+        )
+
+        # The `create_post` method in the client will handle the full flow:
+        # 1. Upload media
+        # 2. Publish post
+        # 3. Fetch final post data
+        # A more advanced implementation might involve callbacks from the client
+        # to the manager for more granular progress updates.
+        post = await client.create_post(request)
+
+        if self.is_cancelled():
+            # If cancellation happened during the client call, we might need cleanup.
+            # For now, we just raise.
+            raise InterruptedError("Post creation was cancelled during execution.")
+
+        self._progress_tracker.emit_progress(
+            "execute_post",
+            progress=90,
+            total=100,
+            message="Finalizing post...",
+        )
+
+        self._progress_tracker.emit_complete(
+            "execute_post", message="TikTok post published successfully!"
+        )
+
+        return post