marqetive-lib 0.1.18__tar.gz → 0.1.20__tar.gz

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marqetive-lib
-Version: 0.1.18
+Version: 0.1.20
 Summary: Modern Python utilities for web APIs
 Keywords: api,utilities,web,http,marqetive
 Requires-Python: >=3.12

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "marqetive-lib"
-version = "0.1.18"
+version = "0.1.20"
 description = "Modern Python utilities for web APIs"
 readme = "README.md"
 requires-python = ">=3.12"

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/core/base.py

@@ -119,7 +119,10 @@ class SocialMediaPlatform(ABC):
         return self
 
     async def __aexit__(
-        self, exc_type: type[Exception] | None, exc_val: Exception | None, exc_tb: TracebackType | None
+        self,
+        exc_type: type[Exception] | None,
+        exc_val: Exception | None,
+        exc_tb: TracebackType | None,
     ) -> None:
         """Async context manager exit."""
         if self.api_client:
@@ -228,6 +231,35 @@ class SocialMediaPlatform(ABC):
         if inspect.iscoroutine(result):
             await result
 
+    # ==================== Validation Helpers ====================
+
+    @abstractmethod
+    def _validate_create_post_request(self, request: PostCreateRequest) -> None:
+        """Validate a post creation request.
+
+        This base implementation performs no validation. Subclasses should
+        override this method to implement platform-specific validation rules.
+
+        The validation method should raise ValidationError with descriptive
+        messages including platform name and field name for consistency.
+
+        Args:
+            request: The post creation request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+
+        Example:
+            >>> def _validate_create_post_request(self, request):
+            ...     if not request.content:
+            ...         raise ValidationError(
+            ...             "Content is required",
+            ...             platform=self.platform_name,
+            ...             field="content",
+            ...         )
+        """
+        pass
+
     # ==================== Abstract Authentication Methods ====================
 
     @abstractmethod

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/core/models.py

@@ -217,6 +217,7 @@ class AuthCredentials(BaseModel):
         expires_at: Timestamp when access token expires
         scope: List of permission scopes granted
         user_id: ID of the authenticated user
+        username: Username/handle of the authenticated user
         status: Current status of the account credentials
         additional_data: Platform-specific auth data
 
@@ -237,6 +238,7 @@ class AuthCredentials(BaseModel):
     expires_at: datetime | None = None
     scope: list[str] = Field(default_factory=list)
     user_id: str | None = None
+    username: str | None = None
     status: AccountStatus = AccountStatus.VALID
     additional_data: dict[str, Any] = Field(default_factory=dict)
 

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/platforms/instagram/client.py

@@ -211,6 +211,39 @@ class InstagramClient(SocialMediaPlatform):
         except httpx.HTTPError:
             return False
 
+    # ==================== Validation ====================
+
+    def _validate_create_post_request(self, request: PostCreateRequest) -> None:
+        """Validate Instagram post creation request.
+
+        Instagram Requirements:
+            - Media is ALWAYS required (Instagram is a visual platform)
+            - For carousels: 2-10 images
+            - For reels: 1 video (3 sec - 15 min)
+            - Caption max 2200 characters
+            - Media must be publicly accessible URLs
+
+        Args:
+            request: Post creation request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+        """
+        if not request.media_urls and not request.media_ids:
+            raise ValidationError(
+                "Instagram posts require at least one media attachment. "
+                "Instagram is a visual platform - text-only posts are not supported.",
+                platform=self.platform_name,
+                field="media",
+            )
+
+        if request.content and len(request.content) > 2200:
+            raise ValidationError(
+                f"Caption exceeds 2200 characters ({len(request.content)} characters)",
+                platform=self.platform_name,
+                field="content",
+            )
+
     # ==================== Post CRUD Methods ====================
 
     async def create_post(self, request: PostCreateRequest) -> Post:
@@ -256,12 +289,8 @@ class InstagramClient(SocialMediaPlatform):
         if not self.api_client:
             raise RuntimeError("Client must be used as async context manager")
 
