marqetive-lib 0.1.21__py3-none-any.whl → 0.2.1__py3-none-any.whl

marqetive/__init__.py

@@ -47,6 +47,7 @@ from marqetive.core.exceptions import (
     PlatformError,
     PostNotFoundError,
     RateLimitError,
+    ThreadCancelledException,
     ValidationError,
 )
 
@@ -56,6 +57,10 @@ from marqetive.core.models import (
     AuthCredentials,
     Comment,
     CommentStatus,
+    Conversation,
+    DirectMessage,
+    DMCreateRequest,
+    GroupDMCreateRequest,
     MediaAttachment,
     MediaType,
     Post,
@@ -75,7 +80,7 @@ from marqetive.utils.helpers import format_response
 # Retry utilities
 from marqetive.utils.retry import STANDARD_BACKOFF, BackoffConfig, retry_async
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     # Core
@@ -102,6 +107,11 @@ __all__ = [
     # Base Request Models
     "PostCreateRequest",
     "PostUpdateRequest",
+    # Direct Message Models
+    "DMCreateRequest",
+    "GroupDMCreateRequest",
+    "DirectMessage",
+    "Conversation",
     # Exceptions
     "PlatformError",
     "PlatformAuthError",
@@ -110,6 +120,7 @@ __all__ = [
     "MediaUploadError",
     "ValidationError",
     "InvalidFileTypeError",
+    "ThreadCancelledException",
     # Types
     "ProgressCallback",
     # Utilities

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/core/exceptions.py

@@ -4,6 +4,13 @@ This module defines platform-specific exceptions for handling errors
 that may occur during API interactions with various social media platforms.
 """
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from marqetive.core.models import Post
+
 
 class PlatformError(Exception):
     """Base exception for all platform-related errors.
@@ -266,3 +273,42 @@ class InvalidFileTypeError(PlatformError):
         if self.file_type:
             return f"{base_message} | File type: {self.file_type}"
         return base_message
+
+
+class ThreadCancelledException(PlatformError):
+    """Raised when a thread is cancelled mid-posting.
+
+    This exception is raised when:
+    - A cancellation callback returns True during thread creation
+    - Thread posting is interrupted before completion
+
+    The exception includes the list of posts that were successfully
+    created before cancellation, allowing the caller to handle rollback.
+
+    Args:
+        message: Human-readable error message
+        platform: Name of the platform where cancellation occurred
+        posted_tweets: List of Post objects that were created before cancellation
+
+    Example:
+        >>> try:
+        ...     await client.create_thread(tweets, cancellation_check=check_cancel)
+        ... except ThreadCancelledException as e:
+        ...     for post in e.posted_tweets:
+        ...         await client.delete_post(post.post_id)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        platform: str | None = None,
+        posted_tweets: list[Post] | None = None,
+    ) -> None:
+        self.posted_tweets = posted_tweets or []
+        super().__init__(message, platform)
+
+    def _format_message(self) -> str:
+        """Format the error message with posted tweet count."""
+        base_message = super()._format_message()
+        count = len(self.posted_tweets)
+        return f"{base_message} | Posted tweets: {count}"

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/platforms/twitter/__init__.py

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

marqetive/platforms/twitter/client.py

@@ -6,6 +6,7 @@ ABC for Twitter (X), using the Twitter API v2 via tweepy.
 API Documentation: https://developer.x.com/en/docs/twitter-api
 """
 
+from collections.abc import Awaitable, Callable
 from datetime import datetime
 from typing import Any
 
@@ -20,12 +21,17 @@ from marqetive.core.exceptions import (
     PlatformError,
     PostNotFoundError,
     RateLimitError,
+    ThreadCancelledException,
     ValidationError,
 )
 from marqetive.core.models import (
     AuthCredentials,
     Comment,
     CommentStatus,
+    Conversation,
+    DirectMessage,
+    DMCreateRequest,
+    GroupDMCreateRequest,
     MediaAttachment,
     MediaType,
     Post,
@@ -34,8 +40,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):
@@ -677,6 +683,7 @@ class TwitterClient(SocialMediaPlatform):
     async def create_thread(
         self,
         posts: list[PostCreateRequest],
+        cancellation_check: Callable[[], Awaitable[bool]] | None = None,
     ) -> list[Post]:
         """Create a Twitter thread (multiple linked tweets).
 
@@ -687,6 +694,8 @@ class TwitterClient(SocialMediaPlatform):
             posts: List of PostCreateRequest objects to create as a thread.
                    First tweet is the head of the thread.
                    Use TwitterPostRequest for Twitter-specific features.
+            cancellation_check: Optional async callback that returns True if the
+                   thread creation should be cancelled. Called before each tweet.
 
         Returns:
             List of Post objects for each tweet in the thread.
@@ -695,6 +704,7 @@ class TwitterClient(SocialMediaPlatform):
             ValidationError: If posts list is empty.
             PlatformAuthError: If not authenticated.
             MediaUploadError: If media upload fails.
+            ThreadCancelledException: If cancelled mid-thread (includes posted tweets).
             RuntimeError: If client not used as context manager.
 
         Example:
@@ -719,6 +729,14 @@ class TwitterClient(SocialMediaPlatform):
         reply_to_id: str | None = None
 
         for idx, post_request in enumerate(posts):
+            # Check cancellation BEFORE posting each tweet
+            if cancellation_check is not None and await cancellation_check():
+                raise ThreadCancelledException(
+                    f"Thread cancelled after {len(created_posts)} of {len(posts)} tweets",
+                    platform=self.platform_name,
+                    posted_tweets=created_posts,
+                )
+
             # Convert to TwitterPostRequest if needed and set reply chain
             if isinstance(post_request, TwitterPostRequest):
                 if reply_to_id is not None:
@@ -755,6 +773,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/platforms/twitter/models.py

@@ -1,11 +1,13 @@
-"""Twitter/X-specific models for post creation.
+"""Twitter/X-specific models for post creation and direct messages.
 
 This module defines Twitter-specific data models for creating tweets,
-replies, quote tweets, and polls.
+replies, quote tweets, polls, and direct messages.
 """
 
 from pydantic import BaseModel, Field
 
+# ==================== Post Models ====================
+
 
 class TwitterPostRequest(BaseModel):
     """Twitter/X-specific post creation request.
@@ -56,3 +58,73 @@ class TwitterPostRequest(BaseModel):
     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.21.dist-info → marqetive_lib-0.2.1.dist-info}/METADATA

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

{marqetive_lib-0.1.21.dist-info → marqetive_lib-0.2.1.dist-info}/RECORD

@@ -1,9 +1,9 @@
-marqetive/__init__.py,sha256=pW77CUnzOQ0X1pb-GTcRgrrvsSaJBdVhGZLnvCD_4q4,3032
+marqetive/__init__.py,sha256=oAbgnTV2fTfnocxwampca87E3HTY_DclPv-rjOCQlhM,3298
 marqetive/core/__init__.py,sha256=0_0vzxJ619YIJkz1yzSvhnGDJRkrErs_QSg2q3Bloss,1172
-marqetive/core/base.py,sha256=A1RgZZLX5aMkFVmjNdJak9O0WFWOl1PPMIU8-ngEjxA,17225
+marqetive/core/base.py,sha256=PXq1u0QT3oKC338-QJXu0gebXI1n6v5MCGgLi2Kt-Sg,20001
 marqetive/core/client.py,sha256=eCtvL100dkxYQHC_TJzHbs3dGjgsa_me9VTHo-CUN2M,3900
-marqetive/core/exceptions.py,sha256=CQXGPjzWJU2NZ0a7E007PxrG_orOOJNmvcsZ0L4HTiQ,8195
-marqetive/core/models.py,sha256=HmUSKZgJFw4o6Orjn4SGaCwLN6s8_FCsFkK1ptvnad8,14819
+marqetive/core/exceptions.py,sha256=h4boyxGY2tUQXMfnDcpVzAKVW71VpqvOZtGkQ-oVkYM,9710
+marqetive/core/models.py,sha256=0n5z1GcrNJWmPCgc_k5glxd3dLGUANwp4qvHCM5FIC4,19287
 marqetive/factory.py,sha256=SfHsp6mdIZpDBtryUvHSwljBRkCyAHhtwV7qDfgL9k4,15268
 marqetive/platforms/__init__.py,sha256=RBxlQSGyELsulSnwf5uaE1ohxFc7jC61OO9CrKaZp48,1312
 marqetive/platforms/instagram/__init__.py,sha256=c1Gs0ozG6D7Z-Uz_UQ7S3joL0qUTT9eUZPWcePyESk8,229
@@ -21,11 +21,11 @@ marqetive/platforms/tiktok/client.py,sha256=IhLCphzu_qxTSP6CDFqLBQqM3zJ7bLy7uHDS
 marqetive/platforms/tiktok/exceptions.py,sha256=vxwyAKujMGZJh0LetG1QsLF95QfUs_kR6ujsWSHGqL0,10124
 marqetive/platforms/tiktok/media.py,sha256=NmvzvzfaZMmzIx88wkXI5tWLd4vYN1VJXN-IkaEAO2c,28638
 marqetive/platforms/tiktok/models.py,sha256=WWdjuFqhTIR8SnHkz-8UaNc5Mm2PrGomwQ3W7pJcQFg,2962
-marqetive/platforms/twitter/__init__.py,sha256=dvcgVT-v-JOtjSz-OUvxGrn_43OI6w_ep42Wx_nHTSM,217
-marqetive/platforms/twitter/client.py,sha256=x4czyl1TnP-JmxRKl19fEE0gcYCppqK2Xdwpyf7G2E8,29035
+marqetive/platforms/twitter/__init__.py,sha256=0-EETW3kIAw7kFo-JuOivS42BDVdNJfqHe2depIbx2U,339
+marqetive/platforms/twitter/client.py,sha256=BCVPz-wIKJx1FThm-dI9QfTVG9VdYLYBPOWJEzX8QJc,42417
 marqetive/platforms/twitter/exceptions.py,sha256=eZ-dJKOXH_-bAMg29zWKbEqMFud29piEJ5IWfC9wFts,8926
 marqetive/platforms/twitter/media.py,sha256=KpPxnLCas8NhnsEvaXSJZ7To4wW4FY0YqQvUkJIIr7g,28010
-marqetive/platforms/twitter/models.py,sha256=yPQlx40SlNmz7YGasXUqdx7rEDEgrQ64aYovlPKo6oc,2126
+marqetive/platforms/twitter/models.py,sha256=afFK1jJyrIC6BvY6ShkHlg-KnvawdeLGS-hB-GoloWA,4579
 marqetive/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 marqetive/utils/__init__.py,sha256=bSrNajbxYBSKQayrPviLz8JeGjplnyK8y_NGDtgb7yQ,977
 marqetive/utils/file_handlers.py,sha256=mDBGLQpCBYD-AN3W_qysZn0JmXxQE017_lnURdkkucA,17224
@@ -33,6 +33,6 @@ marqetive/utils/helpers.py,sha256=Sh5HZD6AOJig_6T84n6JsKLosIkKIkpkiYTl69rnOOw,13
 marqetive/utils/media.py,sha256=reVousdueG-h5jeI6uLGqVCfjYxlsMiWhx6XZwg-iHY,14664
 marqetive/utils/oauth.py,sha256=3TtbUCVuGxtOBxIUvVJH_DUMIHrP76XDpabPYaLXhTU,15392
 marqetive/utils/retry.py,sha256=UcgrmVBVG5zd30_11mZnRnTaSFrbUYXBO1DrXPR0f8E,7627
-marqetive_lib-0.1.21.dist-info/METADATA,sha256=bYGdoaoexmFhLH4yVmG5CxkTKyP0fnztXVGa-msRi7M,7876
-marqetive_lib-0.1.21.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-marqetive_lib-0.1.21.dist-info/RECORD,,
+marqetive_lib-0.2.1.dist-info/METADATA,sha256=TGRiCpdcZ3x0eCi1OsaH37-BIuimbqVCrbaZvWvUNqE,7875
+marqetive_lib-0.2.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+marqetive_lib-0.2.1.dist-info/RECORD,,