Rop-twitter-client NPM

modified-agent-twitter-client

Modded agent client to do Grok things. This package does not require the Twitter API to use and will run in both the browser and server.

Setup

Configure environment variables for authentication.

TWITTER_USERNAME=    # Account username
TWITTER_PASSWORD=    # Account password
TWITTER_EMAIL=       # Account email

Getting Twitter Cookies

It is important to use Twitter cookies to avoid sending a new login request to Twitter every time you want to perform an action.

In your application, you will likely want to check for existing cookies. If cookies are not available, log in with user authentication credentials and cache the cookies for future use.

const scraper = await getScraper({ authMethod: 'password' });

scraper.getCookies().then((cookies) => {
  console.log(cookies);
  // Remove 'Cookies' and save the cookies as a JSON array
});

Getting Started

const scraper = new Scraper();
await scraper.login('username', 'password');

// If using v2 functionality (currently required to support polls)
await scraper.login(
  'username',
  'password',
  'email',
  'appKey',
  'appSecret',
  'accessToken',
  'accessSecret',
);

const tweets = await scraper.getTweets('elonmusk', 10);
const tweetsAndReplies = scraper.getTweetsAndReplies('elonmusk');
const latestTweet = await scraper.getLatestTweet('elonmusk');
const tweet = await scraper.getTweet('1234567890123456789');
await scraper.sendTweet('Hello world!');

// Create a poll
await scraper.sendTweetV2(
  `What's got you most hyped? Let us know! 🤖💸`,
  undefined,
  {
    poll: {
      options: [
        { label: 'AI Innovations 🤖' },
        { label: 'Crypto Craze 💸' },
        { label: 'Both! 🌌' },
        { label: 'Neither for Me 😅' },
      ],
      durationMinutes: 120, // Duration of the poll in minutes
    },
  },
);

Fetching Specific Tweet Data (V2)

// Fetch a single tweet with poll details
const tweet = await scraper.getTweetV2('1856441982811529619', {
  expansions: ['attachments.poll_ids'],
  pollFields: ['options', 'end_datetime'],
});
console.log('tweet', tweet);

// Fetch multiple tweets with poll and media details
const tweets = await scraper.getTweetsV2(
  ['1856441982811529619', '1856429655215260130'],
  {
    expansions: ['attachments.poll_ids', 'attachments.media_keys'],
    pollFields: ['options', 'end_datetime'],
    mediaFields: ['url', 'preview_image_url'],
  },
);
console.log('tweets', tweets);

API

Authentication

// Log in
await scraper.login('username', 'password');

// Log out
await scraper.logout();

// Check if logged in
const isLoggedIn = await scraper.isLoggedIn();

// Get current session cookies
const cookies = await scraper.getCookies();

// Set current session cookies
await scraper.setCookies(cookies);

// Clear current cookies
await scraper.clearCookies();

Profile

// Get a user's profile
const profile = await scraper.getProfile('TwitterDev');

// Get a user ID from their screen name
const userId = await scraper.getUserIdByScreenName('TwitterDev');

// Get logged-in user's profile
const me = await scraper.me();

Search

import { SearchMode } from 'agent-twitter-client';

// Search for recent tweets
const tweets = scraper.searchTweets('#nodejs', 20, SearchMode.Latest);

// Search for profiles
const profiles = scraper.searchProfiles('John', 10);

// Fetch a page of tweet results
const results = await scraper.fetchSearchTweets('#nodejs', 20, SearchMode.Top);

// Fetch a page of profile results
const profileResults = await scraper.fetchSearchProfiles('John', 10);

Relationships

// Get a user's followers
const followers = scraper.getFollowers('12345', 100);

// Get who a user is following
const following = scraper.getFollowing('12345', 100);

// Fetch a page of a user's followers
const followerResults = await scraper.fetchProfileFollowers('12345', 100);

// Fetch a page of who a user is following
const followingResults = await scraper.fetchProfileFollowing('12345', 100);

// Follow a user
const followUserResults = await scraper.followUser('elonmusk');

Trends

// Get current trends
const trends = await scraper.getTrends();

// Fetch tweets from a list
const listTweets = await scraper.fetchListTweets('1234567890', 50);

Tweets

// Get a user's tweets
const tweets = scraper.getTweets('TwitterDev');

// Fetch the home timeline
const homeTimeline = await scraper.fetchHomeTimeline(10, ['seenTweetId1','seenTweetId2']);

// Get a user's liked tweets
const likedTweets = scraper.getLikedTweets('TwitterDev');

// Get a user's tweets and replies
const tweetsAndReplies = scraper.getTweetsAndReplies('TwitterDev');

// Get tweets matching specific criteria
const timeline = scraper.getTweets('TwitterDev', 100);
const retweets = await scraper.getTweetsWhere(
  timeline,
  (tweet) => tweet.isRetweet,
);

// Get a user's latest tweet
const latestTweet = await scraper.getLatestTweet('TwitterDev');

// Get a specific tweet by ID
const tweet = await scraper.getTweet('1234567890123456789');

// Send a tweet
const sendTweetResults = await scraper.sendTweet('Hello world!');

// Send a quote tweet - Media files are optional
const sendQuoteTweetResults = await scraper.sendQuoteTweet(
  'Hello world!',
  '1234567890123456789',
  ['mediaFile1', 'mediaFile2'],
);

// Retweet a tweet
const retweetResults = await scraper.retweet('1234567890123456789');