-        if not request.media_urls and not request.media_ids:
-            raise ValidationError(
-                "Instagram posts require at least one media attachment",
-                platform=self.platform_name,
-                field="media",
-            )
+        # Validate request
+        self._validate_create_post_request(request)
 
         # Determine content type from request
         media_type = self._get_media_type(request)
@@ -375,7 +404,9 @@ class InstagramClient(SocialMediaPlatform):
             content=request.content,
             status=PostStatus.PUBLISHED,
             created_at=datetime.now(),
+            author_id=self.instagram_account_id,
             url=cast(HttpUrl, result.permalink) if result.permalink else None,
+            raw_data={"container_id": container_ids[0]},
         )
 
     async def _create_carousel_post(self, request: PostCreateRequest) -> Post:
@@ -826,7 +857,9 @@ class InstagramClient(SocialMediaPlatform):
             content=caption,
             status=PostStatus.PUBLISHED,
             created_at=datetime.now(),
+            author_id=self.instagram_account_id,
             url=cast(HttpUrl, result.permalink) if result.permalink else None,
+            raw_data={"container_id": container_ids[0]},
         )
 
     async def create_reel(
@@ -890,7 +923,9 @@ class InstagramClient(SocialMediaPlatform):
             content=caption,
             status=PostStatus.PUBLISHED,
             created_at=datetime.now(),
+            author_id=self.instagram_account_id,
             url=cast(HttpUrl, result.permalink) if result.permalink else None,
+            raw_data={"container_id": container_id},
         )
 
     async def create_story(
@@ -941,7 +976,9 @@ class InstagramClient(SocialMediaPlatform):
             content=None,  # Stories don't have captions
             status=PostStatus.PUBLISHED,
             created_at=datetime.now(),
+            author_id=self.instagram_account_id,
             url=cast(HttpUrl, result.permalink) if result.permalink else None,
+            raw_data={"container_id": container_id},
         )
 
     # ==================== Helper Methods ====================

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/platforms/linkedin/client.py

@@ -319,6 +319,48 @@ class LinkedInClient(SocialMediaPlatform):
         except httpx.HTTPError:
             return False
 
+    # ==================== Validation ====================
+
+    def _validate_create_post_request(self, request: PostCreateRequest) -> None:
+        """Validate LinkedIn post creation request.
+
+        LinkedIn Requirements:
+            - Content is required (text post content)
+            - Content max 3000 characters
+            - CTA labels must be from approved list if provided
+            - Media: max 20 images, or 1 video, or 1 document
+
+        Args:
+            request: Post creation request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+        """
+        if not request.content:
+            raise ValidationError(
+                "LinkedIn posts require content",
+                platform=self.platform_name,
+                field="content",
+            )
+
+        if len(request.content) > 3000:
+            raise ValidationError(
+                f"Post content exceeds 3000 characters ({len(request.content)} characters)",
+                platform=self.platform_name,
+                field="content",
+            )
+
+        # Validate CTA label if provided
+        if cta := request.additional_data.get("call_to_action"):
+            cta_upper = cta.upper()
+            if cta_upper not in VALID_CTA_LABELS:
+                raise ValidationError(
+                    f"Invalid call_to_action: '{cta}'. "
+                    f"Valid values: {', '.join(sorted(VALID_CTA_LABELS))}",
+                    platform=self.platform_name,
+                    field="call_to_action",
+                )
+
     # ==================== Post CRUD Methods ====================
 
     async def create_post(self, request: PostCreateRequest) -> Post:
@@ -434,20 +476,8 @@ class LinkedInClient(SocialMediaPlatform):
         if not self.api_client:
             raise RuntimeError("Client must be used as async context manager")
 
-        if not request.content:
-            raise ValidationError(
-                "LinkedIn posts require content",
-                platform=self.platform_name,
-                field="content",
-            )
-
-        # Validate content length (3000 characters for posts)
-        if len(request.content) > 3000:
-            raise ValidationError(
-                f"Post content exceeds 3000 characters ({len(request.content)} characters)",
-                platform=self.platform_name,
-                field="content",
-            )
+        # Validate request
+        self._validate_create_post_request(request)
 
         try:
             # Build REST API payload structure
