marqetive-lib 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

marqetive/__init__.py

@@ -4,49 +4,54 @@ A comprehensive library providing utilities for working with web APIs,
 HTTP requests, data processing, and social media platform integrations.
 
 Usage:
-    Basic API client:
-        >>> from marqetive import APIClient
-        >>> async with APIClient(base_url="https://api.example.com") as client:
-        ...     response = await client.get("/endpoint")
+    Simple usage with factory:
+        >>> from marqetive import get_client, AuthCredentials, PostCreateRequest
+        >>> credentials = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="...",
+        ...     refresh_token="..."
+        ... )
+        >>> client = await get_client(credentials)
+        >>> async with client:
+        ...     post = await client.create_post(PostCreateRequest(content="Hello!"))
 
-    Platform managers (high-level):
-        >>> from marqetive import initialize_platform_registry, get_manager_for_platform
-        >>> from marqetive.platforms.models import AuthCredentials, PostCreateRequest
-        >>>
-        >>> initialize_platform_registry()
-        >>> manager = get_manager_for_platform("twitter")
-        >>> credentials = AuthCredentials(platform="twitter", access_token="...")
-        >>> request = PostCreateRequest(content="Hello!")
-        >>> post = await manager.execute_post(credentials, request)
+    Factory with custom OAuth credentials:
+        >>> from marqetive import PlatformFactory, AuthCredentials
+        >>> factory = PlatformFactory(
+        ...     twitter_client_id="your_client_id",
+        ...     twitter_client_secret="your_client_secret"
+        ... )
+        >>> client = await factory.get_client(credentials)
 
-    Platform clients (low-level):
+    Direct client usage:
         >>> from marqetive.platforms.twitter import TwitterClient
-        >>> credentials = AuthCredentials(platform="twitter", access_token="...")
         >>> async with TwitterClient(credentials) as client:
         ...     post = await client.create_post(request)
