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

marqetive/__init__.py

@@ -62,6 +62,8 @@ from marqetive.core.models import (
     PostCreateRequest,
     PostStatus,
     PostUpdateRequest,
+    ProgressEvent,
+    ProgressStatus,
 )
 
 # Factory
@@ -85,17 +87,21 @@ __all__ = [
     "BackoffConfig",
     "STANDARD_BACKOFF",
     "retry_async",
-    # Models
-    "AuthCredentials",
+    # Enums
     "AccountStatus",
-    "Post",
+    "CommentStatus",
+    "MediaType",
     "PostStatus",
-    "PostCreateRequest",
-    "PostUpdateRequest",
+    "ProgressStatus",
+    # Core Models
+    "AuthCredentials",
     "Comment",
-    "CommentStatus",
     "MediaAttachment",
-    "MediaType",
+    "Post",
+    "ProgressEvent",
+    # Base Request Models
+    "PostCreateRequest",
+    "PostUpdateRequest",
     # Exceptions
     "PlatformError",
     "PlatformAuthError",

marqetive/core/__init__.py

@@ -31,17 +31,19 @@ __all__ = [
     # Base class
     "SocialMediaPlatform",
     "ProgressCallback",
-    # Models
+    # Enums
     "AccountStatus",
+    "CommentStatus",
+    "MediaType",
+    "PostStatus",
+    # Core Models
     "AuthCredentials",
     "Comment",
-    "CommentStatus",
     "MediaAttachment",
-    "MediaType",
     "PlatformResponse",
     "Post",
+    # Base Request Models
     "PostCreateRequest",
-    "PostStatus",
     "PostUpdateRequest",
     # Exceptions
     "InvalidFileTypeError",

marqetive/core/base.py

@@ -5,8 +5,9 @@ for implementing platform-specific clients (Instagram, Twitter, LinkedIn, etc.).
 All concrete implementations must implement the abstract methods defined here.
 """
 
+import inspect
 from abc import ABC, abstractmethod
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from datetime import datetime
 from traceback import TracebackException
 from typing import Any
@@ -24,11 +25,15 @@ from marqetive.core.models import (
     Post,
     PostCreateRequest,
     PostUpdateRequest,
+    ProgressEvent,
+    ProgressStatus,
 )
 
-# Type alias for progress callback
-# (operation: str, progress: int, total: int, message: str | None) -> None
-type ProgressCallback = Callable[[str, int, int, str | None], None]
+# Type aliases for progress callbacks
+# Supports both sync and async callbacks using ProgressEvent
+type SyncProgressCallback = Callable[[ProgressEvent], None]
+type AsyncProgressCallback = Callable[[ProgressEvent], Awaitable[None]]
+type ProgressCallback = SyncProgressCallback | AsyncProgressCallback
 
 
 class SocialMediaPlatform(ABC):
@@ -162,28 +167,66 @@ class SocialMediaPlatform(ABC):
         self._rate_limit_remaining = remaining
         self._rate_limit_reset = reset_time
 
-    def _emit_progress(
+    async def _emit_progress(
         self,
         operation: str,
+        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.
 
-        This method is safe to call even if no callback is registered.
+        This method supports both synchronous and asynchronous callbacks.
+        It is safe to call even if no callback is registered.
 
         Args:
-            operation: Name of the operation (e.g., "upload_media", "create_post")
-            progress: Current progress value
-            total: Total value for completion
-            message: Optional human-readable message
+            operation: Name of the operation (e.g., "upload_media", "create_post", "create_thread")
+            status: Current status of the operation
+            progress: Current progress value (0-100 for percentage, or bytes)
+            total: Total value for completion (100 for percentage, or total bytes)
+            message: Optional human-readable status message
+            entity_id: Optional platform-specific ID (media_id, post_id, etc.)
+            file_path: Optional file path for upload operations
+            bytes_uploaded: Optional bytes uploaded so far
+            total_bytes: Optional total bytes to upload
 
         Example:
-            >>> self._emit_progress("upload_media", 1, 3, "Uploading image 1 of 3")
+            >>> await self._emit_progress(
+            ...     operation="upload_media",
+            ...     status=ProgressStatus.UPLOADING,
+            ...     progress=50,
+            ...     total=100,
+            ...     message="Uploading image 1 of 3",
+            ...     entity_id="media_123",
+            ... )
         """
-        if self._progress_callback is not None:
-            self._progress_callback(operation, progress, total, message)
+        if self._progress_callback is None:
+            return
+
+        event = ProgressEvent(
+            operation=operation,
+            platform=self.platform_name,
+            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
 
     # ==================== Abstract Authentication Methods ====================
 
@@ -307,6 +350,42 @@ class SocialMediaPlatform(ABC):
         """
         pass
 
+    async def create_thread(
+        self,
+        posts: list[PostCreateRequest],
+    ) -> list[Post]:
+        """Create a thread of connected posts.
+
+        Not all platforms support threads. The default implementation raises
+        NotImplementedError. Platforms that support threads (like Twitter)
+        should override this method.
+
+        Args:
+            posts: List of post requests to create as a thread.
+                   Each post can have its own content, media, etc.
+                   First post is the head of the thread.
+
+        Returns:
+            List of Post objects for each post in the thread.
+
+        Raises:
+            NotImplementedError: If platform doesn't support threads.
+            ValidationError: If posts list is empty.
+            PlatformAuthError: If not authenticated.
+
+        Example:
+            >>> # Twitter thread example
+            >>> posts = [
+            ...     TwitterPostRequest(content="Thread start! 1/3"),
+            ...     TwitterPostRequest(content="Middle 2/3", media_urls=[...]),
+            ...     TwitterPostRequest(content="End 3/3"),
+            ... ]
+            >>> thread = await client.create_thread(posts)
+        """
+        raise NotImplementedError(
+            f"{self.platform_name} does not support thread creation"
+        )
+
     # ==================== Abstract Comment Methods ====================
 
     @abstractmethod

marqetive/core/models.py

@@ -6,10 +6,10 @@ and type safety.
 """
 
 from datetime import UTC, datetime, timedelta
-from enum import Enum
+from enum import Enum, StrEnum
 from typing import Any
 
-from pydantic import BaseModel, Field, HttpUrl
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl
 
 
 class MediaType(str, Enum):
@@ -19,6 +19,8 @@ class MediaType(str, Enum):
     VIDEO = "video"
     CAROUSEL = "carousel"
     DOCUMENT = "document"
+    REEL = "reel"
+    STORY = "story"
 
 
 class PostStatus(str, Enum):
@@ -55,6 +57,29 @@ class AccountStatus(str, Enum):
     ERROR = "error"
 
 
+class ProgressStatus(StrEnum):
+    """Standard progress status for operations across all platforms.
+
+    Used with ProgressEvent to provide consistent progress tracking
+    for long-running operations like media uploads and post creation.
+
+    Attributes:
+        INITIALIZING: Operation is starting, preparing resources.
+        UPLOADING: Actively transferring data (e.g., uploading media).
+        PROCESSING: Server-side processing (e.g., video transcoding).
+        FINALIZING: Completing the operation (e.g., publishing post).
+        COMPLETED: Operation finished successfully.
+        FAILED: Operation failed with an error.
+    """
+
+    INITIALIZING = "initializing"
+    UPLOADING = "uploading"
+    PROCESSING = "processing"
+    FINALIZING = "finalizing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
 class MediaAttachment(BaseModel):
     """Represents a media attachment (image, video, etc.).
 
@@ -294,8 +319,82 @@ class PlatformResponse(BaseModel):
     rate_limit_reset: datetime | None = None
 
 
+class ProgressEvent(BaseModel):
+    """Unified progress event for tracking long-running operations.
+
+    Provides a consistent interface for progress callbacks across all platforms.
+    Supports both synchronous and asynchronous callbacks.
+
+    Attributes:
+        operation: Name of the operation (e.g., "upload_media", "create_post", "create_thread").
+        platform: Platform name (e.g., "twitter", "linkedin", "instagram", "tiktok").
+        status: Current status of the operation.
+        progress: Current progress value (0-100 for percentage, or bytes uploaded).
+        total: Total value for completion (100 for percentage, or total bytes).
+        message: Optional human-readable status message.
+        entity_id: Optional platform-specific ID (media_id, post_id, container_id).
+        file_path: Optional file path for upload operations.
+        bytes_uploaded: Optional bytes uploaded so far.
+        total_bytes: Optional total bytes to upload.
+
+    Example:
+        >>> # Progress callback for media upload
+        >>> def on_progress(event: ProgressEvent) -> None:
+        ...     print(f"{event.operation}: {event.percentage:.1f}% - {event.message}")
+        ...
+        >>> # Async progress callback
+        >>> async def on_progress_async(event: ProgressEvent) -> None:
+        ...     await log_to_database(event)
+
+        >>> event = ProgressEvent(
+        ...     operation="upload_media",
+        ...     platform="twitter",
+        ...     status=ProgressStatus.UPLOADING,
+        ...     progress=50,
+        ...     total=100,
+        ...     message="Uploading image 1 of 2",
+        ...     bytes_uploaded=524288,
+        ...     total_bytes=1048576,
+        ... )
+        >>> print(event.percentage)  # 50.0
+    """
+
+    operation: str
+    platform: str
+    status: ProgressStatus
+    progress: int
+    total: int
+    message: str | None = None
+
+    # Optional detailed info
+    entity_id: str | None = None
+    file_path: str | None = None
+    bytes_uploaded: int | None = None
+    total_bytes: int | None = None
+
+    @property
+    def percentage(self) -> float:
+        """Calculate progress as a percentage.
+
+        Returns:
+            Progress percentage (0.0 to 100.0).
+        """
+        if self.total == 0:
+            return 0.0
+        return (self.progress / self.total) * 100
+
+    model_config = ConfigDict(frozen=True)
+
+
 class PostCreateRequest(BaseModel):
-    """Request model for creating a new post.
+    """Base request model for creating a new post.
+
+    This is a minimal base model with universal fields that work across all platforms.
+    For platform-specific features, use the dedicated request models:
+    - TwitterPostRequest
+    - LinkedInPostRequest
+    - InstagramPostRequest
+    - TikTokPostRequest
 
     Attributes:
         content: Text content of the post
@@ -305,7 +404,7 @@ class PostCreateRequest(BaseModel):
         link: URL to include in the post
         tags: List of hashtags or user tags
         location: Location/place tag for the post
-        additional_data: Platform-specific data
+        additional_data: Platform-specific data for backward compatibility
 
     Example:
         >>> request = PostCreateRequest(
@@ -326,10 +425,15 @@ class PostCreateRequest(BaseModel):
 
 
 class PostUpdateRequest(BaseModel):
-    """Request model for updating an existing post.
+    """Base request model for updating an existing post.
+
+    Note: Not all platforms support editing posts:
+    - Twitter: No editing support (for most users)
+    - Instagram: No editing support
+    - TikTok: No editing support
+    - LinkedIn: Supports updating content, CTA, and landing page
 
-    Note: Not all platforms support editing posts. Fields that can be
-    updated vary by platform.
+    For LinkedIn-specific update features, use LinkedInPostUpdateRequest.
 
     Attributes:
         content: Updated text content

marqetive/platforms/instagram/__init__.py

@@ -1,5 +1,6 @@
 """Instagram platform integration."""
 
 from marqetive.platforms.instagram.client import InstagramClient
+from marqetive.platforms.instagram.models import InstagramPostRequest
 
-__all__ = ["InstagramClient"]
+__all__ = ["InstagramClient", "InstagramPostRequest"]

marqetive/platforms/instagram/media.py

@@ -11,8 +11,9 @@ This module provides comprehensive media management for:
 """
 
 import asyncio
+import inspect
 import logging
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from enum import Enum
 from typing import Any, Literal
@@ -23,8 +24,14 @@ from marqetive.core.exceptions import (
     MediaUploadError,
     ValidationError,
 )
+from marqetive.core.models import ProgressEvent, ProgressStatus
 from marqetive.utils.retry import STANDARD_BACKOFF, retry_async
 
+# Type aliases for progress callbacks
+type SyncProgressCallback = Callable[[ProgressEvent], None]
+type AsyncProgressCallback = Callable[[ProgressEvent], Awaitable[None]]
+type ProgressCallback = SyncProgressCallback | AsyncProgressCallback
+
 logger = logging.getLogger(__name__)
 
 # Instagram API limits
@@ -136,7 +143,7 @@ class InstagramMediaManager:
         *,
         api_version: str = "v21.0",
         timeout: float = 30.0,
-        progress_callback: Callable[[str, str, int], None] | None = None,
+        progress_callback: ProgressCallback | None = None,
     ) -> None:
         """Initialize Instagram media manager.
 
@@ -145,7 +152,8 @@ class InstagramMediaManager:
             access_token: Instagram/Facebook access token.
             api_version: Instagram Graph API version.
             timeout: Request timeout in seconds.
-            progress_callback: Optional callback(container_id, status, progress_pct).
+            progress_callback: Optional callback for progress updates.
+                Receives ProgressEvent objects with upload status and metrics.
         """
         self.ig_user_id = ig_user_id
         self.access_token = access_token
@@ -167,6 +175,44 @@ class InstagramMediaManager:
         """Exit async context and cleanup."""
         await self.client.aclose()
 
+    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="instagram",
+            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 create_feed_containers(
         self,
         media_items: list[MediaItem],
@@ -260,9 +306,14 @@ class InstagramMediaManager:
             container_ids.append(container_id)
 
             # Notify progress
-            if self.progress_callback:
-                progress = int(((idx + 1) / len(media_items)) * 100)
-                self.progress_callback(container_id, "created", progress)
+            progress = int(((idx + 1) / len(media_items)) * 100)
+            await self._emit_progress(
+                status=ProgressStatus.COMPLETED,
+                progress=progress,
+                total=100,
+                message=f"Created container {idx + 1}/{len(media_items)}",
+                entity_id=container_id,
+            )
 
         # If carousel, create parent container
         if is_carousel:
@@ -355,8 +406,13 @@ class InstagramMediaManager:
                     media_type="reel",
                 )
 
-            if self.progress_callback:
-                self.progress_callback(container_id, "ready", 100)
+            await self._emit_progress(
+                status=ProgressStatus.COMPLETED,
+                progress=100,
+                total=100,
+                message="Reel container ready for publishing",
+                entity_id=container_id,
+            )
 
             return container_id
 
@@ -426,8 +482,13 @@ class InstagramMediaManager:
                     media_type="story",
                 )
 
-            if self.progress_callback:
-                self.progress_callback(container_id, "ready", 100)
+            await self._emit_progress(
+                status=ProgressStatus.COMPLETED,
+                progress=100,
+                total=100,
+                message="Story container ready for publishing",
+                entity_id=container_id,
+            )
 
             return container_id
 
@@ -549,9 +610,14 @@ class InstagramMediaManager:
                 )
 
             # Notify progress