@@ -578,6 +608,7 @@ class LinkedInClient(SocialMediaPlatform):
                 status=PostStatus.PUBLISHED,
                 created_at=datetime.now(),
                 author_id=self.author_urn,
+                url=None,  # Not available without separate fetch
                 raw_data=response.data,
             )
 

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/platforms/tiktok/client.py

@@ -166,6 +166,32 @@ class TikTokClient(SocialMediaPlatform):
         except PlatformError:
             return False
 
+    # ==================== Validation ====================
+
+    def _validate_create_post_request(self, request: PostCreateRequest) -> None:
+        """Validate TikTok post creation request.
+
+        TikTok Requirements:
+            - Video URL is ALWAYS required (TikTok is a video-only platform)
+            - Video duration: 3 seconds to 10 minutes
+            - open_id must be in credentials.additional_data
+
+        Args:
+            request: Post creation request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+        """
+        if not request.media_urls:
+            raise ValidationError(
+                "A video URL is required to create a TikTok post. "
+                "TikTok is a video platform - image-only or text-only posts are not supported.",
+                platform=self.platform_name,
+                field="media_urls",
+            )
+
+    # ==================== TikTok-specific Methods ====================
+
     async def query_creator_info(self) -> CreatorInfo:
         """Query creator info before posting.
 
@@ -203,11 +229,8 @@ class TikTokClient(SocialMediaPlatform):
         if not self._media_manager or not self.api_client:
             raise RuntimeError("Client must be used as async context manager")
 
-        if not request.media_urls:
-            raise ValidationError(
-                "A video URL is required to create a TikTok post.",
-                platform=self.platform_name,
-            )
+        # Validate request
+        self._validate_create_post_request(request)
 
         # 1. Query creator info (required before posting)
         if not self._creator_info:
@@ -232,12 +255,21 @@ class TikTokClient(SocialMediaPlatform):
         )
 
         # 4. Return minimal Post object without fetching details
+        video_id = upload_result.video_id or upload_result.publish_id
+        url = (
+            HttpUrl(f"https://www.tiktok.com/@{self.credentials.username}/video/{video_id}")
+            if self.credentials.username and video_id
+            else None
+        )
+
         return Post(
-            post_id=upload_result.video_id or upload_result.publish_id,
+            post_id=video_id,
             platform=self.platform_name,
             content=request.content,
             status=PostStatus.PUBLISHED,
             created_at=datetime.now(),
+            author_id=self.credentials.additional_data.get("open_id"),
+            url=url,
             raw_data={
                 "publish_id": upload_result.publish_id,
                 "video_id": upload_result.video_id,
@@ -458,16 +490,25 @@ class TikTokClient(SocialMediaPlatform):
         # 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
+        # Handle share_url - construct URL from username if share_url not available
         share_url = video_data.get("share_url", "")
-        media_url = (
-            HttpUrl(share_url) if share_url else HttpUrl("https://www.tiktok.com/")
-        )
+        if share_url:
+            post_url: HttpUrl | None = HttpUrl(share_url)
+        elif self.credentials.username and video_id:
+            post_url = HttpUrl(
+                f"https://www.tiktok.com/@{self.credentials.username}/video/{video_id}"
+            )
+        else:
+            post_url = None
+
+        # MediaAttachment.url requires a non-null HttpUrl, use placeholder if needed
+        media_url = post_url if post_url else HttpUrl("https://www.tiktok.com/")
 
         return Post(
             post_id=video_id,
             platform=self.platform_name,
             content=video_data.get("title", video_data.get("video_description", "")),
+            url=post_url,
             media=[
                 MediaAttachment(
                     media_id=video_id,

{marqetive_lib-0.1.18 → marqetive_lib-0.1.20}/src/marqetive/platforms/twitter/client.py

@@ -185,29 +185,68 @@ class TwitterClient(SocialMediaPlatform):
         except tweepy.TweepyException:
             return False
 
+    # ==================== Validation ====================
+
+    def _validate_create_post_request(self, request: PostCreateRequest) -> None:
+        """Validate Twitter post creation request.
+
+        Twitter Requirements:
+            - Must have content OR media (at least one)
+            - Content max 280 characters (enforced by Twitter API)
+            - Max 4 images or 1 video per tweet
+
+        Args:
+            request: Post creation request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+        """
+        if not request.content and not request.media_urls and not request.media_ids:
+            raise ValidationError(
+                "Tweet must contain content or media",
+                platform=self.platform_name,
+                field="content",
+            )
+
     # ==================== Post CRUD Methods ====================
 
     async def create_post(self, request: PostCreateRequest) -> Post:
         """Create and publish a tweet.
 