+
+    Basic API client:
+        >>> from marqetive import APIClient
+        >>> async with APIClient(base_url="https://api.example.com") as client:
+        ...     response = await client.get("/endpoint")
 """
 
 # Core API client
-# Account management
-from marqetive.core.account_factory import BaseAccountFactory
-
-# Registry and managers
-from marqetive.core.base_manager import BasePostManager
 from marqetive.core.client import APIClient
 
-# Progress tracking
-from marqetive.core.progress import (
-    ProgressCallback,
-    ProgressEvent,
-    ProgressStatus,
-    ProgressTracker,
-)
-from marqetive.core.registry import (
-    PlatformRegistry,
-    get_available_platforms,
-    get_manager_for_platform,
-    get_registry,
-    register_platform,
+# Factory
+from marqetive.factory import PlatformFactory, get_client
+
+# Progress callback type
+from marqetive.platforms.base import ProgressCallback
+
+# Exceptions
+from marqetive.platforms.exceptions import (
+    InvalidFileTypeError,
+    MediaUploadError,
+    PlatformAuthError,
+    PlatformError,
+    PostNotFoundError,
+    RateLimitError,
+    ValidationError,
 )
 
 # Models
@@ -62,10 +67,6 @@ from marqetive.platforms.models import (
     PostStatus,
     PostUpdateRequest,
 )
-from marqetive.registry_init import (
-    initialize_platform_registry,
-    is_registry_initialized,
-)
 
 # Utilities
 from marqetive.utils.helpers import format_response
@@ -73,28 +74,14 @@ from marqetive.utils.helpers import format_response
 # Retry utilities
 from marqetive.utils.retry import STANDARD_BACKOFF, BackoffConfig, retry_async
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     # Core
     "APIClient",
-    "format_response",
-    # Registry
-    "PlatformRegistry",
-    "initialize_platform_registry",
-    "is_registry_initialized",
-    "get_registry",
-    "register_platform",
-    "get_manager_for_platform",
-    "get_available_platforms",
-    # Managers and factories
-    "BasePostManager",
-    "BaseAccountFactory",
-    # Progress tracking
-    "ProgressEvent",
-    "ProgressStatus",
-    "ProgressTracker",
-    "ProgressCallback",
+    # Factory
+    "PlatformFactory",
+    "get_client",
     # Retry
     "BackoffConfig",
     "STANDARD_BACKOFF",
@@ -110,4 +97,16 @@ __all__ = [
     "CommentStatus",
     "MediaAttachment",
     "MediaType",
+    # Exceptions
+    "PlatformError",
+    "PlatformAuthError",
+    "RateLimitError",
+    "PostNotFoundError",
+    "MediaUploadError",
+    "ValidationError",
+    "InvalidFileTypeError",
+    # Types
+    "ProgressCallback",
+    # Utilities
+    "format_response",
 ]

marqetive/factory.py

@@ -0,0 +1,380 @@
+"""Platform factory for creating social media clients.
+
+This module provides a simple factory for creating authenticated platform clients
+with automatic token refresh and validation.
+"""
+
+import logging
+import os
+from typing import TYPE_CHECKING
+
+from marqetive.platforms.exceptions import PlatformAuthError
+from marqetive.platforms.models import AuthCredentials
+from marqetive.utils.oauth import (
+    refresh_instagram_token,
+    refresh_linkedin_token,
+    refresh_tiktok_token,
+    refresh_twitter_token,
+)
+
+if TYPE_CHECKING:
+    from marqetive.platforms.base import SocialMediaPlatform
+
+logger = logging.getLogger(__name__)
+
+# Supported platforms
+SUPPORTED_PLATFORMS = frozenset({"twitter", "linkedin", "instagram", "tiktok"})
+
+
+def _create_client(
+    platform: str, credentials: "AuthCredentials"
+) -> "SocialMediaPlatform":
+    """Create a client for a platform (with lazy imports).
+
+    Args:
+        platform: Platform name (twitter, linkedin, instagram, tiktok).
+        credentials: Authentication credentials for the platform.
+
+    Returns:
+        The platform client instance.
+
+    Raises:
+        ValueError: If platform is unknown.
+    """
+    if platform == "twitter":
+        from marqetive.platforms.twitter.client import TwitterClient
+
+        return TwitterClient(credentials=credentials)
+    elif platform == "linkedin":
+        from marqetive.platforms.linkedin.client import LinkedInClient
+
+        return LinkedInClient(credentials=credentials)
+    elif platform == "instagram":
+        from marqetive.platforms.instagram.client import InstagramClient
+
+        return InstagramClient(credentials=credentials)
+    elif platform == "tiktok":
+        from marqetive.platforms.tiktok.client import TikTokClient
+
+        return TikTokClient(credentials=credentials)
+    else:
+        raise ValueError(
+            f"Unknown platform: {platform}. "
+            f"Supported platforms: {', '.join(sorted(SUPPORTED_PLATFORMS))}"
+        )
+
+
+class PlatformFactory:
+    """Factory for creating authenticated social media platform clients.
+
+    This factory handles:
+    - Token refresh before client creation (if expired)
+    - Platform-specific credential validation
+    - OAuth client credentials from environment variables
+
+    Example:
+        >>> factory = PlatformFactory()
+        >>> credentials = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="token",
+        ...     refresh_token="refresh"
+        ... )
+        >>> client = await factory.get_client(credentials)
+        >>> async with client:
+        ...     post = await client.create_post(request)
+
+    Example with custom OAuth credentials:
+        >>> factory = PlatformFactory(
+        ...     twitter_client_id="your_client_id",
+        ...     twitter_client_secret="your_client_secret"
+        ... )
+        >>> client = await factory.get_client(credentials)
+    """
+
+    def __init__(
+        self,
+        *,
+        twitter_client_id: str | None = None,
+        twitter_client_secret: str | None = None,
+        twitter_api_key: str | None = None,
+        twitter_api_secret: str | None = None,
+        linkedin_client_id: str | None = None,
+        linkedin_client_secret: str | None = None,
+        tiktok_client_id: str | None = None,
+        tiktok_client_secret: str | None = None,
+    ) -> None:
+        """Initialize platform factory with OAuth credentials.
+
+        OAuth credentials can be provided directly or via environment variables:
+        - TWITTER_CLIENT_ID, TWITTER_CLIENT_SECRET, TWITTER_API_KEY, TWITTER_API_SECRET
+        - LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET
+        - TIKTOK_CLIENT_ID, TIKTOK_CLIENT_SECRET
+
+        Note: Instagram uses long-lived tokens that don't require client credentials
+        for refresh (only the current access token is needed).
+
+        Args:
+            twitter_client_id: Twitter OAuth client ID.
+            twitter_client_secret: Twitter OAuth client secret.
+            twitter_api_key: Twitter API key (for media operations).
+            twitter_api_secret: Twitter API secret (for media operations).
+            linkedin_client_id: LinkedIn OAuth client ID.
+            linkedin_client_secret: LinkedIn OAuth client secret.
+            tiktok_client_id: TikTok OAuth client ID.
+            tiktok_client_secret: TikTok OAuth client secret.
+        """
+        self._oauth_credentials = {
+            "twitter": {
+                "client_id": twitter_client_id or os.getenv("TWITTER_CLIENT_ID"),
+                "client_secret": twitter_client_secret
+                or os.getenv("TWITTER_CLIENT_SECRET"),
+                "api_key": twitter_api_key or os.getenv("TWITTER_API_KEY"),
+                "api_secret": twitter_api_secret or os.getenv("TWITTER_API_SECRET"),
+            },
+            "linkedin": {
+                "client_id": linkedin_client_id or os.getenv("LINKEDIN_CLIENT_ID"),
+                "client_secret": linkedin_client_secret
+                or os.getenv("LINKEDIN_CLIENT_SECRET"),
+            },
+            "tiktok": {
+                "client_id": tiktok_client_id or os.getenv("TIKTOK_CLIENT_ID"),
+                "client_secret": tiktok_client_secret
+                or os.getenv("TIKTOK_CLIENT_SECRET"),
+            },
+        }
+
+    async def get_client(
+        self,
+        credentials: AuthCredentials,
+        *,
+        auto_refresh: bool = True,
+    ) -> "SocialMediaPlatform":
+        """Create a platform client with the given credentials.
+
+        If credentials are expired and auto_refresh is True, attempts to
+        refresh the token before creating the client.
+
+        Args:
+            credentials: Authentication credentials for the platform.
+            auto_refresh: Whether to automatically refresh expired tokens.
+
+        Returns:
+            Platform client (TwitterClient, LinkedInClient, etc.).
+            The client must be used as an async context manager.
+
+        Raises:
+            PlatformAuthError: If credentials are invalid or refresh fails.
+            ValueError: If platform is unknown.
+
+        Example:
+            >>> factory = PlatformFactory()
+            >>> client = await factory.get_client(credentials)
+            >>> async with client:
+            ...     post = await client.create_post(request)
+        """
+        platform = credentials.platform.lower()
+
+        # Validate platform-specific requirements
+        self._validate_credentials(credentials)
+
+        # 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()
+
+        # Enrich credentials with API keys for Twitter (needed for media operations)
+        if platform == "twitter":
+            credentials = self._enrich_twitter_credentials(credentials)
+
+        # Create and return client
+        return _create_client(platform, credentials)
+
+    def _validate_credentials(self, credentials: AuthCredentials) -> None:
+        """Validate platform-specific credential requirements.
+
+        Args:
+            credentials: The credentials to validate.
+
+        Raises:
+            PlatformAuthError: If credentials are missing required fields.
+        """
+        platform = credentials.platform.lower()
+
+        if platform not in SUPPORTED_PLATFORMS:
+            raise ValueError(
+                f"Unknown platform: {platform}. "
+                f"Supported platforms: {', '.join(sorted(SUPPORTED_PLATFORMS))}"
+            )
+
+        if not credentials.access_token:
+            raise PlatformAuthError(
+                "Access token is required",
+                platform=platform,
+            )
+
+        if platform == "instagram":
+            # Instagram requires user_id or business_account_id
+            business_account_id = credentials.additional_data.get(
+                "instagram_business_account_id"
+            )
+            if not credentials.user_id and not business_account_id:
+                raise PlatformAuthError(
+                    "Instagram requires user_id or 'instagram_business_account_id' "
+                    "in additional_data",
+                    platform=platform,
+                )
+
+        elif platform == "tiktok":
+            # TikTok requires open_id
+            if not credentials.additional_data.get("open_id"):
+                raise PlatformAuthError(
+                    "TikTok requires 'open_id' in additional_data",
+                    platform=platform,
+                )
+
+        elif platform == "linkedin":
+            # LinkedIn requires user_id (person URN)
+            if not credentials.user_id:
+                raise PlatformAuthError(
+                    "LinkedIn requires user_id (person URN, e.g., 'urn:li:person:xxx')",
+                    platform=platform,
+                )
+
+    async def _refresh_token(self, credentials: AuthCredentials) -> AuthCredentials:
+        """Refresh the access token for the given credentials.
+
+        Args:
+            credentials: The credentials with expired token.
+
+        Returns:
+            Updated credentials with new access token.
+
+        Raises:
+            PlatformAuthError: If refresh fails or required OAuth credentials are missing.
+        """
+        platform = credentials.platform.lower()
+
+        if platform == "twitter":
+            oauth_creds = self._oauth_credentials.get("twitter", {})
+            client_id = oauth_creds.get("client_id")
+            client_secret = oauth_creds.get("client_secret")
+
+            if not client_id or not client_secret:
+                raise PlatformAuthError(
+                    "Twitter client_id and client_secret required for token refresh. "
+                    "Provide them via PlatformFactory constructor or environment variables "
+                    "(TWITTER_CLIENT_ID, TWITTER_CLIENT_SECRET).",
+                    platform=platform,
+                )
+
+            return await refresh_twitter_token(credentials, client_id, client_secret)
+
+        elif platform == "linkedin":
+            oauth_creds = self._oauth_credentials.get("linkedin", {})
+            client_id = oauth_creds.get("client_id")
+            client_secret = oauth_creds.get("client_secret")
+
+            if not client_id or not client_secret:
+                raise PlatformAuthError(
+                    "LinkedIn client_id and client_secret required for token refresh. "
+                    "Provide them via PlatformFactory constructor or environment variables "
+                    "(LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET).",
+                    platform=platform,
+                )
+
+            return await refresh_linkedin_token(credentials, client_id, client_secret)
+
+        elif platform == "instagram":
+            # Instagram doesn't need OAuth credentials for refresh
+            return await refresh_instagram_token(credentials)
+
+        elif platform == "tiktok":
+            oauth_creds = self._oauth_credentials.get("tiktok", {})
+            client_id = oauth_creds.get("client_id")
+            client_secret = oauth_creds.get("client_secret")
+
+            if not client_id or not client_secret:
+                raise PlatformAuthError(
+                    "TikTok client_id and client_secret required for token refresh. "
+                    "Provide them via PlatformFactory constructor or environment variables "
+                    "(TIKTOK_CLIENT_ID, TIKTOK_CLIENT_SECRET).",
+                    platform=platform,
+                )
+
+            return await refresh_tiktok_token(credentials, client_id, client_secret)
+
+        else:
+            raise ValueError(f"Unknown platform: {platform}")
+
+    def _enrich_twitter_credentials(
+        self, credentials: AuthCredentials
+    ) -> AuthCredentials:
+        """Enrich Twitter credentials with API keys for media operations.
+
+        Args:
+            credentials: The Twitter credentials.
+
+        Returns:
+            Credentials with api_key and api_secret in additional_data.
+        """
+        oauth_creds = self._oauth_credentials.get("twitter", {})
+
+        # Only add if not already present
+        if "api_key" not in credentials.additional_data:
+            api_key = oauth_creds.get("api_key")
+            if api_key:
+                credentials.additional_data["api_key"] = api_key
+
+        if "api_secret" not in credentials.additional_data:
+            api_secret = oauth_creds.get("api_secret")
+            if api_secret:
+                credentials.additional_data["api_secret"] = api_secret
+
+        return credentials
+
+    def get_supported_platforms(self) -> frozenset[str]:
+        """Get the set of supported platform names.
+
+        Returns:
+            Frozenset of supported platform names.
+        """
+        return SUPPORTED_PLATFORMS
+
+
+async def get_client(
+    credentials: AuthCredentials,
+    *,
+    auto_refresh: bool = True,
+) -> "SocialMediaPlatform":
+    """Create a platform client with the given credentials.
+
+    This is a convenience function that creates a PlatformFactory with
+    environment-based OAuth credentials and returns a client.
+
+    For more control over OAuth credentials, create a PlatformFactory directly.
+
+    Args:
+        credentials: Authentication credentials for the platform.
+        auto_refresh: Whether to automatically refresh expired tokens.
+
+    Returns:
+        Platform client ready to be used as async context manager.
+
+    Raises:
+        PlatformAuthError: If credentials are invalid or refresh fails.
+        ValueError: If platform is unknown.
+
+    Example:
+        >>> from marqetive import get_client, AuthCredentials, PostCreateRequest
+        >>> credentials = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="...",
+        ...     refresh_token="..."
+        ... )
+        >>> client = await get_client(credentials)
+        >>> async with client:
+        ...     post = await client.create_post(PostCreateRequest(content="Hello!"))
+    """
+    factory = PlatformFactory()
+    return await factory.get_client(credentials, auto_refresh=auto_refresh)

marqetive/platforms/base.py

@@ -6,6 +6,7 @@ All concrete implementations must implement the abstract methods defined here.
 """
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from datetime import datetime
 from traceback import TracebackException
 from typing import Any
@@ -25,6 +26,10 @@ from marqetive.platforms.models import (
     PostUpdateRequest,
 )
 
+# Type alias for progress callback
+# (operation: str, progress: int, total: int, message: str | None) -> None
+type ProgressCallback = Callable[[str, int, int, str | None], None]
+
 
 class SocialMediaPlatform(ABC):
     """Abstract base class for social media platform integrations.
@@ -57,6 +62,7 @@ class SocialMediaPlatform(ABC):
         credentials: AuthCredentials,
         base_url: str,
         timeout: float = 30.0,
+        progress_callback: ProgressCallback | None = None,
     ) -> None:
         """Initialize the platform client.
 
@@ -65,6 +71,9 @@ class SocialMediaPlatform(ABC):
             credentials: Authentication credentials
             base_url: Base URL for the platform API
             timeout: Request timeout in seconds
+            progress_callback: Optional callback for progress updates during
+                long-running operations (e.g., media uploads). The callback
+                receives (operation, progress, total, message).
 
         Raises:
             PlatformAuthError: If credentials are invalid or expired
@@ -73,6 +82,7 @@ class SocialMediaPlatform(ABC):
         self.credentials = credentials
         self.base_url = base_url
         self.timeout = timeout
+        self._progress_callback = progress_callback
         self.api_client: APIClient | None = None
         self._rate_limit_remaining: int | None = None
         self._rate_limit_reset: datetime | None = None
@@ -152,6 +162,29 @@ class SocialMediaPlatform(ABC):
         self._rate_limit_remaining = remaining
         self._rate_limit_reset = reset_time
 
+    def _emit_progress(
+        self,
+        operation: str,
+        progress: int,
+        total: int,
+        message: str | None = None,
+    ) -> None:
+        """Emit a progress update if a callback is registered.
+
+        This method 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
+
+        Example:
+            >>> self._emit_progress("upload_media", 1, 3, "Uploading image 1 of 3")
+        """
+        if self._progress_callback is not None:
+            self._progress_callback(operation, progress, total, message)
+
     # ==================== Abstract Authentication Methods ====================
 
     @abstractmethod

marqetive/platforms/instagram/__init__.py

@@ -1,7 +1,5 @@
 """Instagram platform integration."""
 
 from marqetive.platforms.instagram.client import InstagramClient
-from marqetive.platforms.instagram.factory import InstagramAccountFactory
-from marqetive.platforms.instagram.manager import InstagramPostManager
 
-__all__ = ["InstagramClient", "InstagramAccountFactory", "InstagramPostManager"]
+__all__ = ["InstagramClient"]

marqetive/platforms/instagram/client.py

@@ -12,7 +12,7 @@ from typing import Any, Literal, cast
 import httpx
 from pydantic import HttpUrl
 
