marqetive-lib 0.1.6__py3-none-any.whl → 0.1.8__py3-none-any.whl

marqetive/platforms/tiktok/media.py

@@ -10,24 +10,35 @@ Reference: https://developers.tiktok.com/doc/content-posting-api-reference-direc
 """
 
 import asyncio
+import inspect
+import json
 import logging
 import math
 import os
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Literal
 
+import aiofiles
 import httpx
 
 from marqetive.core.exceptions import (
     InvalidFileTypeError,
     MediaUploadError,
+    PlatformError,
 )
+from marqetive.core.models import ProgressEvent, ProgressStatus
 from marqetive.platforms.tiktok.exceptions import TikTokErrorCode, map_tiktok_error
+from marqetive.platforms.tiktok.models import PrivacyLevel
 from marqetive.utils.file_handlers import download_file
 from marqetive.utils.media import detect_mime_type, format_file_size
 
+# Type aliases for progress callbacks
+type SyncProgressCallback = Callable[[ProgressEvent], None]
+type AsyncProgressCallback = Callable[[ProgressEvent], Awaitable[None]]
+type ProgressCallback = SyncProgressCallback | AsyncProgressCallback
+
 logger = logging.getLogger(__name__)
 
 # TikTok API Base URLs
@@ -62,17 +73,21 @@ class PublishStatus(str, Enum):
     FAILED = "FAILED"
 
 
-class PrivacyLevel(str, Enum):
-    """Privacy level options for TikTok posts."""
-
-    PUBLIC_TO_EVERYONE = "PUBLIC_TO_EVERYONE"
-    MUTUAL_FOLLOW_FRIENDS = "MUTUAL_FOLLOW_FRIENDS"
-    SELF_ONLY = "SELF_ONLY"  # Private - only for unaudited apps or private posts
-
-
 @dataclass
 class UploadProgress:
-    """Progress information for a media upload."""
+    """Progress information for a media upload.
+
+    .. deprecated:: 0.2.0
+        Use :class:`marqetive.core.models.ProgressEvent` instead.
+        This class will be removed in a future version.
+
+    Attributes:
+        publish_id: TikTok publish ID (if available).
+        file_path: Path to file being uploaded.
+        bytes_uploaded: Number of bytes uploaded so far.
+        total_bytes: Total file size in bytes.
+        status: Current upload status.
+    """
 
     publish_id: str | None
     file_path: str
@@ -141,7 +156,7 @@ class TikTokMediaManager:
         access_token: str,
         open_id: str,
         *,
-        progress_callback: Callable[[UploadProgress], None] | None = None,
+        progress_callback: ProgressCallback | None = None,
         timeout: float = DEFAULT_REQUEST_TIMEOUT,
     ) -> None:
         """Initialize the TikTok media manager.
@@ -149,7 +164,8 @@ class TikTokMediaManager:
         Args:
             access_token: OAuth access token with video.publish scope.
             open_id: User's open_id from OAuth flow.
-            progress_callback: Optional callback for upload progress updates.
+            progress_callback: Optional callback for progress updates.
+                Accepts ProgressEvent and can be sync or async.
             timeout: Request timeout in seconds.
         """
         self.access_token = access_token
@@ -176,6 +192,65 @@ class TikTokMediaManager:
         await self._client.aclose()
         await self._upload_client.aclose()
 
+    def _parse_json_response(self, response: httpx.Response) -> dict[str, Any]:
+        """Parse JSON from HTTP response with proper error handling.
+
+        Args:
+            response: HTTP response object.
+
+        Returns:
+            Parsed JSON data as dictionary.
+
+        Raises:
+            PlatformError: If response is not valid JSON.
+        """
+        try:
+            return response.json()
+        except json.JSONDecodeError as e:
+            raise PlatformError(
+                f"Invalid JSON response from TikTok API: {e}",
+                platform="tiktok",
+                status_code=response.status_code,
+            ) from e
+
+    async def _emit_progress(
+        self,
+        status: ProgressStatus,
+        progress: int,
+        total: int,
+        message: str | None = None,
+        *,
+        entity_id: str | None = None,
+        file_path: str | None = None,
+        bytes_uploaded: int | None = None,
+        total_bytes: int | None = None,
+    ) -> None:
+        """Emit a progress update if a callback is registered.
+
+        Supports both sync and async callbacks.
+        """
+        if self.progress_callback is None:
+            return
+
+        event = ProgressEvent(
+            operation="upload_media",
+            platform="tiktok",
+            status=status,
+            progress=progress,
+            total=total,
+            message=message,
+            entity_id=entity_id,
+            file_path=file_path,
+            bytes_uploaded=bytes_uploaded,
+            total_bytes=total_bytes,
+        )
+
+        result = self.progress_callback(event)
+
+        # If callback returned a coroutine, await it
+        if inspect.iscoroutine(result):
+            await result
+
     async def query_creator_info(self) -> CreatorInfo:
         """Query creator info before posting.
 