// Like a tweet
const likeTweetResults = await scraper.likeTweet('1234567890123456789');

Sending Tweets with Media

Media Handling

The scraper requires media files to be processed into a specific format before sending:

Media must be converted to Buffer format
Each media file needs its MIME type specified
This helps the scraper distinguish between image and video processing models

Basic Tweet with Media

// Example: Sending a tweet with media attachments
const mediaData = [
  {
    data: fs.readFileSync('path/to/image.jpg'),
    mediaType: 'image/jpeg',
  },
  {
    data: fs.readFileSync('path/to/video.mp4'),
    mediaType: 'video/mp4',
  },
];

await scraper.sendTweet('Hello world!', undefined, mediaData);

Supported Media Types

// Image formats and their MIME types
const imageTypes = {
  '.jpg': 'image/jpeg',
  '.jpeg': 'image/jpeg',
  '.png': 'image/png',
  '.gif': 'image/gif',
};

// Video format
const videoTypes = {
  '.mp4': 'video/mp4',
};

Media Upload Limitations

Maximum 4 images per tweet
Only 1 video per tweet
Maximum video file size: 512MB
Supported image formats: JPG, PNG, GIF
Supported video format: MP4

Grok Integration

This client provides programmatic access to Grok through Twitter's interface. Grok is Twitter's AI assistant that has direct access to real-time Twitter data and can analyze current Twitter content. This integration allows you to interact with Grok programmatically, including access to its thinking process and reasoning traces.

Basic Usage

const scraper = new Scraper();
await scraper.login('username', 'password');

// Create a new conversation explicitly
const conversationId = await scraper.createGrokConversation();

// Start chatting with Grok
const response = await scraper.grokChat({
  messages: [{ role: 'user', content: 'What are your thoughts on AI?' }],
  fetchThinkingTraces: true, // Optional: get Grok's reasoning process
  enableReasoning: true,     // Optional: enable reasoning mode (default: true)
  enableDeepsearch: false    // Optional: enable deep search mode (default: false)
});

console.log(response.message); // Grok's response
console.log(response.messages); // Full conversation history
console.log(response.thinkingTraces); // Grok's reasoning process

Reasoning vs Deep Search Mode

Grok supports two primary modes of operation:

Reasoning Mode (enableReasoning: true):
- Better for analytical questions
- Shows step-by-step thinking process
- Good for math, logic problems, and structured analysis
- Default mode if not specified
Deep Search Mode (enableDeepsearch: true):
- Better for research and information gathering
- Searches through Twitter content more thoroughly
- Good for finding specific information or trends
- Disabled by default to optimize response time

You can enable both modes simultaneously for complex queries:

const response = await scraper.grokChat({
  messages: [{ 
    role: 'user', 
    content: 'Analyze recent AI discussions on Twitter and explain key trends'
  }],
  enableReasoning: true,
  enableDeepsearch: true,
  fetchThinkingTraces: true
});

Continuing Conversations

You can continue conversations by providing the conversation ID and previous messages:

const followUpResponse = await scraper.grokChat({
  conversationId: response.conversationId,
  messages: [
    ...response.messages,
    { role: 'user', content: 'Can you elaborate on that?' }
  ],
  fetchThinkingTraces: true
});

Handling Rate Limits

Grok has rate limits of approximately 5 messages every 2 hours for non-premium accounts. The client provides detailed rate limit information:

const response = await scraper.grokChat({
  messages: [{ role: 'user', content: 'Hello!' }],
});

if (response.rateLimit?.isRateLimited) {
  console.log('Rate limit hit:', response.rateLimit.message);
  if (response.rateLimit.upsellInfo) {
    console.log('Usage limit:', response.rateLimit.upsellInfo.usageLimit);
    console.log('Quota duration:', response.rateLimit.upsellInfo.quotaDuration);
    console.log('Upgrade info:', response.rateLimit.upsellInfo.message);
  }
}

Response Types

The Grok integration includes TypeScript types for better development experience:

interface GrokChatOptions {
  messages: GrokMessage[];
  conversationId?: string;
  returnSearchResults?: boolean;
  returnCitations?: boolean;
  fetchThinkingTraces?: boolean;
}

interface GrokChatResponse {
  conversationId: string;
  message: string;
  messages: GrokMessage[];
  webResults?: any[];
  metadata?: any;
  rateLimit?: GrokRateLimit;
  thinkingTraces?: GrokConversationItem[];
}

interface GrokConversationItem {
  chat_item_id: string;
  created_at_ms: number;
  grok_mode: string;
  message: string;
  thinking_trace?: string;
  is_partial: boolean;
  sender_type: 'Agent' | 'User';
}

Advanced Usage

// Get Grok's detailed thinking process
const response = await scraper.grokChat({
  messages: [{ role: 'user', content: 'Research quantum computing' }],
  fetchThinkingTraces: true,
  returnSearchResults: true
});

// Access thinking traces
if (response.thinkingTraces) {
  response.thinkingTraces.forEach(trace => {
    if (trace.sender_type === 'Agent') {
      console.log('Reasoning:', trace.thinking_trace);
      console.log('Final response:', trace.message);
    }
  });
}

// Access web results if available
if (response.webResults) {
  console.log('Sources:', response.webResults);
}

Limitations

Rate limits are strictly enforced (approximately 5 messages/2 hours for non-premium)
Message history and context length are limited
Web search results may not always be available
Response times can vary based on server load