tweetapi 1.0.0__py3-none-any.whl

tweetapi/__init__.py

@@ -0,0 +1,37 @@
+"""TweetAPI Python SDK — Official client for the Twitter/X Data API.
+
+Usage::
+
+    from tweetapi import TweetAPI
+
+    client = TweetAPI(api_key="YOUR_API_KEY")
+
+    user = client.user.get_by_username(username="elonmusk")
+    print(user["data"]["followerCount"])
+"""
+
+from .client import TweetAPI
+from .errors import (
+    TweetAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    ConnectionError_ as NetworkError,
+)
+
+__all__ = [
+    "TweetAPI",
+    "TweetAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+]
+
+__version__ = "1.0.0"

tweetapi/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from .errors import (
+    TweetAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    ConnectionError_,
+)
+
+
+class TweetAPI:
+    """TweetAPI Python SDK client.
+
+    Args:
+        api_key: Your TweetAPI API key.
+        base_url: Base URL for the API (default: https://api.tweetapi.com).
+        timeout: Request timeout in seconds (default: 30).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.tweetapi.com",
+        timeout: int = 30,
+    ) -> None:
+        if not api_key:
+            raise ValueError("TweetAPI: api_key is required")
+
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({"X-API-Key": api_key})
+
+        # Lazy imports to avoid circular dependencies
+        from .resources.user import UserResource
+        from .resources.tweet import TweetResource
+        from .resources.post import PostResource
+        from .resources.interaction import InteractionResource
+        from .resources.list_ import ListResource
+        from .resources.community import CommunityResource
+        from .resources.space import SpaceResource
+        from .resources.explore import ExploreResource
+        from .resources.auth import AuthResource
+        from .resources.xchat import XChatResource
+        from .resources.unencrypted_dm import UnencryptedDMResource
+
+        self.user = UserResource(self)
+        self.tweet = TweetResource(self)
+        self.post = PostResource(self)
+        self.interaction = InteractionResource(self)
+        self.list = ListResource(self)
+        self.community = CommunityResource(self)
+        self.space = SpaceResource(self)
+        self.explore = ExploreResource(self)
+        self.auth = AuthResource(self)
+        self.xchat = XChatResource(self)
+        self.dm = UnencryptedDMResource(self)
+
+    def _get(self, path: str, params: Optional[dict[str, Any]] = None) -> Any:
+        """Send a GET request to the API."""
+        clean_params = None
+        if params:
+            clean_params = {
+                k: v for k, v in params.items() if v is not None
+            }
+        return self._request("GET", path, params=clean_params)
+
+    def _post(self, path: str, body: Optional[dict[str, Any]] = None) -> Any:
+        """Send a POST request to the API."""
+        clean_body = None
+        if body:
+            clean_body = {k: v for k, v in body.items() if v is not None}
+        return self._request("POST", path, json=clean_body)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        json: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        url = f"{self._base_url}{path}"
+
+        try:
+            response = self._session.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.Timeout as e:
+            raise ConnectionError_(
+                f"Request timed out after {self._timeout}s", e
+            ) from e
+        except requests.exceptions.ConnectionError as e:
+            raise ConnectionError_(f"Network error: {e}", e) from e
+        except requests.exceptions.RequestException as e:
+            raise ConnectionError_(f"Request failed: {e}", e) from e
+
+        if not response.ok:
+            self._handle_error_response(response)
+
+        return response.json()
+
+    def _handle_error_response(self, response: requests.Response) -> None:
+        """Parse error response and raise the appropriate exception."""
+        try:
+            body = response.json()
+        except (ValueError, requests.exceptions.JSONDecodeError):
+            body = None
+
+        code = "UNKNOWN_ERROR"
+        message = f"HTTP {response.status_code}"
+        details = None
+
+        if body and isinstance(body.get("error"), dict):
+            error = body["error"]
+            code = error.get("code", code)
+            message = error.get("message", message)
+            details = error.get("details")
+
+        status = response.status_code
+
+        if status == 400:
+            raise ValidationError(message, code, details)
+        elif status == 401:
+            raise AuthenticationError(message, code, details)
+        elif status == 403:
+            raise ForbiddenError(message, code, details)
+        elif status == 404:
+            raise NotFoundError(message, code, details)
+        elif status == 429:
+            raise RateLimitError(message, code, details)
+        elif status >= 500:
+            raise ServerError(message, code, status, details)
+        else:
+            raise TweetAPIError(message, code, status, details)

tweetapi/errors.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class TweetAPIError(Exception):
+    """Base error for all TweetAPI errors.
+
+    Contains the API error code, HTTP status, and optional details.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.details = details
+
+    def __str__(self) -> str:
+        return f"[{self.code}] {self.message}"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(code={self.code!r}, status_code={self.status_code}, message={self.message!r})"
+
+
+class AuthenticationError(TweetAPIError):
+    """Thrown when the API key or auth token is invalid or missing (HTTP 401)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 401, details)
+
+
+class ForbiddenError(TweetAPIError):
+    """Thrown when the request is forbidden (HTTP 403)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 403, details)
+
+
+class NotFoundError(TweetAPIError):
+    """Thrown when the requested resource is not found (HTTP 404)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 404, details)
+
+
+class ValidationError(TweetAPIError):
+    """Thrown when the request parameters are invalid (HTTP 400)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 400, details)
+
+
+class RateLimitError(TweetAPIError):
+    """Thrown when you've exceeded rate limits (HTTP 429).
+
+    Check ``retry_after`` for seconds until you can retry.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, 429, details)
+        self.retry_after: int = (details or {}).get("retryAfter", 60)
+
+
+class ServerError(TweetAPIError):
+    """Thrown when the API encounters a server error (HTTP 5xx)."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message, code, status_code, details)
+
+
+class ConnectionError_(TweetAPIError):
+    """Thrown when a network error occurs (DNS failure, timeout, connection refused).
+
+    Named ``ConnectionError_`` to avoid shadowing the built-in ``ConnectionError``.
+    Also importable as ``NetworkError``.
+    """
+
+    def __init__(self, message: str, cause: Optional[Exception] = None) -> None:
+        super().__init__(message, "CONNECTION_ERROR", 0, None)
+        self.__cause__ = cause
+
+
+# Alias for cleaner imports
+NetworkError = ConnectionError_