+        Twitter Requirements:
+            - Must have content OR media (at least one)
+            - Content max 280 characters (enforced by Twitter API)
+            - Max 4 images or 1 video per tweet
+
         Args:
-            request: Post creation request.
+            request: Post creation request. Supports:
+                - content: Tweet text (max 280 chars)
+                - media_urls: URLs of media to attach
+                - reply_to_post_id: Tweet ID to reply to (for threads)
+                - quote_post_id: Tweet ID to quote
 
         Returns:
-            Created Post object.
+            Post object with:
+                - post_id: Twitter tweet ID
+                - platform: "twitter"
+                - content: Tweet text
+                - status: PostStatus.PUBLISHED
+                - created_at: Creation timestamp
+                - author_id: None (not available without extra API call)
+                - url: None (not returned in create response)
+                - raw_data: {"tweet_id": ...}
 
         Raises:
             ValidationError: If request is invalid.
             MediaUploadError: If media upload fails.
+            RateLimitError: If Twitter rate limit is exceeded.
+            PlatformError: For other Twitter API errors.
         """
         if not self._tweepy_client:
             raise RuntimeError("Client must be used as async context manager")
 
-        if not request.content and not request.media_urls:
-            raise ValidationError(
-                "Tweet must contain content or media",
-                platform=self.platform_name,
-            )
+        # Validate request
+        self._validate_create_post_request(request)
 
         try:
             media_ids = []
@@ -241,6 +280,13 @@ class TwitterClient(SocialMediaPlatform):
             response = self._tweepy_client.create_tweet(**tweet_params, user_auth=False)
             tweet_id = response.data["id"]  # type: ignore[index]
 
+            # Construct Twitter URL if username is available
+            url = (
+                HttpUrl(f"https://x.com/{self.credentials.username}/status/{tweet_id}")
+                if self.credentials.username
+                else HttpUrl(f"https://x.com/web/status/{tweet_id}")
+            )
+
             # Return minimal Post object without fetching details
             return Post(
                 post_id=tweet_id,
@@ -248,6 +294,9 @@ class TwitterClient(SocialMediaPlatform):
                 content=request.content or "",
                 status=PostStatus.PUBLISHED,
                 created_at=datetime.now(),
+                author_id=None,  # Not available without extra API call
+                url=url,
+                raw_data={"tweet_id": tweet_id},
             )
 
         except tweepy.TweepyException as e:
@@ -741,10 +790,19 @@ class TwitterClient(SocialMediaPlatform):
 
         metrics = tweet.public_metrics or {}
 
+        # Construct Twitter URL if username is available
+        tweet_id = str(tweet.id)
+        url = (
+            HttpUrl(f"https://x.com/{self.credentials.username}/status/{tweet_id}")
+            if self.credentials.username
+            else HttpUrl(f"https://x.com/web/status/{tweet_id}")
+        )
+
         return Post(
-            post_id=str(tweet.id),
+            post_id=tweet_id,
             platform=self.platform_name,
             content=tweet.text,
+            url=url,
             media=media,
             status=PostStatus.PUBLISHED,
             created_at=tweet.created_at or datetime.now(),