@cm-growth-hacking/twitter-client 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thaddeus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,360 @@
+# @thaddeus/twitter-client
+
+Lightweight Twitter/X GraphQL client and CLI tool.
+
+## Quick Start
+
+```bash
+# Install
+bun install
+
+# Set credentials (get from browser DevTools → Application → Cookies)
+export TWITTER_AUTH_TOKEN="your_auth_token"
+export TWITTER_CT0="your_ct0_token"
+
+# Search tweets
+bun run src/cli.ts search "bitcoin"
+
+# Post tweet
+bun run src/cli.ts tweet "Hello World!"
+```
+
+## Features
+
+- 🚀 Zero dependencies (except for CLI colors)
+- 📝 Full TypeScript support
+- 🔐 Cookie-based authentication
+- 🎯 GraphQL API integration
+- 💻 CLI tool included
+- ⚡ Bun-optimized
+
+## Installation
+
+```bash
+npm install @thaddeus/twitter-client
+```
+
+Both `npm` and `bun` work for installation.
+
+Or globally for the CLI:
+
+```bash
+npm install -g @thaddeus/twitter-client
+```
+
+## Authentication
+
+This client uses Twitter's cookie-based authentication (same as the web app). You'll need two values from your browser:
+
+1. **auth_token** - From cookie `auth_token`
+2. **ct0** - From cookie `ct0`
+
+### Getting Credentials
+
+1. Open Twitter/X in your browser
+2. Open Developer Tools (F12)
+3. Go to Application > Storage > Cookies
+4. Copy the values for `auth_token` and `ct0`
+
+### Setting Up Environment
+
+Create a `.env` file:
+
+```bash
+TWITTER_AUTH_TOKEN=your_auth_token_here
+TWITTER_CT0=your_ct0_here
+```
+
+## Known Limitations
+
+- **Tweet Posting Error 226**: New or low-activity accounts may get "looks automated" error. Try posting from web interface first to warm up the account.
+- **Rate Limiting**: Not yet implemented - Twitter may temporarily block rapid requests.
+- **Query ID Rotation**: Query IDs rotate frequently (daily/weekly). Use `twitter update-query-ids --fresh` if commands fail.
+
+## Query ID Management
+
+Twitter rotates GraphQL query IDs frequently. This client handles this automatically:
+
+**Auto-Refresh (Recommended):**
+- On 404 errors, the client automatically refreshes query IDs and retries
+- No manual intervention needed
+- Cache updated to `~/.config/twitter-client/query-ids.json` (24h TTL)
+
+**Manual Refresh:**
+```bash
+twitter update-query-ids        # Update if cache is stale
+twitter update-query-ids --fresh  # Force refresh regardless of cache age
+```
+
+**How It Works:**
+1. Client fetches Twitter's web client JavaScript bundle
+2. Extracts current query IDs using regex patterns
+3. Caches IDs locally with 24-hour TTL
+4. Falls back to baked-in IDs if scraping fails
+
+**Troubleshooting:**
+- If commands fail with "persisted query not found": Run `twitter update-query-ids --fresh`
+- Check cache freshness: `cat ~/.config/twitter-client/query-ids.json`
+- Clear cache: `rm ~/.config/twitter-client/query-ids.json`
+
+## Commands
+
+### whoami
+
+Shows your authenticated Twitter account information.
+
+```bash
+twitter whoami
+```
+
+Example output:
+```
+Logged in as: @username (Display Name)
+User ID: 1234567890
+Followers: 1,234
+Following: 567
+```
+
+**Note:** The `whoami` command uses Twitter's GraphQL API. If you encounter authentication errors, verify your environment variables are set correctly:
+```bash
+echo $TWITTER_AUTH_TOKEN
+echo $TWITTER_CT0
+```
+
+## CLI Usage
+
+Once installed globally, the `twitter` command is available:
+
+```bash
+# Show current user info
+twitter whoami
+
+# Search for tweets
+twitter search "typescript"
+
+# Post a tweet
+twitter tweet "Hello, world!"
+
+# Get a tweet by ID or URL
+twitter get 1234567890
+twitter get https://x.com/user/status/1234567890
+
+# Get tweets from a user
+twitter user username
+
+# Get news timeline
+twitter news
+
+# Get mentions
+twitter mentions
+```
+
+## Library Usage
+
+```typescript
+import { TwitterClient } from '@thaddeus/twitter-client';
+
+const client = new TwitterClient({
+  authToken: process.env.TWITTER_AUTH_TOKEN!,
+  ct0: process.env.TWITTER_CT0!,
+});
+
+// Get current user info
+const result = await client.whoami();
+if (result.success) {
+  console.log(`@${result.user.username}`);
+}
+
+// Search for tweets
+const searchResult = await client.search('typescript');
+if (searchResult.success) {
+  searchResult.tweets.forEach(tweet => {
+    console.log(`@${tweet.author.username}: ${tweet.text}`);
+  });
+}
+
+// Post a tweet
+const postResult = await client.tweet('Hello from the API!');
+if (postResult.success) {
+  console.log(`Tweet ID: ${postResult.tweetId}`);
+}
+
+// Get a tweet
+const tweetResult = await client.getTweet('1234567890');
+if (tweetResult.success) {
+  console.log(tweetResult.tweet.text);
+}
+
+// Get user's tweets
+const userResult = await client.getUserTweets('username');
+if (userResult.success) {
+  userResult.tweets.forEach(tweet => {
+    console.log(tweet.text);
+  });
+}
+
+// Reply to a tweet
+const replyResult = await client.reply('1234567890', 'This is a reply');
+
+// Like a tweet
+const likeResult = await client.likeTweet('1234567890');
+
+// Unlike a tweet
+const unlikeResult = await client.unlikeTweet('1234567890');
+
+// Get news timeline
+const newsResult = await client.getNews();
+if (newsResult.success) {
+  newsResult.items.forEach(item => {
+    console.log(item.headline);
+  });
+}
+
+// Get mentions
+const mentionsResult = await client.getMentions();
+if (mentionsResult.success) {
+  mentionsResult.tweets.forEach(tweet => {
+    console.log(`@${tweet.author.username}: ${tweet.text}`);
+  });
+}
+```
+
+## API Reference
+
+### TwitterClient
+
+#### Constructor
+
+```typescript
+new TwitterClient(options: {
+  authToken: string;
+  ct0: string;
+  timeout?: number;
+})
+```
+
+#### Methods
+
+##### `whoami(): Promise<UserResult>`
+Verify authentication and get current user info.
+
+##### `search(query: string, count?: number): Promise<SearchResult>`
+Search for tweets. Count must be between 1-200 (default: 20).
+
+##### `tweet(text: string): Promise<PostResult>`
+Post a new tweet.
+
+##### `getTweet(tweetIdOrUrl: string): Promise<TweetResult>`
+Get a single tweet by ID or URL.
+
+##### `getUserTweets(username: string, count?: number): Promise<TweetsResult>`
+Get recent tweets from a user.
+
+##### `reply(tweetId: string, text: string): Promise<PostResult>`
+Reply to a tweet.
+
+##### `likeTweet(tweetId: string): Promise<PostResult>`
+Like a tweet.
+
+##### `unlikeTweet(tweetId: string): Promise<PostResult>`
+Unlike a tweet.
+
+##### `getNews(count?: number): Promise<NewsResult>`
+Get news timeline (For You timeline). Count must be between 1-200 (default: 20).
+
+##### `getMentions(count?: number): Promise<TweetsResult>`
+Get mentions timeline. Count must be between 1-200 (default: 20).
+
+### Types
+
+#### `Tweet`
+```typescript
+interface Tweet {
+  id: string;
+  text: string;
+  author: User;
+  createdAt: string;
+  likeCount: number;
+  retweetCount: number;
+  replyCount: number;
+  quoteCount: number;
+  viewCount: number;
+  bookmarkCount: number;
+  media?: MediaItem[];
+  isQuote?: boolean;
+  quotedTweet?: Tweet;
+  isRetweet?: boolean;
+  retweetedTweet?: Tweet;
+  inReplyTo?: string;
+  conversationId?: string;
+}
+```
+
+#### `User`
+```typescript
+interface User {
+  id: string;
+  username: string;
+  name: string;
+  description?: string;
+  followersCount?: number;
+  followingCount?: number;
+  isBlueVerified?: boolean;
+  profileImageUrl?: string;
+  createdAt?: string;
+}
+```
+
+#### `Result<T>`
+All methods return a Result object:
+```typescript
+interface Result<T> {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: string;
+  code: ErrorCode;
+}
+```
+
+## Error Codes
+
+- `AUTH_FAILED` - Authentication credentials are invalid or expired
+- `NETWORK_ERROR` - Network request failed
+- `RATE_LIMITED` - Rate limit exceeded
+- `INVALID_INPUT` - Invalid input parameters
+- `NOT_FOUND` - Resource not found
+- `SERVER_ERROR` - Twitter server error
+- `UNKNOWN_ERROR` - Unknown error occurred
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run tests with live API calls
+TWITTER_LIVE=1 bun test tests/live/
+
+# Build
+bun run build
+
+# Run CLI directly
+bun run dev
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Disclaimer
+
+This project is not affiliated with Twitter/X. Use at your own risk and make sure to comply with Twitter's Terms of Service.