@@ -191,7 +266,7 @@ class TikTokMediaManager:
         url = f"{TIKTOK_API_BASE}/post/publish/creator_info/query/"
 
         response = await self._client.post(url)
-        data = response.json()
+        data = self._parse_json_response(response)
 
         self._check_response_error(response.status_code, data)
 
@@ -214,7 +289,7 @@ class TikTokMediaManager:
         file_path: str,
         *,
         title: str = "",
-        privacy_level: PrivacyLevel = PrivacyLevel.SELF_ONLY,
+        privacy_level: PrivacyLevel = PrivacyLevel.PRIVATE,
         disable_duet: bool = False,
         disable_comment: bool = False,
         disable_stitch: bool = False,
@@ -263,7 +338,7 @@ class TikTokMediaManager:
         }
 
         response = await self._client.post(url, json=payload)
-        data = response.json()
+        data = self._parse_json_response(response)
 
         self._check_response_error(response.status_code, data)
 
@@ -285,7 +360,7 @@ class TikTokMediaManager:
         video_url: str,
         *,
         title: str = "",
-        privacy_level: PrivacyLevel = PrivacyLevel.SELF_ONLY,
+        privacy_level: PrivacyLevel = PrivacyLevel.PRIVATE,
         disable_duet: bool = False,
         disable_comment: bool = False,
         disable_stitch: bool = False,
@@ -328,7 +403,7 @@ class TikTokMediaManager:
         }
 
         response = await self._client.post(url, json=payload)
-        data = response.json()
+        data = self._parse_json_response(response)
 
         self._check_response_error(response.status_code, data)
 
@@ -368,23 +443,23 @@ class TikTokMediaManager:
         chunk_size = self._normalize_chunk_size(chunk_size, file_size)
         mime_type = detect_mime_type(file_path)
 
-        if self.progress_callback:
-            self.progress_callback(
-                UploadProgress(
-                    publish_id=publish_id,
-                    file_path=file_path,
-                    bytes_uploaded=0,
-                    total_bytes=file_size,
-                    status="uploading",
-                )
-            )
+        await self._emit_progress(
+            status=ProgressStatus.UPLOADING,
+            progress=0,
+            total=100,
+            message="Starting video upload",
+            entity_id=publish_id,
+            file_path=file_path,
+            bytes_uploaded=0,
+            total_bytes=file_size,
+        )
 
         bytes_uploaded = 0
 
-        with open(file_path, "rb") as f:
+        async with aiofiles.open(file_path, "rb") as f:
             chunk_index = 0
             while True:
-                chunk_data = f.read(chunk_size)
+                chunk_data = await f.read(chunk_size)
                 if not chunk_data:
                     break
 
@@ -419,16 +494,16 @@ class TikTokMediaManager:
                 bytes_uploaded += len(chunk_data)
                 chunk_index += 1
 
