marqetive-lib 0.1.17__py3-none-any.whl → 0.1.20__py3-none-any.whl

marqetive/platforms/linkedin/client.py

@@ -46,6 +46,24 @@ from marqetive.platforms.linkedin.models import (
     SocialMetadata,
 )
 
+# Valid CTA (Call-To-Action) labels per LinkedIn API documentation
+# Note: BUY_NOW and SHOP_NOW require API version 202504 or later
+VALID_CTA_LABELS = frozenset({
+    "APPLY",
+    "DOWNLOAD",
+    "VIEW_QUOTE",
+    "LEARN_MORE",
+    "SIGN_UP",
+    "SUBSCRIBE",
+    "REGISTER",
+    "JOIN",
+    "ATTEND",
+    "REQUEST_DEMO",
+    "SEE_MORE",
+    "BUY_NOW",  # Requires API version 202504+
+    "SHOP_NOW",  # Requires API version 202504+
+})
+
 
 class LinkedInClient(SocialMediaPlatform):
     """LinkedIn API client using the Community Management API.
@@ -301,53 +319,165 @@ 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:
         """Create and publish a LinkedIn post.
 
         Uses the Community Management API to create posts on personal profiles
-        or organization pages.
+        or organization pages. Supports text, images, videos, documents,
+        multi-image posts, articles, and Direct Sponsored Content (dark posts).
 
         Args:
-            request: Post creation request. Use additional_data for LinkedIn-specific
-                options like visibility, distribution, and call-to-action.
+            request: Post creation request with the following fields:
+                - content: Post text (max 3000 chars). Supports mentions and hashtags.
+                - link: URL for article posts.
+                - media_ids: List of media URNs (images, videos, documents).
+                - additional_data: LinkedIn-specific options (see below).
+
+        Additional Data Options:
+            Basic options:
+                - visibility: "PUBLIC" (default), "CONNECTIONS", "LOGGED_IN"
+                - feed_distribution: "MAIN_FEED" (default), "NONE" (for dark posts)
+                - disable_reshare: bool (default False)
+
+            Call-to-action:
+                - call_to_action: CTA label (APPLY, DOWNLOAD, VIEW_QUOTE, LEARN_MORE,
+                    SIGN_UP, SUBSCRIBE, REGISTER, JOIN, ATTEND, REQUEST_DEMO,
+                    SEE_MORE, BUY_NOW, SHOP_NOW)
+                - landing_page: URL for CTA button
+
+            Media options:
+                - media_title: Title for single media
+                - media_alt_text: Alt text for single media
+                - media_alt_texts: List of alt texts for multi-image posts
+
+            Article options:
+                - article_title: Title for link preview
+                - article_description: Description for link preview
+                - article_thumbnail: Image URN for article thumbnail
+
+            Targeting (for targeted posts):
+                - target_entities: List of targeting criteria
+
+            Direct Sponsored Content (dark posts):
+                - ad_context: Dict with DSC configuration:
+                    - is_dsc: True for dark posts
+                    - dsc_ad_type: VIDEO, STANDARD, CAROUSEL, JOB_POSTING,
+                        NATIVE_DOCUMENT, EVENT
+                    - dsc_status: ACTIVE, ARCHIVED
+                    - dsc_ad_account: Sponsored account URN
+                    - dsc_name: Display name for the DSC
+
+        Mentions and Hashtags:
+            Use these formats in the content field:
+            - Organization mention: @[Display Name](urn:li:organization:12345)
+            - Person mention: @[Jane Smith](urn:li:person:abc123)
+            - Hashtag: #coding (plain text, auto-formatted by LinkedIn)
+
+            Note: Organization names in mentions must match exactly (case-sensitive).
 
         Returns:
             Created Post object.
 
         Raises:
-            ValidationError: If request is invalid.
+            ValidationError: If request is invalid or CTA label is invalid.
             MediaUploadError: If media upload fails.
 
         Example:
+            >>> # Text post with link and CTA
             >>> request = PostCreateRequest(
             ...     content="Check out our new product!",
             ...     link="https://example.com/product",
             ...     additional_data={
             ...         "visibility": "PUBLIC",
-            ...         "call_to_action": "LEARN_MORE"
+            ...         "call_to_action": "LEARN_MORE",
+            ...         "landing_page": "https://example.com/signup"
             ...     }
             ... )
             >>> post = await client.create_post(request)