-            if self.progress_callback:
-                progress = min(int((elapsed / timeout) * 90), 90)  # Cap at 90%
-                self.progress_callback(container_id, "processing", progress)
+            progress = min(int((elapsed / timeout) * 90), 90)  # Cap at 90%
+            await self._emit_progress(
+                status=ProgressStatus.PROCESSING,
+                progress=progress,
+                total=100,
+                message=f"Processing {media_type} container",
+                entity_id=container_id,
+            )
 
             await asyncio.sleep(check_interval)
             elapsed += check_interval

marqetive/platforms/instagram/models.py

@@ -0,0 +1,74 @@
+"""Instagram-specific models for post creation.
+
+This module defines Instagram-specific data models for creating feed posts,
+carousels, reels, and stories.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from marqetive.core.models import MediaType
+
+
+class InstagramPostRequest(BaseModel):
+    """Instagram-specific post creation request.
+
+    Supports feed posts, carousels, reels, and stories.
+    Instagram requires media for all posts (no text-only posts).
+
+    Attributes:
+        caption: Post caption/text
+        media_urls: List of media URLs (required, 1 for single, 2-10 for carousel)
+        media_ids: List of pre-uploaded media container IDs
+        media_type: Type of post (IMAGE, VIDEO, CAROUSEL, REEL, STORY)
+        alt_texts: Alt text for each media item (accessibility)
+        location_id: Facebook Place ID for location tag
+        cover_url: Cover/thumbnail image URL (for Reels)
+        share_to_feed: Share Reel/Story to main feed
+        collaborators: List of collaborator Instagram user IDs
+        product_tags: Product tags for shopping posts
+        audio_name: Audio track name (for Reels)
+
+    Example:
+        >>> # Single image post
+        >>> request = InstagramPostRequest(
+        ...     caption="Beautiful sunset!",
+        ...     media_urls=["https://example.com/sunset.jpg"],
+        ...     media_type=MediaType.IMAGE,
+        ...     alt_texts=["A colorful sunset over the ocean"]
+        ... )
+
+        >>> # Carousel post
+        >>> request = InstagramPostRequest(
+        ...     caption="Our product lineup",
+        ...     media_urls=[
+        ...         "https://example.com/product1.jpg",
+        ...         "https://example.com/product2.jpg",
+        ...         "https://example.com/product3.jpg"
+        ...     ],
+        ...     media_type=MediaType.CAROUSEL,
+        ...     alt_texts=["Product 1", "Product 2", "Product 3"]
+        ... )
+
+        >>> # Reel
+        >>> request = InstagramPostRequest(
+        ...     caption="Check out this tutorial!",
+        ...     media_urls=["https://example.com/tutorial.mp4"],
+        ...     media_type=MediaType.REEL,
+        ...     cover_url="https://example.com/thumbnail.jpg",
+        ...     share_to_feed=True
+        ... )
+    """
+
+    caption: str | None = None
+    media_urls: list[str] = Field(default_factory=list)
+    media_ids: list[str] = Field(default_factory=list)
+    media_type: MediaType = MediaType.IMAGE
+    alt_texts: list[str] = Field(default_factory=list)
+    location_id: str | None = None
+    cover_url: str | None = None
+    share_to_feed: bool = True
+    collaborators: list[str] = Field(default_factory=list)
+    product_tags: list[dict[str, Any]] = Field(default_factory=list)
+    audio_name: str | None = None

marqetive/platforms/linkedin/__init__.py

@@ -1,5 +1,54 @@
-"""LinkedIn platform integration."""
+"""LinkedIn platform integration using the Community Management API.
+
+This module provides the LinkedIn client and related models for interacting
+with LinkedIn's Community Management API, supporting:
+- Posts (create, read, update, delete, list)
+- Comments (with nested replies)
+- Reactions (Like, Celebrate, Love, Insightful, Support, Funny)
+- Social metadata and engagement metrics
+- Organization (Company Page) management
+- Media uploads (images, videos, documents)
+"""
 
 from marqetive.platforms.linkedin.client import LinkedInClient
+from marqetive.platforms.linkedin.media import (
+    LinkedInMediaManager,
+    MediaAsset,
+    UploadProgress,
+    VideoProcessingState,
+)
+from marqetive.platforms.linkedin.models import (
+    CallToActionLabel,
+    CommentsState,
+    FeedDistribution,
+    LinkedInPostRequest,
+    LinkedInPostUpdateRequest,
+    Organization,
+    OrganizationType,
+    PostVisibility,
+    Reaction,
+    ReactionType,
+    SocialMetadata,
+)
 
-__all__ = ["LinkedInClient"]
+__all__ = [
+    # Client
+    "LinkedInClient",
+    # Media
+    "LinkedInMediaManager",
+    "MediaAsset",
+    "UploadProgress",
+    "VideoProcessingState",
+    # Models
+    "CallToActionLabel",
+    "CommentsState",
+    "FeedDistribution",
+    "LinkedInPostRequest",
+    "LinkedInPostUpdateRequest",
+    "Organization",
+    "OrganizationType",
+    "PostVisibility",
+    "Reaction",
+    "ReactionType",
+    "SocialMetadata",
+]