-                if self.progress_callback:
-                    self.progress_callback(
-                        UploadProgress(
-                            publish_id=publish_id,
-                            file_path=file_path,
-                            bytes_uploaded=bytes_uploaded,
-                            total_bytes=file_size,
-                            status="uploading",
-                        )
-                    )
+                await self._emit_progress(
+                    status=ProgressStatus.UPLOADING,
+                    progress=int((bytes_uploaded / file_size) * 100),
+                    total=100,
+                    message=f"Uploading chunk {chunk_index}",
+                    entity_id=publish_id,
+                    file_path=file_path,
+                    bytes_uploaded=bytes_uploaded,
+                    total_bytes=file_size,
+                )
 
         logger.info(
             f"TikTok video upload complete: {bytes_uploaded} bytes in {chunk_index} chunks"
@@ -449,7 +524,7 @@ class TikTokMediaManager:
         url = f"{TIKTOK_API_BASE}/post/publish/status/fetch/"
 
         response = await self._client.post(url, json={"publish_id": publish_id})
-        data = response.json()
+        data = self._parse_json_response(response)
 
         self._check_response_error(response.status_code, data)
 
@@ -490,16 +565,17 @@ class TikTokMediaManager:
         Raises:
             MediaUploadError: If publishing fails or times out.
         """
-        if self.progress_callback and file_path:
+        if file_path:
             file_size = os.path.getsize(file_path) if os.path.exists(file_path) else 0
-            self.progress_callback(
-                UploadProgress(
-                    publish_id=publish_id,
-                    file_path=file_path,
-                    bytes_uploaded=file_size,
-                    total_bytes=file_size,
-                    status="processing",
-                )
+            await self._emit_progress(
+                status=ProgressStatus.PROCESSING,
+                progress=0,
+                total=100,
+                message="Processing video on TikTok servers",
+                entity_id=publish_id,
+                file_path=file_path,
+                bytes_uploaded=file_size,
+                total_bytes=file_size,
             )
 
         elapsed = 0.0
@@ -508,31 +584,33 @@ class TikTokMediaManager:
 
             if result.status == PublishStatus.PUBLISH_COMPLETE:
                 logger.info(f"TikTok video published: video_id={result.video_id}")
-                if self.progress_callback and file_path:
+                if file_path:
                     file_size = (
                         os.path.getsize(file_path) if os.path.exists(file_path) else 0
                     )
-                    self.progress_callback(
-                        UploadProgress(
-                            publish_id=publish_id,
-                            file_path=file_path,
-                            bytes_uploaded=file_size,
-                            total_bytes=file_size,
-                            status="completed",
-                        )
+                    await self._emit_progress(
+                        status=ProgressStatus.COMPLETED,
+                        progress=100,
+                        total=100,
+                        message="Video published successfully",
+                        entity_id=publish_id,
+                        file_path=file_path,
+                        bytes_uploaded=file_size,
+                        total_bytes=file_size,
                     )
                 return result
 
             if result.status == PublishStatus.FAILED:
-                if self.progress_callback and file_path:
-                    self.progress_callback(
-                        UploadProgress(
-                            publish_id=publish_id,
-                            file_path=file_path,
-                            bytes_uploaded=0,
-                            total_bytes=0,
-                            status="failed",
-                        )
+                if file_path:
+                    await self._emit_progress(
+                        status=ProgressStatus.FAILED,
+                        progress=0,
+                        total=100,
+                        message="Video publishing failed",
+                        entity_id=publish_id,
+                        file_path=file_path,
+                        bytes_uploaded=0,
+                        total_bytes=0,
                     )
                 raise MediaUploadError(
                     f"TikTok video publishing failed: publish_id={publish_id}",
@@ -553,7 +631,7 @@ class TikTokMediaManager:
         file_path: str,
         *,
         title: str = "",
-        privacy_level: PrivacyLevel = PrivacyLevel.SELF_ONLY,
+        privacy_level: PrivacyLevel = PrivacyLevel.PRIVATE,
         chunk_size: int = DEFAULT_CHUNK_SIZE,
         wait_for_publish: bool = True,
     ) -> MediaUploadResult:
@@ -581,43 +659,56 @@ class TikTokMediaManager:
             InvalidFileTypeError: If the file is not a supported video format.
             MediaUploadError: If upload or processing fails.
         """
-        # Handle URL downloads
-        if file_path.startswith(("http://", "https://")):
-            logger.info(f"Downloading media from URL: {file_path}")
-            file_path = await download_file(file_path)
-
-        if not os.path.exists(file_path):
-            raise FileNotFoundError(f"Media file not found: {file_path}")
-
-        # Validate file
-        mime_type = detect_mime_type(file_path)
-        file_size = os.path.getsize(file_path)
-        self._validate_media(mime_type, file_size)
-
-        # Initialize upload
-        init_result = await self.init_video_upload(
-            file_path,
-            title=title,
-            privacy_level=privacy_level,
-            chunk_size=chunk_size,
-        )
+        # Track if we downloaded a temp file that needs cleanup
+        temp_file_path: str | None = None
+
+        try:
+            # Handle URL downloads
+            if file_path.startswith(("http://", "https://")):
+                logger.info(f"Downloading media from URL: {file_path}")
+                file_path = await download_file(file_path)
+                temp_file_path = file_path  # Mark for cleanup
+
+            if not os.path.exists(file_path):
+                raise FileNotFoundError(f"Media file not found: {file_path}")
+
+            # Validate file
+            mime_type = detect_mime_type(file_path)
+            file_size = os.path.getsize(file_path)
+            self._validate_media(mime_type, file_size)
+
+            # Initialize upload
+            init_result = await self.init_video_upload(
+                file_path,
+                title=title,
+                privacy_level=privacy_level,
+                chunk_size=chunk_size,
+            )
 
-        # Upload chunks
-        await self.upload_video_chunks(
-            init_result.upload_url,
-            file_path,
-            init_result.publish_id,
-            chunk_size=chunk_size,
-        )
+            # Upload chunks
+            await self.upload_video_chunks(
+                init_result.upload_url,
+                file_path,
+                init_result.publish_id,
+                chunk_size=chunk_size,
+            )
 
-        # Wait for publish
-        if wait_for_publish:
-            return await self.wait_for_publish(init_result.publish_id, file_path)
+            # Wait for publish
+            if wait_for_publish:
+                return await self.wait_for_publish(init_result.publish_id, file_path)
 
-        return MediaUploadResult(
-            publish_id=init_result.publish_id,
-            status=PublishStatus.PROCESSING_UPLOAD,
-        )
+            return MediaUploadResult(
+                publish_id=init_result.publish_id,
+                status=PublishStatus.PROCESSING_UPLOAD,
+            )
+        finally:
+            # Clean up downloaded temp file
+            if temp_file_path and os.path.exists(temp_file_path):
+                try:
+                    os.remove(temp_file_path)
+                    logger.debug(f"Cleaned up temp file: {temp_file_path}")
+                except OSError as e:
+                    logger.warning(f"Failed to clean up temp file {temp_file_path}: {e}")
 
     def _normalize_chunk_size(self, chunk_size: int, file_size: int) -> int:
         """Normalize chunk size to TikTok's requirements.

marqetive/platforms/tiktok/models.py

@@ -0,0 +1,79 @@
+"""TikTok-specific models for post creation.
+
+This module defines TikTok-specific data models for creating video posts,
+including privacy settings and content toggles.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class PrivacyLevel(StrEnum):
+    """Privacy level options for TikTok posts.
+
+    Attributes:
+        PUBLIC: Visible to everyone
+        FRIENDS: Visible to mutual followers/friends only
+        PRIVATE: Visible only to the author (for unaudited apps)
+    """
+
+    PUBLIC = "PUBLIC_TO_EVERYONE"
+    FRIENDS = "MUTUAL_FOLLOW_FRIENDS"
+    PRIVATE = "SELF_ONLY"
+
+
+class TikTokPostRequest(BaseModel):
+    """TikTok-specific post creation request with full API options.
+
+    This model provides a type-safe way to configure TikTok-specific post settings.
+    It can be converted to the universal PostCreateRequest for use with TikTokClient.
+
+    TikTok only supports video posts. Videos must be between 3 seconds
+    and 10 minutes, and under 4GB in size.
+
+    Attributes:
+        title: Video title/caption (max 2200 characters)
+        video_url: URL to video file (required)
+        video_id: Pre-uploaded video ID
+        privacy_level: Privacy setting (PUBLIC, FRIENDS, PRIVATE)
+        disable_comment: Disable comments on the video
+        disable_duet: Disable duet feature
+        disable_stitch: Disable stitch feature
+        video_cover_timestamp_ms: Timestamp in ms for auto-generated cover
+        brand_content_toggle: Mark as branded/sponsored content
+        brand_organic_toggle: Mark as organic branded content
+        schedule_time: Unix timestamp to schedule post (10 mins to 10 days ahead)
+
+    Example:
+        >>> from marqetive.core.models import PostCreateRequest
+        >>>
+        >>> # Create TikTok-specific request
+        >>> tiktok_request = TikTokPostRequest(
+        ...     title="Check out this dance!",
+        ...     video_url="https://example.com/dance.mp4",
+        ...     privacy_level=PrivacyLevel.PUBLIC,
+        ...     disable_duet=True,
+        ... )
+        >>>
+        >>> # Convert to universal PostCreateRequest for client
+        >>> request = PostCreateRequest(
+        ...     content=tiktok_request.title,
+        ...     media_urls=[tiktok_request.video_url] if tiktok_request.video_url else [],
+        ...     additional_data=tiktok_request.model_dump(exclude_none=True),
+        ... )
+        >>> async with TikTokClient(credentials) as client:
+        ...     post = await client.create_post(request)
+    """
+
+    title: str | None = None
+    video_url: str | None = None
+    video_id: str | None = None
+    privacy_level: PrivacyLevel = PrivacyLevel.PRIVATE
+    disable_comment: bool = False
+    disable_duet: bool = False
+    disable_stitch: bool = False
+    video_cover_timestamp_ms: int | None = None
+    brand_content_toggle: bool = False
+    brand_organic_toggle: bool = False
+    schedule_time: int | None = Field(default=None, description="Unix timestamp")

marqetive/platforms/twitter/__init__.py

@@ -1,5 +1,6 @@
 """Twitter/X platform integration."""
 
 from marqetive.platforms.twitter.client import TwitterClient
+from marqetive.platforms.twitter.models import TwitterPostRequest
 
-__all__ = ["TwitterClient"]
+__all__ = ["TwitterClient", "TwitterPostRequest"]

marqetive/platforms/twitter/client.py

@@ -527,6 +527,92 @@ class TwitterClient(SocialMediaPlatform):
                 media_type=media_type,
             ) from e
 
