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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marqetive-lib
-Version: 0.1.18
+Version: 0.1.21
 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.21}/pyproject.toml

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

{marqetive_lib-0.1.18 → marqetive_lib-0.1.21}/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.21}/src/marqetive/core/exceptions.py

@@ -47,15 +47,44 @@ class PlatformAuthError(PlatformError):
     - OAuth flow encounters errors
     - Insufficient permissions for requested operation
 
+    Args:
+        message: Human-readable error message
+        platform: Name of the platform where error occurred
+        status_code: HTTP status code if applicable
+        requires_reconnection: If True, user must re-authenticate (token permanently invalid)
+
     Example:
         >>> raise PlatformAuthError(
         ...     "Access token expired",
         ...     platform="twitter",
         ...     status_code=401
         ... )
+        >>> # For invalid refresh token requiring user re-auth:
+        >>> raise PlatformAuthError(
+        ...     "Refresh token invalid",
+        ...     platform="twitter",
+        ...     status_code=400,
+        ...     requires_reconnection=True
+        ... )
     """
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        platform: str | None = None,
+        status_code: int | None = None,
+        *,
+        requires_reconnection: bool = False,
+    ) -> None:
+        self.requires_reconnection = requires_reconnection
+        super().__init__(message, platform, status_code)
+
+    def _format_message(self) -> str:
+        """Format the error message with reconnection info."""
+        base_message = super()._format_message()
+        if self.requires_reconnection:
+            return f"{base_message} | Reconnection required"
+        return base_message
 
 
 class RateLimitError(PlatformError):

{marqetive_lib-0.1.18 → marqetive_lib-0.1.21}/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.21}/src/marqetive/factory.py

@@ -25,6 +25,24 @@ logger = logging.getLogger(__name__)
 # Supported platforms
 SUPPORTED_PLATFORMS = frozenset({"twitter", "linkedin", "instagram", "tiktok"})
 
+# Platform aliases (alternative names that map to canonical names)
+PLATFORM_ALIASES: dict[str, str] = {
+    "x": "twitter",
+}
+
+
+def normalize_platform(platform: str) -> str:
+    """Normalize platform name to canonical form.
+
+    Args:
+        platform: Platform name (may be an alias like 'x').
+
+    Returns:
+        Canonical platform name (e.g., 'twitter').
+    """
+    platform = platform.lower()
+    return PLATFORM_ALIASES.get(platform, platform)
+
 
 def _create_client(
     platform: str, credentials: "AuthCredentials"
@@ -172,7 +190,12 @@ class PlatformFactory:
             >>> async with client:
             ...     post = await client.create_post(request)
         """
-        platform = credentials.platform.lower()
+        # Normalize platform name (handle aliases like 'x' -> 'twitter')
+        platform = normalize_platform(credentials.platform)
+
+        # Update credentials with normalized platform name
+        if platform != credentials.platform.lower():
+            credentials.platform = platform
 
         # Validate platform-specific requirements
         self._validate_credentials(credentials)
@@ -180,8 +203,17 @@ class PlatformFactory:
         # Refresh token if needed
         if auto_refresh and credentials.needs_refresh():
             logger.info(f"Refreshing expired token for {platform}")
-            credentials = await self._refresh_token(credentials)
-            credentials.mark_valid()
+            try:
+                credentials = await self._refresh_token(credentials)
+                credentials.mark_valid()
+            except PlatformAuthError as e:
+                # If refresh failed and requires reconnection, update credentials status
+                if e.requires_reconnection:
+                    credentials.mark_reconnection_required()
+                    logger.warning(
+                        f"Token refresh for {platform} requires user reconnection"
+                    )
+                raise
 
         # Enrich credentials with API keys for Twitter (needed for media operations)
         if platform == "twitter":
@@ -337,9 +369,9 @@ class PlatformFactory:
         """Get the set of supported platform names.
 
         Returns:
-            Frozenset of supported platform names.
+            Frozenset of supported platform names (includes aliases).
         """
-        return SUPPORTED_PLATFORMS
+        return SUPPORTED_PLATFORMS | frozenset(PLATFORM_ALIASES.keys())
 
 
 async def get_client(

{marqetive_lib-0.1.18 → marqetive_lib-0.1.21}/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.21}/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.21}/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.21}/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(),

{marqetive_lib-0.1.18 → marqetive_lib-0.1.21}/src/marqetive/utils/oauth.py

@@ -180,10 +180,32 @@ async def refresh_twitter_token(
 
     except httpx.HTTPStatusError as e:
         logger.error(f"HTTP error refreshing Twitter token: {e.response.status_code}")
+
+        # Determine if this is a permanent failure requiring user re-authentication
+        # Twitter returns 400 with "invalid_request" or "invalid_grant" when:
+        # - Refresh token was already used (single-use tokens)
+        # - Refresh token expired
+        # - User revoked access
+        requires_reconnection = False
+        if e.response.status_code == 400:
+            try:
+                error_data = e.response.json()
+                error_code = error_data.get("error", "")
+                if error_code in ("invalid_request", "invalid_grant"):
+                    requires_reconnection = True
+                    logger.warning(
+                        f"Twitter refresh token is invalid ({error_code}), "
+                        "user needs to reconnect their account"
+                    )
+            except Exception:
+                # If we can't parse the response, assume reconnection is needed for 400
+                requires_reconnection = True
+
         raise PlatformAuthError(
             f"Failed to refresh token: {_sanitize_response_text(e.response.text)}",
             platform="twitter",
             status_code=e.response.status_code,
+            requires_reconnection=requires_reconnection,
         ) from e
 
     except httpx.HTTPError as e: