marqetive-lib 0.1.0__py3-none-any.whl

marqetive/utils/media.py

@@ -0,0 +1,399 @@
+"""Media utilities for file validation, MIME type detection, and chunking.
+
+This module provides utilities for working with media files including:
+- MIME type detection using multiple methods
+- File validation (size, type, format)
+- File chunking for large uploads
+- File hashing for integrity verification
+"""
+
+import hashlib
+import mimetypes
+import os
+from collections.abc import AsyncGenerator
+from pathlib import Path
+from typing import Literal
+
+# Initialize mimetypes database
+mimetypes.init()
+
+# Common MIME type mappings
+MIME_TYPE_MAP = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".avi": "video/x-msvideo",
+    ".mkv": "video/x-matroska",
+    ".webm": "video/webm",
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+}
+
+# Magic number signatures for file type detection
+MAGIC_NUMBERS = {
+    b"\xff\xd8\xff": "image/jpeg",
+    b"\x89PNG\r\n\x1a\n": "image/png",
+    b"GIF87a": "image/gif",
+    b"GIF89a": "image/gif",
+    b"RIFF": "image/webp",  # Needs additional check for WEBP
+    b"\x00\x00\x00\x18ftypmp4": "video/mp4",  # Offset at byte 4
+    b"\x00\x00\x00\x1cftypiso": "video/mp4",  # Alternative MP4
+    b"%PDF": "application/pdf",
+}
+
+# Platform-specific file size limits (in bytes)
+PLATFORM_LIMITS = {
+    "twitter": {
+        "image": 5 * 1024 * 1024,  # 5 MB
+        "gif": 15 * 1024 * 1024,  # 15 MB
+        "video": 512 * 1024 * 1024,  # 512 MB
+    },
+    "instagram": {
+        "image": 8 * 1024 * 1024,  # 8 MB
+        "video": 100 * 1024 * 1024,  # 100 MB
+        "reel": 100 * 1024 * 1024,  # 100 MB
+        "story": 100 * 1024 * 1024,  # 100 MB
+    },
+    "linkedin": {
+        "image": 10 * 1024 * 1024,  # 10 MB
+        "video": 200 * 1024 * 1024,  # 200 MB
+        "document": 10 * 1024 * 1024,  # 10 MB
+    },
+    "tiktok": {
+        "video": 4 * 1024 * 1024 * 1024,  # 4 GB
+    },
+}
+
+# Supported media types by platform
+PLATFORM_MEDIA_TYPES = {
+    "twitter": {
+        "image": [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+        "video": [".mp4", ".mov"],
+    },
+    "instagram": {
+        "image": [".jpg", ".jpeg", ".png"],
+        "video": [".mp4", ".mov"],
+    },
+    "linkedin": {
+        "image": [".jpg", ".jpeg", ".png", ".gif"],
+        "video": [".mp4", ".mov", ".avi", ".webm"],
+        "document": [".pdf", ".doc", ".docx", ".ppt", ".pptx"],
+    },
+    "tiktok": {
+        "video": [".mp4", ".mov", ".webm"],
+    },
+}
+
+
+class MediaValidator:
+    """Validator for media files with platform-specific rules."""
+
+    def __init__(
+        self,
+        platform: Literal["twitter", "instagram", "linkedin", "tiktok"],
+        media_type: Literal["image", "video", "document", "gif", "reel", "story"],
+    ) -> None:
+        """Initialize the media validator.
+
+        Args:
+            platform: Target platform name.
+            media_type: Type of media being validated.
+        """
+        self.platform = platform
+        self.media_type = media_type
+        self.max_size = PLATFORM_LIMITS.get(platform, {}).get(media_type, 0)
+        self.allowed_extensions = PLATFORM_MEDIA_TYPES.get(platform, {}).get(
+            media_type, []
+        )
+
+    def validate(self, file_path: str) -> tuple[bool, str | None]:
+        """Validate a media file.
+
+        Args:
+            file_path: Path to the file to validate.
+
+        Returns:
+            Tuple of (is_valid, error_message). If valid, error_message is None.
+        """
+        # Check file exists
+        if not os.path.exists(file_path):
+            return False, f"File not found: {file_path}"
+
+        # Check file extension
+        extension = Path(file_path).suffix.lower()
+        if extension not in self.allowed_extensions:
+            return (
+                False,
+                f"Invalid file type '{extension}' for {self.platform} "
+                f"{self.media_type}. Allowed: {', '.join(self.allowed_extensions)}",
+            )
+
+        # Check file size
+        file_size = os.path.getsize(file_path)
+        if self.max_size and file_size > self.max_size:
+            max_mb = self.max_size / (1024 * 1024)
+            actual_mb = file_size / (1024 * 1024)
+            return (
+                False,
+                f"File size {actual_mb:.2f}MB exceeds {self.platform} "
+                f"{self.media_type} limit of {max_mb:.2f}MB",
+            )
+
+        # Check MIME type matches extension
+        detected_mime = detect_mime_type(file_path)
+        expected_mime = MIME_TYPE_MAP.get(extension)
+        if expected_mime and detected_mime != expected_mime:
+            return (
+                False,
+                f"File content type '{detected_mime}' doesn't match "
+                f"extension '{extension}' (expected '{expected_mime}')",
+            )
+
+        return True, None
+
+
+def detect_mime_type(file_path: str) -> str:
+    """Detect MIME type of a file using multiple methods.
+
+    Uses a combination of:
+    1. Magic number (file signature) detection
+    2. Extension-based lookup
+    3. Python's mimetypes module
+
+    Args:
+        file_path: Path to the file.
+
+    Returns:
+        MIME type string (e.g., 'image/jpeg').
+
+    Example:
+        >>> mime_type = detect_mime_type('/path/to/image.jpg')
+        >>> print(mime_type)
+        image/jpeg
+    """
+    # Try magic number detection first (most reliable)
+    try:
+        with open(file_path, "rb") as f:
+            header = f.read(32)  # Read first 32 bytes
+
+            # Check for magic numbers
+            for magic, mime_type in MAGIC_NUMBERS.items():
+                if header.startswith(magic):
+                    # Special case for WEBP
+                    if magic == b"RIFF" and b"WEBP" in header[:16]:
+                        return "image/webp"
+                    if "ftyp" not in magic.decode("latin-1", errors="ignore"):
+                        return mime_type
+
+            # Check for MP4 variants (ftyp at offset 4)
+            if len(header) >= 12:
+                ftyp_check = header[4:12]
+                if b"ftyp" in ftyp_check:
+                    return "video/mp4"
+
+    except OSError:
+        pass
+
+    # Try extension-based lookup
+    extension = Path(file_path).suffix.lower()
+    if extension in MIME_TYPE_MAP:
+        return MIME_TYPE_MAP[extension]
+
+    # Fall back to mimetypes module
+    mime_type, _ = mimetypes.guess_type(file_path)
+    return mime_type or "application/octet-stream"
+
+
+def validate_file_size(
+    file_path: str, max_size: int, *, raise_error: bool = False
+) -> bool:
+    """Validate that a file doesn't exceed the maximum size.
+
+    Args:
+        file_path: Path to the file.
+        max_size: Maximum size in bytes.
+        raise_error: If True, raise ValueError instead of returning False.
+
+    Returns:
+        True if file size is within limit, False otherwise.
+
+    Raises:
+        ValueError: If file exceeds size limit and raise_error=True.
+        FileNotFoundError: If file doesn't exist.
+
+    Example:
+        >>> is_valid = validate_file_size('image.jpg', 5 * 1024 * 1024)
+        >>> if not is_valid:
+        ...     print("File too large")
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    file_size = os.path.getsize(file_path)
+
+    if file_size > max_size:
+        if raise_error:
+            max_mb = max_size / (1024 * 1024)
+            actual_mb = file_size / (1024 * 1024)
+            raise ValueError(
+                f"File size {actual_mb:.2f}MB exceeds limit of {max_mb:.2f}MB"
+            )
+        return False
+
+    return True
+
+
+def validate_media_type(
+    file_path: str, allowed_types: list[str], *, raise_error: bool = False
+) -> bool:
+    """Validate that a file is one of the allowed media types.
+
+    Args:
+        file_path: Path to the file.
+        allowed_types: List of allowed MIME types or extensions.
+        raise_error: If True, raise ValueError instead of returning False.
+
+    Returns:
+        True if file type is allowed, False otherwise.
+
+    Raises:
+        ValueError: If file type not allowed and raise_error=True.
+
+    Example:
+        >>> allowed = ['image/jpeg', 'image/png', '.jpg', '.png']
+        >>> is_valid = validate_media_type('photo.jpg', allowed)
+        >>> print(is_valid)
+        True
+    """
+    mime_type = detect_mime_type(file_path)
+    extension = Path(file_path).suffix.lower()
+
+    # Check against both MIME types and extensions
+    is_allowed = mime_type in allowed_types or extension in allowed_types
+
+    if not is_allowed and raise_error:
+        raise ValueError(
+            f"File type '{mime_type}' (extension '{extension}') not allowed. "
+            f"Allowed types: {', '.join(allowed_types)}"
+        )
+
+    return is_allowed
+
+
+async def chunk_file(
+    file_path: str, chunk_size: int = 1024 * 1024
+) -> AsyncGenerator[bytes, None]:
+    """Asynchronously read file in chunks.
+
+    Yields file content in chunks of specified size. Useful for uploading
+    large files without loading entire file into memory.
+
+    Args:
+        file_path: Path to the file.
+        chunk_size: Size of each chunk in bytes (default: 1MB).
+
+    Yields:
+        Bytes chunks of the file.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+
+    Example:
+        >>> async for chunk in chunk_file('large_video.mp4', chunk_size=5*1024*1024):
+        ...     await upload_chunk(chunk)
+    """
+    import aiofiles
+
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    async with aiofiles.open(file_path, "rb") as f:
+        while True:
+            chunk = await f.read(chunk_size)
+            if not chunk:
+                break
+            yield chunk
+
+
+def get_file_hash(file_path: str, algorithm: str = "sha256") -> str:
+    """Calculate hash of a file for integrity verification.
+
+    Args:
+        file_path: Path to the file.
+        algorithm: Hash algorithm to use (default: 'sha256').
+
+    Returns:
+        Hexadecimal hash string.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+
+    Example:
+        >>> file_hash = get_file_hash('document.pdf')
+        >>> print(file_hash)
+        a1b2c3d4e5f6...
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    hash_obj = hashlib.new(algorithm)
+
+    with open(file_path, "rb") as f:
+        # Read in chunks to handle large files
+        for chunk in iter(lambda: f.read(8192), b""):
+            hash_obj.update(chunk)
+
+    return hash_obj.hexdigest()
+
+
+def format_file_size(size_bytes: int) -> str:
+    """Format file size in human-readable format.
+
+    Args:
+        size_bytes: File size in bytes.
+
+    Returns:
+        Formatted string (e.g., '1.5 MB').
+
+    Example:
+        >>> size = format_file_size(1536000)
+        >>> print(size)
+        1.46 MB
+    """
+    size: float = float(size_bytes)
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if size < 1024.0:
+            return f"{size:.2f} {unit}"
+        size /= 1024.0
+    return f"{size:.2f} PB"
+
+
+def get_chunk_count(file_path: str, chunk_size: int) -> int:
+    """Calculate number of chunks needed to upload a file.
+
+    Args:
+        file_path: Path to the file.
+        chunk_size: Size of each chunk in bytes.
+
+    Returns:
+        Number of chunks needed.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+
+    Example:
+        >>> chunks = get_chunk_count('video.mp4', 5 * 1024 * 1024)
+        >>> print(f"Will upload in {chunks} chunks")
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    file_size = os.path.getsize(file_path)
+    return (file_size + chunk_size - 1) // chunk_size  # Ceiling division

marqetive/utils/oauth.py

@@ -0,0 +1,265 @@
+"""OAuth token refresh utilities for social media platforms.
+
+This module provides utilities for refreshing OAuth2 access tokens across
+different social media platforms.
+"""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Any
+
+import httpx
+
+from marqetive.platforms.exceptions import PlatformAuthError
+from marqetive.platforms.models import AuthCredentials
+
+logger = logging.getLogger(__name__)
+
+
+async def refresh_oauth2_token(
+    refresh_token: str,
+    client_id: str,
+    client_secret: str,
+    token_url: str,
+    additional_params: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Refresh an OAuth2 access token.
+
+    Generic OAuth2 token refresh implementation that works with most providers.
+
+    Args:
+        refresh_token: The refresh token.
+        client_id: OAuth client ID.
+        client_secret: OAuth client secret.
+        token_url: Token endpoint URL.
+        additional_params: Additional parameters to include in request.
+
+    Returns:
+        Token response dictionary with access_token, expires_in, etc.
+
+    Raises:
+        PlatformAuthError: If token refresh fails.
+
+    Example:
+        >>> token_data = await refresh_oauth2_token(
+        ...     refresh_token="refresh_token_here",
+        ...     client_id="my_client_id",
+        ...     client_secret="my_client_secret",
+        ...     token_url="https://oauth.example.com/token"
+        ... )
+        >>> print(token_data["access_token"])
+    """
+    params = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+        "client_secret": client_secret,
+    }
+
+    if additional_params:
+        params.update(additional_params)
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                token_url,
+                data=params,
+                headers={"Content-Type": "application/x-www-form-urlencoded"},
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            return response.json()
+
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error refreshing token: {e.response.status_code}")
+        raise PlatformAuthError(
+            f"Failed to refresh token: {e.response.text}",
+            platform="oauth2",
+            status_code=e.response.status_code,
+        ) from e
+
+    except httpx.HTTPError as e:
+        logger.error(f"Network error refreshing token: {e}")
+        raise PlatformAuthError(
+            f"Network error refreshing token: {e}",
+            platform="oauth2",
+        ) from e
+
+
+async def refresh_twitter_token(
+    credentials: AuthCredentials,
+    client_id: str,
+    client_secret: str,
+) -> AuthCredentials:
+    """Refresh Twitter OAuth2 access token.
+
+    Args:
+        credentials: Current credentials with refresh token.
+        client_id: Twitter OAuth client ID.
+        client_secret: Twitter OAuth client secret.
+
+    Returns:
+        Updated credentials with new access token.
+
+    Raises:
+        PlatformAuthError: If refresh fails.
+
+    Example:
+        >>> import os
+        >>> creds = AuthCredentials(
+        ...     platform="twitter",
+        ...     access_token="old_token",
+        ...     refresh_token="refresh_token_here"
+        ... )
+        >>> refreshed = await refresh_twitter_token(
+        ...     creds,
+        ...     os.getenv("TWITTER_CLIENT_ID"),
+        ...     os.getenv("TWITTER_CLIENT_SECRET")
+        ... )
+    """
+    if not credentials.refresh_token:
+        raise PlatformAuthError(
+            "No refresh token available",
+            platform="twitter",
+        )
+
+    token_url = "https://api.x.com/2/oauth2/token"
+
+    token_data = await refresh_oauth2_token(
+        refresh_token=credentials.refresh_token,
+        client_id=client_id,
+        client_secret=client_secret,
+        token_url=token_url,
+    )
+
+    # Update credentials
+    credentials.access_token = token_data["access_token"]
+
+    # Update refresh token if provided
+    if "refresh_token" in token_data:
+        credentials.refresh_token = token_data["refresh_token"]
+
+    # Calculate expiry
+    if "expires_in" in token_data:
+        expires_in = int(token_data["expires_in"])
+        credentials.expires_at = datetime.now() + timedelta(seconds=expires_in)
+
+    return credentials
+
+
+async def refresh_linkedin_token(
+    credentials: AuthCredentials,
+    client_id: str,
+    client_secret: str,
+) -> AuthCredentials:
+    """Refresh LinkedIn OAuth2 access token.
+
+    Args:
+        credentials: Current credentials with refresh token.
+        client_id: LinkedIn OAuth client ID.
+        client_secret: LinkedIn OAuth client secret.
+
+    Returns:
+        Updated credentials with new access token.
+
+    Raises:
+        PlatformAuthError: If refresh fails.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="linkedin",
+        ...     access_token="old_token",
+        ...     refresh_token="refresh_token_here"
+        ... )
+        >>> refreshed = await refresh_linkedin_token(creds, client_id, client_secret)
+    """
+    if not credentials.refresh_token:
+        raise PlatformAuthError(
+            "No refresh token available",
+            platform="linkedin",
+        )
+
+    token_url = "https://www.linkedin.com/oauth/v2/accessToken"
+
+    token_data = await refresh_oauth2_token(
+        refresh_token=credentials.refresh_token,
+        client_id=client_id,
+        client_secret=client_secret,
+        token_url=token_url,
+    )
+
+    # Update credentials
+    credentials.access_token = token_data["access_token"]
+
+    # LinkedIn might provide new refresh token
+    if "refresh_token" in token_data:
+        credentials.refresh_token = token_data["refresh_token"]
+
+    # Calculate expiry
+    if "expires_in" in token_data:
+        expires_in = int(token_data["expires_in"])
+        credentials.expires_at = datetime.now() + timedelta(seconds=expires_in)
+
+    return credentials
+
+
+async def refresh_instagram_token(
+    credentials: AuthCredentials,
+) -> AuthCredentials:
+    """Refresh Instagram long-lived access token.
+
+    Instagram uses a different refresh mechanism - exchanging the current
+    long-lived token for a new one.
+
+    Args:
+        credentials: Current credentials.
+
+    Returns:
+        Updated credentials with refreshed token.
+
+    Raises:
+        PlatformAuthError: If refresh fails.
+
+    Example:
+        >>> creds = AuthCredentials(
+        ...     platform="instagram",
+        ...     access_token="current_token"
+        ... )
+        >>> refreshed = await refresh_instagram_token(creds)
+    """
+    url = "https://graph.instagram.com/refresh_access_token"
+    params = {
+        "grant_type": "ig_refresh_token",
+        "access_token": credentials.access_token,
+    }
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(url, params=params, timeout=30.0)
+            response.raise_for_status()
+            data = response.json()
+
+            # Update credentials
+            credentials.access_token = data["access_token"]
+
+            # Instagram returns expires_in
+            if "expires_in" in data:
+                expires_in = int(data["expires_in"])
+                credentials.expires_at = datetime.now() + timedelta(seconds=expires_in)
+
+            return credentials
+
+    except httpx.HTTPStatusError as e:
+        logger.error(f"HTTP error refreshing Instagram token: {e.response.status_code}")
+        raise PlatformAuthError(
+            f"Failed to refresh Instagram token: {e.response.text}",
+            platform="instagram",
+            status_code=e.response.status_code,
+        ) from e
+
+    except httpx.HTTPError as e:
+        logger.error(f"Network error refreshing Instagram token: {e}")
+        raise PlatformAuthError(
+            f"Network error refreshing Instagram token: {e}",
+            platform="instagram",
+        ) from e