tweetapi/resources/auth.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class AuthResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def login(self, *, username: str, password: str, proxy: str, two_factor_secret: Optional[str] = None) -> dict[str, Any]:
+        """Log in to a Twitter account and get auth tokens."""
+        return self._client._post("/tw-v2/auth/login", {
+            "username": username, "password": password,
+            "proxy": proxy, "twoFactorSecret": two_factor_secret,
+        })

tweetapi/resources/community.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class CommunityResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_details(self, *, community_id: str) -> dict[str, Any]:
+        """Get community details."""
+        return self._client._get("/tw-v2/community/details", {"communityId": community_id})
+
+    def get_tweets(self, *, community_id: str, sort_by: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get tweets in a community."""
+        return self._client._get("/tw-v2/community/tweets", {"communityId": community_id, "sortBy": sort_by, "cursor": cursor})
+
+    def get_members(self, *, community_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get community members."""
+        return self._client._get("/tw-v2/community/members", {"communityId": community_id, "cursor": cursor})
+
+    def search(self, *, query: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Search communities."""
+        return self._client._get("/tw-v2/community/search", {"query": query, "cursor": cursor})
+
+    def create_post(self, *, auth_token: str, text: str, community_id: str, proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Create a post in a community."""
+        return self._client._post("/tw-v2/interaction/create-community-post", {
+            "authToken": auth_token, "text": text, "communityId": community_id,
+            "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def create_post_with_media(self, *, auth_token: str, text: str, community_id: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Create a post with media in a community."""
+        return self._client._post("/tw-v2/interaction/create-community-post-with-media", {
+            "authToken": auth_token, "text": text, "communityId": community_id,
+            "media": media, "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post(self, *, auth_token: str, text: str, tweet_id: str, community_id: str, proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Reply to a community post."""
+        return self._client._post("/tw-v2/interaction/reply-community-post", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "communityId": community_id, "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post_with_media(self, *, auth_token: str, text: str, tweet_id: str, community_id: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Reply to a community post with media."""
+        return self._client._post("/tw-v2/interaction/reply-community-post-with-media", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "communityId": community_id, "media": media, "proxy": proxy,
+            "disableLinkPreview": disable_link_preview,
+        })
+
+    def join(self, *, auth_token: str, community_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Join a community."""
+        return self._client._post("/tw-v2/interaction/join-community", {
+            "authToken": auth_token, "communityId": community_id, "proxy": proxy,
+        })
+
+    def leave(self, *, auth_token: str, community_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Leave a community."""
+        return self._client._post("/tw-v2/interaction/leave-community", {
+            "authToken": auth_token, "communityId": community_id, "proxy": proxy,
+        })

tweetapi/resources/explore.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class ExploreResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def search(self, *, query: str, type: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Search for tweets, users, photos, or videos.
+
+        Args:
+            query: Search query string. Supports Twitter search operators.
+            type: Type of search results — "Latest", "Top", "People", "Photos", or "Videos".
+            cursor: Pagination cursor for fetching next page.
+        """
+        return self._client._get("/tw-v2/search", {"query": query, "type": type, "cursor": cursor})

tweetapi/resources/interaction.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class InteractionResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def favorite_post(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Like a tweet."""
+        return self._client._post("/tw-v2/interaction/like-post", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def unfavorite_post(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Unlike a tweet."""
+        return self._client._post("/tw-v2/interaction/unlike-post", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def retweet(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Retweet a tweet."""
+        return self._client._post("/tw-v2/interaction/retweet", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def delete_retweet(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Remove a retweet."""
+        return self._client._post("/tw-v2/interaction/delete-retweet", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def bookmark(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Bookmark a tweet."""
+        return self._client._post("/tw-v2/interaction/bookmark", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def delete_bookmark(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Remove a bookmark."""
+        return self._client._post("/tw-v2/interaction/delete-bookmark", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })
+
+    def follow(self, *, auth_token: str, user_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Follow a user."""
+        return self._client._post("/tw-v2/interaction/follow", {
+            "authToken": auth_token, "userId": user_id, "proxy": proxy,
+        })
+
+    def unfollow(self, *, auth_token: str, user_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Unfollow a user."""
+        return self._client._post("/tw-v2/interaction/unfollow", {
+            "authToken": auth_token, "userId": user_id, "proxy": proxy,
+        })
+
+    def add_member_to_list(self, *, auth_token: str, list_id: str, user_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Add a user to a list."""
+        return self._client._post("/tw-v2/interaction/add-to-list", {
+            "authToken": auth_token, "listId": list_id, "userId": user_id, "proxy": proxy,
+        })
+
+    def remove_member_from_list(self, *, auth_token: str, list_id: str, user_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Remove a user from a list."""
+        return self._client._post("/tw-v2/interaction/remove-from-list", {
+            "authToken": auth_token, "listId": list_id, "userId": user_id, "proxy": proxy,
+        })
+
+    def get_notifications(self, *, auth_token: str, timeline_type: Optional[str] = None, count: Optional[int] = None, cursor: Optional[str] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get your notifications."""
+        return self._client._get("/tw-v2/interaction/notifications", {
+            "authToken": auth_token, "timelineType": timeline_type,
+            "count": count, "cursor": cursor, "proxy": proxy,
+        })
+
+    def get_user_analytics(self, *, auth_token: str, to_time: Optional[str] = None, from_time: Optional[str] = None, granularity: Optional[str] = None, show_verified_followers: Optional[bool] = None, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Get your account analytics."""
+        return self._client._get("/tw-v2/interaction/user-analytics", {
+            "authToken": auth_token, "toTime": to_time, "fromTime": from_time,
+            "granularity": granularity, "showVerifiedFollowers": show_verified_followers,
+            "proxy": proxy,
+        })

tweetapi/resources/list_.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class ListResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_details(self, *, list_id: str) -> dict[str, Any]:
+        """Get list details."""
+        return self._client._get("/tw-v2/list/details", {"listId": list_id})
+
+    def get_tweets(self, *, list_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get tweets in a list."""
+        return self._client._get("/tw-v2/list/tweets", {"listId": list_id, "cursor": cursor})
+
+    def get_members(self, *, list_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get members of a list."""
+        return self._client._get("/tw-v2/list/members", {"listId": list_id, "cursor": cursor})
+
+    def get_followers(self, *, list_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get followers of a list."""
+        return self._client._get("/tw-v2/list/followers", {"listId": list_id, "cursor": cursor})

tweetapi/resources/post.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class PostResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def create_post(self, *, auth_token: str, text: str, proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Create a new tweet."""
+        return self._client._post("/tw-v2/interaction/create-post", {
+            "authToken": auth_token, "text": text, "proxy": proxy,
+            "disableLinkPreview": disable_link_preview,
+        })
+
+    def create_post_quote(self, *, auth_token: str, text: str, attachment_url: str, proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Create a quote tweet."""
+        return self._client._post("/tw-v2/interaction/create-post-quote", {
+            "authToken": auth_token, "text": text, "attachmentUrl": attachment_url,
+            "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def create_post_with_media(self, *, auth_token: str, text: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Create a tweet with media attachments."""
+        return self._client._post("/tw-v2/interaction/create-post-with-media", {
+            "authToken": auth_token, "text": text, "media": media,
+            "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post(self, *, auth_token: str, text: str, tweet_id: str, proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Reply to a tweet."""
+        return self._client._post("/tw-v2/interaction/reply-post", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def reply_post_with_media(self, *, auth_token: str, text: str, tweet_id: str, media: list[Any], proxy: str, disable_link_preview: Optional[bool] = None) -> dict[str, Any]:
+        """Reply to a tweet with media attachments."""
+        return self._client._post("/tw-v2/interaction/reply-post-with-media", {
+            "authToken": auth_token, "text": text, "tweetId": tweet_id,
+            "media": media, "proxy": proxy, "disableLinkPreview": disable_link_preview,
+        })
+
+    def delete_post(self, *, auth_token: str, tweet_id: str, proxy: Optional[str] = None) -> dict[str, Any]:
+        """Delete a tweet."""
+        return self._client._post("/tw-v2/interaction/delete-post", {
+            "authToken": auth_token, "tweetId": tweet_id, "proxy": proxy,
+        })

tweetapi/resources/space.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class SpaceResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_by_id(self, *, space_id: str) -> dict[str, Any]:
+        """Get Space details by ID."""
+        return self._client._get("/tw-v2/space/by-id", {"spaceId": space_id})
+
+    def get_stream_url(self, *, media_key: str) -> dict[str, Any]:
+        """Get the HLS stream URL for a Space."""
+        return self._client._get("/tw-v2/space/stream-url", {"mediaKey": media_key})

tweetapi/resources/tweet.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import TweetAPI
+
+
+class TweetResource:
+    def __init__(self, client: TweetAPI) -> None:
+        self._client = client
+
+    def get_details_and_conversation(self, *, tweet_id: str, cursor: Optional[str] = None, sort_by: Optional[str] = None) -> dict[str, Any]:
+        """Get tweet details and conversation thread."""
+        return self._client._get("/tw-v2/tweet/details", {"tweetId": tweet_id, "cursor": cursor, "sortBy": sort_by})
+
+    def get_details_by_ids(self, *, ids: str) -> dict[str, Any]:
+        """Get details for multiple tweets by IDs (comma-separated, max 200)."""
+        return self._client._get("/tw-v2/tweet/details-by-ids", {"ids": ids})
+
+    def get_retweets(self, *, tweet_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get users who retweeted a tweet."""
+        return self._client._get("/tw-v2/tweet/retweets", {"tweetId": tweet_id, "cursor": cursor})
+
+    def get_quotes(self, *, tweet_id: str, cursor: Optional[str] = None) -> dict[str, Any]:
+        """Get quote tweets for a tweet."""
+        return self._client._get("/tw-v2/tweet/quotes", {"tweetId": tweet_id, "cursor": cursor})
+
+    def translate(self, *, tweet_id: str, dst_lang: str) -> dict[str, Any]:
+        """Translate a tweet to a different language."""
+        return self._client._post("/tw-v2/tweet/translate", {"tweetId": tweet_id, "dstLang": dst_lang})