+            >>>
+            >>> # Multi-image post
+            >>> img1 = await client.upload_image("photo1.jpg")
+            >>> img2 = await client.upload_image("photo2.jpg")
+            >>> request = PostCreateRequest(
+            ...     content="Check out these photos!",
+            ...     media_ids=[img1.asset_id, img2.asset_id],
+            ...     additional_data={
+            ...         "media_alt_texts": ["First photo", "Second photo"]
+            ...     }
+            ... )
+            >>> post = await client.create_post(request)
+            >>>
+            >>> # Dark post (Direct Sponsored Content)
+            >>> request = PostCreateRequest(
+            ...     content="Sponsored content",
+            ...     media_ids=[video_asset.asset_id],
+            ...     additional_data={
+            ...         "ad_context": {
+            ...             "is_dsc": True,
+            ...             "dsc_ad_type": "VIDEO",
+            ...             "dsc_status": "ACTIVE",
+            ...             "dsc_ad_account": "urn:li:sponsoredAccount:123"
+            ...         }
+            ...     }
+            ... )
+            >>> post = await client.create_post(request)
+            >>>
+            >>> # Post with mentions and hashtags
+            >>> request = PostCreateRequest(
+            ...     content="Excited to announce our partnership with "
+            ...             "@[LinkedIn](urn:li:organization:1337)! #exciting #partnership"
+            ... )
+            >>> post = await client.create_post(request)
         """
         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
@@ -370,23 +500,37 @@ class LinkedInClient(SocialMediaPlatform):
                 ),
             }
 
-            # Add media content if provided
+            # Add media content if provided (images, videos, or documents)
             if request.media_ids:
-                # Determine media type from URN prefix
-                media_id = request.media_ids[0]
-                post_payload["content"] = {
-                    "media": {
-                        "id": media_id,
-                        "title": request.additional_data.get("media_title"),
-                        "altText": request.additional_data.get("media_alt_text"),
+                if len(request.media_ids) > 1:
+                    # Multi-image post (organic only, not for sponsored content)
+                    # Per docs: use "multiImage" content type with array of images
+                    images = []
+                    for media_id in request.media_ids:
+                        image_entry: dict[str, Any] = {"id": media_id}
+                        # Alt text can be provided per image via additional_data
+                        alt_texts = request.additional_data.get("media_alt_texts", [])
+                        if alt_texts and len(alt_texts) > len(images):
+                            image_entry["altText"] = alt_texts[len(images)]
+                        images.append(image_entry)
+
+                    post_payload["content"] = {"multiImage": {"images": images}}
+                else:
+                    # Single media (image, video, or document)
+                    media_id = request.media_ids[0]
+                    post_payload["content"] = {
+                        "media": {
+                            "id": media_id,
+                            "title": request.additional_data.get("media_title"),
+                            "altText": request.additional_data.get("media_alt_text"),
+                        }
+                    }
+                    # Remove None values
+                    post_payload["content"]["media"] = {
+                        k: v
+                        for k, v in post_payload["content"]["media"].items()
+                        if v is not None
                     }
-                }
-                # Remove None values
-                post_payload["content"]["media"] = {
-                    k: v
-                    for k, v in post_payload["content"]["media"].items()
-                    if v is not None
-                }
 
             # Add article/link if provided (and no media)
             elif request.link:
@@ -411,10 +555,40 @@ class LinkedInClient(SocialMediaPlatform):
 
             # Add call-to-action if provided
             if cta := request.additional_data.get("call_to_action"):
-                post_payload["contentCallToActionLabel"] = cta
+                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_payload["contentCallToActionLabel"] = cta_upper
             if landing_page := request.additional_data.get("landing_page"):
                 post_payload["contentLandingPage"] = landing_page
 
+            # Add adContext for Direct Sponsored Content (DSC) / dark posts
+            # Dark posts don't appear on company page but can be used in ad campaigns
+            if ad_context := request.additional_data.get("ad_context"):
+                post_payload["adContext"] = {}
+                if ad_context.get("is_dsc"):
+                    post_payload["adContext"]["isDsc"] = True
+                if dsc_ad_type := ad_context.get("dsc_ad_type"):
+                    # Valid types: VIDEO, STANDARD, CAROUSEL, JOB_POSTING,
+                    # NATIVE_DOCUMENT, EVENT
+                    post_payload["adContext"]["dscAdType"] = dsc_ad_type
+                if dsc_status := ad_context.get("dsc_status"):
+                    # Valid values: ACTIVE, ARCHIVED
+                    post_payload["adContext"]["dscStatus"] = dsc_status
+                if dsc_ad_account := ad_context.get("dsc_ad_account"):
+                    post_payload["adContext"]["dscAdAccount"] = dsc_ad_account
+                if dsc_name := ad_context.get("dsc_name"):
+                    post_payload["adContext"]["dscName"] = dsc_name
+
+                # For dark posts, set feedDistribution to NONE
+                if ad_context.get("is_dsc"):
+                    post_payload["distribution"]["feedDistribution"] = "NONE"
+
             # Create the post
             response = await self.api_client.post("/posts", data=post_payload)
 
@@ -434,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,
             )
 
@@ -534,7 +709,15 @@ class LinkedInClient(SocialMediaPlatform):
             # Handle additional LinkedIn-specific fields
             additional = getattr(request, "additional_data", {}) or {}
             if cta := additional.get("call_to_action"):
-                patch_payload["patch"]["$set"]["contentCallToActionLabel"] = cta
+                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",
+                    )
+                patch_payload["patch"]["$set"]["contentCallToActionLabel"] = cta_upper
             if landing_page := additional.get("landing_page"):
                 patch_payload["patch"]["$set"]["contentLandingPage"] = landing_page
             if lifecycle := additional.get("lifecycle_state"):
@@ -597,9 +780,13 @@ class LinkedInClient(SocialMediaPlatform):
                 raise RuntimeError("API client not initialized")
 
             encoded_post_id = quote(post_id, safe="")
+            headers = {
+                **self._build_auth_headers(),
+                "X-RestLi-Method": "DELETE",
+            }
             await self.api_client._client.delete(
                 f"{self.base_url}/posts/{encoded_post_id}",
-                headers=self._build_auth_headers(),
+                headers=headers,
             )
             return True
 
@@ -693,6 +880,204 @@ class LinkedInClient(SocialMediaPlatform):
                 platform=self.platform_name,
             ) from e
 
+    async def create_reshare(
+        self,
+        parent_post_urn: str,
+        commentary: str | None = None,
+        visibility: str = "PUBLIC",
+    ) -> Post:
+        """Create a reshare (repost) of an existing LinkedIn post.
+
+        Args:
+            parent_post_urn: URN of the post to reshare (urn:li:share:xxx or urn:li:ugcPost:xxx).
+            commentary: Optional commentary to add to the reshare.
+            visibility: Post visibility (PUBLIC, CONNECTIONS, LOGGED_IN).
+
+        Returns:
+            Created Post object.
+
+        Raises:
+            ValidationError: If parent_post_urn is invalid.
+
+        Example:
+            >>> reshare = await client.create_reshare(
+            ...     "urn:li:share:6957408550713184256",
+            ...     commentary="Great insights!"
+            ... )
+        """
+        if not self.api_client:
+            raise RuntimeError("Client must be used as async context manager")
+
+        try:
+            post_payload: dict[str, Any] = {
+                "author": self.author_urn,
+                "visibility": visibility,
+                "distribution": {
+                    "feedDistribution": "MAIN_FEED",
+                    "targetEntities": [],
+                    "thirdPartyDistributionChannels": [],
+                },
+                "lifecycleState": "PUBLISHED",
+                "reshareContext": {
+                    "parent": parent_post_urn,
+                },
+            }
+
+            if commentary:
+                post_payload["commentary"] = commentary
+
+            response = await self.api_client.post("/posts", data=post_payload)
+
+            post_id = response.data.get("id") or response.headers.get("x-restli-id")
+            if not post_id:
+                raise PlatformError(
+                    "Failed to get post ID from response",
+                    platform=self.platform_name,
+                )
+
+            return Post(
+                post_id=post_id,
+                platform=self.platform_name,
+                content=commentary or "",
+                status=PostStatus.PUBLISHED,
+                created_at=datetime.now(),
+                author_id=self.author_urn,
+                raw_data=response.data,
+            )
+
+        except httpx.HTTPError as e:
+            raise PlatformError(
+                f"Failed to create reshare: {e}",
+                platform=self.platform_name,
+            ) from e
+
+    async def batch_get_posts(self, post_ids: list[str]) -> list[Post]:
+        """Retrieve multiple posts by their URNs in a single request.
+
+        Uses the BATCH_GET method for efficient retrieval of multiple posts.
+
+        Args:
+            post_ids: List of post URNs (urn:li:share:xxx or urn:li:ugcPost:xxx).
+
+        Returns:
+            List of Post objects (in the same order as input if available).
+
+        Example:
+            >>> posts = await client.batch_get_posts([
+            ...     "urn:li:share:123",
+            ...     "urn:li:ugcPost:456"
+            ... ])
+        """
+        if not self.api_client:
+            raise RuntimeError("Client must be used as async context manager")
+
+        if not self.api_client._client:
+            raise RuntimeError("API client not initialized")
+
+        if not post_ids:
+            return []
+
+        try:
+            # URL encode each post ID
+            encoded_ids = [quote(pid, safe="") for pid in post_ids]
+            ids_param = f"List({','.join(encoded_ids)})"
+
+            headers = {
+                **self._build_auth_headers(),
+                "X-RestLi-Method": "BATCH_GET",
+            }
+
+            response = await self.api_client._client.get(
+                f"{self.base_url}/posts",
+                params={"ids": ids_param},
+                headers=headers,
+            )
+
+            data = response.json()
+            results = data.get("results", {})
+
+            # Parse posts, maintaining order where possible
+            posts = []
+            for post_id in post_ids:
+                if post_id in results:
+                    posts.append(self._parse_post(results[post_id]))
+
+            return posts
+
+        except httpx.HTTPError as e:
+            raise PlatformError(
+                f"Failed to batch get posts: {e}",
+                platform=self.platform_name,
+            ) from e
+
+    async def list_dsc_posts(
+        self,
+        dsc_ad_account: str,
+        dsc_ad_types: list[str] | None = None,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> list[Post]:
+        """List Direct Sponsored Content (DSC) posts by ad account.
+
+        Args:
+            dsc_ad_account: Sponsored account URN (urn:li:sponsoredAccount:xxx).
+            dsc_ad_types: Optional filter by DSC types (VIDEO, STANDARD, CAROUSEL,
+                JOB_POSTING, NATIVE_DOCUMENT, EVENT).
+            limit: Maximum number of posts to retrieve (max 100).
+            offset: Number of posts to skip for pagination.
+
+        Returns:
+            List of Post objects.
+
+        Example:
+            >>> dsc_posts = await client.list_dsc_posts(
+            ...     "urn:li:sponsoredAccount:520866471",
+            ...     dsc_ad_types=["VIDEO", "STANDARD"]
+            ... )
+        """
+        if not self.api_client:
+            raise RuntimeError("Client must be used as async context manager")
+
+        if not self.api_client._client:
+            raise RuntimeError("API client not initialized")
+
+        try:
+            encoded_account = quote(dsc_ad_account, safe="")
+
+            params: dict[str, Any] = {
+                "dscAdAccount": encoded_account,
+                "q": "dscAdAccount",
+                "count": min(limit, 100),
+                "start": offset,
+            }
+
+            if dsc_ad_types:
+                params["dscAdTypes"] = f"List({','.join(dsc_ad_types)})"
+
+            headers = {
+                **self._build_auth_headers(),
+                "X-RestLi-Method": "FINDER",
+            }
+
+            response = await self.api_client._client.get(
+                f"{self.base_url}/posts",
+                params=params,
+                headers=headers,
+            )
+
+            posts = []
+            data = response.json()
+            for post_data in data.get("elements", []):
+                posts.append(self._parse_post(post_data))
+
+            return posts
+
+        except httpx.HTTPError as e:
+            raise PlatformError(
+                f"Failed to list DSC posts: {e}",
+                platform=self.platform_name,
+            ) from e
+
     # ==================== Comment Methods ====================
 
     async def get_comments(
@@ -1098,20 +1483,25 @@ class LinkedInClient(SocialMediaPlatform):
         *,
         title: str | None = None,
     ) -> MediaAsset:
-        """Upload a document/PDF to LinkedIn.
+        """Upload a document to LinkedIn using the Documents API.
 
-        Convenience method for document uploads.
+        Convenience method for document uploads. Supports PDF, PPT, PPTX, DOC, DOCX.
 
         Args:
-            file_path: Path to PDF file or URL.
-            title: Document title.
+            file_path: Path to document file or URL.
+            title: Document title (reserved for future use).
 
         Returns:
-            MediaAsset with asset ID.
+            MediaAsset with document URN (urn:li:document:xxx).
 
         Example:
             >>> async with LinkedInClient(credentials) as client:
             ...     asset = await client.upload_document("report.pdf")
+            ...     request = PostCreateRequest(
+            ...         content="Check out our report!",
+            ...         media_ids=[asset.asset_id]
+            ...     )
+            ...     post = await client.create_post(request)
         """
         if not self._media_manager:
             raise RuntimeError("Client must be used as async context manager")