X-Client

A modern X/Twitter client library built with Bun and Playwright, featuring browser-based authentication with anti-detection capabilities and parallel search for multiple terms.

Features

• Browser-based Authentication - Uses Playwright with fingerprint injection to bypass anti-bot measures
• Parallel Search - Search multiple terms simultaneously for faster results
• Cookie Persistence - Save and restore sessions via cookies.json
• Proxy Support - Full proxy support with simple ip:port:user:pass format
• Type-Safe - Full TypeScript support with detailed type definitions

Installation

# Install dependencies
bun install

# Install Playwright browsers
bunx playwright install chromium

Quick Start

1. Set up cookies

Export your X/Twitter cookies using a browser extension (like "Cookie-Editor") and save them to cookies.json:

[
  {
    "domain": ".x.com",
    "name": "auth_token",
    "value": "your_auth_token",
    ...
  },
  {
    "domain": ".x.com",
    "name": "ct0",
    "value": "your_ct0_token",
    ...
  }
]

2. Use the client

import { XClient } from './src';

const client = new XClient({
  headless: true,
  cookiesPath: './cookies.json',
});

// Login with cookies
await client.loginWithCookies();

// Search multiple terms in parallel
const results = await client.search('$surge, ai agents, crypto', {
  mode: 'Top',
  count: 50, // per term
});

console.log(`Found ${results.totalCount} tweets total`);

// Get tweets as flat array
for (const tweet of results.allTweets) {
  console.log(`@${tweet.username}: ${tweet.text}`);
}

await client.close();

API Reference

XClient

const client = new XClient({
  headless?: boolean;      // Default: true
  cookiesPath?: string;    // Default: './cookies.json'
  debug?: boolean;         // Default: false
  timeout?: number;        // Default: 30000
  proxy?: string | ProxyConfig;  // Optional proxy
});

Methods

login(username, password, email?)

Login with credentials. Saves cookies on success.

loginWithCookies(path?)

Login using saved cookies. Returns { success: boolean, error?: string }.

search(terms, options?)

Search for tweets. Supports multiple terms in parallel.

// Single term
await client.search('bitcoin', { count: 50 });

// Multiple terms (comma-separated)
await client.search('$surge, ai agents, crypto', { count: 25 });

// Multiple terms (array)
await client.search(['$surge', 'ai agents'], { count: 100 });

Options:

• mode: 'Top' | 'Latest' | 'Photos' | 'Videos' (default: 'Top')
• count: Max tweets per term (default: 20, max: 100)
• delay: Delay between parallel requests in ms (default: 100)

searchSingle(query, options?)

Search for a single term (no parallel execution).

searchUsers(query, options?)

Search for user profiles.

getTweets(terms, options?)

Convenience method that returns flat array of tweets.

close()

Close browser and cleanup resources.

Response Types

MultiSearchResponse

interface MultiSearchResponse {
  results: Map<string, Tweet[]>;  // Results by search term
  allTweets: Tweet[];             // All tweets flattened
  totalCount: number;             // Total tweet count
  searchTerms: string[];          // Terms searched
  errors: Map<string, string>;    // Errors by term
}

Tweet

interface Tweet {
  id: string;
  text: string;
  username: string;
  name: string;
  userId: string;
  timeParsed: Date;
  timestamp: number;
  likes: number;
  retweets: number;
  replies: number;
  views: number;
  permanentUrl: string;
  searchTerm?: string;  // The term that found this tweet
  // ... and more
}

Proxy Support

// Simple format: ip:port:username:password
const client = new XClient({
  proxy: '208.195.170.230:65095:OC48765887:VbnAeTwp',
});

// Or as object
const client = new XClient({
  proxy: {
    server: 'http://208.195.170.230:65095',
    username: 'OC48765887',
    password: 'VbnAeTwp',
  },
});

Running Tests

# Run the test script (headless: false for development)
bun run test

# Or run directly
bun run scripts/test.ts

Example: Building an API

See scripts/example-api.ts for an example of using this library to build a JSON API:

import { XClient } from './src';

export async function searchTweets(terms: string, count: number = 25) {
  const client = new XClient({ headless: true });
  await client.loginWithCookies();

  const result = await client.search(terms, { count });

  return {
    tweets: result.allTweets,
    totalCount: result.totalCount,
  };
}

Project Structure

x-client/
├── src/
│   ├── index.ts              # Main exports
│   ├── client.ts             # XClient main class
│   ├── browser/
│   │   ├── manager.ts        # Browser lifecycle management
│   │   └── interceptor.ts    # Response interception
│   ├── auth/
│   │   ├── login.ts          # Login flow
│   │   ├── cookies.ts        # Cookie persistence
│   │   └── session.ts        # Session validation
│   ├── search/
│   │   ├── timeline.ts       # Search implementation
│   │   └── parser.ts         # Response parsing
│   ├── types/                # TypeScript types
│   ├── errors/               # Error classes
│   └── utils/                # Utilities
├── scripts/
│   ├── test.ts               # Test script
│   └── example-api.ts        # API example
├── cookies.json              # Your cookies (gitignored)
└── cookies.example.json      # Example format

License

MIT