marqetive-lib 0.1.20__tar.gz → 0.1.22__tar.gz

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marqetive-lib
-Version: 0.1.20
+Version: 0.1.22
 Summary: Modern Python utilities for web APIs
 Keywords: api,utilities,web,http,marqetive
 Requires-Python: >=3.12

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [project]
 name = "marqetive-lib"
-version = "0.1.20"
+version = "0.1.22"
 description = "Modern Python utilities for web APIs"
 readme = "README.md"
 requires-python = ">=3.12"

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/__init__.py

@@ -56,6 +56,10 @@ from marqetive.core.models import (
     AuthCredentials,
     Comment,
     CommentStatus,
+    Conversation,
+    DirectMessage,
+    DMCreateRequest,
+    GroupDMCreateRequest,
     MediaAttachment,
     MediaType,
     Post,
@@ -102,6 +106,11 @@ __all__ = [
     # Base Request Models
     "PostCreateRequest",
     "PostUpdateRequest",
+    # Direct Message Models
+    "DMCreateRequest",
+    "GroupDMCreateRequest",
+    "DirectMessage",
+    "Conversation",
     # Exceptions
     "PlatformError",
     "PlatformAuthError",

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/core/base.py

@@ -20,6 +20,10 @@ from marqetive.core.exceptions import (
 from marqetive.core.models import (
     AuthCredentials,
     Comment,
+    Conversation,
+    DirectMessage,
+    DMCreateRequest,
+    GroupDMCreateRequest,
     MediaAttachment,
     PlatformResponse,
     Post,
@@ -418,6 +422,77 @@ class SocialMediaPlatform(ABC):
             f"{self.platform_name} does not support thread creation"
         )
 
+    # ==================== Direct Message Methods ====================
+
+    async def send_direct_message(
+        self,
+        request: DMCreateRequest,
+    ) -> DirectMessage:
+        """Send a direct message to a user or conversation.
+
+        Not all platforms support direct messaging. The default implementation
+        raises NotImplementedError. Platforms that support DMs (like Twitter)
+        should override this method.
+
+        Args:
+            request: DM creation request with text and recipient info.
+                Must provide either participant_id (for new 1-to-1 DM)
+                or conversation_id (for existing conversation).
+
+        Returns:
+            DirectMessage object with message ID and metadata.
+
+        Raises:
+            NotImplementedError: If platform doesn't support DMs.
+            ValidationError: If request is invalid (missing recipient, text too long).
+            PlatformAuthError: If not authenticated or unauthorized.
+            MediaUploadError: If media attachment fails.
+
+        Example:
+            >>> request = DMCreateRequest(
+            ...     text="Hello!",
+            ...     participant_id="user123"
+            ... )
+            >>> dm = await client.send_direct_message(request)
+            >>> print(f"Sent: {dm.message_id}")
+        """
+        raise NotImplementedError(
+            f"{self.platform_name} does not support direct messages"
+        )
+
+    async def create_group_conversation(
+        self,
+        request: GroupDMCreateRequest,
+    ) -> Conversation:
+        """Create a group DM conversation with an initial message.
+
+        Not all platforms support group DMs. The default implementation
+        raises NotImplementedError. Platforms that support group DMs
+        should override this method.
+
+        Args:
+            request: Group DM request with participant IDs and initial message.
+
+        Returns:
+            Conversation object with conversation ID and participant info.
+
+        Raises:
+            NotImplementedError: If platform doesn't support group DMs.
+            ValidationError: If request is invalid (too few/many participants).
+            PlatformAuthError: If not authenticated or unauthorized.
+
+        Example:
+            >>> request = GroupDMCreateRequest(
+            ...     participant_ids=["user1", "user2", "user3"],
+            ...     text="Welcome to the group!"
+            ... )
+            >>> conversation = await client.create_group_conversation(request)
+            >>> print(f"Created: {conversation.conversation_id}")
+        """
+        raise NotImplementedError(
+            f"{self.platform_name} does not support group conversations"
+        )
+
     # ==================== Abstract Comment Methods ====================
 
     @abstractmethod

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/core/exceptions.py

@@ -47,15 +47,44 @@ class PlatformAuthError(PlatformError):
     - OAuth flow encounters errors
     - Insufficient permissions for requested operation
 
+    Args:
+        message: Human-readable error message
+        platform: Name of the platform where error occurred
+        status_code: HTTP status code if applicable
+        requires_reconnection: If True, user must re-authenticate (token permanently invalid)
+
     Example:
         >>> raise PlatformAuthError(
         ...     "Access token expired",
         ...     platform="twitter",
         ...     status_code=401
         ... )
+        >>> # For invalid refresh token requiring user re-auth:
+        >>> raise PlatformAuthError(
+        ...     "Refresh token invalid",
+        ...     platform="twitter",
+        ...     status_code=400,
+        ...     requires_reconnection=True
+        ... )
     """
 
-    pass
+    def __init__(
+        self,
+        message: str,
+        platform: str | None = None,
+        status_code: int | None = None,
+        *,
+        requires_reconnection: bool = False,
+    ) -> None:
+        self.requires_reconnection = requires_reconnection
+        super().__init__(message, platform, status_code)
+
+    def _format_message(self) -> str:
+        """Format the error message with reconnection info."""
+        base_message = super()._format_message()
+        if self.requires_reconnection:
+            return f"{base_message} | Reconnection required"
+        return base_message
 
 
 class RateLimitError(PlatformError):

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/core/models.py

@@ -7,7 +7,7 @@ and type safety.
 
 from datetime import UTC, datetime, timedelta
 from enum import Enum, StrEnum
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, HttpUrl
 
@@ -451,3 +451,137 @@ class PostUpdateRequest(BaseModel):
     content: str | None = None
     tags: list[str] | None = None
     location: str | None = None
+
+
+# ==================== Direct Message Models ====================
+
+
+class DMCreateRequest(BaseModel):
+    """Base request model for sending a direct message.
+
+    Supports sending DMs to individuals or existing conversations.
+    For platform-specific features, use dedicated request models like TwitterDMRequest.
+
+    Attributes:
+        text: Message content (required, max length varies by platform)
+        participant_id: User ID for new 1-to-1 conversation
+        conversation_id: ID of existing conversation (1-1 or group)
+        media_url: URL to media file to attach (single attachment)
+        media_id: Pre-uploaded media ID
+        additional_data: Platform-specific data
+
+    Example:
+        >>> # Send 1-to-1 DM
+        >>> request = DMCreateRequest(
+        ...     text="Hello!",
+        ...     participant_id="1234567890"
+        ... )
+
+        >>> # Send to existing conversation
+        >>> request = DMCreateRequest(
+        ...     text="Following up...",
+        ...     conversation_id="dm_conv_123"
+        ... )
+    """
+
+    text: str
+    participant_id: str | None = None
+    conversation_id: str | None = None
+    media_url: str | None = None
+    media_id: str | None = None
+    additional_data: dict[str, Any] = Field(default_factory=dict)
+
+
+class GroupDMCreateRequest(BaseModel):
+    """Request model for creating a group conversation with initial message.
+
+    Creates a new group DM conversation with multiple participants and sends
+    an initial message to the group.
+
+    Attributes:
+        participant_ids: List of user IDs to include in group (platform limits vary)
+        text: Initial message content (required)
+        media_url: Optional media URL to attach
+        media_id: Optional pre-uploaded media ID
+        additional_data: Platform-specific data
+
+    Example:
+        >>> request = GroupDMCreateRequest(
+        ...     participant_ids=["user1_id", "user2_id", "user3_id"],
+        ...     text="Welcome to the group!"
+        ... )
+    """
+
+    participant_ids: list[str] = Field(min_length=2)
+    text: str
+    media_url: str | None = None
+    media_id: str | None = None
+    additional_data: dict[str, Any] = Field(default_factory=dict)
+
+
+class DirectMessage(BaseModel):
+    """Universal representation of a direct message.
+
+    Provides a consistent interface for DMs across platforms that support messaging.
+
+    Attributes:
+        message_id: Platform-specific message identifier
+        conversation_id: ID of the conversation this message belongs to
+        platform: Name of the platform (twitter, etc.)
+        text: Message content
+        sender_id: ID of the user who sent the message
+        created_at: Timestamp when message was sent
+        media: Optional media attachment
+        raw_data: Original platform-specific response data
+
+    Example:
+        >>> dm = DirectMessage(
+        ...     message_id="dm_event_123",
+        ...     conversation_id="dm_conv_456",
+        ...     platform="twitter",
+        ...     text="Hello!",
+        ...     sender_id="user789",
+        ...     created_at=datetime.now()
+        ... )
+    """
+
+    message_id: str
+    conversation_id: str
+    platform: str
+    text: str
+    sender_id: str | None = None
+    created_at: datetime
+    media: MediaAttachment | None = None
+    raw_data: dict[str, Any] = Field(default_factory=dict)
+
+
+class Conversation(BaseModel):
+    """Universal representation of a DM conversation.
+
+    Represents a direct message conversation (1-to-1 or group) on platforms
+    that support messaging.
+
+    Attributes:
+        conversation_id: Platform-specific conversation identifier
+        platform: Name of the platform
+        conversation_type: Type of conversation ("group" or "one_to_one")
+        participant_ids: List of participant user IDs
+        created_at: Timestamp when conversation was created
+        raw_data: Original platform-specific response data
+
+    Example:
+        >>> conversation = Conversation(
+        ...     conversation_id="dm_conv_123",
+        ...     platform="twitter",
+        ...     conversation_type="group",
+        ...     participant_ids=["user1", "user2", "user3"],
+        ...     created_at=datetime.now()
+        ... )
+    """
+
+    conversation_id: str
+    platform: str
+    conversation_type: Literal["group", "one_to_one"]
+    participant_ids: list[str] = Field(default_factory=list)
+    created_at: datetime
+    raw_data: dict[str, Any] = Field(default_factory=dict)

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/factory.py

@@ -25,6 +25,24 @@ logger = logging.getLogger(__name__)
 # Supported platforms
 SUPPORTED_PLATFORMS = frozenset({"twitter", "linkedin", "instagram", "tiktok"})
 
+# Platform aliases (alternative names that map to canonical names)
+PLATFORM_ALIASES: dict[str, str] = {
+    "x": "twitter",
+}
+
+
+def normalize_platform(platform: str) -> str:
+    """Normalize platform name to canonical form.
+
+    Args:
+        platform: Platform name (may be an alias like 'x').
+
+    Returns:
+        Canonical platform name (e.g., 'twitter').
+    """
+    platform = platform.lower()
+    return PLATFORM_ALIASES.get(platform, platform)
+
 
 def _create_client(
     platform: str, credentials: "AuthCredentials"
@@ -172,7 +190,12 @@ class PlatformFactory:
             >>> async with client:
             ...     post = await client.create_post(request)
         """
-        platform = credentials.platform.lower()
+        # Normalize platform name (handle aliases like 'x' -> 'twitter')
+        platform = normalize_platform(credentials.platform)
+
+        # Update credentials with normalized platform name
+        if platform != credentials.platform.lower():
+            credentials.platform = platform
 
         # Validate platform-specific requirements
         self._validate_credentials(credentials)
@@ -180,8 +203,17 @@ class PlatformFactory:
         # 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()
+            try:
+                credentials = await self._refresh_token(credentials)
+                credentials.mark_valid()
+            except PlatformAuthError as e:
+                # If refresh failed and requires reconnection, update credentials status
+                if e.requires_reconnection:
+                    credentials.mark_reconnection_required()
+                    logger.warning(
+                        f"Token refresh for {platform} requires user reconnection"
+                    )
+                raise
 
         # Enrich credentials with API keys for Twitter (needed for media operations)
         if platform == "twitter":
@@ -337,9 +369,9 @@ class PlatformFactory:
         """Get the set of supported platform names.
 
         Returns:
-            Frozenset of supported platform names.
+            Frozenset of supported platform names (includes aliases).
         """
-        return SUPPORTED_PLATFORMS
+        return SUPPORTED_PLATFORMS | frozenset(PLATFORM_ALIASES.keys())
 
 
 async def get_client(

marqetive_lib-0.1.22/src/marqetive/platforms/twitter/__init__.py

@@ -0,0 +1,15 @@
+"""Twitter/X platform integration."""
+
+from marqetive.platforms.twitter.client import TwitterClient
+from marqetive.platforms.twitter.models import (
+    TwitterDMRequest,
+    TwitterGroupDMRequest,
+    TwitterPostRequest,
+)
+
+__all__ = [
+    "TwitterClient",
+    "TwitterPostRequest",
+    "TwitterDMRequest",
+    "TwitterGroupDMRequest",
+]

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/platforms/twitter/client.py

@@ -26,6 +26,10 @@ from marqetive.core.models import (
     AuthCredentials,
     Comment,
     CommentStatus,
+    Conversation,
+    DirectMessage,
+    DMCreateRequest,
+    GroupDMCreateRequest,
     MediaAttachment,
     MediaType,
     Post,
@@ -34,8 +38,8 @@ from marqetive.core.models import (
     PostUpdateRequest,
     ProgressStatus,
 )
-from marqetive.platforms.twitter.media import TwitterMediaManager
-from marqetive.platforms.twitter.models import TwitterPostRequest
+from marqetive.platforms.twitter.media import MediaCategory, TwitterMediaManager
+from marqetive.platforms.twitter.models import TwitterDMRequest, TwitterPostRequest
 
 
 class TwitterClient(SocialMediaPlatform):
@@ -755,6 +759,346 @@ class TwitterClient(SocialMediaPlatform):
 
         return created_posts
 
+    # ==================== Direct Message Methods ====================
+
+    def _validate_dm_request(
+        self,
+        request: DMCreateRequest | TwitterDMRequest,
+    ) -> None:
+        """Validate DM request.
+
+        Twitter DM Requirements:
+            - Must have text content (required)
+            - Text max 10,000 characters
+            - Must have either participant_id OR conversation_id (not both)
+            - Max 1 media attachment
+
+        Args:
+            request: DM request to validate.
+
+        Raises:
+            ValidationError: If validation fails.
+        """
+        if not request.text:
+            raise ValidationError(
+                "DM text content is required",
+                platform=self.platform_name,
+                field="text",
+            )
+
+        if len(request.text) > 10000:
+            raise ValidationError(
+                f"DM text exceeds 10,000 characters ({len(request.text)} characters)",
+                platform=self.platform_name,
+                field="text",
+            )
+
+        # Must have exactly one of participant_id or conversation_id
+        has_participant = request.participant_id is not None
+        has_conversation = request.conversation_id is not None
+
+        if not has_participant and not has_conversation:
+            raise ValidationError(
+                "Either participant_id or conversation_id is required",
+                platform=self.platform_name,
+                field="participant_id",
+            )
+
+        if has_participant and has_conversation:
+            raise ValidationError(
+                "Cannot specify both participant_id and conversation_id",
+                platform=self.platform_name,
+                field="conversation_id",
+            )
+
+    async def _upload_dm_media(
+        self,
+        media_url: str,
+        alt_text: str | None = None,
+    ) -> MediaAttachment:
+        """Upload media for DM attachment.
+
+        Uses DM-specific media category for proper Twitter processing.
+
+        Args:
+            media_url: URL or file path of media.
+            alt_text: Optional alt text for accessibility.
+
+        Returns:
+            MediaAttachment with media ID.
+
+        Raises:
+            MediaUploadError: If upload fails.
+        """
+        if not self._media_manager:
+            raise RuntimeError("Client must be used as async context manager")
+
+        try:
+            # Detect media type and use appropriate DM category
+            from marqetive.utils.media import detect_mime_type
+
+            # Determine DM-specific media category based on file type
+            if media_url.startswith(("http://", "https://")):
+                # Default to DM_IMAGE for URLs (will be validated by Twitter)
+                category = MediaCategory.DM_IMAGE
+            else:
+                mime_type = detect_mime_type(media_url)
+                if "video" in mime_type:
+                    category = MediaCategory.DM_VIDEO
+                elif "gif" in mime_type:
+                    category = MediaCategory.DM_GIF
+                else:
+                    category = MediaCategory.DM_IMAGE
+
+            result = await self._media_manager.upload_media(
+                media_url,
+                media_category=category,
+                alt_text=alt_text,
+            )
+
+            return MediaAttachment(
+                media_id=result.media_id,
+                media_type=MediaType.IMAGE,  # Simplified type
+                url=HttpUrl(media_url)
+                if media_url.startswith("http")
+                else HttpUrl(f"file://{media_url}"),
+            )
+
+        except Exception as e:
+            raise MediaUploadError(
+                f"Failed to upload DM media: {e}",
+                platform=self.platform_name,
+            ) from e
+
+    async def send_direct_message(
+        self,
+        request: DMCreateRequest,
+    ) -> DirectMessage:
+        """Send a direct message on Twitter.
+
+        Supports both 1-to-1 DMs (new conversations) and messages to existing
+        conversations (including groups). Optionally attach a single media file.
+
+        Twitter Requirements:
+            - Text required (max 10,000 characters)
+            - Either participant_id (new 1-to-1) or conversation_id (existing)
+            - Max 1 media attachment per DM
+
+        Args:
+            request: DM creation request. Supports:
+                - text: Message content (required, max 10,000 chars)
+                - participant_id: User ID for new 1-to-1 DM
+                - conversation_id: Existing conversation ID
+                - media_url: URL of media to attach
+                - media_id: Pre-uploaded media ID
+
+        Returns:
+            DirectMessage object with:
+                - message_id: Twitter DM event ID
+                - conversation_id: Conversation ID
+                - platform: "twitter"
+                - text: Message content
+                - sender_id: Authenticated user ID (if available)
+                - created_at: Timestamp
+                - media: Attached media (if any)
+                - raw_data: Full API response
+
+        Raises:
+            ValidationError: If request is invalid.
+            MediaUploadError: If media upload fails.
+            RateLimitError: If Twitter rate limit exceeded.
+            PlatformError: For other Twitter API errors.
+            RuntimeError: If client not used as context manager.
+
+        Example:
+            >>> async with TwitterClient(credentials) as client:
+            ...     request = DMCreateRequest(
+            ...         text="Hello!",
+            ...         participant_id="1234567890"
+            ...     )
+            ...     dm = await client.send_direct_message(request)
+            ...     print(f"Sent DM: {dm.message_id}")
+        """
+        if not self._tweepy_client:
+            raise RuntimeError("Client must be used as async context manager")
+
+        # Validate request
+        self._validate_dm_request(request)
+
+        try:
+            # Handle media upload if provided
+            media_id = request.media_id
+            if request.media_url and not media_id:
+                media_attachment = await self._upload_dm_media(request.media_url)
+                media_id = media_attachment.media_id
+
+            # Build DM parameters
+            dm_params: dict[str, Any] = {"text": request.text}
+
+            if request.participant_id:
+                dm_params["participant_id"] = request.participant_id
+            elif request.conversation_id:
+                dm_params["dm_conversation_id"] = request.conversation_id
+
+            if media_id:
+                dm_params["media_id"] = media_id
+
+            # Send DM using tweepy
+            response = self._tweepy_client.create_direct_message(
+                **dm_params,
+                user_auth=False,
+            )
+
+            # Parse response
+            dm_data = response.data  # type: ignore[attr-defined]
+
+            return DirectMessage(
+                message_id=str(dm_data["dm_event_id"]),
+                conversation_id=str(dm_data["dm_conversation_id"]),
+                platform=self.platform_name,
+                text=request.text,
+                sender_id=self.credentials.user_id,
+                created_at=datetime.now(),
+                media=None,  # Media info not returned in create response
+                raw_data=dm_data,
+            )
+
+        except tweepy.TweepyException as e:
+            if "429" in str(e):
+                raise RateLimitError(
+                    "Twitter rate limit exceeded",
+                    platform=self.platform_name,
+                    status_code=429,
+                ) from e
+            if "403" in str(e) or "401" in str(e):
+                raise PlatformAuthError(
+                    f"Not authorized to send DM: {e}",
+                    platform=self.platform_name,
+                ) from e
+            raise PlatformError(
+                f"Failed to send direct message: {e}",
+                platform=self.platform_name,
+            ) from e
+
+    async def create_group_conversation(
+        self,
+        request: GroupDMCreateRequest,
+    ) -> Conversation:
+        """Create a Twitter group DM conversation with initial message.
+
+        Creates a new group conversation with 2-49 other participants
+        and sends an initial message to the group.
+
+        Args:
+            request: Group DM request with:
+                - participant_ids: List of user IDs (2-49 participants)
+                - text: Initial message text (required, max 10,000 chars)
+                - media_url: Optional media URL
+                - media_id: Optional pre-uploaded media ID
+
+        Returns:
+            Conversation object with:
+                - conversation_id: Twitter conversation ID
+                - platform: "twitter"
+                - conversation_type: "group"
+                - participant_ids: List of participant IDs
+                - created_at: Timestamp
+                - raw_data: Full API response
+
+        Raises:
+            ValidationError: If request is invalid.
+            MediaUploadError: If media upload fails.
+            RateLimitError: If rate limit exceeded.
+            PlatformError: For other API errors.
+            RuntimeError: If client not used as context manager.
+
+        Example:
+            >>> async with TwitterClient(credentials) as client:
+            ...     request = GroupDMCreateRequest(
+            ...         participant_ids=["user1", "user2"],
+            ...         text="Welcome to the group!"
+            ...     )
+            ...     conv = await client.create_group_conversation(request)
+            ...     print(f"Created group: {conv.conversation_id}")
+        """
+        if not self._tweepy_client:
+            raise RuntimeError("Client must be used as async context manager")
+
+        # Validate participant count
+        if len(request.participant_ids) < 2:
+            raise ValidationError(
+                "Group conversation requires at least 2 participants",
+                platform=self.platform_name,
+                field="participant_ids",
+            )
+
+        if len(request.participant_ids) > 49:
+            raise ValidationError(
+                "Group conversation cannot exceed 49 participants",
+                platform=self.platform_name,
+                field="participant_ids",
+            )
+
+        # Validate text
+        if not request.text:
+            raise ValidationError(
+                "Initial message text is required",
+                platform=self.platform_name,
+                field="text",
+            )
+
+        if len(request.text) > 10000:
+            raise ValidationError(
+                f"Message text exceeds 10,000 characters ({len(request.text)} chars)",
+                platform=self.platform_name,
+                field="text",
+            )
+
+        try:
+            # Handle media upload if provided
+            media_id = request.media_id
+            if request.media_url and not media_id:
+                media_attachment = await self._upload_dm_media(request.media_url)
+                media_id = media_attachment.media_id
+
+            # Create group conversation using tweepy
+            conv_params: dict[str, Any] = {
+                "conversation_type": "Group",
+                "participant_ids": request.participant_ids,
+                "text": request.text,
+            }
+
+            if media_id:
+                conv_params["media_id"] = media_id
+
+            response = self._tweepy_client.create_direct_message_conversation(
+                **conv_params,
+                user_auth=False,
+            )
+
+            conv_data = response.data  # type: ignore[attr-defined]
+
+            return Conversation(
+                conversation_id=str(conv_data["dm_conversation_id"]),
+                platform=self.platform_name,
+                conversation_type="group",
+                participant_ids=request.participant_ids,
+                created_at=datetime.now(),
+                raw_data=conv_data,
+            )
+
+        except tweepy.TweepyException as e:
+            if "429" in str(e):
+                raise RateLimitError(
+                    "Twitter rate limit exceeded",
+                    platform=self.platform_name,
+                    status_code=429,
+                ) from e
+            raise PlatformError(
+                f"Failed to create group conversation: {e}",
+                platform=self.platform_name,
+            ) from e
+
     # ==================== Helper Methods ====================
 
     def _parse_tweet(

marqetive_lib-0.1.22/src/marqetive/platforms/twitter/models.py

@@ -0,0 +1,130 @@
+"""Twitter/X-specific models for post creation and direct messages.
+
+This module defines Twitter-specific data models for creating tweets,
+replies, quote tweets, polls, and direct messages.
+"""
+
+from pydantic import BaseModel, Field
+
+# ==================== Post Models ====================
+
+
+class TwitterPostRequest(BaseModel):
+    """Twitter/X-specific post creation request.
+
+    Supports tweets, replies, quote tweets, and media attachments.
+    Twitter has a 280 character limit for text content.
+
+    Attributes:
+        content: Tweet text (max 280 characters)
+        media_urls: List of media URLs to attach (max 4 images or 1 video)
+        media_ids: List of pre-uploaded media IDs
+        reply_to_post_id: Tweet ID to reply to
+        quote_post_id: Tweet ID to quote
+        poll_options: List of poll options (2-4 options, each max 25 chars)
+        poll_duration_minutes: Poll duration in minutes (5-10080)
+        alt_texts: Alt text for each media item (for accessibility)
+
+    Example:
+        >>> # Simple tweet
+        >>> request = TwitterPostRequest(content="Hello Twitter!")
+
+        >>> # Reply to a tweet
+        >>> request = TwitterPostRequest(
+        ...     content="Great point!",
+        ...     reply_to_post_id="1234567890"
+        ... )
+
+        >>> # Quote tweet with media
+        >>> request = TwitterPostRequest(
+        ...     content="Check this out!",
+        ...     quote_post_id="1234567890",
+        ...     media_urls=["https://example.com/image.jpg"]
+        ... )
+
+        >>> # Tweet with poll
+        >>> request = TwitterPostRequest(
+        ...     content="What's your favorite?",
+        ...     poll_options=["Option A", "Option B", "Option C"],
+        ...     poll_duration_minutes=1440
+        ... )
+    """
+
+    content: str | None = None
+    media_urls: list[str] = Field(default_factory=list, max_length=4)
+    media_ids: list[str] = Field(default_factory=list, max_length=4)
+    reply_to_post_id: str | None = None
+    quote_post_id: str | None = None
+    poll_options: list[str] = Field(default_factory=list, max_length=4)
+    poll_duration_minutes: int | None = Field(default=None, ge=5, le=10080)
+    alt_texts: list[str] = Field(default_factory=list)
+
+
+# ==================== Direct Message Models ====================
+
+
+class TwitterDMRequest(BaseModel):
+    """Twitter/X-specific direct message request.
+
+    Supports sending DMs to individuals or existing conversations.
+    Twitter has a 10,000 character limit for DM text content.
+    Only one media attachment is allowed per DM.
+
+    Attributes:
+        text: Message text (max 10,000 characters)
+        participant_id: User ID for new 1-to-1 DM (mutually exclusive with conversation_id)
+        conversation_id: Existing conversation ID (mutually exclusive with participant_id)
+        media_url: URL of media to attach (max 1 attachment)
+        media_id: Pre-uploaded media ID (from TwitterMediaManager)
+
+    Example:
+        >>> # Send 1-to-1 DM
+        >>> request = TwitterDMRequest(
+        ...     text="Hello!",
+        ...     participant_id="1234567890"
+        ... )
+
+        >>> # Send to existing conversation
+        >>> request = TwitterDMRequest(
+        ...     text="Hello group!",
+        ...     conversation_id="dm_conv_123456"
+        ... )
+
+        >>> # Send DM with media
+        >>> request = TwitterDMRequest(
+        ...     text="Check this out!",
+        ...     participant_id="1234567890",
+        ...     media_url="https://example.com/image.jpg"
+        ... )
+    """
+
+    text: str = Field(max_length=10000)
+    participant_id: str | None = None
+    conversation_id: str | None = None
+    media_url: str | None = None
+    media_id: str | None = None
+
+
+class TwitterGroupDMRequest(BaseModel):
+    """Twitter/X-specific group DM creation request.
+
+    Creates a new group conversation with multiple participants and an initial message.
+    Twitter allows 2-49 participants in a group DM (excluding the sender).
+
+    Attributes:
+        participant_ids: List of user IDs (2-49 participants, excluding sender)
+        text: Initial message text (max 10,000 characters)
+        media_url: URL of media to attach
+        media_id: Pre-uploaded media ID
+
+    Example:
+        >>> request = TwitterGroupDMRequest(
+        ...     participant_ids=["user1_id", "user2_id", "user3_id"],
+        ...     text="Welcome to the group!"
+        ... )
+    """
+
+    participant_ids: list[str] = Field(min_length=2, max_length=49)
+    text: str = Field(max_length=10000)
+    media_url: str | None = None
+    media_id: str | None = None

{marqetive_lib-0.1.20 → marqetive_lib-0.1.22}/src/marqetive/utils/oauth.py

@@ -180,10 +180,32 @@ async def refresh_twitter_token(
 
     except httpx.HTTPStatusError as e:
         logger.error(f"HTTP error refreshing Twitter token: {e.response.status_code}")
+
+        # Determine if this is a permanent failure requiring user re-authentication
+        # Twitter returns 400 with "invalid_request" or "invalid_grant" when:
+        # - Refresh token was already used (single-use tokens)
+        # - Refresh token expired
+        # - User revoked access
+        requires_reconnection = False
+        if e.response.status_code == 400:
+            try:
+                error_data = e.response.json()
+                error_code = error_data.get("error", "")
+                if error_code in ("invalid_request", "invalid_grant"):
+                    requires_reconnection = True
+                    logger.warning(
+                        f"Twitter refresh token is invalid ({error_code}), "
+                        "user needs to reconnect their account"
+                    )
+            except Exception:
+                # If we can't parse the response, assume reconnection is needed for 400
+                requires_reconnection = True
+
         raise PlatformAuthError(
             f"Failed to refresh token: {_sanitize_response_text(e.response.text)}",
             platform="twitter",
             status_code=e.response.status_code,
+            requires_reconnection=requires_reconnection,
         ) from e
 
     except httpx.HTTPError as e:

marqetive_lib-0.1.20/src/marqetive/platforms/twitter/__init__.py

@@ -1,6 +0,0 @@
-"""Twitter/X platform integration."""
-
-from marqetive.platforms.twitter.client import TwitterClient
-from marqetive.platforms.twitter.models import TwitterPostRequest
-
-__all__ = ["TwitterClient", "TwitterPostRequest"]

marqetive_lib-0.1.20/src/marqetive/platforms/twitter/models.py

@@ -1,58 +0,0 @@
-"""Twitter/X-specific models for post creation.
-
-This module defines Twitter-specific data models for creating tweets,
-replies, quote tweets, and polls.
-"""
-
-from pydantic import BaseModel, Field
-
-
-class TwitterPostRequest(BaseModel):
-    """Twitter/X-specific post creation request.
-
-    Supports tweets, replies, quote tweets, and media attachments.
-    Twitter has a 280 character limit for text content.
-
-    Attributes:
-        content: Tweet text (max 280 characters)
-        media_urls: List of media URLs to attach (max 4 images or 1 video)
-        media_ids: List of pre-uploaded media IDs
-        reply_to_post_id: Tweet ID to reply to
-        quote_post_id: Tweet ID to quote
-        poll_options: List of poll options (2-4 options, each max 25 chars)
-        poll_duration_minutes: Poll duration in minutes (5-10080)
-        alt_texts: Alt text for each media item (for accessibility)
-
-    Example:
-        >>> # Simple tweet
-        >>> request = TwitterPostRequest(content="Hello Twitter!")
-
-        >>> # Reply to a tweet
-        >>> request = TwitterPostRequest(
-        ...     content="Great point!",
-        ...     reply_to_post_id="1234567890"
-        ... )
-
-        >>> # Quote tweet with media
-        >>> request = TwitterPostRequest(
-        ...     content="Check this out!",
-        ...     quote_post_id="1234567890",
-        ...     media_urls=["https://example.com/image.jpg"]
-        ... )
-
-        >>> # Tweet with poll
-        >>> request = TwitterPostRequest(
-        ...     content="What's your favorite?",
-        ...     poll_options=["Option A", "Option B", "Option C"],
-        ...     poll_duration_minutes=1440
-        ... )
-    """
-
-    content: str | None = None
-    media_urls: list[str] = Field(default_factory=list, max_length=4)
-    media_ids: list[str] = Field(default_factory=list, max_length=4)
-    reply_to_post_id: str | None = None
-    quote_post_id: str | None = None
-    poll_options: list[str] = Field(default_factory=list, max_length=4)
-    poll_duration_minutes: int | None = Field(default=None, ge=5, le=10080)
-    alt_texts: list[str] = Field(default_factory=list)