tweetapi 1.0.0__py3-none-any.whl

tweetapi/resources/unencrypted_dm.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class UnencryptedDMResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def send_dm(self, *, auth_token: str, conversation_id: str, text: str, proxy: str, request_id: Optional[str] = None, media: Optional[list[Any]] = None) -> dict[str, Any]:
+        """Send an unencrypted direct message."""
+        return self._client._post("/tw-v2/interaction/send-dm", {
+            "authToken": auth_token, "conversationId": conversation_id,
+            "text": text, "proxy": proxy, "requestId": request_id, "media": media,
+        })
+
+    def get_dm_permissions(self, *, auth_token: str, recipient_ids: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Check DM permissions for recipients."""
+        return self._client._get("/tw-v2/interaction/dm-permissions", {
+            "authToken": auth_token, "recipientIds": recipient_ids, "proxy": proxy,
+        })
+
+    def get_inbox_initial_state(self, *, auth_token: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get initial inbox state."""
+        return self._client._get("/tw-v2/interaction/inbox-initial-state", {
+            "authToken": auth_token, "proxy": proxy,
+        })
+
+    def get_inbox_trusted(self, *, auth_token: str, cursor: str, filter_low_quality: Optional[bool] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get trusted inbox conversations."""
+        return self._client._get("/tw-v2/interaction/inbox-timeline-trusted", {
+            "authToken": auth_token, "cursor": cursor,
+            "filterLowQuality": filter_low_quality, "proxy": proxy,
+        })
+
+    def get_inbox_untrusted(self, *, auth_token: str, cursor: str, filter_low_quality: Optional[bool] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get untrusted (message requests) inbox conversations."""
+        return self._client._get("/tw-v2/interaction/inbox-timeline-untrusted", {
+            "authToken": auth_token, "cursor": cursor,
+            "filterLowQuality": filter_low_quality, "proxy": proxy,
+        })
+
+    def get_conversation(self, *, auth_token: str, conversation_id: str, cursor: Optional[str] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get messages in a conversation."""
+        return self._client._get("/tw-v2/interaction/conversation", {
+            "authToken": auth_token, "conversationId": conversation_id,
+            "cursor": cursor, "proxy": proxy,
+        })
+
+    def get_dm_user_updates(self, *, auth_token: str, cursor: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get DM user updates."""
+        return self._client._get("/tw-v2/interaction/dm-user-updates", {
+            "authToken": auth_token, "cursor": cursor, "proxy": proxy,
+        })
+
+    def accept_conversation(self, *, auth_token: str, conversation_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Accept a conversation request."""
+        return self._client._post("/tw-v2/interaction/accept-conversation", {
+            "authToken": auth_token, "conversationId": conversation_id, "proxy": proxy,
+        })

tweetapi/resources/user.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class UserResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_by_username(self, *, username: str) -> dict[str, Any]:
+        """Get a user profile by username."""
+        return self._client._get("/tw-v2/user/by-username", {"username": username})
+
+    def get_by_usernames(self, *, usernames: str) -> dict[str, Any]:
+        """Get multiple user profiles by usernames (comma-separated)."""
+        return self._client._get("/tw-v2/user/by-usernames", {"usernames": usernames})
+
+    def get_by_user_id(self, *, user_id: str) -> dict[str, Any]:
+        """Get a user profile by user ID."""
+        return self._client._get("/tw-v2/user/by-id", {"userId": user_id})
+
+    def get_by_user_ids(self, *, user_ids: str) -> dict[str, Any]:
+        """Get multiple user profiles by user IDs (comma-separated)."""
+        return self._client._get("/tw-v2/user/by-ids", {"userIds": user_ids})
+
+    def get_tweets(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's tweets."""
+        return self._client._get("/tw-v2/user/tweets", {"userId": user_id, "cursor": cursor})
+
+    def get_tweets_and_replies(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's tweets and replies."""
+        return self._client._get("/tw-v2/user/tweets-and-replies", {"userId": user_id, "cursor": cursor})
+
+    def get_following(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get who a user follows (v2 — full user objects)."""
+        return self._client._get("/tw-v2/user/following", {"userId": user_id, "cursor": cursor})
+
+    def get_followers(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's followers (v2 — full user objects)."""
+        return self._client._get("/tw-v2/user/followers", {"userId": user_id, "cursor": cursor})
+
+    def get_verified_followers(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's verified followers."""
+        return self._client._get("/tw-v2/user/verified-followers", {"userId": user_id, "cursor": cursor})
+
+    def get_subscriptions(self, *, user_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's subscriptions."""
+        return self._client._get("/tw-v2/user/subscriptions", {"userId": user_id, "cursor": cursor})
+
+    def get_following_v1(self, *, user_id: str, count: Optional[str] = None, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get who a user follows (v1 — supports count)."""
+        return self._client._get("/tw-v2/user/following-list", {"userId": user_id, "count": count, "cursor": cursor})
+
+    def get_followers_v1(self, *, user_id: str, count: Optional[str] = None, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get a user's followers (v1 — supports count)."""
+        return self._client._get("/tw-v2/user/followers-list", {"userId": user_id, "count": count, "cursor": cursor})
+
+    def get_following_ids(self, *, user_id: str, count: Optional[str] = None, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get IDs of accounts a user is following."""
+        return self._client._get("/tw-v2/user/following-ids", {"userId": user_id, "count": count, "cursor": cursor})
+
+    def get_followers_ids(self, *, user_id: str, count: Optional[str] = None, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get IDs of a user's followers."""
+        return self._client._get("/tw-v2/user/followers-ids", {"userId": user_id, "count": count, "cursor": cursor})
+
+    def check_follow(self, *, subject_id: str, target_id: str) -> dict[str, Any]:
+        """Check the follow relationship between two users."""
+        return self._client._get("/tw-v2/user/friendship", {"subjectId": subject_id, "targetId": target_id})
+
+    def about_account(self, *, username: str) -> dict[str, Any]:
+        """Get account creation details and transparency information."""
+        return self._client._get("/tw-v2/user/about-account", {"username": username})

tweetapi/resources/xchat.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class XChatResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def setup(self, *, auth_token: str, user_id: str, pin: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Initialize X Chat (encrypted DMs) for your account."""
+        return self._client._post("/tw-v2/xchat/setup", {
+            "authToken": auth_token, "userId": user_id, "pin": pin, "proxy": proxy,
+        })
+
+    def get_conversations(self, *, auth_token: str, cursor: Optional[str] = None, graph_snapshot_id: Optional[str] = None, limit: Optional[int] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """List encrypted DM conversations."""
+        return self._client._post("/tw-v2/xchat/conversations", {
+            "authToken": auth_token, "cursor": cursor,
+            "graphSnapshotId": graph_snapshot_id, "limit": limit, "proxy": proxy,
+        })
+
+    def send(self, *, auth_token: str, recipient_id: str, message: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Send an encrypted message."""
+        return self._client._post("/tw-v2/xchat/send", {
+            "authToken": auth_token, "recipientId": recipient_id,
+            "message": message, "proxy": proxy,
+        })
+
+    def get_history(self, *, auth_token: str, conversation_id: str, cursor: Optional[str] = None, limit: Optional[int] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get encrypted conversation history."""
+        return self._client._post("/tw-v2/xchat/history", {
+            "authToken": auth_token, "conversationId": conversation_id,
+            "cursor": cursor, "limit": limit, "proxy": proxy,
+        })
+
+    def can_dm(self, *, auth_token: str, user_ids: list[str], proxy: Optional[str] = None) -> dict[str, Any]:
+        """Check if you can send encrypted DMs to users."""
+        return self._client._post("/tw-v2/xchat/can-dm", {
+            "authToken": auth_token, "userIds": user_ids, "proxy": proxy,
+        })

tweetapi/types.py

@@ -0,0 +1,484 @@
+"""Response types for TweetAPI.
+
+Uses TypedDict for lightweight, JSON-compatible type hints.
+All types mirror the API's JSON response shapes exactly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List as TypingList, Optional, TypedDict
+
+
+# ─── Response Wrappers ───────────────────────────────────────────────────────
+
+
+class ApiResponse(TypedDict):
+    data: Any
+
+
+class Pagination(TypedDict):
+    nextCursor: Optional[str]
+    prevCursor: Optional[str]
+
+
+class PaginatedResponse(TypedDict):
+    data: list[Any]
+    pagination: Pagination
+
+
+class SearchMeta(TypedDict):
+    query: str
+    resultType: str
+    resultCount: int
+    completedIn: int
+
+
+class SearchResponse(TypedDict):
+    data: list[Any]
+    pagination: Pagination
+    meta: SearchMeta
+
+
+class ActionData(TypedDict, total=False):
+    id: str
+    action: str
+    timestamp: str
+    success: bool
+    message: str
+    metadata: dict[str, Any]
+
+
+class ActionResponse(TypedDict):
+    data: ActionData
+
+
+# ─── User ────────────────────────────────────────────────────────────────────
+
+
+class Professional(TypedDict, total=False):
+    type: Optional[str]
+    category: list[str]
+    restId: Optional[str]
+
+
+class BusinessAccount(TypedDict):
+    affiliatesCount: int
+
+
+class HighlightsInfo(TypedDict):
+    canHighlight: bool
+    highlightedTweetsCount: str
+
+
+class User(TypedDict, total=False):
+    id: str
+    username: str
+    name: str
+    bio: str
+    location: Optional[str]
+    website: Optional[str]
+    pinnedTweetIds: list[str]
+    avatar: Optional[str]
+    banner: Optional[str]
+    profileImageShape: Optional[str]
+    verified: bool
+    isBlueVerified: bool
+    verifiedType: Optional[str]
+    verifiedSince: Optional[str]
+    isIdentityVerified: bool
+    isProtected: bool
+    possiblySensitive: bool
+    profileInterstitialType: Optional[str]
+    withheldInCountries: list[str]
+    professional: Optional[Professional]
+    businessAccount: Optional[BusinessAccount]
+    creatorSubscriptionsCount: int
+    hasHiddenSubscriptions: bool
+    highlightsInfo: Optional[HighlightsInfo]
+    hasGraduatedAccess: bool
+    isProfileTranslatable: bool
+    hasCustomTimelines: bool
+    isTranslator: bool
+    affiliatesHighlightedLabel: Optional[dict[str, Any]]
+    defaultProfile: bool
+    defaultProfileImage: bool
+    followerCount: int
+    followingCount: int
+    tweetCount: int
+    listedCount: int
+    mediaCount: int
+    favoritesCount: int
+    createdAt: Optional[str]
+
+
+class UserRelationship(TypedDict, total=False):
+    sourceId: str
+    targetId: str
+    following: bool
+    followedBy: bool
+    blocking: bool
+    blockedBy: bool
+    muting: bool
+    notificationsEnabled: bool
+    canDm: bool
+    canMediaTag: bool
+    wantRetweets: bool
+    markedSpam: bool
+    followRequestSent: bool
+    followRequestReceived: bool
+    allReplies: bool
+
+
+class UserAnalytics(TypedDict, total=False):
+    userId: str
+    period: str
+    impressions: int
+    engagements: int
+    engagementRate: float
+    linkClicks: int
+    profileVisits: int
+    mentions: int
+    newFollowers: int
+    topTweet: Optional[str]
+    detailedMetrics: dict[str, int]
+
+
+# ─── Media ───────────────────────────────────────────────────────────────────
+
+
+class MediaSize(TypedDict, total=False):
+    width: int
+    height: int
+    resize: str
+    url: str
+
+
+class VideoVariant(TypedDict, total=False):
+    bitrate: Optional[int]
+    contentType: str
+    url: str
+
+
+class MediaAvailability(TypedDict):
+    status: str
+    reason: Optional[str]
+
+
+class Media(TypedDict, total=False):
+    id: str
+    key: str
+    type: str  # "photo" | "video" | "animated_gif"
+    url: str
+    displayUrl: str
+    expandedUrl: str
+    thumbnailUrl: Optional[str]
+    width: int
+    height: int
+    aspectRatio: list[int]
+    sizes: dict[str, MediaSize]
+    duration: Optional[float]
+    bitrate: Optional[int]
+    videoInfo: Optional[dict[str, Any]]
+    altText: Optional[str]
+    sensitiveMedia: bool
+    mediaAvailability: MediaAvailability
+    allowDownload: bool
+    mediaStats: Optional[dict[str, int]]
+    sourceStatusId: Optional[str]
+    sourceUserId: Optional[str]
+
+
+# ─── Poll ────────────────────────────────────────────────────────────────────
+
+
+class PollOption(TypedDict):
+    position: int
+    label: str
+    voteCount: int
+    percentage: float
+
+
+class Poll(TypedDict, total=False):
+    id: str
+    options: list[PollOption]
+    endDatetime: str
+    durationMinutes: int
+    votingStatus: str
+    totalVotes: int
+
+
+# ─── Card ────────────────────────────────────────────────────────────────────
+
+
+class CardBindingValues(TypedDict, total=False):
+    title: str
+    description: str
+    domain: str
+    thumbnailImageUrl: Optional[str]
+    thumbnailImageColor: Optional[str]
+    playerUrl: Optional[str]
+    playerWidth: Optional[int]
+    playerHeight: Optional[int]
+    appId: Optional[str]
+    appName: Optional[str]
+
+
+class Card(TypedDict, total=False):
+    name: str
+    url: str
+    cardType: str
+    type: str
+    bindingValues: CardBindingValues
+    vanityUrl: Optional[str]
+
+
+# ─── Place ───────────────────────────────────────────────────────────────────
+
+
+class Place(TypedDict, total=False):
+    id: str
+    fullName: str
+    name: str
+    country: str
+    countryCode: str
+    placeType: str
+    url: str
+
+
+# ─── Tweet ───────────────────────────────────────────────────────────────────
+
+
+class ReplyTo(TypedDict):
+    tweetId: str
+    userId: str
+    username: str
+
+
+class Mention(TypedDict):
+    id: str
+    username: str
+    name: str
+
+
+class EditControl(TypedDict, total=False):
+    editTweetIds: list[str]
+    editableUntil: str
+    isEditEligible: bool
+    editsRemaining: int
+
+
+class BirdwatchPivot(TypedDict, total=False):
+    calloutText: str
+    shortTitle: str
+    noteId: str
+    iconType: str
+    destinationUrl: str
+
+
+class ConversationControl(TypedDict, total=False):
+    policy: str
+    allowedUserIds: list[str]
+
+
+class Tweet(TypedDict, total=False):
+    id: str
+    conversationId: Optional[str]
+    text: str
+    displayTextRange: list[int]
+    author: User
+    source: Optional[str]
+    type: str  # "tweet" | "reply" | "quote" | "retweet" | "thread"
+    replyTo: Optional[ReplyTo]
+    quotedTweet: Optional[Any]  # recursive Tweet
+    retweetedTweet: Optional[Any]
+    likeCount: int
+    retweetCount: int
+    replyCount: int
+    quoteCount: int
+    bookmarkCount: int
+    viewCount: Optional[int]
+    media: Optional[list[Media]]
+    poll: Optional[Poll]
+    card: Optional[Card]
+    hashtags: list[str]
+    mentions: list[Mention]
+    urls: list[str]
+    symbols: list[str]
+    possiblySensitive: bool
+    limitedActions: Optional[str]
+    hasAIGeneratedMedia: bool
+    isPaidPromotion: bool
+    isEdited: bool
+    editControl: Optional[EditControl]
+    isTranslatable: bool
+    lang: str
+    translatedText: Optional[str]
+    hasBirdwatchNotes: bool
+    birdwatchPivot: Optional[BirdwatchPivot]
+    conversationControl: Optional[ConversationControl]
+    isPromoted: bool
+    communityId: Optional[str]
+    createdAt: Optional[str]
+    place: Optional[Place]
+
+
+class TweetTranslation(TypedDict):
+    text: str
+    lang: str
+    sourceLanguage: str
+    destinationLanguage: str
+    translationSource: str
+
+
+# ─── List ────────────────────────────────────────────────────────────────────
+
+
+class List(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    mode: str  # "public" | "private"
+    owner: User
+    bannerUrl: Optional[str]
+    facepileUrls: list[str]
+    memberCount: int
+    subscriberCount: int
+    createdAt: Optional[str]
+    slug: str
+    uri: str
+
+
+# ─── Community ───────────────────────────────────────────────────────────────
+
+
+class CommunityRule(TypedDict):
+    id: str
+    name: str
+    description: str
+    order: int
+    createdAt: str
+
+
+class Community(TypedDict, total=False):
+    id: str
+    name: str
+    description: str
+    bannerUrl: Optional[str]
+    avatarUrl: Optional[str]
+    rules: list[CommunityRule]
+    memberCount: int
+    moderatorCount: int
+    adminCount: int
+    isPrivate: bool
+    pinnedTweetId: Optional[str]
+    createdAt: Optional[str]
+    isMember: bool
+    isAdmin: bool
+    isModerator: bool
+    canPost: bool
+
+
+class CommunityMember(TypedDict, total=False):
+    user: User
+    role: str  # "member" | "moderator" | "admin"
+    joinedAt: str
+
+
+class CommunitySearchResult(TypedDict, total=False):
+    id: str
+    name: str
+    memberCount: int
+    topic: Optional[str]
+    isNsfw: bool
+    bannerUrl: Optional[str]
+    defaultBannerUrl: Optional[str]
+    membersFacepile: list[str]
+
+
+# ─── Space ───────────────────────────────────────────────────────────────────
+
+
+class SpaceParticipant(TypedDict, total=False):
+    periscopeUserId: str
+    twitterUserId: str
+    username: str
+    displayName: str
+    avatarUrl: str
+    isVerified: bool
+    isBlueVerified: bool
+
+
+class SpaceTopic(TypedDict):
+    id: str
+    name: str
+
+
+class SpaceParticipants(TypedDict, total=False):
+    admins: list[SpaceParticipant]
+    speakers: list[SpaceParticipant]
+    listeners: list[SpaceParticipant]
+    total: int
+
+
+class Space(TypedDict, total=False):
+    id: str
+    title: str
+    state: str  # "Running" | "Ended" | "Scheduled" | "Canceled"
+    mediaKey: str
+    createdAt: int
+    scheduledStart: Optional[int]
+    startedAt: Optional[int]
+    endedAt: Optional[int]
+    updatedAt: Optional[int]
+    creator: Optional[User]
+    totalLiveListeners: int
+    totalReplayWatched: int
+    participants: SpaceParticipants
+    isAvailableForReplay: bool
+    topics: list[SpaceTopic]
+    tweetId: Optional[str]
+
+
+class SpaceStreamInfo(TypedDict, total=False):
+    hlsUrl: str
+    status: str
+    streamType: str
+    shareUrl: Optional[str]
+
+
+# ─── Notification ────────────────────────────────────────────────────────────
+
+
+class Notification(TypedDict, total=False):
+    id: str
+    type: str
+    createdAt: str
+    message: str
+    icon: str
+    fromUsers: list[str]
+    targetTweetId: Optional[str]
+    targetUserId: Optional[str]
+    seen: bool
+
+
+# ─── Auth ────────────────────────────────────────────────────────────────────
+
+
+class LoginCookies(TypedDict):
+    auth_token: str
+    ct0: str
+    twid: str
+    kdt: str
+    __cf_bm: str
+
+
+class LoginUser(TypedDict):
+    id: str
+    username: str
+    name: str
+
+
+class LoginResponse(TypedDict):
+    cookies: LoginCookies
+    user: LoginUser
+    timestamp: str