+    # ==================== Thread Methods ====================
+
+    async def create_thread(
+        self,
+        posts: list[PostCreateRequest],
+    ) -> list[Post]:
+        """Create a Twitter thread (multiple linked tweets).
+
+        Each tweet in the list can have its own content, media, polls, and alt texts.
+        Tweets are posted sequentially, with each tweet replying to the previous one.
+
+        Args:
+            posts: List of PostCreateRequest objects to create as a thread.
+                   First tweet is the head of the thread.
+                   Use TwitterPostRequest for Twitter-specific features.
+
+        Returns:
+            List of Post objects for each tweet in the thread.
+
+        Raises:
+            ValidationError: If posts list is empty.
+            PlatformAuthError: If not authenticated.
+            MediaUploadError: If media upload fails.
+            RuntimeError: If client not used as context manager.
+
+        Example:
+            >>> from marqetive.platforms.twitter import TwitterPostRequest
+            >>> tweets = [
+            ...     TwitterPostRequest(content="Thread start! 1/3"),
+            ...     TwitterPostRequest(content="Middle 2/3", media_urls=["..."]),
+            ...     TwitterPostRequest(content="End 3/3", poll_options=["Yes", "No"]),
+            ... ]
+            >>> async with TwitterClient(credentials) as client:
+            ...     thread_posts = await client.create_thread(tweets)
+            ...     for post in thread_posts:
+            ...         print(f"Tweet {post.post_id}: {post.content}")
+        """
+        from marqetive.core.models import ProgressStatus
+        from marqetive.platforms.twitter.models import TwitterPostRequest
+
+        if not posts:
+            raise ValidationError(
+                "At least one tweet is required for thread creation",
+                platform=self.platform_name,
+            )
+
+        created_posts: list[Post] = []
+        reply_to_id: str | None = None
+
+        for idx, post_request in enumerate(posts):
+            # Convert to TwitterPostRequest if needed and set reply chain
+            if isinstance(post_request, TwitterPostRequest):
+                if reply_to_id is not None:
+                    post_request = post_request.model_copy(
+                        update={"reply_to_post_id": reply_to_id}
+                    )
+                # TwitterPostRequest works with create_post via duck typing
+                final_request = post_request
+            else:
+                # Create TwitterPostRequest from generic PostCreateRequest
+                request_data: dict[str, Any] = {
+                    "content": post_request.content,
+                    "media_urls": post_request.media_urls,
+                    "media_ids": post_request.media_ids,
+                }
+                if reply_to_id is not None:
+                    request_data["reply_to_post_id"] = reply_to_id
+                final_request = TwitterPostRequest(**request_data)
+
+            # TwitterPostRequest has compatible interface with PostCreateRequest
+            created_post = await self.create_post(final_request)  # type: ignore[arg-type]
+            created_posts.append(created_post)
+            reply_to_id = created_post.post_id
+
+            # Emit progress
+            await self._emit_progress(
+                operation="create_thread",
+                status=ProgressStatus.PROCESSING,
+                progress=idx + 1,
+                total=len(posts),
+                message=f"Tweet {idx + 1}/{len(posts)} created",
+                entity_id=created_post.post_id,
+            )
+
+        return created_posts
+
     # ==================== Helper Methods ====================
 
     def _parse_tweet(