marqetive-lib 0.1.6__py3-none-any.whl → 0.1.8__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/client.py

@@ -5,6 +5,11 @@ from typing import Any
 import httpx
 from pydantic import BaseModel
 
+# Default connection pool limits for optimal performance
+DEFAULT_MAX_CONNECTIONS = 100
+DEFAULT_MAX_KEEPALIVE_CONNECTIONS = 20
+DEFAULT_KEEPALIVE_EXPIRY = 30.0
+
 
 class APIResponse(BaseModel):
     """Response model for API calls."""
@@ -24,6 +29,8 @@ class APIClient:
         base_url: The base URL for API requests
         timeout: Request timeout in seconds (default: 30)
         headers: Optional default headers for all requests
+        max_connections: Maximum total connections in pool (default: 100)
+        max_keepalive_connections: Maximum persistent connections (default: 20)
 
     Example:
         >>> client = APIClient(base_url="https://api.example.com")
@@ -36,12 +43,19 @@ class APIClient:
         base_url: str,
         timeout: float = 30.0,
         headers: dict[str, str] | None = None,
+        max_connections: int = DEFAULT_MAX_CONNECTIONS,
+        max_keepalive_connections: int = DEFAULT_MAX_KEEPALIVE_CONNECTIONS,
     ) -> None:
         """Initialize the API client."""
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self.default_headers = headers or {}
         self._client: httpx.AsyncClient | None = None
+        self._limits = httpx.Limits(
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+            keepalive_expiry=DEFAULT_KEEPALIVE_EXPIRY,
+        )
 
     async def __aenter__(self) -> "APIClient":
         """Async context manager entry."""
@@ -49,6 +63,7 @@ class APIClient:
             base_url=self.base_url,
             timeout=self.timeout,
             headers=self.default_headers,
+            limits=self._limits,
         )
         return self
 

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/client.py

@@ -35,6 +35,7 @@ from marqetive.platforms.instagram.media import (
     InstagramMediaManager,
     MediaItem,
 )
+from marqetive.utils.media import validate_media_url
 
 
 class InstagramClient(SocialMediaPlatform):
@@ -245,7 +246,11 @@ class InstagramClient(SocialMediaPlatform):
         }
 
         if request.media_urls:
-            container_params["image_url"] = request.media_urls[0]
+            # Validate URL to prevent SSRF attacks
+            validated_url = validate_media_url(
+                request.media_urls[0], platform=self.platform_name
+            )
+            container_params["image_url"] = validated_url
 
         if request.content:
             container_params["caption"] = request.content
@@ -533,14 +538,17 @@ class InstagramClient(SocialMediaPlatform):
         if not self.api_client:
             raise RuntimeError("Client must be used as async context manager")
 
+        # Validate URL to prevent SSRF attacks
+        validated_url = validate_media_url(media_url, platform=self.platform_name)
+
         params: dict[str, Any] = {
             "access_token": self.credentials.access_token,
         }
 
         if media_type.lower() == "image":
-            params["image_url"] = media_url
+            params["image_url"] = validated_url
         elif media_type.lower() == "video":
-            params["video_url"] = media_url
+            params["video_url"] = validated_url
             params["media_type"] = "VIDEO"
         else:
             raise ValidationError(
@@ -612,13 +620,15 @@ class InstagramClient(SocialMediaPlatform):
         if not self._media_manager:
             raise RuntimeError("Client must be used as async context manager")
 
-        # Convert to MediaItem objects
+        # Convert to MediaItem objects with URL validation
         media_items = []
         for idx, url in enumerate(media_urls):
+            # Validate each URL to prevent SSRF attacks
+            validated_url = validate_media_url(url, platform=self.platform_name)
             alt_text = None
             if alt_texts and idx < len(alt_texts):
                 alt_text = alt_texts[idx]
-            media_items.append(MediaItem(url=url, type="image", alt_text=alt_text))
+            media_items.append(MediaItem(url=validated_url, type="image", alt_text=alt_text))
 
         # Create containers
         container_ids = await self._media_manager.create_feed_containers(
@@ -667,11 +677,19 @@ class InstagramClient(SocialMediaPlatform):
         if not self._media_manager:
             raise RuntimeError("Client must be used as async context manager")
 
+        # Validate URLs to prevent SSRF attacks
+        validated_video_url = validate_media_url(video_url, platform=self.platform_name)
+        validated_cover_url = None
+        if cover_url:
+            validated_cover_url = validate_media_url(
+                cover_url, platform=self.platform_name
+            )
+
         # Create reel container
         container_id = await self._media_manager.create_reel_container(
-            video_url,
+            validated_video_url,
             caption=caption,
-            cover_url=cover_url,
+            cover_url=validated_cover_url,
             share_to_feed=share_to_feed,
             wait_for_processing=True,
         )
@@ -710,9 +728,12 @@ class InstagramClient(SocialMediaPlatform):
         if not self._media_manager:
             raise RuntimeError("Client must be used as async context manager")
 
+        # Validate URL to prevent SSRF attacks
+        validated_url = validate_media_url(media_url, platform=self.platform_name)
+
         # Create story container
         container_id = await self._media_manager.create_story_container(
-            media_url,
+            validated_url,
             media_type,
             wait_for_processing=(media_type == "video"),
         )

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