-from marqetive.platforms.base import SocialMediaPlatform
+from marqetive.platforms.base import ProgressCallback, SocialMediaPlatform
 from marqetive.platforms.exceptions import (
     MediaUploadError,
     PlatformAuthError,
@@ -69,6 +69,7 @@ class InstagramClient(SocialMediaPlatform):
         credentials: AuthCredentials,
         timeout: float = 30.0,
         api_version: str = "v21.0",
+        progress_callback: ProgressCallback | None = None,
     ) -> None:
         """Initialize Instagram client.
 
@@ -76,6 +77,8 @@ class InstagramClient(SocialMediaPlatform):
             credentials: Instagram authentication credentials
             timeout: Request timeout in seconds
             api_version: Instagram Graph API version
+            progress_callback: Optional callback for progress updates during
+                long-running operations like media uploads.
 
         Raises:
             PlatformAuthError: If credentials are invalid
@@ -86,6 +89,7 @@ class InstagramClient(SocialMediaPlatform):
             credentials=credentials,
             base_url=base_url,
             timeout=timeout,
+            progress_callback=progress_callback,
         )
         self.instagram_account_id = credentials.user_id
         self.api_version = api_version

marqetive/platforms/linkedin/__init__.py

@@ -1,7 +1,5 @@
 """LinkedIn platform integration."""
 
 from marqetive.platforms.linkedin.client import LinkedInClient
-from marqetive.platforms.linkedin.factory import LinkedInAccountFactory
-from marqetive.platforms.linkedin.manager import LinkedInPostManager
 
-__all__ = ["LinkedInClient", "LinkedInAccountFactory", "LinkedInPostManager"]
+__all__ = ["LinkedInClient"]

marqetive/platforms/linkedin/client.py

@@ -12,7 +12,7 @@ from typing import Any, cast
 import httpx
 from pydantic import HttpUrl
 
-from marqetive.platforms.base import SocialMediaPlatform
+from marqetive.platforms.base import ProgressCallback, SocialMediaPlatform
 from marqetive.platforms.exceptions import (
     MediaUploadError,
     PlatformAuthError,
@@ -66,6 +66,7 @@ class LinkedInClient(SocialMediaPlatform):
         credentials: AuthCredentials,
         timeout: float = 30.0,
         api_version: str = "v2",
+        progress_callback: ProgressCallback | None = None,
     ) -> None:
         """Initialize LinkedIn client.
 
@@ -73,6 +74,8 @@ class LinkedInClient(SocialMediaPlatform):
             credentials: LinkedIn authentication credentials
             timeout: Request timeout in seconds
             api_version: LinkedIn API version
+            progress_callback: Optional callback for progress updates during
+                long-running operations like media uploads.
 
         Raises:
             PlatformAuthError: If credentials are invalid
@@ -83,6 +86,7 @@ class LinkedInClient(SocialMediaPlatform):
             credentials=credentials,
             base_url=base_url,
             timeout=timeout,
+            progress_callback=progress_callback,
         )
         self.author_urn = (
             credentials.user_id