marqetive-lib 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

marqetive/platforms/tiktok/client.py

@@ -1,9 +1,9 @@
 """TikTok API client implementation.
 
 This module provides a concrete implementation of the SocialMediaPlatform
-ABC for TikTok, using the TikTok for Business API (hypothetical).
+ABC for TikTok, using the TikTok Content Posting API v2.
 
-API Documentation: https://developers.tiktok.com/doc/overview
+API Documentation: https://developers.tiktok.com/doc/content-posting-api-get-started
 """
 
 from datetime import datetime
@@ -11,14 +11,14 @@ from typing import Any
 
 from pydantic import HttpUrl
 
-from src.marqetive.platforms.base import SocialMediaPlatform
-from src.marqetive.platforms.exceptions import (
+from marqetive.platforms.base import ProgressCallback, SocialMediaPlatform
+from marqetive.platforms.exceptions import (
     PlatformAuthError,
     PlatformError,
     PostNotFoundError,
     ValidationError,
 )
-from src.marqetive.platforms.models import (
+from marqetive.platforms.models import (
     AuthCredentials,
     Comment,
     CommentStatus,
@@ -29,35 +29,78 @@ from src.marqetive.platforms.models import (
     PostStatus,
     PostUpdateRequest,
 )
-from src.marqetive.platforms.tiktok.media import TikTokMediaManager
+from marqetive.platforms.tiktok.exceptions import TikTokErrorCode, map_tiktok_error
+from marqetive.platforms.tiktok.media import (
+    CreatorInfo,
+    MediaUploadResult,
+    PrivacyLevel,
+    TikTokMediaManager,
+)
+
+# TikTok API base URL
+TIKTOK_API_BASE = "https://open.tiktokapis.com/v2"
+
+# Video query fields
+VIDEO_QUERY_FIELDS = [
+    "id",
+    "title",
+    "video_description",
+    "create_time",
+    "cover_image_url",
+    "share_url",
+    "duration",
+    "height",
+    "width",
+    "like_count",
+    "comment_count",
+    "share_count",
+    "view_count",
+]
 
 
 class TikTokClient(SocialMediaPlatform):
     """TikTok API client.
 
     This client implements the SocialMediaPlatform interface for TikTok,
-    focusing on video uploads and management.
+    focusing on video uploads and management using the Content Posting API v2.
+
+    Note: Some operations (delete, update, comments) are not supported by TikTok API.
     """
 
     def __init__(
         self,
         credentials: AuthCredentials,
         timeout: float = 300.0,
+        progress_callback: ProgressCallback | None = None,
     ) -> None:
-        """Initialize TikTok client."""
-        base_url = "https://open.tiktokapis.com/v2/"
+        """Initialize TikTok client.
+
+        Args:
+            credentials: OAuth credentials with access_token and open_id in additional_data.
+            timeout: Request timeout in seconds (default 300s for video processing).
+            progress_callback: Optional callback for progress updates during
+                long-running operations like video uploads.
+        """
         super().__init__(
             platform_name="tiktok",
             credentials=credentials,
-            base_url=base_url,
+            base_url=TIKTOK_API_BASE,
             timeout=timeout,
+            progress_callback=progress_callback,
         )
         self._media_manager: TikTokMediaManager | None = None
+        self._creator_info: CreatorInfo | None = None
 
     async def _setup_managers(self) -> None:
         """Setup media manager."""
-        if not self.credentials.access_token or not self.credentials.additional_data:
-            raise PlatformAuthError("Access token and open_id are required", "tiktok")
+        if not self.credentials.access_token:
+            raise PlatformAuthError("Access token is required", "tiktok")
+
+        if (
+            not self.credentials.additional_data
+            or "open_id" not in self.credentials.additional_data
+        ):
+            raise PlatformAuthError("open_id is required in additional_data", "tiktok")
 
         self._media_manager = TikTokMediaManager(
             access_token=self.credentials.access_token,
@@ -90,29 +133,62 @@ class TikTokClient(SocialMediaPlatform):
         )
 
     async def refresh_token(self) -> AuthCredentials:
-        """Refresh TikTok access token."""
-        # The refresh logic should be handled by the AccountFactory
-        # For now, we assume it's done and we just return the creds
+        """Refresh TikTok access token.
+
+        Note: Token refresh should be handled by the AccountFactory.
+        This method just returns the current credentials.
+        """
         return self.credentials
 
     async def is_authenticated(self) -> bool:
-        """Check if TikTok credentials are valid."""
-        if not self.api_client or not self.credentials.additional_data:
+        """Check if TikTok credentials are valid.
+
+        Validates credentials by fetching user info from the API.
+        """
+        if not self.api_client:
             return False
         try:
             # Verify credentials by fetching authenticated user info
-            params = {
-                "fields": "open_id,union_id,avatar_url,display_name",
-                "open_id": self.credentials.additional_data["open_id"],
-            }
-            response = await self.api_client.get("user/info/", params=params)
-            return response.data.get("data", {}).get("user") is not None
+            # TikTok requires 'fields' as query parameter
+            response = await self.api_client.get(
+                "user/info/",
+                params={"fields": "open_id,union_id,avatar_url,display_name"},
+            )
+            data = response.data
+
+            # Check for error in response
+            error_code = data.get("error", {}).get("code", "")
+            if error_code and error_code != TikTokErrorCode.OK:
+                return False
+
+            return data.get("data", {}).get("user") is not None
         except PlatformError:
             return False
 
+    async def query_creator_info(self) -> CreatorInfo:
+        """Query creator info before posting.
+
+        This must be called before creating a post to get available
+        privacy levels and posting limits.
+
+        Returns:
+            CreatorInfo with available options for this creator.
+        """
+        if not self._media_manager:
+            raise RuntimeError("Client must be used as async context manager")
+
+        self._creator_info = await self._media_manager.query_creator_info()
+        return self._creator_info
+
     async def create_post(self, request: PostCreateRequest) -> Post:
         """Create and publish a TikTok video.
 
+        TikTok requires a video to be uploaded. The upload flow is:
+        1. Query creator info (required)
+        2. Initialize upload (get publish_id and upload_url)
+        3. Upload video chunks
+        4. Poll status until PUBLISH_COMPLETE
+
         Args:
             request: The post creation request, must contain a video URL.
 
@@ -132,128 +208,268 @@ class TikTokClient(SocialMediaPlatform):
                 platform=self.platform_name,
             )
 
-        # 1. Upload the video
+        # 1. Query creator info (required before posting)
+        if not self._creator_info:
+            await self.query_creator_info()
+
+        # 2. Determine privacy level
+        privacy_level = PrivacyLevel.SELF_ONLY  # Default for unaudited apps
+        requested_privacy = request.additional_data.get("privacy_level")
+        if requested_privacy and self._creator_info:
+            # Check if requested privacy is available
+            available_privacies = self._creator_info.privacy_level_options or []
+            if requested_privacy in available_privacies:
+                privacy_level = PrivacyLevel(requested_privacy)
+
+        # 3. Upload video and wait for publish
         video_url = request.media_urls[0]
-        upload_result = await self._media_manager.upload_media(video_url)
-
-        if not upload_result.media_id:
-            raise PlatformError("Media upload succeeded but did not yield a media ID.")
-
-        # 2. Create the post with the uploaded video
-        payload = {
-            "post_info": {
-                "title": request.content or "",
-                "description": request.additional_data.get("description", ""),
-                "privacy_level": request.additional_data.get(
-                    "privacy_level", "PUBLIC_TO_EVERYONE"
-                ),
-            },
-            "source_info": {
-                "source": "FILE_UPLOAD",
-                "video_id": upload_result.media_id,
-            },
-        }
-        response = await self.api_client.post("video/publish/", data=payload)
-        post_id = response.data.get("data", {}).get("publish_id")
-
-        if not post_id:
-            raise PlatformError("Post creation succeeded but no publish_id returned.")
-
-        # 3. Fetch the created post to return a full Post object
-        return await self.get_post(post_id)
+        upload_result = await self._media_manager.upload_media(
+            video_url,
+            title=request.content or "",
+            privacy_level=privacy_level,
+            wait_for_publish=True,
+        )
+
+        if not upload_result.video_id:
+            raise PlatformError(
+                "Video upload succeeded but no video ID returned. "
+                "Video may still be processing.",
+                platform=self.platform_name,
+            )
+
+        # 4. Fetch the created post to return full Post object
+        return await self.get_post(upload_result.video_id)
 
     async def get_post(self, post_id: str) -> Post:
-        """Retrieve a TikTok video by its ID."""
-        if not self.api_client or not self.credentials.additional_data:
+        """Retrieve a TikTok video by its ID.
+
+        Uses POST /video/query/ endpoint with filters.video_ids.
+
+        Args:
+            post_id: The video ID to retrieve.
+
+        Returns:
+            Post object with video details.
+
+        Raises:
+            PostNotFoundError: If the video doesn't exist.
+        """
+        if not self.api_client:
             raise RuntimeError("Client must be used as async context manager")
+
         try:
-            params = {
-                "open_id": self.credentials.additional_data["open_id"],
-                "video_ids": [post_id],
-            }
-            response = await self.api_client.post("video/query/", data=params)
-            video_data = response.data.get("data", {}).get("videos", [])
-            if not video_data:
+            # TikTok uses POST for video query with body
+            response = await self.api_client.post(
+                "video/query/",
+                data={
+                    "filters": {"video_ids": [post_id]},
+                    "fields": VIDEO_QUERY_FIELDS,
+                },
+            )
+            data = response.data
+
+            # Check for API errors
+            error_code = data.get("error", {}).get("code", "")
+            if error_code and error_code != TikTokErrorCode.OK:
+                raise map_tiktok_error(
+                    status_code=response.status_code,
+                    error_code=error_code,
+                    error_message=data.get("error", {}).get("message"),
+                    response_data=data,
+                )
+
+            videos = data.get("data", {}).get("videos", [])
+            if not videos:
                 raise PostNotFoundError(post_id, self.platform_name)
-            return self._parse_video_post(video_data[0])
+
+            return self._parse_video_post(videos[0])
+
+        except PostNotFoundError:
+            raise
         except PlatformError as e:
             raise PostNotFoundError(
                 post_id, self.platform_name, status_code=e.status_code
             ) from e
 
-    async def update_post(self, post_id: str, request: PostUpdateRequest) -> Post:
-        """Update a TikTok video. This is not supported by TikTok API."""
+    async def update_post(
+        self, post_id: str, request: PostUpdateRequest  # noqa: ARG002
+    ) -> Post:
+        """Update a TikTok video.
+
+        TikTok API does not support updating videos after publishing.
+        """
         raise PlatformError(
-            "TikTok API does not support updating videos.", self.platform_name
+            "TikTok API does not support updating videos after publishing.",
+            self.platform_name,
         )
 
-    async def delete_post(self, post_id: str) -> bool:
-        """Delete a TikTok video. This is not supported by TikTok API."""
+    async def delete_post(self, post_id: str) -> bool:  # noqa: ARG002
+        """Delete a TikTok video.
+
+        TikTok API does not support deleting videos via API.
+        Users must delete videos through the TikTok app.
+        """
         raise PlatformError(
-            "TikTok API does not support deleting videos.", self.platform_name
+            "TikTok API does not support deleting videos. "
+            "Please delete the video through the TikTok app.",
+            self.platform_name,
         )
 
     async def get_comments(
-        self, post_id: str, limit: int = 20, offset: int = 0
+        self,
+        post_id: str,  # noqa: ARG002
+        limit: int = 20,  # noqa: ARG002
+        offset: int = 0,  # noqa: ARG002
     ) -> list[Comment]:
-        """Retrieve comments for a TikTok video."""
-        if not self.api_client or not self.credentials.additional_data:
-            raise RuntimeError("Client must be used as async context manager")
-        # This is a hypothetical endpoint
-        params = {
-            "open_id": self.credentials.additional_data["open_id"],
-            "video_id": post_id,
-            "count": limit,
-            "cursor": offset,
-        }
-        response = await self.api_client.get("video/comment/list/", params=params)
-        comments_data = response.data.get("data", {}).get("comments", [])
-        return [self._parse_comment(c, post_id) for c in comments_data]
-
-    async def create_comment(self, post_id: str, content: str) -> Comment:
-        """Create a comment on a TikTok video."""
-        raise PlatformError("Commenting via API is not supported.", self.platform_name)
-
-    async def delete_comment(self, comment_id: str) -> bool:
-        """Delete a comment on a TikTok video."""
+        """Retrieve comments for a TikTok video.
+
+        Note: The standard TikTok API v2 does NOT provide access to video comments.
+        Only comment_count is available in video metadata.
+        The Comments API is only available via the Research API for academic use.
+
+        Raises:
+            PlatformError: Always, as this feature is not available.
+        """
         raise PlatformError(
-            "Deleting comments via API is not supported.", self.platform_name
+            "TikTok's standard API does not provide access to video comments. "
+            "Comments are only available via the Research API for academic researchers.",
+            self.platform_name,
+        )
+
+    async def create_comment(
+        self, post_id: str, content: str  # noqa: ARG002
+    ) -> Comment:
+        """Create a comment on a TikTok video.
+
+        TikTok API does not support creating comments programmatically.
+        """
+        raise PlatformError(
+            "TikTok API does not support creating comments.",
+            self.platform_name,
+        )
+
+    async def delete_comment(self, comment_id: str) -> bool:  # noqa: ARG002
+        """Delete a comment on a TikTok video.
+
+        TikTok API does not support deleting comments programmatically.
+        """
+        raise PlatformError(
+            "TikTok API does not support deleting comments.",
+            self.platform_name,
         )
 
     async def upload_media(
-        self, media_url: str, media_type: str, alt_text: str | None = None
+        self,
+        media_url: str,
+        media_type: str,
+        alt_text: str | None = None,  # noqa: ARG002
     ) -> MediaAttachment:
-        """Upload a video to TikTok."""
+        """Upload a video to TikTok.
+
+        This initiates the upload flow but doesn't publish.
+        Use create_post() for full upload + publish flow.
+
+        Args:
+            media_url: URL or path to the video file.
+            media_type: Must be "video" for TikTok.
+            alt_text: Not used (TikTok doesn't support alt text).
+
+        Returns:
+            MediaAttachment with publish_id as media_id.
+
+        Raises:
+            ValidationError: If media_type is not "video".
+        """
         if not self._media_manager:
             raise RuntimeError("Client not initialized. Use as async context manager.")
+
         if media_type != "video":
-            raise ValidationError("Only video media type is supported for TikTok.")
+            raise ValidationError(
+                "Only video media type is supported for TikTok.",
+                platform=self.platform_name,
+            )
+
+        # Upload without waiting for publish
+        result = await self._media_manager.upload_media(
+            media_url,
+            wait_for_publish=False,
+        )
+
+        # Use original URL if it's a valid HTTP URL, otherwise use a placeholder
+        url = (
+            HttpUrl(media_url)
+            if media_url.startswith("http")
+            else HttpUrl("https://www.tiktok.com/")
+        )
 
-        result = await self._media_manager.upload_media(media_url)
         return MediaAttachment(
-            media_id=result.media_id or result.upload_id,
+            media_id=result.publish_id,
             media_type=MediaType.VIDEO,
-            url=HttpUrl(media_url),
+            url=url,
         )
 
+    async def check_publish_status(self, publish_id: str) -> MediaUploadResult:
+        """Check the publish status of an upload.
+
+        Args:
+            publish_id: The publish_id from upload_media.
+
+        Returns:
+            MediaUploadResult with current status and video_id if complete.
+        """
+        if not self._media_manager:
+            raise RuntimeError("Client not initialized. Use as async context manager.")
+
+        return await self._media_manager.check_publish_status(publish_id)
+
+    async def wait_for_publish(self, publish_id: str) -> MediaUploadResult:
+        """Wait for a video to finish publishing.
+
+        Args:
+            publish_id: The publish_id from upload_media.
+
+        Returns:
+            MediaUploadResult with video_id once published.
+        """
+        if not self._media_manager:
+            raise RuntimeError("Client not initialized. Use as async context manager.")
+
+        return await self._media_manager.wait_for_publish(publish_id)
+
     def _parse_video_post(self, video_data: dict[str, Any]) -> Post:
-        """Parse a TikTok API video object into a Post model."""
+        """Parse a TikTok API video object into a Post model.
+
+        Args:
+            video_data: Raw video data from TikTok API.
+
+        Returns:
+            Post model with video details.
+        """
+        # TikTok uses 'id' field for video ID
+        video_id = video_data.get("id", video_data.get("video_id", ""))
+
+        # Handle share_url - use placeholder if empty
+        share_url = video_data.get("share_url", "")
+        media_url = (
+            HttpUrl(share_url) if share_url else HttpUrl("https://www.tiktok.com/")
+        )
+
         return Post(
-            post_id=video_data["video_id"],
+            post_id=video_id,
             platform=self.platform_name,
-            content=video_data.get("title", ""),
+            content=video_data.get("title", video_data.get("video_description", "")),
             media=[
                 MediaAttachment(
-                    media_id=video_data["video_id"],
+                    media_id=video_id,
                     media_type=MediaType.VIDEO,
-                    url=HttpUrl(video_data.get("share_url", "")),
+                    url=media_url,
                     width=video_data.get("width"),
                     height=video_data.get("height"),
                 )
             ],
             status=PostStatus.PUBLISHED,
             created_at=datetime.fromtimestamp(video_data.get("create_time", 0)),
-            author_id=str(video_data.get("open_id")),
+            author_id=video_data.get("open_id", ""),
             likes_count=video_data.get("like_count", 0),
             comments_count=video_data.get("comment_count", 0),
             shares_count=video_data.get("share_count", 0),
@@ -262,16 +478,20 @@ class TikTokClient(SocialMediaPlatform):
         )
 
     def _parse_comment(self, comment_data: dict[str, Any], post_id: str) -> Comment:
-        """Parse a TikTok API comment object into a Comment model."""
+        """Parse a TikTok API comment object into a Comment model.
+
+        Note: This method exists for interface completeness but comments
+        are not accessible via standard TikTok API.
+        """
         return Comment(
-            comment_id=comment_data["comment_id"],
+            comment_id=comment_data.get("id", ""),
             post_id=post_id,
             platform=self.platform_name,
             content=comment_data.get("text", ""),
             author_id=comment_data.get("open_id", ""),
             created_at=datetime.fromtimestamp(comment_data.get("create_time", 0)),
             likes_count=comment_data.get("like_count", 0),
-            replies_count=0,
+            replies_count=comment_data.get("reply_count", 0),
             status=CommentStatus.VISIBLE,
             raw_data=comment_data,
         )