tweetapi 1.0.0__tar.gz

tweetapi-1.0.0/.claude/settings.local.json

@@ -0,0 +1,3 @@
+{
+  "includeCoAuthoredBy": false
+}

tweetapi-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.env.*
+.pytest_cache/

tweetapi-1.0.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: tweetapi
+Version: 1.0.0
+Summary: Official Python SDK for TweetAPI — Twitter/X Data API for developers and researchers
+Project-URL: Homepage, https://tweetapi.com?utm_source=pypi&utm_medium=readme&utm_campaign=python-sdk
+Project-URL: Documentation, https://tweetapi.com/docs?utm_source=pypi&utm_medium=readme&utm_campaign=python-sdk
+Project-URL: Repository, https://github.com/tweetapi/tweetapi-python
+Project-URL: Issues, https://github.com/tweetapi/tweetapi-python/issues
+Author-email: TweetAPI <support@tweetapi.com>
+License-Expression: MIT
+Keywords: social media api,tweet api,tweetapi,tweets,twitter,twitter api,twitter client,twitter data,twitter library,twitter sdk,twitter wrapper,x api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: responses>=0.23.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TweetAPI Python SDK
+
+Official Python SDK for [TweetAPI](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk) — the Twitter/X Data API for developers and researchers.
+
+Access tweets, user profiles, followers, analytics, and full interaction capabilities. 70+ endpoints with built-in error handling and type hints.
+
+## Install
+
+```bash
+pip install tweetapi
+```
+
+## Quick Start
+
+```python
+from tweetapi import TweetAPI
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+# Get a user profile
+user = client.user.get_by_username(username="elonmusk")
+print(user["data"]["followerCount"])  # 180000000
+
+# Search tweets
+results = client.explore.search(query="bitcoin", type="Latest")
+
+# Get followers with pagination
+followers = client.user.get_followers(user_id="123456")
+next_page = client.user.get_followers(
+    user_id="123456",
+    cursor=followers["pagination"]["nextCursor"],
+)
+```
+
+> **Get your free API key** — [100 requests, no credit card required](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+
+## Features
+
+- **70+ endpoints** covering users, tweets, posts, interactions, DMs, communities, spaces, and search
+- **Full type hints** with TypedDict definitions for IDE autocomplete
+- **Solid error handling** with typed exceptions (`RateLimitError`, `NotFoundError`, etc.)
+- **Single dependency** — `requests` only
+- **Pagination support** with cursor-based navigation
+- **Python 3.9+** compatible
+
+## API Reference
+
+### User
+
+| Method | Description |
+|--------|-------------|
+| `client.user.get_by_username(username=...)` | Get user profile by username |
+| `client.user.get_by_usernames(usernames=...)` | Get multiple users (comma-separated) |
+| `client.user.get_by_user_id(user_id=...)` | Get user profile by ID |
+| `client.user.get_by_user_ids(user_ids=...)` | Get multiple users by IDs |
+| `client.user.get_tweets(user_id=...)` | Get a user's tweets |
+| `client.user.get_tweets_and_replies(user_id=...)` | Get tweets and replies |
+| `client.user.get_following(user_id=...)` | Get who a user follows |
+| `client.user.get_followers(user_id=...)` | Get a user's followers |
+| `client.user.get_verified_followers(user_id=...)` | Get verified followers |
+| `client.user.get_subscriptions(user_id=...)` | Get subscriptions |
+| `client.user.get_following_v1(user_id=...)` | Get following (v1, supports count) |
+| `client.user.get_followers_v1(user_id=...)` | Get followers (v1, supports count) |
+| `client.user.get_following_ids(user_id=...)` | Get following user IDs |
+| `client.user.get_followers_ids(user_id=...)` | Get follower user IDs |
+| `client.user.check_follow(subject_id=..., target_id=...)` | Check follow relationship |
+| `client.user.about_account(username=...)` | Get account transparency info |
+
+### Tweet
+
+| Method | Description |
+|--------|-------------|
+| `client.tweet.get_details_and_conversation(tweet_id=...)` | Get tweet details and replies |
+| `client.tweet.get_details_by_ids(ids=...)` | Get multiple tweets (max 200) |
+| `client.tweet.get_retweets(tweet_id=...)` | Get who retweeted |
+| `client.tweet.get_quotes(tweet_id=...)` | Get quote tweets |
+| `client.tweet.translate(tweet_id=..., dst_lang=...)` | Translate a tweet |
+
+### Post
+
+| Method | Description |
+|--------|-------------|
+| `client.post.create_post(auth_token=..., text=..., proxy=...)` | Create a tweet |
+| `client.post.create_post_quote(auth_token=..., text=..., attachment_url=..., proxy=...)` | Quote tweet |
+| `client.post.create_post_with_media(auth_token=..., text=..., media=..., proxy=...)` | Tweet with media |
+| `client.post.reply_post(auth_token=..., text=..., tweet_id=..., proxy=...)` | Reply to a tweet |
+| `client.post.reply_post_with_media(...)` | Reply with media |
+| `client.post.delete_post(auth_token=..., tweet_id=...)` | Delete a tweet |
+
+### Interaction
+
+| Method | Description |
+|--------|-------------|
+| `client.interaction.favorite_post(auth_token=..., tweet_id=...)` | Like a tweet |
+| `client.interaction.unfavorite_post(auth_token=..., tweet_id=...)` | Unlike a tweet |
+| `client.interaction.retweet(auth_token=..., tweet_id=...)` | Retweet |
+| `client.interaction.delete_retweet(auth_token=..., tweet_id=...)` | Remove retweet |
+| `client.interaction.bookmark(auth_token=..., tweet_id=...)` | Bookmark a tweet |
+| `client.interaction.delete_bookmark(auth_token=..., tweet_id=...)` | Remove bookmark |
+| `client.interaction.follow(auth_token=..., user_id=...)` | Follow a user |
+| `client.interaction.unfollow(auth_token=..., user_id=...)` | Unfollow a user |
+| `client.interaction.add_member_to_list(auth_token=..., list_id=..., user_id=...)` | Add to list |
+| `client.interaction.remove_member_from_list(auth_token=..., list_id=..., user_id=...)` | Remove from list |
+| `client.interaction.get_notifications(auth_token=...)` | Get notifications |
+| `client.interaction.get_user_analytics(auth_token=...)` | Get analytics |
+
+### List
+
+| Method | Description |
+|--------|-------------|
+| `client.list.get_details(list_id=...)` | Get list details |
+| `client.list.get_tweets(list_id=...)` | Get tweets in a list |
+| `client.list.get_members(list_id=...)` | Get list members |
+| `client.list.get_followers(list_id=...)` | Get list followers |
+
+### Community
+
+| Method | Description |
+|--------|-------------|
+| `client.community.get_details(community_id=...)` | Get community details |
+| `client.community.get_tweets(community_id=..., sort_by=...)` | Get community tweets |
+| `client.community.get_members(community_id=...)` | Get members |
+| `client.community.search(query=...)` | Search communities |
+| `client.community.create_post(auth_token=..., text=..., community_id=..., proxy=...)` | Post in community |
+| `client.community.create_post_with_media(...)` | Post with media |
+| `client.community.reply_post(...)` | Reply to community post |
+| `client.community.reply_post_with_media(...)` | Reply with media |
+| `client.community.join(auth_token=..., community_id=...)` | Join |
+| `client.community.leave(auth_token=..., community_id=...)` | Leave |
+
+### Space
+
+| Method | Description |
+|--------|-------------|
+| `client.space.get_by_id(space_id=...)` | Get Space details |
+| `client.space.get_stream_url(media_key=...)` | Get HLS stream URL |
+
+### Explore
+
+| Method | Description |
+|--------|-------------|
+| `client.explore.search(query=..., type=...)` | Search tweets/users/photos/videos |
+
+### Auth
+
+| Method | Description |
+|--------|-------------|
+| `client.auth.login(username=..., password=..., proxy=...)` | Log in, get auth tokens |
+
+### X Chat (Encrypted DMs)
+
+| Method | Description |
+|--------|-------------|
+| `client.xchat.setup(auth_token=..., user_id=..., pin=...)` | Initialize encrypted DMs |
+| `client.xchat.get_conversations(auth_token=...)` | List conversations |
+| `client.xchat.send(auth_token=..., recipient_id=..., message=...)` | Send message |
+| `client.xchat.get_history(auth_token=..., conversation_id=...)` | Get history |
+| `client.xchat.can_dm(auth_token=..., user_ids=...)` | Check DM availability |
+
+### Unencrypted DMs
+
+| Method | Description |
+|--------|-------------|
+| `client.dm.send_dm(auth_token=..., conversation_id=..., text=..., proxy=...)` | Send DM |
+| `client.dm.get_dm_permissions(auth_token=..., recipient_ids=...)` | Check permissions |
+| `client.dm.get_inbox_initial_state(auth_token=...)` | Get inbox state |
+| `client.dm.get_inbox_trusted(auth_token=..., cursor=...)` | Trusted inbox |
+| `client.dm.get_inbox_untrusted(auth_token=..., cursor=...)` | Message requests |
+| `client.dm.get_conversation(auth_token=..., conversation_id=...)` | Get messages |
+| `client.dm.get_dm_user_updates(auth_token=..., cursor=...)` | DM user updates |
+| `client.dm.accept_conversation(auth_token=..., conversation_id=...)` | Accept request |
+
+## Error Handling
+
+The SDK throws typed exceptions you can catch and handle:
+
+```python
+import time
+from tweetapi import (
+    TweetAPI,
+    TweetAPIError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    NetworkError,
+)
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+try:
+    user = client.user.get_by_username(username="elonmusk")
+except RateLimitError as e:
+    # Wait and retry
+    print(f"Rate limited. Retry in {e.retry_after}s")
+    time.sleep(e.retry_after)
+except NotFoundError:
+    print("User not found")
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Bad request: {e.message}")
+except ServerError:
+    print("API is having issues, try again later")
+except NetworkError:
+    print("Network error — check your connection")
+except TweetAPIError as e:
+    # Catch-all for any other API error
+    print(f"Error [{e.code}]: {e.message}")
+```
+
+Every error includes:
+- `code` — API error code (e.g., `"ACCOUNT_SUSPENDED"`, `"RATE_LIMIT"`)
+- `status_code` — HTTP status code
+- `message` — Human-readable error message
+- `details` — Additional context (field, reason, retry_after, etc.)
+
+## Configuration
+
+```python
+client = TweetAPI(
+    api_key="YOUR_API_KEY",           # Required
+    base_url="https://...",           # Optional (default: https://api.tweetapi.com)
+    timeout=30,                       # Optional (default: 30 seconds)
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- `requests` library
+
+## Links
+
+- [Full Documentation](https://tweetapi.com/docs?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Get API Key (Free)](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Dashboard](https://tweetapi.com/dashboard?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Node.js SDK](https://github.com/tweetapi/tweetapi-node)
+
+## License
+
+MIT
+
+---
+
+*TweetAPI is a third-party service and is not affiliated with X Corp.*

tweetapi-1.0.0/README.md

@@ -0,0 +1,247 @@
+# TweetAPI Python SDK
+
+Official Python SDK for [TweetAPI](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk) — the Twitter/X Data API for developers and researchers.
+
+Access tweets, user profiles, followers, analytics, and full interaction capabilities. 70+ endpoints with built-in error handling and type hints.
+
+## Install
+
+```bash
+pip install tweetapi
+```
+
+## Quick Start
+
+```python
+from tweetapi import TweetAPI
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+# Get a user profile
+user = client.user.get_by_username(username="elonmusk")
+print(user["data"]["followerCount"])  # 180000000
+
+# Search tweets
+results = client.explore.search(query="bitcoin", type="Latest")
+
+# Get followers with pagination
+followers = client.user.get_followers(user_id="123456")
+next_page = client.user.get_followers(
+    user_id="123456",
+    cursor=followers["pagination"]["nextCursor"],
+)
+```
+
+> **Get your free API key** — [100 requests, no credit card required](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+
+## Features
+
+- **70+ endpoints** covering users, tweets, posts, interactions, DMs, communities, spaces, and search
+- **Full type hints** with TypedDict definitions for IDE autocomplete
+- **Solid error handling** with typed exceptions (`RateLimitError`, `NotFoundError`, etc.)
+- **Single dependency** — `requests` only
+- **Pagination support** with cursor-based navigation
+- **Python 3.9+** compatible
+
+## API Reference
+
+### User
+
+| Method | Description |
+|--------|-------------|
+| `client.user.get_by_username(username=...)` | Get user profile by username |
+| `client.user.get_by_usernames(usernames=...)` | Get multiple users (comma-separated) |
+| `client.user.get_by_user_id(user_id=...)` | Get user profile by ID |
+| `client.user.get_by_user_ids(user_ids=...)` | Get multiple users by IDs |
+| `client.user.get_tweets(user_id=...)` | Get a user's tweets |
+| `client.user.get_tweets_and_replies(user_id=...)` | Get tweets and replies |
+| `client.user.get_following(user_id=...)` | Get who a user follows |
+| `client.user.get_followers(user_id=...)` | Get a user's followers |
+| `client.user.get_verified_followers(user_id=...)` | Get verified followers |
+| `client.user.get_subscriptions(user_id=...)` | Get subscriptions |
+| `client.user.get_following_v1(user_id=...)` | Get following (v1, supports count) |
+| `client.user.get_followers_v1(user_id=...)` | Get followers (v1, supports count) |
+| `client.user.get_following_ids(user_id=...)` | Get following user IDs |
+| `client.user.get_followers_ids(user_id=...)` | Get follower user IDs |
+| `client.user.check_follow(subject_id=..., target_id=...)` | Check follow relationship |
+| `client.user.about_account(username=...)` | Get account transparency info |
+
+### Tweet
+
+| Method | Description |
+|--------|-------------|
+| `client.tweet.get_details_and_conversation(tweet_id=...)` | Get tweet details and replies |
+| `client.tweet.get_details_by_ids(ids=...)` | Get multiple tweets (max 200) |
+| `client.tweet.get_retweets(tweet_id=...)` | Get who retweeted |
+| `client.tweet.get_quotes(tweet_id=...)` | Get quote tweets |
+| `client.tweet.translate(tweet_id=..., dst_lang=...)` | Translate a tweet |
+
+### Post
+
+| Method | Description |
+|--------|-------------|
+| `client.post.create_post(auth_token=..., text=..., proxy=...)` | Create a tweet |
+| `client.post.create_post_quote(auth_token=..., text=..., attachment_url=..., proxy=...)` | Quote tweet |
+| `client.post.create_post_with_media(auth_token=..., text=..., media=..., proxy=...)` | Tweet with media |
+| `client.post.reply_post(auth_token=..., text=..., tweet_id=..., proxy=...)` | Reply to a tweet |
+| `client.post.reply_post_with_media(...)` | Reply with media |
+| `client.post.delete_post(auth_token=..., tweet_id=...)` | Delete a tweet |
+
+### Interaction
+
+| Method | Description |
+|--------|-------------|
+| `client.interaction.favorite_post(auth_token=..., tweet_id=...)` | Like a tweet |
+| `client.interaction.unfavorite_post(auth_token=..., tweet_id=...)` | Unlike a tweet |
+| `client.interaction.retweet(auth_token=..., tweet_id=...)` | Retweet |
+| `client.interaction.delete_retweet(auth_token=..., tweet_id=...)` | Remove retweet |
+| `client.interaction.bookmark(auth_token=..., tweet_id=...)` | Bookmark a tweet |
+| `client.interaction.delete_bookmark(auth_token=..., tweet_id=...)` | Remove bookmark |
+| `client.interaction.follow(auth_token=..., user_id=...)` | Follow a user |
+| `client.interaction.unfollow(auth_token=..., user_id=...)` | Unfollow a user |
+| `client.interaction.add_member_to_list(auth_token=..., list_id=..., user_id=...)` | Add to list |
+| `client.interaction.remove_member_from_list(auth_token=..., list_id=..., user_id=...)` | Remove from list |
+| `client.interaction.get_notifications(auth_token=...)` | Get notifications |
+| `client.interaction.get_user_analytics(auth_token=...)` | Get analytics |
+
+### List
+
+| Method | Description |
+|--------|-------------|
+| `client.list.get_details(list_id=...)` | Get list details |
+| `client.list.get_tweets(list_id=...)` | Get tweets in a list |
+| `client.list.get_members(list_id=...)` | Get list members |
+| `client.list.get_followers(list_id=...)` | Get list followers |
+
+### Community
+
+| Method | Description |
+|--------|-------------|
+| `client.community.get_details(community_id=...)` | Get community details |
+| `client.community.get_tweets(community_id=..., sort_by=...)` | Get community tweets |
+| `client.community.get_members(community_id=...)` | Get members |
+| `client.community.search(query=...)` | Search communities |
+| `client.community.create_post(auth_token=..., text=..., community_id=..., proxy=...)` | Post in community |
+| `client.community.create_post_with_media(...)` | Post with media |
+| `client.community.reply_post(...)` | Reply to community post |
+| `client.community.reply_post_with_media(...)` | Reply with media |
+| `client.community.join(auth_token=..., community_id=...)` | Join |
+| `client.community.leave(auth_token=..., community_id=...)` | Leave |
+
+### Space
+
+| Method | Description |
+|--------|-------------|
+| `client.space.get_by_id(space_id=...)` | Get Space details |
+| `client.space.get_stream_url(media_key=...)` | Get HLS stream URL |
+
+### Explore
+
+| Method | Description |
+|--------|-------------|
+| `client.explore.search(query=..., type=...)` | Search tweets/users/photos/videos |
+
+### Auth
+
+| Method | Description |
+|--------|-------------|
+| `client.auth.login(username=..., password=..., proxy=...)` | Log in, get auth tokens |
+
+### X Chat (Encrypted DMs)
+
+| Method | Description |
+|--------|-------------|
+| `client.xchat.setup(auth_token=..., user_id=..., pin=...)` | Initialize encrypted DMs |
+| `client.xchat.get_conversations(auth_token=...)` | List conversations |
+| `client.xchat.send(auth_token=..., recipient_id=..., message=...)` | Send message |
+| `client.xchat.get_history(auth_token=..., conversation_id=...)` | Get history |
+| `client.xchat.can_dm(auth_token=..., user_ids=...)` | Check DM availability |
+
+### Unencrypted DMs
+
+| Method | Description |
+|--------|-------------|
+| `client.dm.send_dm(auth_token=..., conversation_id=..., text=..., proxy=...)` | Send DM |
+| `client.dm.get_dm_permissions(auth_token=..., recipient_ids=...)` | Check permissions |
+| `client.dm.get_inbox_initial_state(auth_token=...)` | Get inbox state |
+| `client.dm.get_inbox_trusted(auth_token=..., cursor=...)` | Trusted inbox |
+| `client.dm.get_inbox_untrusted(auth_token=..., cursor=...)` | Message requests |
+| `client.dm.get_conversation(auth_token=..., conversation_id=...)` | Get messages |
+| `client.dm.get_dm_user_updates(auth_token=..., cursor=...)` | DM user updates |
+| `client.dm.accept_conversation(auth_token=..., conversation_id=...)` | Accept request |
+
+## Error Handling
+
+The SDK throws typed exceptions you can catch and handle:
+
+```python
+import time
+from tweetapi import (
+    TweetAPI,
+    TweetAPIError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    ServerError,
+    NetworkError,
+)
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+try:
+    user = client.user.get_by_username(username="elonmusk")
+except RateLimitError as e:
+    # Wait and retry
+    print(f"Rate limited. Retry in {e.retry_after}s")
+    time.sleep(e.retry_after)
+except NotFoundError:
+    print("User not found")
+except AuthenticationError:
+    print("Invalid API key")
+except ValidationError as e:
+    print(f"Bad request: {e.message}")
+except ServerError:
+    print("API is having issues, try again later")
+except NetworkError:
+    print("Network error — check your connection")
+except TweetAPIError as e:
+    # Catch-all for any other API error
+    print(f"Error [{e.code}]: {e.message}")
+```
+
+Every error includes:
+- `code` — API error code (e.g., `"ACCOUNT_SUSPENDED"`, `"RATE_LIMIT"`)
+- `status_code` — HTTP status code
+- `message` — Human-readable error message
+- `details` — Additional context (field, reason, retry_after, etc.)
+
+## Configuration
+
+```python
+client = TweetAPI(
+    api_key="YOUR_API_KEY",           # Required
+    base_url="https://...",           # Optional (default: https://api.tweetapi.com)
+    timeout=30,                       # Optional (default: 30 seconds)
+)
+```
+
+## Requirements
+
+- Python 3.9+
+- `requests` library
+
+## Links
+
+- [Full Documentation](https://tweetapi.com/docs?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Get API Key (Free)](https://tweetapi.com?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Dashboard](https://tweetapi.com/dashboard?utm_source=github&utm_medium=readme&utm_campaign=python-sdk)
+- [Node.js SDK](https://github.com/tweetapi/tweetapi-node)
+
+## License
+
+MIT
+
+---
+
+*TweetAPI is a third-party service and is not affiliated with X Corp.*

tweetapi-1.0.0/examples/create_post.py

@@ -0,0 +1,37 @@
+from tweetapi import TweetAPI, AuthenticationError, TweetAPIError
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+try:
+    # First, log in to get an auth token
+    login_result = client.auth.login(
+        username="your_twitter_username",
+        password="your_twitter_password",
+        proxy="hostname:port@username:password",
+    )
+
+    auth_token = login_result["data"]["cookies"]["auth_token"]
+    print(f'Logged in as @{login_result["data"]["user"]["username"]}')
+
+    # Create a tweet
+    post = client.post.create_post(
+        auth_token=auth_token,
+        text="Hello from TweetAPI! 🚀",
+        proxy="hostname:port@username:password",
+    )
+
+    print(f'Tweet created: {post["data"]["metadata"]["tweet_id"]}')
+    print(f'URL: {post["data"]["metadata"]["url"]}')
+
+    # Like the tweet we just created
+    client.interaction.favorite_post(
+        auth_token=auth_token,
+        tweet_id=post["data"]["id"],
+        proxy="hostname:port@username:password",
+    )
+    print("Liked the tweet!")
+
+except AuthenticationError:
+    print("Authentication failed. Check your credentials.")
+except TweetAPIError as e:
+    print(f"API error [{e.code}]: {e.message}")

tweetapi-1.0.0/examples/get_user.py

@@ -0,0 +1,31 @@
+from tweetapi import TweetAPI, NotFoundError, RateLimitError, TweetAPIError
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+try:
+    # Get a single user by username
+    user = client.user.get_by_username(username="elonmusk")
+    data = user["data"]
+    print(f'{data["name"]} (@{data["username"]})')
+    print(f'Followers: {data["followerCount"]:,}')
+    print(f'Tweets: {data["tweetCount"]:,}')
+    print(f'Verified: {data["isBlueVerified"]}')
+
+    # Get first page of followers
+    followers = client.user.get_followers(user_id=data["id"])
+    print(f"\nFirst {len(followers['data'])} followers:")
+    for follower in followers["data"][:5]:
+        print(f'  - @{follower["username"]} ({follower["followerCount"]} followers)')
+
+    # Paginate to next page
+    next_cursor = followers["pagination"]["nextCursor"]
+    if next_cursor:
+        next_page = client.user.get_followers(user_id=data["id"], cursor=next_cursor)
+        print(f"\nNext page: {len(next_page['data'])} more followers")
+
+except NotFoundError:
+    print("User not found")
+except RateLimitError as e:
+    print(f"Rate limited. Retry in {e.retry_after} seconds")
+except TweetAPIError as e:
+    print(f"API error [{e.code}]: {e.message}")

tweetapi-1.0.0/examples/search_tweets.py

@@ -0,0 +1,20 @@
+from tweetapi import TweetAPI
+
+client = TweetAPI(api_key="YOUR_API_KEY")
+
+# Search for latest tweets about Bitcoin
+results = client.explore.search(query="bitcoin", type="Latest")
+
+print(f'Found {results["meta"]["resultCount"]} results in {results["meta"]["completedIn"]}ms\n')
+
+for item in results["data"]:
+    if "text" in item and "author" in item:
+        author = item["author"]
+        print(f'@{author["username"]}: {item["text"][:100]}')
+        print(f'  ♥ {item["likeCount"]}  🔁 {item["retweetCount"]}  💬 {item["replyCount"]}\n')
+
+# Paginate if more results exist
+next_cursor = results["pagination"]["nextCursor"]
+if next_cursor:
+    print(f'More results available. Use cursor to paginate:')
+    print(f'  cursor="{next_cursor}"')