chore(release): 0.5.0

feat: add following and followers commands

CHANGELOG.md

@@ -1,9 +1,26 @@
 # Changelog
 
+## 0.5.0 — 2026-01-01
+
+### Added
+- `likes` command to list your liked tweets (thanks @swairshah).
+- Quoted tweet data in JSON output + `--quote-depth` (thanks @alexknowshtml).
+- `following`/`followers` commands to list users (thanks @lockmeister).
+
+### Changed
+- Query ID updater now tracks the Likes GraphQL operation.
+- Query ID updater now tracks Following/Followers GraphQL operations.
+- Query ID updater now tracks BookmarkFolderTimeline and keeps bookmark query IDs seeded.
+- `following`/`followers` JSON user fields are now camelCase (`followersCount`, `followingCount`, `isBlueVerified`, `profileImageUrl`, `createdAt`).
+- Cookie extraction timeout is now configurable (default 30s on macOS) via `--cookie-timeout` / `BIRD_COOKIE_TIMEOUT_MS` (thanks @tylerseymour).
+- Search now paginates beyond 20 results when using `-n` (thanks @ryanh-ai).
+- Library exports are now separated from the CLI entrypoint for easier embedding.
+
 ## 0.4.1 — 2025-12-31
 
 ### Added
 - `bookmarks` command to list your bookmarked tweets.
+- `bookmarks --folder-id` to fetch bookmark folders (thanks @tylerseymour).
 
 ### Changed
 - Cookie extraction now uses `@steipete/sweet-cookie` (drops `sqlite3` CLI + custom browser readers in `bird`).

README.md

@@ -50,11 +50,35 @@ bird mentions --user @steipete -n 5
 
 # Bookmarks
 bird bookmarks -n 5
+bird bookmarks --folder-id 123456789123456789 -n 5 # https://x.com/i/bookmarks/<folder-id>
+
+# Likes
+bird likes -n 5
+
+# Following (who you follow)
+bird following -n 20
+bird following --user 12345678 -n 10  # by user ID
+
+# Followers (who follows you)
+bird followers -n 20
+bird followers --user 12345678 -n 10  # by user ID
 
 # Refresh GraphQL query IDs cache (no rebuild)
 bird query-ids --fresh
 ```
 
+## Library
+
+`bird` can be used as a library (same GraphQL client as the CLI):
+
+```ts
+import { TwitterClient, resolveCredentials } from '@steipete/bird';
+
+const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
+const client = new TwitterClient({ cookies });
+const result = await client.search('from:steipete', 50);
+```
+
 ## Commands
 
 - `bird tweet "<text>"` — post a new tweet.
@@ -67,16 +91,27 @@ bird query-ids --fresh
 - `bird thread <tweet-id-or-url> [--json]` — show the full conversation thread.
 - `bird search "<query>" [-n count] [--json]` — search for tweets matching a query.
 - `bird mentions [-n count] [--user @handle] [--json]` — find tweets mentioning a user (defaults to the authenticated user).
-- `bird bookmarks [-n count] [--json]` — list your bookmarked tweets.
+- `bird bookmarks [-n count] [--folder-id id] [--json]` — list your bookmarked tweets (or a specific bookmark folder).
+- `bird likes [-n count] [--json]` — list your liked tweets.
+- `bird following [--user <userId>] [-n count] [--json]` — list users that you (or another user) follow.
+- `bird followers [--user <userId>] [-n count] [--json]` — list users that follow you (or another user).
 - `bird whoami` — print which Twitter account your cookies belong to.
 - `bird check` — show which credentials are available and where they were sourced from.
 
 Global options:
+- `--auth-token <token>`: set the `auth_token` cookie manually.
+- `--ct0 <token>`: set the `ct0` cookie manually.
+- `--cookie-source <safari|chrome|firefox>`: choose browser cookie source (repeatable; order matters).
+- `--chrome-profile <name>`: Chrome profile for cookie extraction.
+- `--firefox-profile <name>`: Firefox profile for cookie extraction.
+- `--cookie-timeout <ms>`: cookie extraction timeout for keychain/OS helpers (milliseconds).
 - `--timeout <ms>`: abort requests after the given timeout (milliseconds).
+- `--quote-depth <n>`: max quoted tweet depth in JSON output (default: 1; 0 disables).
 - `--plain`: stable output (no emoji, no color).
 - `--no-emoji`: disable emoji output.
 - `--no-color`: disable ANSI colors (or set `NO_COLOR=1`).
-- `--cookie-source <safari|chrome|firefox>`: choose browser cookie source (repeatable; order matters).
+- `--media <path>`: attach media file (repeatable, up to 4 images or 1 video).
+- `--alt <text>`: alt text for the corresponding `--media` (repeatable).
 
 ## Authentication (GraphQL)
 
@@ -112,19 +147,55 @@ Example `~/.config/bird/config.json5`:
   // Cookie source order for browser extraction (string or array)
   cookieSource: ["firefox", "safari"],
   firefoxProfile: "default-release",
-  timeoutMs: 20000
+  cookieTimeoutMs: 30000,
+  timeoutMs: 20000,
+  quoteDepth: 1
 }
 ```
 
 Environment shortcuts:
 - `BIRD_TIMEOUT_MS`
+- `BIRD_COOKIE_TIMEOUT_MS`
+- `BIRD_QUOTE_DEPTH`
 
 ## Output
 
-- `--json` prints raw tweet objects for read/replies/thread/search/mentions/bookmarks.
+- `--json` prints raw tweet objects for read/replies/thread/search/mentions/bookmarks/likes.
 - `read` returns full text for Notes and Articles when present.
 - Use `--plain` for stable, script-friendly output (no emoji, no color).
 
+### JSON Schema
+
+When using `--json`, tweet objects include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Tweet ID |
+| `text` | string | Full tweet text (includes Note/Article content when present) |
+| `author` | object | `{ username, name }` |
+| `authorId` | string? | Author's user ID |
+| `createdAt` | string | Timestamp |
+| `replyCount` | number | Number of replies |
+| `retweetCount` | number | Number of retweets |
+| `likeCount` | number | Number of likes |
+| `conversationId` | string | Thread conversation ID |
+| `inReplyToStatusId` | string? | Parent tweet ID (present if this is a reply) |
+| `quotedTweet` | object? | Embedded quote tweet (same schema; depth controlled by `--quote-depth`) |
+
+When using `--json` with `following`/`followers`, user objects include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | User ID |
+| `username` | string | Username/handle |
+| `name` | string | Display name |
+| `description` | string? | User bio |
+| `followersCount` | number? | Followers count |
+| `followingCount` | number? | Following count |
+| `isBlueVerified` | boolean? | Blue verified flag |
+| `profileImageUrl` | string? | Profile image URL |
+| `createdAt` | string? | Account creation timestamp |
+
 ## Query IDs (GraphQL)
 
 X rotates GraphQL “query IDs” frequently. Each GraphQL operation is addressed as:

package.json

@@ -1,11 +1,12 @@
 {
   "name": "@steipete/bird",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "CLI tool for tweeting and replying via Twitter/X GraphQL API",
   "type": "module",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
-    "bird": "dist/index.js"
+    "bird": "dist/cli.js"
   },
   "files": [
     "dist",
@@ -16,7 +17,7 @@
   "scripts": {
     "build": "pnpm run build:dist && pnpm run build:binary",
     "build:dist": "tsc && node scripts/copy-dist-assets.js",
-    "build:binary": "BIRD_VERSION=$(node -p \"require('./package.json').version\") BIRD_GIT_SHA=$(git rev-parse --short=8 HEAD 2>/dev/null || true) bun build --compile --minify --env=BIRD_* src/index.ts --outfile bird",
+    "build:binary": "BIRD_VERSION=$(node -p \"require('./package.json').version\") BIRD_GIT_SHA=$(git rev-parse --short=8 HEAD 2>/dev/null || true) bun build --compile --minify --env=BIRD_* src/cli.ts --outfile bird",
     "dev": "tsx src/index.ts",
     "bird": "pnpm run build:dist && node dist/index.js",
     "test": "vitest run",

patches/@steipete__sweet-cookie.patch

@@ -0,0 +1,13 @@
+diff --git a/dist/providers/chromeSqliteMac.js b/dist/providers/chromeSqliteMac.js
+index 71c815f77378d03e07061976ac372b3a55a61ac4..3a85a2fce102128d7e7b69145d97bc353f663008 100644
+--- a/dist/providers/chromeSqliteMac.js
++++ b/dist/providers/chromeSqliteMac.js
+@@ -15,7 +15,7 @@ export async function getCookiesFromChromeSqliteMac(options, origins, allowlistN
+     const passwordResult = await readKeychainGenericPasswordFirst({
+         account: 'Chrome',
+         services: ['Chrome Safe Storage'],
+-        timeoutMs: 3_000,
++        timeoutMs: options.timeoutMs ?? 3_000,
+         label: 'Chrome Safe Storage',
+     });
+     if (!passwordResult.ok) {

pnpm-lock.yaml

@@ -4,13 +4,18 @@ settings:
   autoInstallPeers: false
   excludeLinksFromLockfile: false
 
+patchedDependencies:
+  '@steipete/sweet-cookie':
+    hash: 05180a0fa74ba5074775f965db7d4561e59ba51978bd5e955c0e4f058a4ed340
+    path: patches/@steipete__sweet-cookie.patch
+
 importers:
 
   .:
     dependencies:
       '@steipete/sweet-cookie':
         specifier: 0.1.0
-        version: 0.1.0
+        version: 0.1.0(patch_hash=05180a0fa74ba5074775f965db7d4561e59ba51978bd5e955c0e4f058a4ed340)
       commander:
         specifier: ^14.0.2
         version: 14.0.2
@@ -1051,7 +1056,7 @@ snapshots:
 
   '@standard-schema/[email protected]': {}
 
-  '@steipete/[email protected]': {}
+  '@steipete/[email protected](patch_hash=05180a0fa74ba5074775f965db7d4561e59ba51978bd5e955c0e4f058a4ed340)': {}
 
   '@types/[email protected]':
     dependencies:

pnpm-workspace.yaml

@@ -1,2 +1,5 @@
 onlyBuiltDependencies:
   - esbuild
+
+patchedDependencies:
+  '@steipete/sweet-cookie': patches/@steipete__sweet-cookie.patch

scripts/update-query-ids.ts

@@ -14,6 +14,10 @@ const TARGET_OPERATIONS = [
   'TweetDetail',
   'SearchTimeline',
   'Bookmarks',
+  'BookmarkFolderTimeline',
+  'Following',
+  'Followers',
+  'Likes',
 ] as const;
 
 type OperationName = (typeof TARGET_OPERATIONS)[number];

src/cli.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * bird - CLI tool for posting tweets and replies
+ *
+ * Usage:
+ *   bird tweet "Hello world!"
+ *   bird reply <tweet-id> "This is a reply"
+ *   bird reply <tweet-url> "This is a reply"
+ *   bird read <tweet-id-or-url>
+ */
+
+import { Command } from 'commander';
+import { collectCookieSource, createCliContext } from './cli/shared.js';
+import { registerBookmarksCommand } from './commands/bookmarks.js';
+import { registerCheckCommand } from './commands/check.js';
+import { registerHelpCommand } from './commands/help.js';
+import { registerPostCommands } from './commands/post.js';
+import { registerQueryIdsCommand } from './commands/query-ids.js';
+import { registerReadCommands } from './commands/read.js';
+import { registerSearchCommands } from './commands/search.js';
+import { registerUserCommands } from './commands/users.js';
+import { resolveCliInvocation } from './lib/cli-args.js';
+import { getCliVersion } from './lib/version.js';
+
+const program: Command = new Command();
+
+const rawArgs: string[] = process.argv.slice(2);
+const normalizedArgs: string[] = rawArgs[0] === '--' ? rawArgs.slice(1) : rawArgs;
+
+const ctx = createCliContext(normalizedArgs);
+
+const collect = (value: string, previous: string[] = []): string[] => {
+  previous.push(value);
+  return previous;
+};
+
+const KNOWN_COMMANDS = new Set([
+  'tweet',
+  'reply',
+  'query-ids',
+  'read',
+  'replies',
+  'thread',
+  'search',
+  'mentions',
+  'bookmarks',
+  'following',
+  'followers',
+  'likes',
+  'help',
+  'whoami',
+  'check',
+]);
+
+program.addHelpText(
+  'beforeAll',
+  () => `${ctx.colors.banner('bird CLI')} ${ctx.colors.subtitle('— fast X CLI for tweeting, replying, and reading')}`,
+);
+
+program.name('bird').description('Post tweets and replies via Twitter/X GraphQL API').version(getCliVersion());
+
+const formatExample = (command: string, description: string): string =>
+  `${ctx.colors.command(`  ${command}`)}\n${ctx.colors.muted(`    ${description}`)}`;
+
+program.addHelpText(
+  'afterAll',
+  () =>
+    `\n${ctx.colors.section('Examples')}\n${[
+      formatExample('bird whoami', 'Show the logged-in account via GraphQL cookies'),
+      formatExample('bird --firefox-profile default-release whoami', 'Use Firefox profile cookies'),
+      formatExample('bird tweet "hello from bird"', 'Send a tweet'),
+      formatExample('bird replies https://x.com/user/status/1234567890123456789', 'Check replies to a tweet'),
+    ].join('\n\n')}`,
+);
+
+program
+  .option('--auth-token <token>', 'Twitter auth_token cookie')
+  .option('--ct0 <token>', 'Twitter ct0 cookie')
+  .option('--chrome-profile <name>', 'Chrome profile name for cookie extraction', ctx.config.chromeProfile)
+  .option('--firefox-profile <name>', 'Firefox profile name for cookie extraction', ctx.config.firefoxProfile)
+  .option('--cookie-timeout <ms>', 'Cookie extraction timeout in milliseconds (keychain/OS helpers)')
+  .option(
+    '--cookie-source <source>',
+    'Cookie source for browser cookie extraction (repeatable)',
+    collectCookieSource,
+    [],
+  )
+  .option('--media <path>', 'Attach media file (repeatable, up to 4 images or 1 video)', collect, [])
+  .option('--alt <text>', 'Alt text for the corresponding --media (repeatable)', collect, [])
+  .option('--timeout <ms>', 'Request timeout in milliseconds')
+  .option('--quote-depth <depth>', 'Max quoted tweet depth (default: 1; 0 disables)')
+  .option('--plain', 'Plain output (stable, no emoji, no color)')
+  .option('--no-emoji', 'Disable emoji output')
+  .option('--no-color', 'Disable ANSI colors (or set NO_COLOR)');
+
+program.hook('preAction', (_thisCommand, actionCommand) => {
+  ctx.applyOutputFromCommand(actionCommand);
+});
+
+registerHelpCommand(program, ctx);
+registerQueryIdsCommand(program, ctx);
+registerPostCommands(program, ctx);
+registerReadCommands(program, ctx);
+registerSearchCommands(program, ctx);
+registerBookmarksCommand(program, ctx);
+registerUserCommands(program, ctx);
+registerCheckCommand(program, ctx);
+
+const { argv, showHelp } = resolveCliInvocation(normalizedArgs, KNOWN_COMMANDS);
+
+if (showHelp) {
+  program.outputHelp();
+  process.exit(0);
+}
+
+if (argv) {
+  program.parse(argv);
+} else {
+  program.parse(['node', 'bird', ...normalizedArgs]);
+}

src/cli/shared.ts

@@ -0,0 +1,299 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import JSON5 from 'json5';
+import kleur from 'kleur';
+import { type CookieSource, resolveCredentials } from '../lib/cookies.js';
+import { extractTweetId } from '../lib/extract-tweet-id.js';
+import {
+  labelPrefix,
+  type OutputConfig,
+  resolveOutputConfigFromArgv,
+  resolveOutputConfigFromCommander,
+  statusPrefix,
+} from '../lib/output.js';
+import type { TweetData } from '../lib/twitter-client.js';
+
+export type BirdConfig = {
+  chromeProfile?: string;
+  firefoxProfile?: string;
+  cookieSource?: CookieSource | CookieSource[];
+  cookieTimeoutMs?: number;
+  timeoutMs?: number;
+  quoteDepth?: number;
+};
+
+export type MediaSpec = { path: string; alt?: string; mime: string; buffer: Buffer };
+
+export type CliContext = {
+  isTty: boolean;
+  getOutput: () => OutputConfig;
+  colors: {
+    banner: (t: string) => string;
+    subtitle: (t: string) => string;
+    section: (t: string) => string;
+    bullet: (t: string) => string;
+    command: (t: string) => string;
+    option: (t: string) => string;
+    argument: (t: string) => string;
+    description: (t: string) => string;
+    muted: (t: string) => string;
+    accent: (t: string) => string;
+  };
+  p: (kind: Parameters<typeof statusPrefix>[0]) => string;
+  l: (kind: Parameters<typeof labelPrefix>[0]) => string;
+  config: BirdConfig;
+  applyOutputFromCommand: (command: Command) => void;
+  resolveTimeoutFromOptions: (options: { timeout?: string | number }) => number | undefined;
+  resolveQuoteDepthFromOptions: (options: { quoteDepth?: string | number }) => number | undefined;
+  resolveCredentialsFromOptions: (opts: CredentialsOptions) => ReturnType<typeof resolveCredentials>;
+  loadMedia: (opts: { media: string[]; alts: string[] }) => MediaSpec[];
+  printTweets: (tweets: TweetData[], opts?: { json?: boolean; emptyMessage?: string; showSeparator?: boolean }) => void;
+  extractTweetId: (tweetIdOrUrl: string) => string;
+};
+
+const COOKIE_SOURCES: CookieSource[] = ['safari', 'chrome', 'firefox'];
+
+function parseCookieSource(value: string): CookieSource {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === 'safari' || normalized === 'chrome' || normalized === 'firefox') {
+    return normalized;
+  }
+  throw new Error(`Invalid --cookie-source "${value}". Allowed: safari, chrome, firefox.`);
+}
+
+export const collectCookieSource = (value: string, previous: CookieSource[] = []): CookieSource[] => {
+  previous.push(parseCookieSource(value));
+  return previous;
+};
+
+function resolveCookieSourceOrder(input: unknown): CookieSource[] | undefined {
+  if (typeof input === 'string') {
+    return [parseCookieSource(input)];
+  }
+  if (Array.isArray(input)) {
+    const result: CookieSource[] = [];
+    for (const entry of input) {
+      if (typeof entry !== 'string') {
+        continue;
+      }
+      result.push(parseCookieSource(entry));
+    }
+    return result.length > 0 ? result : undefined;
+  }
+  return undefined;
+}
+
+function resolveTimeoutMs(...values: Array<string | number | undefined | null>): number | undefined {
+  for (const value of values) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    const parsed = typeof value === 'number' ? value : Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
+function resolveQuoteDepth(...values: Array<string | number | undefined | null>): number | undefined {
+  for (const value of values) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    const parsed = typeof value === 'number' ? value : Number.parseInt(value, 10);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      return Math.floor(parsed);
+    }
+  }
+  return undefined;
+}
+
+function detectMime(path: string): string | null {
+  const ext = path.toLowerCase();
+  if (ext.endsWith('.jpg') || ext.endsWith('.jpeg')) {
+    return 'image/jpeg';
+  }
+  if (ext.endsWith('.png')) {
+    return 'image/png';
+  }
+  if (ext.endsWith('.webp')) {
+    return 'image/webp';
+  }
+  if (ext.endsWith('.gif')) {
+    return 'image/gif';
+  }
+  if (ext.endsWith('.mp4') || ext.endsWith('.m4v')) {
+    return 'video/mp4';
+  }
+  if (ext.endsWith('.mov')) {
+    return 'video/quicktime';
+  }
+  return null;
+}
+
+function readConfigFile(path: string, warn: (message: string) => void): Partial<BirdConfig> {
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(path, 'utf8');
+    const parsed = JSON5.parse(raw) as Partial<BirdConfig>;
+    return parsed ?? {};
+  } catch (error) {
+    warn(`Failed to parse config at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    return {};
+  }
+}
+
+function loadConfig(warn: (message: string) => void): BirdConfig {
+  const globalPath = join(homedir(), '.config', 'bird', 'config.json5');
+  const localPath = join(process.cwd(), '.birdrc.json5');
+
+  return {
+    ...readConfigFile(globalPath, warn),
+    ...readConfigFile(localPath, warn),
+  };
+}
+
+type CredentialsOptions = {
+  authToken?: string;
+  ct0?: string;
+  chromeProfile?: string;
+  firefoxProfile?: string;
+  cookieSource?: CookieSource[];
+  cookieTimeout?: string | number;
+};
+
+export function createCliContext(normalizedArgs: string[], env: NodeJS.ProcessEnv = process.env): CliContext {
+  const isTty = process.stdout.isTTY;
+  let output: OutputConfig = resolveOutputConfigFromArgv(normalizedArgs, env, isTty);
+  kleur.enabled = output.color;
+
+  const wrap =
+    (styler: (text: string) => string): ((text: string) => string) =>
+    (text: string): string =>
+      isTty ? styler(text) : text;
+
+  const colors = {
+    banner: wrap((t) => kleur.bold().blue(t)),
+    subtitle: wrap((t) => kleur.dim(t)),
+    section: wrap((t) => kleur.bold().white(t)),
+    bullet: wrap((t) => kleur.blue(t)),
+    command: wrap((t) => kleur.bold().cyan(t)),
+    option: wrap((t) => kleur.cyan(t)),
+    argument: wrap((t) => kleur.magenta(t)),
+    description: wrap((t) => kleur.white(t)),
+    muted: wrap((t) => kleur.gray(t)),
+    accent: wrap((t) => kleur.green(t)),
+  };
+
+  const p = (kind: Parameters<typeof statusPrefix>[0]): string => statusPrefix(kind, output);
+  const l = (kind: Parameters<typeof labelPrefix>[0]): string => labelPrefix(kind, output);
+
+  const config = loadConfig((message) => {
+    console.error(colors.muted(`${p('warn')}${message}`));
+  });
+
+  function applyOutputFromCommand(command: Command): void {
+    const opts = command.optsWithGlobals() as { plain?: boolean; emoji?: boolean; color?: boolean };
+    output = resolveOutputConfigFromCommander(opts, env, isTty);
+    kleur.enabled = output.color;
+  }
+
+  function resolveTimeoutFromOptions(options: { timeout?: string | number }): number | undefined {
+    return resolveTimeoutMs(options.timeout, config.timeoutMs, env.BIRD_TIMEOUT_MS);
+  }
+
+  function resolveCookieTimeoutFromOptions(options: { cookieTimeout?: string | number }): number | undefined {
+    return resolveTimeoutMs(options.cookieTimeout, config.cookieTimeoutMs, env.BIRD_COOKIE_TIMEOUT_MS);
+  }
+
+  function resolveQuoteDepthFromOptions(options: { quoteDepth?: string | number }): number | undefined {
+    return resolveQuoteDepth(options.quoteDepth, config.quoteDepth, env.BIRD_QUOTE_DEPTH);
+  }
+
+  function resolveCredentialsFromOptions(opts: CredentialsOptions): ReturnType<typeof resolveCredentials> {
+    const cookieSource = opts.cookieSource?.length
+      ? opts.cookieSource
+      : (resolveCookieSourceOrder(config.cookieSource) ?? COOKIE_SOURCES);
+    return resolveCredentials({
+      authToken: opts.authToken,
+      ct0: opts.ct0,
+      cookieSource,
+      chromeProfile: opts.chromeProfile || config.chromeProfile,
+      firefoxProfile: opts.firefoxProfile || config.firefoxProfile,
+      cookieTimeoutMs: resolveCookieTimeoutFromOptions(opts),
+    });
+  }
+
+  function loadMedia(opts: { media: string[]; alts: string[] }): MediaSpec[] {
+    if (opts.media.length === 0) {
+      return [];
+    }
+    const specs: MediaSpec[] = [];
+    for (const [index, path] of opts.media.entries()) {
+      const mime = detectMime(path);
+      if (!mime) {
+        throw new Error(`Unsupported media type for ${path}. Supported: jpg, jpeg, png, webp, gif, mp4, mov`);
+      }
+      const buffer = readFileSync(path);
+      specs.push({ path, mime, buffer, alt: opts.alts[index] });
+    }
+
+    const videoCount = specs.filter((m) => m.mime.startsWith('video/')).length;
+    if (videoCount > 1) {
+      throw new Error('Only one video can be attached');
+    }
+    if (videoCount === 1 && specs.length > 1) {
+      throw new Error('Video cannot be combined with other media');
+    }
+    if (specs.length > 4) {
+      throw new Error('Maximum 4 media attachments');
+    }
+    return specs;
+  }
+
+  function printTweets(
+    tweets: TweetData[],
+    opts: { json?: boolean; emptyMessage?: string; showSeparator?: boolean } = {},
+  ) {
+    if (opts.json) {
+      console.log(JSON.stringify(tweets, null, 2));
+      return;
+    }
+    if (tweets.length === 0) {
+      console.log(opts.emptyMessage ?? 'No tweets found.');
+      return;
+    }
+    for (const tweet of tweets) {
+      console.log(`\n@${tweet.author.username} (${tweet.author.name}):`);
+      console.log(tweet.text);
+      if (tweet.createdAt) {
+        console.log(`${l('date')}${tweet.createdAt}`);
+      }
+      console.log(`${l('url')}https://x.com/${tweet.author.username}/status/${tweet.id}`);
+      if (opts.showSeparator ?? true) {
+        console.log('─'.repeat(50));
+      }
+    }
+  }
+
+  return {
+    isTty,
+    getOutput: () => output,
+    colors,
+    p,
+    l,
+    config,
+    applyOutputFromCommand,
+    resolveTimeoutFromOptions,
+    resolveQuoteDepthFromOptions,
+    resolveCredentialsFromOptions,
+    loadMedia,
+    printTweets,
+    extractTweetId,
+  };
+}

src/commands/bookmarks.ts

@@ -0,0 +1,47 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+import { extractBookmarkFolderId } from '../lib/extract-bookmark-folder-id.js';
+import { TwitterClient } from '../lib/twitter-client.js';
+
+export function registerBookmarksCommand(program: Command, ctx: CliContext): void {
+  program
+    .command('bookmarks')
+    .description('Get your bookmarked tweets')
+    .option('-n, --count <number>', 'Number of bookmarks to fetch', '20')
+    .option('--folder-id <id>', 'Bookmark folder (collection) id')
+    .option('--json', 'Output as JSON')
+    .action(async (cmdOpts: { count?: string; json?: boolean; folderId?: string }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '20', 10);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs });
+      const folderId = cmdOpts.folderId ? extractBookmarkFolderId(cmdOpts.folderId) : null;
+      if (cmdOpts.folderId && !folderId) {
+        console.error(`${ctx.p('err')}Invalid --folder-id. Expected numeric ID or https://x.com/i/bookmarks/<id>.`);
+        process.exit(1);
+      }
+      const result = folderId
+        ? await client.getBookmarkFolderTimeline(folderId, count)
+        : await client.getBookmarks(count);
+
+      if (result.success && result.tweets) {
+        const emptyMessage = folderId ? 'No bookmarks found in folder.' : 'No bookmarks found.';
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage });
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch bookmarks: ${result.error}`);
+        process.exit(1);
+      }
+    });
+}

src/commands/check.ts

@@ -0,0 +1,48 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+
+export function registerCheckCommand(program: Command, ctx: CliContext): void {
+  program
+    .command('check')
+    .description('Check credential availability')
+    .action(async () => {
+      const opts = program.opts();
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      console.log(`${ctx.p('info')}Credential check`);
+      console.log('─'.repeat(40));
+
+      if (cookies.authToken) {
+        console.log(`${ctx.p('ok')}auth_token: ${cookies.authToken.slice(0, 10)}...`);
+      } else {
+        console.log(`${ctx.p('err')}auth_token: not found`);
+      }
+
+      if (cookies.ct0) {
+        console.log(`${ctx.p('ok')}ct0: ${cookies.ct0.slice(0, 10)}...`);
+      } else {
+        console.log(`${ctx.p('err')}ct0: not found`);
+      }
+
+      if (cookies.source) {
+        console.log(`${ctx.l('source')}${cookies.source}`);
+      }
+
+      if (warnings.length > 0) {
+        console.log(`\n${ctx.p('warn')}Warnings:`);
+        for (const warning of warnings) {
+          console.log(`   - ${warning}`);
+        }
+      }
+
+      if (cookies.authToken && cookies.ct0) {
+        console.log(`\n${ctx.p('ok')}Ready to tweet!`);
+      } else {
+        console.log(`\n${ctx.p('err')}Missing credentials. Options:`);
+        console.log('   1. Login to x.com in Safari/Chrome/Firefox');
+        console.log('   2. Set AUTH_TOKEN and CT0 environment variables');
+        console.log('   3. Use --auth-token and --ct0 flags');
+        process.exit(1);
+      }
+    });
+}

src/commands/help.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+
+export function registerHelpCommand(program: Command, ctx: CliContext): void {
+  program
+    .command('help [command]')
+    .description('Show help for a command')
+    .action((commandName?: string) => {
+      if (!commandName) {
+        program.outputHelp();
+        return;
+      }
+
+      const cmd = program.commands.find((c) => c.name() === commandName);
+      if (!cmd) {
+        console.error(`${ctx.p('err')}Unknown command: ${commandName}`);
+        process.exitCode = 2;
+        return;
+      }
+
+      cmd.outputHelp();
+    });
+}

src/commands/post.ts

@@ -0,0 +1,119 @@
+import type { Command } from 'commander';
+import type { CliContext, MediaSpec } from '../cli/shared.js';
+import { formatTweetUrlLine } from '../lib/output.js';
+import { TwitterClient } from '../lib/twitter-client.js';
+
+async function uploadMediaOrExit(
+  client: TwitterClient,
+  media: MediaSpec[],
+  ctx: CliContext,
+): Promise<string[] | undefined> {
+  if (media.length === 0) {
+    return undefined;
+  }
+
+  const uploaded: string[] = [];
+  for (const item of media) {
+    const res = await client.uploadMedia({ data: item.buffer, mimeType: item.mime, alt: item.alt });
+    if (!res.success || !res.mediaId) {
+      console.error(`${ctx.p('err')}Media upload failed: ${res.error ?? 'Unknown error'}`);
+      process.exit(1);
+    }
+    uploaded.push(res.mediaId);
+  }
+  return uploaded;
+}
+
+export function registerPostCommands(program: Command, ctx: CliContext): void {
+  program
+    .command('tweet')
+    .description('Post a new tweet')
+    .argument('<text>', 'Tweet text')
+    .action(async (text: string) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      let media: MediaSpec[] = [];
+      try {
+        media = ctx.loadMedia({ media: opts.media ?? [], alts: opts.alt ?? [] });
+      } catch (error) {
+        console.error(`${ctx.p('err')}${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+      }
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      if (cookies.source) {
+        console.error(`${ctx.l('source')}${cookies.source}`);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const mediaIds = await uploadMediaOrExit(client, media, ctx);
+      const result = await client.tweet(text, mediaIds);
+
+      if (result.success) {
+        console.log(`${ctx.p('ok')}Tweet posted successfully!`);
+        console.log(formatTweetUrlLine(result.tweetId, ctx.getOutput()));
+      } else {
+        console.error(`${ctx.p('err')}Failed to post tweet: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('reply')
+    .description('Reply to an existing tweet')
+    .argument('<tweet-id-or-url>', 'Tweet ID or URL to reply to')
+    .argument('<text>', 'Reply text')
+    .action(async (tweetIdOrUrl: string, text: string) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      let media: MediaSpec[] = [];
+      try {
+        media = ctx.loadMedia({ media: opts.media ?? [], alts: opts.alt ?? [] });
+      } catch (error) {
+        console.error(`${ctx.p('err')}${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+      }
+      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      if (cookies.source) {
+        console.error(`${ctx.l('source')}${cookies.source}`);
+      }
+
+      console.error(`${ctx.p('info')}Replying to tweet: ${tweetId}`);
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const mediaIds = await uploadMediaOrExit(client, media, ctx);
+      const result = await client.reply(text, tweetId, mediaIds);
+
+      if (result.success) {
+        console.log(`${ctx.p('ok')}Reply posted successfully!`);
+        console.log(formatTweetUrlLine(result.tweetId, ctx.getOutput()));
+      } else {
+        console.error(`${ctx.p('err')}Failed to post reply: ${result.error}`);
+        process.exit(1);
+      }
+    });
+}

src/commands/query-ids.ts

@@ -0,0 +1,66 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+import { runtimeQueryIds } from '../lib/runtime-query-ids.js';
+
+export function registerQueryIdsCommand(program: Command, ctx: CliContext): void {
+  program
+    .command('query-ids')
+    .description('Show or refresh cached Twitter GraphQL query IDs')
+    .option('--json', 'Output as JSON')
+    .option('--fresh', 'Force refresh (downloads X client bundles)', false)
+    .action(async (cmdOpts: { json?: boolean; fresh?: boolean }) => {
+      const operations = [
+        'CreateTweet',
+        'CreateRetweet',
+        'FavoriteTweet',
+        'TweetDetail',
+        'SearchTimeline',
+        'UserArticlesTweets',
+        'Bookmarks',
+        'Following',
+        'Followers',
+        'Likes',
+      ];
+
+      if (cmdOpts.fresh) {
+        console.error(`${ctx.p('info')}Refreshing GraphQL query IDs…`);
+        await runtimeQueryIds.refresh(operations, { force: true });
+      }
+
+      const info = await runtimeQueryIds.getSnapshotInfo();
+      if (!info) {
+        if (cmdOpts.json) {
+          console.log(JSON.stringify({ cached: false, cachePath: runtimeQueryIds.cachePath }, null, 2));
+          return;
+        }
+        console.log(`${ctx.p('warn')}No cached query IDs yet.`);
+        console.log(`${ctx.p('info')}Run: bird query-ids --fresh`);
+        return;
+      }
+
+      if (cmdOpts.json) {
+        console.log(
+          JSON.stringify(
+            {
+              cached: true,
+              cachePath: info.cachePath,
+              fetchedAt: info.snapshot.fetchedAt,
+              isFresh: info.isFresh,
+              ageMs: info.ageMs,
+              ids: info.snapshot.ids,
+              discovery: info.snapshot.discovery,
+            },
+            null,
+            2,
+          ),
+        );
+        return;
+      }
+
+      console.log(`${ctx.p('ok')}GraphQL query IDs cached`);
+      console.log(`path: ${info.cachePath}`);
+      console.log(`fetched_at: ${info.snapshot.fetchedAt}`);
+      console.log(`fresh: ${info.isFresh ? 'yes' : 'no'}`);
+      console.log(`ops: ${Object.keys(info.snapshot.ids).length}`);
+    });
+}

src/commands/read.ts

@@ -0,0 +1,115 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+import { formatStatsLine } from '../lib/output.js';
+import { TwitterClient } from '../lib/twitter-client.js';
+
+export function registerReadCommands(program: Command, ctx: CliContext): void {
+  program
+    .command('read')
+    .description('Read/fetch a tweet by ID or URL')
+    .argument('<tweet-id-or-url>', 'Tweet ID or URL to read')
+    .option('--json', 'Output as JSON')
+    .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+
+      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.getTweet(tweetId);
+
+      if (result.success && result.tweet) {
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(result.tweet, null, 2));
+        } else {
+          console.log(`@${result.tweet.author.username} (${result.tweet.author.name}):`);
+          console.log(result.tweet.text);
+          if (result.tweet.createdAt) {
+            console.log(`\n${ctx.l('date')}${result.tweet.createdAt}`);
+          }
+          console.log(formatStatsLine(result.tweet, ctx.getOutput()));
+        }
+      } else {
+        console.error(`${ctx.p('err')}Failed to read tweet: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('replies')
+    .description('List replies to a tweet (by ID or URL)')
+    .argument('<tweet-id-or-url>', 'Tweet ID or URL')
+    .option('--json', 'Output as JSON')
+    .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.getReplies(tweetId);
+
+      if (result.success && result.tweets) {
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No replies found.' });
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch replies: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('thread')
+    .description('Show the full conversation thread containing the tweet')
+    .argument('<tweet-id-or-url>', 'Tweet ID or URL')
+    .option('--json', 'Output as JSON')
+    .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.getThread(tweetId);
+
+      if (result.success && result.tweets) {
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No thread tweets found.' });
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch thread: ${result.error}`);
+        process.exit(1);
+      }
+    });
+}

src/commands/search.ts

@@ -0,0 +1,96 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+import { mentionsQueryFromUserOption, normalizeHandle } from '../lib/normalize-handle.js';
+import { TwitterClient } from '../lib/twitter-client.js';
+
+export function registerSearchCommands(program: Command, ctx: CliContext): void {
+  program
+    .command('search')
+    .description('Search for tweets')
+    .argument('<query>', 'Search query (e.g., "@clawdbot" or "from:clawdbot")')
+    .option('-n, --count <number>', 'Number of tweets to fetch', '10')
+    .option('--json', 'Output as JSON')
+    .action(async (query: string, cmdOpts: { count?: string; json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '10', 10);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.search(query, count);
+
+      if (result.success && result.tweets) {
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No tweets found.' });
+      } else {
+        console.error(`${ctx.p('err')}Search failed: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('mentions')
+    .description('Find tweets mentioning a user (defaults to current user)')
+    .option('-u, --user <handle>', 'User handle (e.g. @steipete)')
+    .option('-n, --count <number>', 'Number of tweets to fetch', '10')
+    .option('--json', 'Output as JSON')
+    .action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '10', 10);
+
+      const fromUserOpt = mentionsQueryFromUserOption(cmdOpts.user);
+      if (fromUserOpt.error) {
+        console.error(`${ctx.p('err')}${fromUserOpt.error}`);
+        process.exit(2);
+      }
+
+      let query: string | null = fromUserOpt.query;
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+
+      if (!query) {
+        const who = await client.getCurrentUser();
+        const handle = normalizeHandle(who.user?.username);
+        if (handle) {
+          query = `@${handle}`;
+        } else {
+          console.error(
+            `${ctx.p('err')}Could not determine current user (${who.error ?? 'Unknown error'}). Use --user <handle>.`,
+          );
+          process.exit(1);
+        }
+      }
+
+      const result = await client.search(query, count);
+
+      if (result.success && result.tweets) {
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No mentions found.' });
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch mentions: ${result.error}`);
+        process.exit(1);
+      }
+    });
+}

src/commands/users.ts

@@ -0,0 +1,199 @@
+import type { Command } from 'commander';
+import type { CliContext } from '../cli/shared.js';
+import { TwitterClient } from '../lib/twitter-client.js';
+
+export function registerUserCommands(program: Command, ctx: CliContext): void {
+  program
+    .command('following')
+    .description('Get users that you (or another user) follow')
+    .option('--user <userId>', 'User ID to get following for (defaults to current user)')
+    .option('-n, --count <number>', 'Number of users to fetch', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '20', 10);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs });
+
+      let userId = cmdOpts.user;
+      if (!userId) {
+        const currentUser = await client.getCurrentUser();
+        if (!currentUser.success || !currentUser.user?.id) {
+          console.error(`${ctx.p('err')}Failed to get current user: ${currentUser.error || 'Unknown error'}`);
+          process.exit(1);
+        }
+        userId = currentUser.user.id;
+      }
+
+      const result = await client.getFollowing(userId, count);
+
+      if (result.success && result.users) {
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(result.users, null, 2));
+        } else {
+          if (result.users.length === 0) {
+            console.log('No users found.');
+          } else {
+            for (const user of result.users) {
+              console.log(`@${user.username} (${user.name})`);
+              if (user.description) {
+                console.log(`  ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
+              }
+              if (user.followersCount !== undefined) {
+                console.log(`  ${ctx.p('info')}${user.followersCount.toLocaleString()} followers`);
+              }
+              console.log('──────────────────────────────────────────────────');
+            }
+          }
+        }
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch following: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('followers')
+    .description('Get users that follow you (or another user)')
+    .option('--user <userId>', 'User ID to get followers for (defaults to current user)')
+    .option('-n, --count <number>', 'Number of users to fetch', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '20', 10);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs });
+
+      let userId = cmdOpts.user;
+      if (!userId) {
+        const currentUser = await client.getCurrentUser();
+        if (!currentUser.success || !currentUser.user?.id) {
+          console.error(`${ctx.p('err')}Failed to get current user: ${currentUser.error || 'Unknown error'}`);
+          process.exit(1);
+        }
+        userId = currentUser.user.id;
+      }
+
+      const result = await client.getFollowers(userId, count);
+
+      if (result.success && result.users) {
+        if (cmdOpts.json) {
+          console.log(JSON.stringify(result.users, null, 2));
+        } else {
+          if (result.users.length === 0) {
+            console.log('No users found.');
+          } else {
+            for (const user of result.users) {
+              console.log(`@${user.username} (${user.name})`);
+              if (user.description) {
+                console.log(`  ${user.description.slice(0, 100)}${user.description.length > 100 ? '...' : ''}`);
+              }
+              if (user.followersCount !== undefined) {
+                console.log(`  ${ctx.p('info')}${user.followersCount.toLocaleString()} followers`);
+              }
+              console.log('──────────────────────────────────────────────────');
+            }
+          }
+        }
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch followers: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('likes')
+    .description('Get your liked tweets')
+    .option('-n, --count <number>', 'Number of likes to fetch', '20')
+    .option('--json', 'Output as JSON')
+    .action(async (cmdOpts: { count?: string; json?: boolean }) => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+      const count = Number.parseInt(cmdOpts.count || '20', 10);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.getLikes(count);
+
+      if (result.success && result.tweets) {
+        ctx.printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No liked tweets found.' });
+      } else {
+        console.error(`${ctx.p('err')}Failed to fetch likes: ${result.error}`);
+        process.exit(1);
+      }
+    });
+
+  program
+    .command('whoami')
+    .description('Show which Twitter account the current credentials belong to')
+    .action(async () => {
+      const opts = program.opts();
+      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+
+      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+
+      for (const warning of warnings) {
+        console.error(`${ctx.p('warn')}${warning}`);
+      }
+
+      if (!cookies.authToken || !cookies.ct0) {
+        console.error(`${ctx.p('err')}Missing required credentials`);
+        process.exit(1);
+      }
+
+      if (cookies.source) {
+        console.error(`${ctx.l('source')}${cookies.source}`);
+      }
+
+      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+      const result = await client.getCurrentUser();
+
+      const credentialSource = cookies.source ?? 'env/auto-detected cookies';
+
+      if (result.success && result.user) {
+        console.log(`${ctx.l('user')}@${result.user.username} (${result.user.name})`);
+        console.log(`${ctx.l('userId')}${result.user.id}`);
+        console.log(`${ctx.l('engine')}graphql`);
+        console.log(`${ctx.l('credentials')}${credentialSource}`);
+      } else {
+        console.error(`${ctx.p('err')}Failed to determine current user: ${result.error ?? 'Unknown error'}`);
+        process.exit(1);
+      }
+    });
+}

src/index.ts

@@ -1,839 +1 @@
-#!/usr/bin/env node
+export * from './lib/index.js';
-/**
- * bird - CLI tool for posting tweets and replies
- *
- * Usage:
- *   bird tweet "Hello world!"
- *   bird reply <tweet-id> "This is a reply"
- *   bird reply <tweet-url> "This is a reply"
- *   bird read <tweet-id-or-url>
- */
-
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { Command } from 'commander';
-import JSON5 from 'json5';
-import kleur from 'kleur';
-import { resolveCliInvocation } from './lib/cli-args.js';
-import { type CookieSource, resolveCredentials } from './lib/cookies.js';
-import { extractTweetId } from './lib/extract-tweet-id.js';
-import { mentionsQueryFromUserOption, normalizeHandle } from './lib/normalize-handle.js';
-import {
-  formatStatsLine,
-  formatTweetUrlLine,
-  labelPrefix,
-  type OutputConfig,
-  resolveOutputConfigFromArgv,
-  resolveOutputConfigFromCommander,
-  statusPrefix,
-} from './lib/output.js';
-import { runtimeQueryIds } from './lib/runtime-query-ids.js';
-import { type TweetData, TwitterClient } from './lib/twitter-client.js';
-import { getCliVersion } from './lib/version.js';
-
-const program: Command = new Command();
-
-const rawArgs: string[] = process.argv.slice(2);
-const normalizedArgs: string[] = rawArgs[0] === '--' ? rawArgs.slice(1) : rawArgs;
-const isTty: boolean = process.stdout.isTTY;
-let output: OutputConfig = resolveOutputConfigFromArgv(normalizedArgs, process.env, isTty);
-kleur.enabled = output.color;
-
-const wrap =
-  (styler: (text: string) => string): ((text: string) => string) =>
-  (text: string): string =>
-    isTty ? styler(text) : text;
-const collect = (value: string, previous: string[] = []): string[] => {
-  previous.push(value);
-  return previous;
-};
-
-const COOKIE_SOURCES: CookieSource[] = ['safari', 'chrome', 'firefox'];
-
-function parseCookieSource(value: string): CookieSource {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === 'safari' || normalized === 'chrome' || normalized === 'firefox') {
-    return normalized;
-  }
-  throw new Error(`Invalid --cookie-source "${value}". Allowed: safari, chrome, firefox.`);
-}
-
-function resolveCookieSourceOrder(input: unknown): CookieSource[] | undefined {
-  if (typeof input === 'string') {
-    return [parseCookieSource(input)];
-  }
-  if (Array.isArray(input)) {
-    const result: CookieSource[] = [];
-    for (const entry of input) {
-      if (typeof entry !== 'string') {
-        continue;
-      }
-      result.push(parseCookieSource(entry));
-    }
-    return result.length > 0 ? result : undefined;
-  }
-  return undefined;
-}
-
-const collectCookieSource = (value: string, previous: CookieSource[] = []): CookieSource[] => {
-  previous.push(parseCookieSource(value));
-  return previous;
-};
-
-const p = (kind: Parameters<typeof statusPrefix>[0]): string => statusPrefix(kind, output);
-const l = (kind: Parameters<typeof labelPrefix>[0]): string => labelPrefix(kind, output);
-
-function applyOutputFromCommand(command: Command): void {
-  const opts = command.optsWithGlobals() as { plain?: boolean; emoji?: boolean; color?: boolean };
-  output = resolveOutputConfigFromCommander(opts, process.env, isTty);
-  kleur.enabled = output.color;
-}
-
-const colors = {
-  banner: wrap((t) => kleur.bold().blue(t)),
-  subtitle: wrap((t) => kleur.dim(t)),
-  section: wrap((t) => kleur.bold().white(t)),
-  bullet: wrap((t) => kleur.blue(t)),
-  command: wrap((t) => kleur.bold().cyan(t)),
-  option: wrap((t) => kleur.cyan(t)),
-  argument: wrap((t) => kleur.magenta(t)),
-  description: wrap((t) => kleur.white(t)),
-  muted: wrap((t) => kleur.gray(t)),
-  accent: wrap((t) => kleur.green(t)),
-};
-
-type BirdConfig = {
-  chromeProfile?: string;
-  firefoxProfile?: string;
-  cookieSource?: CookieSource | CookieSource[];
-  timeoutMs?: number;
-};
-
-function readConfigFile(path: string): Partial<BirdConfig> {
-  if (!existsSync(path)) {
-    return {};
-  }
-  try {
-    const raw = readFileSync(path, 'utf8');
-    const parsed = JSON5.parse(raw) as Partial<BirdConfig>;
-    return parsed ?? {};
-  } catch (error) {
-    console.error(
-      colors.muted(
-        `${p('warn')}Failed to parse config at ${path}: ${error instanceof Error ? error.message : String(error)}`,
-      ),
-    );
-    return {};
-  }
-}
-
-function loadConfig(): BirdConfig {
-  const globalPath = join(homedir(), '.config', 'bird', 'config.json5');
-  const localPath = join(process.cwd(), '.birdrc.json5');
-
-  return {
-    ...readConfigFile(globalPath),
-    ...readConfigFile(localPath),
-  };
-}
-
-const config = loadConfig();
-
-const KNOWN_COMMANDS = new Set([
-  'tweet',
-  'reply',
-  'query-ids',
-  'read',
-  'replies',
-  'thread',
-  'search',
-  'mentions',
-  'bookmarks',
-  'help',
-  'whoami',
-  'check',
-]);
-
-program.addHelpText(
-  'beforeAll',
-  () => `${colors.banner('bird CLI')} ${colors.subtitle('— fast X CLI for tweeting, replying, and reading')}`,
-);
-
-program.name('bird').description('Post tweets and replies via Twitter/X GraphQL API').version(getCliVersion());
-
-const formatExample = (command: string, description: string): string =>
-  `${colors.command(`  ${command}`)}\n${colors.muted(`    ${description}`)}`;
-
-program.addHelpText(
-  'afterAll',
-  () =>
-    `\n${colors.section('Examples')}\n${[
-      formatExample('bird whoami', 'Show the logged-in account via GraphQL cookies'),
-      formatExample('bird --firefox-profile default-release whoami', 'Use Firefox profile cookies'),
-      formatExample('bird tweet "hello from bird"', 'Send a tweet'),
-      formatExample('bird replies https://x.com/user/status/1234567890123456789', 'Check replies to a tweet'),
-    ].join('\n\n')}`,
-);
-
-// Global options for authentication
-program
-  .option('--auth-token <token>', 'Twitter auth_token cookie')
-  .option('--ct0 <token>', 'Twitter ct0 cookie')
-  .option('--chrome-profile <name>', 'Chrome profile name for cookie extraction', config.chromeProfile)
-  .option('--firefox-profile <name>', 'Firefox profile name for cookie extraction', config.firefoxProfile)
-  .option(
-    '--cookie-source <source>',
-    'Cookie source for browser cookie extraction (repeatable)',
-    collectCookieSource,
-    [],
-  )
-  .option('--media <path>', 'Attach media file (repeatable, up to 4 images or 1 video)', collect, [])
-  .option('--alt <text>', 'Alt text for the corresponding --media (repeatable)', collect, [])
-  .option('--timeout <ms>', 'Request timeout in milliseconds')
-  .option('--plain', 'Plain output (stable, no emoji, no color)')
-  .option('--no-emoji', 'Disable emoji output')
-  .option('--no-color', 'Disable ANSI colors (or set NO_COLOR)');
-
-type CredentialsOptions = {
-  authToken?: string;
-  ct0?: string;
-  chromeProfile?: string;
-  firefoxProfile?: string;
-  cookieSource?: CookieSource[];
-};
-
-function resolveCredentialsFromOptions(opts: CredentialsOptions): ReturnType<typeof resolveCredentials> {
-  const cookieSource = opts.cookieSource?.length
-    ? opts.cookieSource
-    : (resolveCookieSourceOrder(config.cookieSource) ?? COOKIE_SOURCES);
-  return resolveCredentials({
-    authToken: opts.authToken,
-    ct0: opts.ct0,
-    cookieSource,
-    chromeProfile: opts.chromeProfile || config.chromeProfile,
-    firefoxProfile: opts.firefoxProfile || config.firefoxProfile,
-  });
-}
-
-program.hook('preAction', (_thisCommand, actionCommand) => {
-  applyOutputFromCommand(actionCommand);
-});
-
-type MediaSpec = { path: string; alt?: string; mime: string; buffer: Buffer };
-
-function resolveTimeoutMs(...values: Array<string | number | undefined | null>): number | undefined {
-  for (const value of values) {
-    if (value === undefined || value === null || value === '') {
-      continue;
-    }
-    const parsed = typeof value === 'number' ? value : Number(value);
-    if (Number.isFinite(parsed) && parsed > 0) {
-      return parsed;
-    }
-  }
-  return undefined;
-}
-
-function resolveTimeoutFromOptions(options: { timeout?: string | number }): number | undefined {
-  return resolveTimeoutMs(options.timeout, config.timeoutMs, process.env.BIRD_TIMEOUT_MS);
-}
-
-function detectMime(path: string): string | null {
-  const ext = path.toLowerCase();
-  if (ext.endsWith('.jpg') || ext.endsWith('.jpeg')) {
-    return 'image/jpeg';
-  }
-  if (ext.endsWith('.png')) {
-    return 'image/png';
-  }
-  if (ext.endsWith('.webp')) {
-    return 'image/webp';
-  }
-  if (ext.endsWith('.gif')) {
-    return 'image/gif';
-  }
-  if (ext.endsWith('.mp4') || ext.endsWith('.m4v')) {
-    return 'video/mp4';
-  }
-  if (ext.endsWith('.mov')) {
-    return 'video/quicktime';
-  }
-  return null;
-}
-
-function loadMedia(opts: { media: string[]; alts: string[] }): MediaSpec[] {
-  if (opts.media.length === 0) {
-    return [];
-  }
-  const specs: MediaSpec[] = [];
-  for (const [index, path] of opts.media.entries()) {
-    const mime = detectMime(path);
-    if (!mime) {
-      throw new Error(`Unsupported media type for ${path}. Supported: jpg, jpeg, png, webp, gif, mp4, mov`);
-    }
-    const buffer = readFileSync(path);
-    specs.push({ path, mime, buffer, alt: opts.alts[index] });
-  }
-
-  const videoCount = specs.filter((m) => m.mime.startsWith('video/')).length;
-  if (videoCount > 1) {
-    throw new Error('Only one video can be attached');
-  }
-  if (videoCount === 1 && specs.length > 1) {
-    throw new Error('Video cannot be combined with other media');
-  }
-  if (specs.length > 4) {
-    throw new Error('Maximum 4 media attachments');
-  }
-  return specs;
-}
-
-function printTweets(
-  tweets: TweetData[],
-  opts: { json?: boolean; emptyMessage?: string; showSeparator?: boolean } = {},
-) {
-  if (opts.json) {
-    console.log(JSON.stringify(tweets, null, 2));
-    return;
-  }
-  if (tweets.length === 0) {
-    console.log(opts.emptyMessage ?? 'No tweets found.');
-    return;
-  }
-  for (const tweet of tweets) {
-    console.log(`\n@${tweet.author.username} (${tweet.author.name}):`);
-    console.log(tweet.text);
-    if (tweet.createdAt) {
-      console.log(`${l('date')}${tweet.createdAt}`);
-    }
-    console.log(`${l('url')}https://x.com/${tweet.author.username}/status/${tweet.id}`);
-    if (opts.showSeparator ?? true) {
-      console.log('─'.repeat(50));
-    }
-  }
-}
-
-program
-  .command('help [command]')
-  .description('Show help for a command')
-  .action((commandName?: string) => {
-    if (!commandName) {
-      program.outputHelp();
-      return;
-    }
-
-    const cmd = program.commands.find((c) => c.name() === commandName);
-    if (!cmd) {
-      console.error(`${p('err')}Unknown command: ${commandName}`);
-      process.exitCode = 2;
-      return;
-    }
-
-    cmd.outputHelp();
-  });
-
-program
-  .command('query-ids')
-  .description('Show or refresh cached Twitter GraphQL query IDs')
-  .option('--json', 'Output as JSON')
-  .option('--fresh', 'Force refresh (downloads X client bundles)', false)
-  .action(async (cmdOpts: { json?: boolean; fresh?: boolean }) => {
-    const operations = [
-      'CreateTweet',
-      'CreateRetweet',
-      'FavoriteTweet',
-      'TweetDetail',
-      'SearchTimeline',
-      'UserArticlesTweets',
-      'Bookmarks',
-    ];
-
-    if (cmdOpts.fresh) {
-      console.error(`${p('info')}Refreshing GraphQL query IDs…`);
-      await runtimeQueryIds.refresh(operations, { force: true });
-    }
-
-    const info = await runtimeQueryIds.getSnapshotInfo();
-    if (!info) {
-      if (cmdOpts.json) {
-        console.log(JSON.stringify({ cached: false, cachePath: runtimeQueryIds.cachePath }, null, 2));
-        return;
-      }
-      console.log(`${p('warn')}No cached query IDs yet.`);
-      console.log(`${p('info')}Run: bird query-ids --fresh`);
-      return;
-    }
-
-    if (cmdOpts.json) {
-      console.log(
-        JSON.stringify(
-          {
-            cached: true,
-            cachePath: info.cachePath,
-            fetchedAt: info.snapshot.fetchedAt,
-            isFresh: info.isFresh,
-            ageMs: info.ageMs,
-            ids: info.snapshot.ids,
-            discovery: info.snapshot.discovery,
-          },
-          null,
-          2,
-        ),
-      );
-      return;
-    }
-
-    console.log(`${p('ok')}GraphQL query IDs cached`);
-    console.log(`path: ${info.cachePath}`);
-    console.log(`fetched_at: ${info.snapshot.fetchedAt}`);
-    console.log(`fresh: ${info.isFresh ? 'yes' : 'no'}`);
-    console.log(`ops: ${Object.keys(info.snapshot.ids).length}`);
-  });
-
-// Tweet command
-program
-  .command('tweet')
-  .description('Post a new tweet')
-  .argument('<text>', 'Tweet text')
-  .action(async (text: string) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    let media: MediaSpec[] = [];
-    try {
-      media = loadMedia({ media: opts.media ?? [], alts: opts.alt ?? [] });
-    } catch (error) {
-      console.error(`${p('err')}${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
-    }
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    if (cookies.source) {
-      console.error(`${l('source')}${cookies.source}`);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    let mediaIds: string[] | undefined;
-    if (media.length > 0) {
-      const uploaded: string[] = [];
-      for (const item of media) {
-        const res = await client.uploadMedia({ data: item.buffer, mimeType: item.mime, alt: item.alt });
-        if (!res.success || !res.mediaId) {
-          console.error(`${p('err')}Media upload failed: ${res.error ?? 'Unknown error'}`);
-          process.exit(1);
-        }
-        uploaded.push(res.mediaId);
-      }
-      mediaIds = uploaded;
-    }
-
-    const result = await client.tweet(text, mediaIds);
-
-    if (result.success) {
-      console.log(`${p('ok')}Tweet posted successfully!`);
-      console.log(formatTweetUrlLine(result.tweetId, output));
-    } else {
-      console.error(`${p('err')}Failed to post tweet: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Reply command
-program
-  .command('reply')
-  .description('Reply to an existing tweet')
-  .argument('<tweet-id-or-url>', 'Tweet ID or URL to reply to')
-  .argument('<text>', 'Reply text')
-  .action(async (tweetIdOrUrl: string, text: string) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    let media: MediaSpec[] = [];
-    try {
-      media = loadMedia({ media: opts.media ?? [], alts: opts.alt ?? [] });
-    } catch (error) {
-      console.error(`${p('err')}${error instanceof Error ? error.message : String(error)}`);
-      process.exit(1);
-    }
-    const tweetId = extractTweetId(tweetIdOrUrl);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    if (cookies.source) {
-      console.error(`${l('source')}${cookies.source}`);
-    }
-
-    console.error(`${p('info')}Replying to tweet: ${tweetId}`);
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    let mediaIds: string[] | undefined;
-    if (media.length > 0) {
-      const uploaded: string[] = [];
-      for (const item of media) {
-        const res = await client.uploadMedia({ data: item.buffer, mimeType: item.mime, alt: item.alt });
-        if (!res.success || !res.mediaId) {
-          console.error(`${p('err')}Media upload failed: ${res.error ?? 'Unknown error'}`);
-          process.exit(1);
-        }
-        uploaded.push(res.mediaId);
-      }
-      mediaIds = uploaded;
-    }
-
-    const result = await client.reply(text, tweetId, mediaIds);
-
-    if (result.success) {
-      console.log(`${p('ok')}Reply posted successfully!`);
-      console.log(formatTweetUrlLine(result.tweetId, output));
-    } else {
-      console.error(`${p('err')}Failed to post reply: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Read command - fetch tweet content
-program
-  .command('read')
-  .description('Read/fetch a tweet by ID or URL')
-  .argument('<tweet-id-or-url>', 'Tweet ID or URL to read')
-  .option('--json', 'Output as JSON')
-  .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-
-    const tweetId = extractTweetId(tweetIdOrUrl);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.getTweet(tweetId);
-
-    if (result.success && result.tweet) {
-      if (cmdOpts.json) {
-        console.log(JSON.stringify(result.tweet, null, 2));
-      } else {
-        console.log(`@${result.tweet.author.username} (${result.tweet.author.name}):`);
-        console.log(result.tweet.text);
-        if (result.tweet.createdAt) {
-          console.log(`\n${l('date')}${result.tweet.createdAt}`);
-        }
-        console.log(formatStatsLine(result.tweet, output));
-      }
-    } else {
-      console.error(`${p('err')}Failed to read tweet: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Replies command - list replies to a tweet
-program
-  .command('replies')
-  .description('List replies to a tweet (by ID or URL)')
-  .argument('<tweet-id-or-url>', 'Tweet ID or URL')
-  .option('--json', 'Output as JSON')
-  .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    const tweetId = extractTweetId(tweetIdOrUrl);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.getReplies(tweetId);
-
-    if (result.success && result.tweets) {
-      printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No replies found.' });
-    } else {
-      console.error(`${p('err')}Failed to fetch replies: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Thread command - show full conversation thread
-program
-  .command('thread')
-  .description('Show the full conversation thread containing the tweet')
-  .argument('<tweet-id-or-url>', 'Tweet ID or URL')
-  .option('--json', 'Output as JSON')
-  .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    const tweetId = extractTweetId(tweetIdOrUrl);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.getThread(tweetId);
-
-    if (result.success && result.tweets) {
-      printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No thread tweets found.' });
-    } else {
-      console.error(`${p('err')}Failed to fetch thread: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Search command - find tweets
-program
-  .command('search')
-  .description('Search for tweets')
-  .argument('<query>', 'Search query (e.g., "@clawdbot" or "from:clawdbot")')
-  .option('-n, --count <number>', 'Number of tweets to fetch', '10')
-  .option('--json', 'Output as JSON')
-  .action(async (query: string, cmdOpts: { count?: string; json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    const count = Number.parseInt(cmdOpts.count || '10', 10);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.search(query, count);
-
-    if (result.success && result.tweets) {
-      printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No tweets found.' });
-    } else {
-      console.error(`${p('err')}Search failed: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Mentions command - shortcut to search for @username mentions
-program
-  .command('mentions')
-  .description('Find tweets mentioning a user (defaults to current user)')
-  .option('-u, --user <handle>', 'User handle (e.g. @steipete)')
-  .option('-n, --count <number>', 'Number of tweets to fetch', '10')
-  .option('--json', 'Output as JSON')
-  .action(async (cmdOpts: { user?: string; count?: string; json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    const count = Number.parseInt(cmdOpts.count || '10', 10);
-
-    const fromUserOpt = mentionsQueryFromUserOption(cmdOpts.user);
-    if (fromUserOpt.error) {
-      console.error(`${p('err')}${fromUserOpt.error}`);
-      process.exit(2);
-    }
-
-    let query: string | null = fromUserOpt.query;
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-
-    if (!query) {
-      const who = await client.getCurrentUser();
-      const handle = normalizeHandle(who.user?.username);
-      if (handle) {
-        query = `@${handle}`;
-      } else {
-        console.error(
-          `${p('err')}Could not determine current user (${who.error ?? 'Unknown error'}). Use --user <handle>.`,
-        );
-        process.exit(1);
-      }
-    }
-
-    const result = await client.search(query, count);
-
-    if (result.success && result.tweets) {
-      printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No mentions found.' });
-    } else {
-      console.error(`${p('err')}Failed to fetch mentions: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Bookmarks command - get user's bookmarks
-program
-  .command('bookmarks')
-  .description('Get your bookmarked tweets')
-  .option('-n, --count <number>', 'Number of bookmarks to fetch', '20')
-  .option('--json', 'Output as JSON')
-  .action(async (cmdOpts: { count?: string; json?: boolean }) => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-    const count = Number.parseInt(cmdOpts.count || '20', 10);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.getBookmarks(count);
-
-    if (result.success && result.tweets) {
-      printTweets(result.tweets, { json: cmdOpts.json, emptyMessage: 'No bookmarks found.' });
-    } else {
-      console.error(`${p('err')}Failed to fetch bookmarks: ${result.error}`);
-      process.exit(1);
-    }
-  });
-
-// Whoami command - show the logged-in account
-program
-  .command('whoami')
-  .description('Show which Twitter account the current credentials belong to')
-  .action(async () => {
-    const opts = program.opts();
-    const timeoutMs = resolveTimeoutFromOptions(opts);
-
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    for (const warning of warnings) {
-      console.error(`${p('warn')}${warning}`);
-    }
-
-    if (!cookies.authToken || !cookies.ct0) {
-      console.error(`${p('err')}Missing required credentials`);
-      process.exit(1);
-    }
-
-    if (cookies.source) {
-      console.error(`${l('source')}${cookies.source}`);
-    }
-
-    const client = new TwitterClient({ cookies, timeoutMs });
-    const result = await client.getCurrentUser();
-
-    const credentialSource = cookies.source ?? 'env/auto-detected cookies';
-
-    if (result.success && result.user) {
-      console.log(`${l('user')}@${result.user.username} (${result.user.name})`);
-      console.log(`${l('userId')}${result.user.id}`);
-      console.log(`${l('engine')}graphql`);
-      console.log(`${l('credentials')}${credentialSource}`);
-    } else {
-      console.error(`${p('err')}Failed to determine current user: ${result.error ?? 'Unknown error'}`);
-      process.exit(1);
-    }
-  });
-
-// Check command - verify credentials
-program
-  .command('check')
-  .description('Check credential availability')
-  .action(async () => {
-    const opts = program.opts();
-    const { cookies, warnings } = await resolveCredentialsFromOptions(opts);
-
-    console.log(`${p('info')}Credential check`);
-    console.log('─'.repeat(40));
-
-    if (cookies.authToken) {
-      console.log(`${p('ok')}auth_token: ${cookies.authToken.slice(0, 10)}...`);
-    } else {
-      console.log(`${p('err')}auth_token: not found`);
-    }
-
-    if (cookies.ct0) {
-      console.log(`${p('ok')}ct0: ${cookies.ct0.slice(0, 10)}...`);
-    } else {
-      console.log(`${p('err')}ct0: not found`);
-    }
-
-    if (cookies.source) {
-      console.log(`${l('source')}${cookies.source}`);
-    }
-
-    if (warnings.length > 0) {
-      console.log(`\n${p('warn')}Warnings:`);
-      for (const warning of warnings) {
-        console.log(`   - ${warning}`);
-      }
-    }
-
-    if (cookies.authToken && cookies.ct0) {
-      console.log(`\n${p('ok')}Ready to tweet!`);
-    } else {
-      console.log(`\n${p('err')}Missing credentials. Options:`);
-      console.log('   1. Login to x.com in Safari/Chrome/Firefox');
-      console.log('   2. Set AUTH_TOKEN and CT0 environment variables');
-      console.log('   3. Use --auth-token and --ct0 flags');
-      process.exit(1);
-    }
-  });
-
-const { argv, showHelp } = resolveCliInvocation(normalizedArgs, KNOWN_COMMANDS);
-
-if (showHelp) {
-  program.outputHelp();
-  process.exit(0);
-}
-
-if (argv) {
-  program.parse(argv);
-} else {
-  program.parse(['node', 'bird', ...normalizedArgs]);
-}

src/lib/cookies.ts

@@ -22,6 +22,7 @@ export type CookieSource = 'safari' | 'chrome' | 'firefox';
 const TWITTER_COOKIE_NAMES = ['auth_token', 'ct0'] as const;
 const TWITTER_URL = 'https://x.com/';
 const TWITTER_ORIGINS: string[] = ['https://x.com/', 'https://twitter.com/'];
+const DEFAULT_COOKIE_TIMEOUT_MS = 30_000;
 
 function normalizeValue(value: unknown): string | null {
   if (typeof value !== 'string') {
@@ -102,6 +103,7 @@ async function readTwitterCookiesFromBrowser(options: {
   source: CookieSource;
   chromeProfile?: string;
   firefoxProfile?: string;
+  cookieTimeoutMs?: number;
 }): Promise<CookieExtractionResult> {
   const warnings: string[] = [];
   const out = buildEmpty();
@@ -114,6 +116,7 @@ async function readTwitterCookiesFromBrowser(options: {
     mode: 'merge',
     chromeProfile: options.chromeProfile,
     firefoxProfile: options.firefoxProfile,
+    timeoutMs: options.cookieTimeoutMs,
   });
   warnings.push(...providerWarnings);
 
@@ -170,9 +173,18 @@ export async function resolveCredentials(options: {
   cookieSource?: CookieSource | CookieSource[];
   chromeProfile?: string;
   firefoxProfile?: string;
+  cookieTimeoutMs?: number;
 }): Promise<CookieExtractionResult> {
   const warnings: string[] = [];
   const cookies = buildEmpty();
+  const cookieTimeoutMs =
+    typeof options.cookieTimeoutMs === 'number' &&
+    Number.isFinite(options.cookieTimeoutMs) &&
+    options.cookieTimeoutMs > 0
+      ? options.cookieTimeoutMs
+      : process.platform === 'darwin'
+        ? DEFAULT_COOKIE_TIMEOUT_MS
+        : undefined;
 
   if (options.authToken) {
     cookies.authToken = options.authToken;
@@ -199,6 +211,7 @@ export async function resolveCredentials(options: {
       source,
       chromeProfile: options.chromeProfile,
       firefoxProfile: options.firefoxProfile,
+      cookieTimeoutMs,
     });
     warnings.push(...res.warnings);
     if (res.cookies.authToken && res.cookies.ct0) {

src/lib/extract-bookmark-folder-id.ts

@@ -0,0 +1,20 @@
+/**
+ * Extract bookmark folder (collection) ID from an X/Twitter bookmarks URL.
+ */
+const BOOKMARK_FOLDER_URL_REGEX = /(?:twitter\.com|x\.com)\/i\/bookmarks\/(\d+)/i;
+const BOOKMARK_FOLDER_ID_REGEX = /^\d{5,}$/;
+
+export function extractBookmarkFolderId(input: string): string | null {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const urlMatch = BOOKMARK_FOLDER_URL_REGEX.exec(trimmed);
+  if (urlMatch) {
+    return urlMatch[1];
+  }
+  if (BOOKMARK_FOLDER_ID_REGEX.test(trimmed)) {
+    return trimmed;
+  }
+  return null;
+}

src/lib/index.ts

@@ -0,0 +1,21 @@
+export {
+  type CookieExtractionResult,
+  type CookieSource,
+  extractCookiesFromChrome,
+  extractCookiesFromFirefox,
+  extractCookiesFromSafari,
+  resolveCredentials,
+  type TwitterCookies,
+} from './cookies.js';
+export { runtimeQueryIds } from './runtime-query-ids.js';
+export {
+  type CurrentUserResult,
+  type FollowingResult,
+  type GetTweetResult,
+  type SearchResult,
+  type TweetData,
+  TwitterClient,
+  type TwitterClientOptions,
+  type TwitterUser,
+} from './twitter-client.js';
+export type { TweetResult, UploadMediaResult } from './twitter-client-types.js';

src/lib/query-ids.json

@@ -3,5 +3,10 @@
   "CreateRetweet": "LFho5rIi4xcKO90p9jwG7A",
   "FavoriteTweet": "lI07N6Otwv1PhnEgXILM7A",
   "TweetDetail": "97JF30KziU00483E_8elBA",
-  "SearchTimeline": "M1jEez78PEfVfbQLvlWMvQ"
+  "SearchTimeline": "M1jEez78PEfVfbQLvlWMvQ",
+  "Bookmarks": "RV1g3b8n_SGOHwkqKYSCFw",
+  "BookmarkFolderTimeline": "KJIQpsvxrTfRIlbaRIySHQ",
+  "Following": "BEkNpEt5pNETESoqMsTEGA",
+  "Followers": "kuFUYP9eV1FPoEy4N-pi7w",
+  "Likes": "JR2gceKucIKcVNB_9JkhsA"
 }

src/lib/twitter-client-base.ts

@@ -0,0 +1,142 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { runtimeQueryIds } from './runtime-query-ids.js';
+import { type OperationName, QUERY_IDS, TARGET_QUERY_ID_OPERATIONS } from './twitter-client-constants.js';
+import type { CurrentUserResult, TwitterClientOptions } from './twitter-client-types.js';
+import { normalizeQuoteDepth } from './twitter-client-utils.js';
+
+// biome-ignore lint/suspicious/noExplicitAny: TS mixin base constructor requirement.
+export type Constructor<T = object> = new (...args: any[]) => T;
+// biome-ignore lint/suspicious/noExplicitAny: TS mixin base constructor requirement.
+export type AbstractConstructor<T = object> = abstract new (...args: any[]) => T;
+export type Mixin<TBase extends AbstractConstructor<TwitterClientBase>, TAdded> = abstract new (
+  ...args: ConstructorParameters<TBase>
+) => TwitterClientBase & TAdded;
+
+export abstract class TwitterClientBase {
+  protected authToken: string;
+  protected ct0: string;
+  protected cookieHeader: string;
+  protected userAgent: string;
+  protected timeoutMs?: number;
+  protected quoteDepth: number;
+  protected clientUuid: string;
+  protected clientDeviceId: string;
+  protected clientUserId?: string;
+
+  constructor(options: TwitterClientOptions) {
+    if (!options.cookies.authToken || !options.cookies.ct0) {
+      throw new Error('Both authToken and ct0 cookies are required');
+    }
+    this.authToken = options.cookies.authToken;
+    this.ct0 = options.cookies.ct0;
+    this.cookieHeader = options.cookies.cookieHeader || `auth_token=${this.authToken}; ct0=${this.ct0}`;
+    this.userAgent =
+      options.userAgent ||
+      'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+    this.timeoutMs = options.timeoutMs;
+    this.quoteDepth = normalizeQuoteDepth(options.quoteDepth);
+    this.clientUuid = randomUUID();
+    this.clientDeviceId = randomUUID();
+  }
+
+  protected abstract getCurrentUser(): Promise<CurrentUserResult>;
+
+  protected async getQueryId(operationName: OperationName): Promise<string> {
+    const cached = await runtimeQueryIds.getQueryId(operationName);
+    return cached ?? QUERY_IDS[operationName];
+  }
+
+  protected async refreshQueryIds(): Promise<void> {
+    if (process.env.NODE_ENV === 'test') {
+      return;
+    }
+    try {
+      await runtimeQueryIds.refresh(TARGET_QUERY_ID_OPERATIONS, { force: true });
+    } catch {
+      // ignore refresh failures; callers will fall back to baked-in IDs
+    }
+  }
+
+  protected async getTweetDetailQueryIds(): Promise<string[]> {
+    const primary = await this.getQueryId('TweetDetail');
+    return Array.from(new Set([primary, '97JF30KziU00483E_8elBA', 'aFvUsJm2c-oDkJV75blV6g']));
+  }
+
+  protected async getSearchTimelineQueryIds(): Promise<string[]> {
+    const primary = await this.getQueryId('SearchTimeline');
+    return Array.from(new Set([primary, 'M1jEez78PEfVfbQLvlWMvQ', '5h0kNbk3ii97rmfY6CdgAA', 'Tp1sewRU1AsZpBWhqCZicQ']));
+  }
+
+  protected async fetchWithTimeout(url: string, init: RequestInit): Promise<Response> {
+    if (!this.timeoutMs || this.timeoutMs <= 0) {
+      return fetch(url, init);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  protected getHeaders(): Record<string, string> {
+    return this.getJsonHeaders();
+  }
+
+  protected createTransactionId(): string {
+    return randomBytes(16).toString('hex');
+  }
+
+  protected getBaseHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      accept: '*/*',
+      'accept-language': 'en-US,en;q=0.9',
+      authorization:
+        'Bearer AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA',
+      'x-csrf-token': this.ct0,
+      'x-twitter-auth-type': 'OAuth2Session',
+      'x-twitter-active-user': 'yes',
+      'x-twitter-client-language': 'en',
+      'x-client-uuid': this.clientUuid,
+      'x-twitter-client-deviceid': this.clientDeviceId,
+      'x-client-transaction-id': this.createTransactionId(),
+      cookie: this.cookieHeader,
+      'user-agent': this.userAgent,
+      origin: 'https://x.com',
+      referer: 'https://x.com/',
+    };
+
+    if (this.clientUserId) {
+      headers['x-twitter-client-user-id'] = this.clientUserId;
+    }
+
+    return headers;
+  }
+
+  protected getJsonHeaders(): Record<string, string> {
+    return {
+      ...this.getBaseHeaders(),
+      'content-type': 'application/json',
+    };
+  }
+
+  protected getUploadHeaders(): Record<string, string> {
+    // Note: do not set content-type; URLSearchParams/FormData need to set it (incl boundary) themselves.
+    return this.getBaseHeaders();
+  }
+
+  protected async ensureClientUserId(): Promise<void> {
+    if (process.env.NODE_ENV === 'test') {
+      return;
+    }
+    if (this.clientUserId) {
+      return;
+    }
+    const result = await this.getCurrentUser();
+    if (result.success && result.user?.id) {
+      this.clientUserId = result.user.id;
+    }
+  }
+}

src/lib/twitter-client-constants.ts

@@ -0,0 +1,37 @@
+// biome-ignore lint/correctness/useImportExtensions: JSON module import doesn't use .js extension.
+import queryIds from './query-ids.json' with { type: 'json' };
+
+export const TWITTER_API_BASE = 'https://x.com/i/api/graphql';
+export const TWITTER_GRAPHQL_POST_URL = 'https://x.com/i/api/graphql';
+export const TWITTER_UPLOAD_URL = 'https://upload.twitter.com/i/media/upload.json';
+export const TWITTER_MEDIA_METADATA_URL = 'https://x.com/i/api/1.1/media/metadata/create.json';
+export const TWITTER_STATUS_UPDATE_URL = 'https://x.com/i/api/1.1/statuses/update.json';
+export const SETTINGS_SCREEN_NAME_REGEX = /"screen_name":"([^"]+)"/;
+export const SETTINGS_USER_ID_REGEX = /"user_id"\s*:\s*"(\d+)"/;
+export const SETTINGS_NAME_REGEX = /"name":"([^"\\]*(?:\\.[^"\\]*)*)"/;
+
+// Query IDs rotate frequently; the values in query-ids.json are refreshed by
+// scripts/update-query-ids.ts. The fallback values keep the client usable if
+// the file is missing or incomplete.
+export const FALLBACK_QUERY_IDS = {
+  CreateTweet: 'TAJw1rBsjAtdNgTdlo2oeg',
+  CreateRetweet: 'ojPdsZsimiJrUGLR1sjUtA',
+  FavoriteTweet: 'lI07N6Otwv1PhnEgXILM7A',
+  TweetDetail: '97JF30KziU00483E_8elBA',
+  SearchTimeline: 'M1jEez78PEfVfbQLvlWMvQ',
+  UserArticlesTweets: '8zBy9h4L90aDL02RsBcCFg',
+  Bookmarks: 'RV1g3b8n_SGOHwkqKYSCFw',
+  Following: 'BEkNpEt5pNETESoqMsTEGA',
+  Followers: 'kuFUYP9eV1FPoEy4N-pi7w',
+  Likes: 'JR2gceKucIKcVNB_9JkhsA',
+  BookmarkFolderTimeline: 'KJIQpsvxrTfRIlbaRIySHQ',
+} as const;
+
+export type OperationName = keyof typeof FALLBACK_QUERY_IDS;
+
+export const QUERY_IDS: Record<OperationName, string> = {
+  ...FALLBACK_QUERY_IDS,
+  ...(queryIds as Partial<Record<OperationName, string>>),
+};
+
+export const TARGET_QUERY_ID_OPERATIONS = Object.keys(FALLBACK_QUERY_IDS) as Array<OperationName>;

src/lib/twitter-client-features.ts

@@ -0,0 +1,210 @@
+export function buildArticleFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    premium_content_api_read_enabled: false,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    responsive_web_grok_share_attachment_enabled: true,
+    articles_preview_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    standardized_nudges_misinfo: true,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_grok_imagine_annotation_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}
+
+export function buildTweetDetailFeatures(): Record<string, boolean> {
+  return {
+    ...buildArticleFeatures(),
+    responsive_web_graphql_exclude_directive_enabled: true,
+    communities_web_enable_tweet_community_results_fetch: true,
+    responsive_web_twitter_article_plain_text_enabled: true,
+    responsive_web_twitter_article_seed_tweet_detail_enabled: true,
+    responsive_web_twitter_article_seed_tweet_summary_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    verified_phone_label_enabled: false,
+  };
+}
+
+export function buildArticleFieldToggles(): Record<string, boolean> {
+  return {
+    withPayments: false,
+    withAuxiliaryUserLabels: false,
+    withArticleRichContentState: true,
+    withArticlePlainText: true,
+    withGrokAnalyze: false,
+    withDisallowedReplyControls: false,
+  };
+}
+
+export function buildSearchFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_graphql_exclude_directive_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    premium_content_api_read_enabled: false,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    responsive_web_grok_share_attachment_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    standardized_nudges_misinfo: true,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    rweb_video_timestamps_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_grok_imagine_annotation_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    articles_preview_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}
+
+export function buildTweetCreateFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    premium_content_api_read_enabled: false,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    responsive_web_grok_share_attachment_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: true,
+    tweet_awards_web_tipping_enabled: false,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    articles_preview_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    standardized_nudges_misinfo: true,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_grok_imagine_annotation_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}
+
+export function buildTimelineFeatures(): Record<string, boolean> {
+  return {
+    ...buildSearchFeatures(),
+    blue_business_profile_image_shape_enabled: true,
+    responsive_web_text_conversations_enabled: false,
+    tweetypie_unmention_optimization_enabled: true,
+    vibe_api_enabled: true,
+    responsive_web_twitter_blue_verified_badge_is_enabled: true,
+    interactive_text_enabled: true,
+    longform_notetweets_richtext_consumption_enabled: true,
+    responsive_web_media_download_video_enabled: false,
+  };
+}
+
+export function buildBookmarksFeatures(): Record<string, boolean> {
+  return {
+    ...buildTimelineFeatures(),
+    graphql_timeline_v2_bookmark_timeline: true,
+  };
+}
+
+export function buildLikesFeatures(): Record<string, boolean> {
+  return buildTimelineFeatures();
+}
+
+export function buildFollowingFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: false,
+    responsive_web_profile_redirect_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    premium_content_api_read_enabled: true,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_jetfuel_frame: false,
+    responsive_web_grok_share_attachment_enabled: false,
+    articles_preview_enabled: true,
+    responsive_web_edit_tweet_api_enabled: true,
+    graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+    view_counts_everywhere_api_enabled: true,
+    longform_notetweets_consumption_enabled: true,
+    responsive_web_twitter_article_tweet_consumption_enabled: true,
+    tweet_awards_web_tipping_enabled: true,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: false,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    freedom_of_speech_not_reach_fetch_enabled: true,
+    standardized_nudges_misinfo: true,
+    tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    responsive_web_grok_image_annotation_enabled: false,
+    responsive_web_grok_imagine_annotation_enabled: false,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}

src/lib/twitter-client-media.ts

@@ -0,0 +1,179 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_MEDIA_METADATA_URL, TWITTER_UPLOAD_URL } from './twitter-client-constants.js';
+import type { UploadMediaResult } from './twitter-client-types.js';
+
+export interface TwitterClientMediaMethods {
+  uploadMedia(input: { data: Uint8Array; mimeType: string; alt?: string }): Promise<UploadMediaResult>;
+}
+
+export function withMedia<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientMediaMethods> {
+  abstract class TwitterClientMedia extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    private mediaCategoryForMime(mimeType: string): string | null {
+      if (mimeType.startsWith('image/')) {
+        if (mimeType === 'image/gif') {
+          return 'tweet_gif';
+        }
+        return 'tweet_image';
+      }
+      if (mimeType.startsWith('video/')) {
+        return 'tweet_video';
+      }
+      return null;
+    }
+
+    private async sleep(ms: number): Promise<void> {
+      await new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    async uploadMedia(input: { data: Uint8Array; mimeType: string; alt?: string }): Promise<UploadMediaResult> {
+      const category = this.mediaCategoryForMime(input.mimeType);
+      if (!category) {
+        return { success: false, error: `Unsupported media type: ${input.mimeType}` };
+      }
+
+      try {
+        const initParams = new URLSearchParams({
+          command: 'INIT',
+          total_bytes: String(input.data.byteLength),
+          media_type: input.mimeType,
+          media_category: category,
+        });
+
+        const initResp = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+          method: 'POST',
+          headers: this.getUploadHeaders(),
+          body: initParams,
+        });
+
+        if (!initResp.ok) {
+          const text = await initResp.text();
+          return { success: false, error: `HTTP ${initResp.status}: ${text.slice(0, 200)}` };
+        }
+
+        const initBody = (await initResp.json()) as { media_id_string?: string; media_id?: string | number };
+        const mediaId =
+          typeof initBody.media_id_string === 'string'
+            ? initBody.media_id_string
+            : initBody.media_id !== undefined
+              ? String(initBody.media_id)
+              : undefined;
+        if (!mediaId) {
+          return { success: false, error: 'Media upload INIT did not return media_id' };
+        }
+
+        const chunkSize = 5 * 1024 * 1024;
+        let segmentIndex = 0;
+        for (let offset = 0; offset < input.data.byteLength; offset += chunkSize) {
+          const chunk = input.data.slice(offset, Math.min(input.data.byteLength, offset + chunkSize));
+          const form = new FormData();
+          form.set('command', 'APPEND');
+          form.set('media_id', mediaId);
+          form.set('segment_index', String(segmentIndex));
+          form.set('media', new Blob([chunk], { type: input.mimeType }), 'media');
+
+          const appendResp = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+            method: 'POST',
+            headers: this.getUploadHeaders(),
+            body: form,
+          });
+
+          if (!appendResp.ok) {
+            const text = await appendResp.text();
+            return { success: false, error: `HTTP ${appendResp.status}: ${text.slice(0, 200)}` };
+          }
+          segmentIndex += 1;
+        }
+
+        const finalizeParams = new URLSearchParams({ command: 'FINALIZE', media_id: mediaId });
+        const finalizeResp = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+          method: 'POST',
+          headers: this.getUploadHeaders(),
+          body: finalizeParams,
+        });
+
+        if (!finalizeResp.ok) {
+          const text = await finalizeResp.text();
+          return { success: false, error: `HTTP ${finalizeResp.status}: ${text.slice(0, 200)}` };
+        }
+
+        const finalizeBody = (await finalizeResp.json()) as {
+          processing_info?: {
+            state?: string;
+            check_after_secs?: number;
+            error?: { message?: string; name?: string };
+          };
+        };
+
+        const info = finalizeBody.processing_info;
+        if (info?.state && info.state !== 'succeeded') {
+          let attempts = 0;
+          while (attempts < 20) {
+            if (info.state === 'failed') {
+              const msg = info.error?.message || info.error?.name || 'Media processing failed';
+              return { success: false, error: msg };
+            }
+            const delaySecs = Number.isFinite(info.check_after_secs) ? Math.max(1, info.check_after_secs as number) : 2;
+            await this.sleep(delaySecs * 1000);
+
+            const statusUrl = `${TWITTER_UPLOAD_URL}?${new URLSearchParams({
+              command: 'STATUS',
+              media_id: mediaId,
+            }).toString()}`;
+            const statusResp = await this.fetchWithTimeout(statusUrl, {
+              method: 'GET',
+              headers: this.getUploadHeaders(),
+            });
+
+            if (!statusResp.ok) {
+              const text = await statusResp.text();
+              return { success: false, error: `HTTP ${statusResp.status}: ${text.slice(0, 200)}` };
+            }
+
+            const statusBody = (await statusResp.json()) as {
+              processing_info?: {
+                state?: string;
+                check_after_secs?: number;
+                error?: { message?: string; name?: string };
+              };
+            };
+            if (!statusBody.processing_info) {
+              break;
+            }
+            info.state = statusBody.processing_info.state;
+            info.check_after_secs = statusBody.processing_info.check_after_secs;
+            info.error = statusBody.processing_info.error;
+            if (info.state === 'succeeded') {
+              break;
+            }
+            attempts += 1;
+          }
+        }
+
+        if (input.alt && input.mimeType.startsWith('image/')) {
+          const metaResp = await this.fetchWithTimeout(TWITTER_MEDIA_METADATA_URL, {
+            method: 'POST',
+            headers: this.getJsonHeaders(),
+            body: JSON.stringify({ media_id: mediaId, alt_text: { text: input.alt } }),
+          });
+          if (!metaResp.ok) {
+            const text = await metaResp.text();
+            return { success: false, error: `HTTP ${metaResp.status}: ${text.slice(0, 200)}` };
+          }
+        }
+
+        return { success: true, mediaId };
+      } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  }
+
+  return TwitterClientMedia;
+}

src/lib/twitter-client-posting.ts

@@ -0,0 +1,287 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_API_BASE, TWITTER_GRAPHQL_POST_URL, TWITTER_STATUS_UPDATE_URL } from './twitter-client-constants.js';
+import { buildTweetCreateFeatures } from './twitter-client-features.js';
+import type { CreateTweetResponse, TweetResult } from './twitter-client-types.js';
+
+export interface TwitterClientPostingMethods {
+  tweet(text: string, mediaIds?: string[]): Promise<TweetResult>;
+  reply(text: string, replyToTweetId: string, mediaIds?: string[]): Promise<TweetResult>;
+}
+
+export function withPosting<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientPostingMethods> {
+  abstract class TwitterClientPosting extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    /**
+     * Post a new tweet
+     */
+    async tweet(text: string, mediaIds?: string[]): Promise<TweetResult> {
+      const variables = {
+        tweet_text: text,
+        dark_request: false,
+        media: {
+          media_entities: (mediaIds ?? []).map((id) => ({ media_id: id, tagged_users: [] })),
+          possibly_sensitive: false,
+        },
+        semantic_annotation_ids: [],
+      };
+
+      const features = buildTweetCreateFeatures();
+
+      return this.createTweet(variables, features);
+    }
+
+    /**
+     * Reply to an existing tweet
+     */
+    async reply(text: string, replyToTweetId: string, mediaIds?: string[]): Promise<TweetResult> {
+      const variables = {
+        tweet_text: text,
+        reply: {
+          in_reply_to_tweet_id: replyToTweetId,
+          exclude_reply_user_ids: [],
+        },
+        dark_request: false,
+        media: {
+          media_entities: (mediaIds ?? []).map((id) => ({ media_id: id, tagged_users: [] })),
+          possibly_sensitive: false,
+        },
+        semantic_annotation_ids: [],
+      };
+
+      const features = buildTweetCreateFeatures();
+
+      return this.createTweet(variables, features);
+    }
+
+    private async createTweet(
+      variables: Record<string, unknown>,
+      features: Record<string, boolean>,
+    ): Promise<TweetResult> {
+      await this.ensureClientUserId();
+      let queryId = await this.getQueryId('CreateTweet');
+      let urlWithOperation = `${TWITTER_API_BASE}/${queryId}/CreateTweet`;
+
+      const buildBody = () => JSON.stringify({ variables, features, queryId });
+      let body = buildBody();
+
+      try {
+        const headers = { ...this.getHeaders(), referer: 'https://x.com/compose/post' };
+        let response = await this.fetchWithTimeout(urlWithOperation, {
+          method: 'POST',
+          headers,
+          body,
+        });
+
+        // Twitter increasingly prefers POST to /i/api/graphql with queryId in the payload.
+        // If the operation URL 404s, retry the generic endpoint.
+        if (response.status === 404) {
+          await this.refreshQueryIds();
+          queryId = await this.getQueryId('CreateTweet');
+          urlWithOperation = `${TWITTER_API_BASE}/${queryId}/CreateTweet`;
+          body = buildBody();
+
+          response = await this.fetchWithTimeout(urlWithOperation, {
+            method: 'POST',
+            headers: { ...this.getHeaders(), referer: 'https://x.com/compose/post' },
+            body,
+          });
+
+          if (response.status === 404) {
+            const retry = await this.fetchWithTimeout(TWITTER_GRAPHQL_POST_URL, {
+              method: 'POST',
+              headers: { ...this.getHeaders(), referer: 'https://x.com/compose/post' },
+              body,
+            });
+
+            if (!retry.ok) {
+              const text = await retry.text();
+              return { success: false, error: `HTTP ${retry.status}: ${text.slice(0, 200)}` };
+            }
+
+            const data = (await retry.json()) as CreateTweetResponse;
+
+            if (data.errors && data.errors.length > 0) {
+              const fallback = await this.tryStatusUpdateFallback(data.errors, variables);
+              if (fallback) {
+                return fallback;
+              }
+              return { success: false, error: this.formatErrors(data.errors) };
+            }
+
+            const tweetId = data.data?.create_tweet?.tweet_results?.result?.rest_id;
+            if (tweetId) {
+              return { success: true, tweetId };
+            }
+
+            return { success: false, error: 'Tweet created but no ID returned' };
+          }
+        }
+
+        if (!response.ok) {
+          const text = await response.text();
+          return {
+            success: false,
+            error: `HTTP ${response.status}: ${text.slice(0, 200)}`,
+          };
+        }
+
+        const data = (await response.json()) as CreateTweetResponse;
+
+        if (data.errors && data.errors.length > 0) {
+          const fallback = await this.tryStatusUpdateFallback(data.errors, variables);
+          if (fallback) {
+            return fallback;
+          }
+          return {
+            success: false,
+            error: this.formatErrors(data.errors),
+          };
+        }
+
+        const tweetId = data.data?.create_tweet?.tweet_results?.result?.rest_id;
+        if (tweetId) {
+          return {
+            success: true,
+            tweetId,
+          };
+        }
+
+        return {
+          success: false,
+          error: 'Tweet created but no ID returned',
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    }
+
+    private formatErrors(errors: Array<{ message: string; code?: number }>): string {
+      return errors
+        .map((error) => (typeof error.code === 'number' ? `${error.message} (${error.code})` : error.message))
+        .join(', ');
+    }
+
+    private statusUpdateInputFromCreateTweetVariables(variables: Record<string, unknown>): {
+      text: string;
+      inReplyToTweetId?: string;
+      mediaIds?: string[];
+    } | null {
+      const text = typeof variables.tweet_text === 'string' ? variables.tweet_text : null;
+      if (!text) {
+        return null;
+      }
+
+      const reply = variables.reply;
+      const inReplyToTweetId =
+        reply &&
+        typeof reply === 'object' &&
+        typeof (reply as { in_reply_to_tweet_id?: unknown }).in_reply_to_tweet_id === 'string'
+          ? (reply as { in_reply_to_tweet_id: string }).in_reply_to_tweet_id
+          : undefined;
+
+      const media = variables.media;
+      const mediaEntities =
+        media && typeof media === 'object' ? (media as { media_entities?: unknown }).media_entities : undefined;
+
+      const mediaIds = Array.isArray(mediaEntities)
+        ? mediaEntities
+            .map((entity) =>
+              entity && typeof entity === 'object' && 'media_id' in (entity as Record<string, unknown>)
+                ? (entity as { media_id?: unknown }).media_id
+                : undefined,
+            )
+            .filter((value): value is string | number => typeof value === 'string' || typeof value === 'number')
+            .map((value) => String(value))
+        : undefined;
+
+      return { text, inReplyToTweetId, mediaIds: mediaIds && mediaIds.length > 0 ? mediaIds : undefined };
+    }
+
+    private async postStatusUpdate(input: {
+      text: string;
+      inReplyToTweetId?: string;
+      mediaIds?: string[];
+    }): Promise<TweetResult> {
+      const params = new URLSearchParams();
+      params.set('status', input.text);
+      if (input.inReplyToTweetId) {
+        params.set('in_reply_to_status_id', input.inReplyToTweetId);
+        params.set('auto_populate_reply_metadata', 'true');
+      }
+      if (input.mediaIds && input.mediaIds.length > 0) {
+        params.set('media_ids', input.mediaIds.join(','));
+      }
+
+      try {
+        const response = await this.fetchWithTimeout(TWITTER_STATUS_UPDATE_URL, {
+          method: 'POST',
+          headers: {
+            ...this.getBaseHeaders(),
+            'content-type': 'application/x-www-form-urlencoded',
+            referer: 'https://x.com/compose/post',
+          },
+          body: params.toString(),
+        });
+
+        if (!response.ok) {
+          const text = await response.text();
+          return { success: false, error: `HTTP ${response.status}: ${text.slice(0, 200)}` };
+        }
+
+        const data = (await response.json()) as {
+          id_str?: string;
+          id?: string | number;
+          errors?: Array<{ message: string; code?: number }>;
+        };
+
+        if (data.errors && data.errors.length > 0) {
+          return { success: false, error: this.formatErrors(data.errors) };
+        }
+
+        const tweetId =
+          typeof data.id_str === 'string' ? data.id_str : data.id !== undefined ? String(data.id) : undefined;
+
+        if (tweetId) {
+          return { success: true, tweetId };
+        }
+        return { success: false, error: 'Tweet created but no ID returned' };
+      } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+
+    private async tryStatusUpdateFallback(
+      errors: Array<{ message: string; code?: number }>,
+      variables: Record<string, unknown>,
+    ): Promise<TweetResult | null> {
+      if (!errors.some((error) => error.code === 226)) {
+        return null;
+      }
+      const input = this.statusUpdateInputFromCreateTweetVariables(variables);
+      if (!input) {
+        return null;
+      }
+
+      const fallback = await this.postStatusUpdate(input);
+      if (fallback.success) {
+        return fallback;
+      }
+
+      return {
+        success: false,
+        error: `${this.formatErrors(errors)} | fallback: ${fallback.error ?? 'Unknown error'}`,
+      };
+    }
+  }
+
+  return TwitterClientPosting;
+}

src/lib/twitter-client-search.ts

@@ -0,0 +1,173 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_API_BASE } from './twitter-client-constants.js';
+import { buildSearchFeatures } from './twitter-client-features.js';
+import type { SearchResult, TweetData } from './twitter-client-types.js';
+import { extractCursorFromInstructions, parseTweetsFromInstructions } from './twitter-client-utils.js';
+
+export interface TwitterClientSearchMethods {
+  search(query: string, count?: number): Promise<SearchResult>;
+}
+
+export function withSearch<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientSearchMethods> {
+  abstract class TwitterClientSearch extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    /**
+     * Search for tweets matching a query
+     */
+    async search(query: string, count = 20): Promise<SearchResult> {
+      const features = buildSearchFeatures();
+      const pageSize = 20;
+      const seen = new Set<string>();
+      const tweets: TweetData[] = [];
+      let cursor: string | undefined;
+
+      const fetchPage = async (pageCount: number, pageCursor?: string) => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getSearchTimelineQueryIds();
+
+        for (const queryId of queryIds) {
+          const variables = {
+            rawQuery: query,
+            count: pageCount,
+            querySource: 'typed_query',
+            product: 'Latest',
+            ...(pageCursor ? { cursor: pageCursor } : {}),
+          };
+
+          const params = new URLSearchParams({
+            variables: JSON.stringify(variables),
+          });
+
+          const url = `${TWITTER_API_BASE}/${queryId}/SearchTimeline?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'POST',
+              headers: this.getHeaders(),
+              body: JSON.stringify({ features, queryId }),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                search_by_raw_query?: {
+                  search_timeline?: {
+                    timeline?: {
+                      instructions?: Array<{
+                        entries?: Array<{
+                          content?: {
+                            itemContent?: {
+                              tweet_results?: {
+                                result?: {
+                                  rest_id?: string;
+                                  legacy?: {
+                                    full_text?: string;
+                                    created_at?: string;
+                                    reply_count?: number;
+                                    retweet_count?: number;
+                                    favorite_count?: number;
+                                    in_reply_to_status_id_str?: string;
+                                  };
+                                  core?: {
+                                    user_results?: {
+                                      result?: {
+                                        legacy?: {
+                                          screen_name?: string;
+                                          name?: string;
+                                        };
+                                      };
+                                    };
+                                  };
+                                };
+                              };
+                            };
+                          };
+                        }>;
+                      }>;
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.search_by_raw_query?.search_timeline?.timeline?.instructions;
+            const pageTweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+            const nextCursor = extractCursorFromInstructions(instructions);
+
+            return { success: true as const, tweets: pageTweets, cursor: nextCursor, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching search results', had404 };
+      };
+
+      const fetchWithRefresh = async (pageCount: number, pageCursor?: string) => {
+        const firstAttempt = await fetchPage(pageCount, pageCursor);
+        if (firstAttempt.success) {
+          return firstAttempt;
+        }
+        if (firstAttempt.had404) {
+          await this.refreshQueryIds();
+          const secondAttempt = await fetchPage(pageCount, pageCursor);
+          if (secondAttempt.success) {
+            return secondAttempt;
+          }
+          return { success: false as const, error: secondAttempt.error };
+        }
+        return { success: false as const, error: firstAttempt.error };
+      };
+
+      while (tweets.length < count) {
+        const pageCount = Math.min(pageSize, count - tweets.length);
+        const page = await fetchWithRefresh(pageCount, cursor);
+        if (!page.success) {
+          return { success: false, error: page.error };
+        }
+
+        for (const tweet of page.tweets) {
+          if (seen.has(tweet.id)) {
+            continue;
+          }
+          seen.add(tweet.id);
+          tweets.push(tweet);
+          if (tweets.length >= count) {
+            break;
+          }
+        }
+
+        if (!page.cursor || page.cursor === cursor || page.tweets.length === 0) {
+          break;
+        }
+        cursor = page.cursor;
+      }
+
+      return { success: true, tweets };
+    }
+  }
+
+  return TwitterClientSearch;
+}

src/lib/twitter-client-timelines.ts

@@ -0,0 +1,352 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_API_BASE } from './twitter-client-constants.js';
+import { buildBookmarksFeatures, buildLikesFeatures } from './twitter-client-features.js';
+import type { GraphqlTweetResult, SearchResult } from './twitter-client-types.js';
+import { parseTweetsFromInstructions } from './twitter-client-utils.js';
+
+export interface TwitterClientTimelineMethods {
+  getBookmarks(count?: number): Promise<SearchResult>;
+  getLikes(count?: number): Promise<SearchResult>;
+  getBookmarkFolderTimeline(folderId: string, count?: number): Promise<SearchResult>;
+}
+
+export function withTimelines<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientTimelineMethods> {
+  abstract class TwitterClientTimelines extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    private async getBookmarksQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('Bookmarks');
+      return Array.from(new Set([primary, 'RV1g3b8n_SGOHwkqKYSCFw', 'tmd4ifV8RHltzn8ymGg1aw']));
+    }
+
+    private async getBookmarkFolderQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('BookmarkFolderTimeline');
+      return Array.from(new Set([primary, 'KJIQpsvxrTfRIlbaRIySHQ']));
+    }
+
+    private async getLikesQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('Likes');
+      return Array.from(new Set([primary, 'JR2gceKucIKcVNB_9JkhsA']));
+    }
+
+    /**
+     * Get the authenticated user's bookmarks
+     */
+    async getBookmarks(count = 20): Promise<SearchResult> {
+      const variables = {
+        count,
+        includePromotedContent: false,
+        withDownvotePerspective: false,
+        withReactionsMetadata: false,
+        withReactionsPerspective: false,
+      };
+
+      const features = buildBookmarksFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getBookmarksQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/Bookmarks?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                bookmark_timeline_v2?: {
+                  timeline?: {
+                    instructions?: Array<{
+                      entries?: Array<{
+                        content?: {
+                          itemContent?: {
+                            tweet_results?: {
+                              result?: GraphqlTweetResult;
+                            };
+                          };
+                        };
+                      }>;
+                    }>;
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.bookmark_timeline_v2?.timeline?.instructions;
+            const tweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+
+            return { success: true as const, tweets, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching bookmarks', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, tweets: firstAttempt.tweets };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, tweets: secondAttempt.tweets };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+
+    /**
+     * Get the authenticated user's liked tweets
+     */
+    async getLikes(count = 20): Promise<SearchResult> {
+      const userResult = await this.getCurrentUser();
+      if (!userResult.success || !userResult.user) {
+        return { success: false, error: userResult.error ?? 'Could not determine current user' };
+      }
+
+      const variables = {
+        userId: userResult.user.id,
+        count,
+        includePromotedContent: false,
+        withClientEventToken: false,
+        withBirdwatchNotes: false,
+        withVoice: true,
+      };
+
+      const features = buildLikesFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getLikesQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/Likes?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                user?: {
+                  result?: {
+                    timeline?: {
+                      timeline?: {
+                        instructions?: Array<{
+                          entries?: Array<{
+                            content?: {
+                              itemContent?: {
+                                tweet_results?: {
+                                  result?: GraphqlTweetResult;
+                                };
+                              };
+                            };
+                          }>;
+                        }>;
+                      };
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.user?.result?.timeline?.timeline?.instructions;
+            const tweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+
+            return { success: true as const, tweets, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching likes', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, tweets: firstAttempt.tweets };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, tweets: secondAttempt.tweets };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+
+    /**
+     * Get the authenticated user's bookmark folder timeline
+     */
+    async getBookmarkFolderTimeline(folderId: string, count = 20): Promise<SearchResult> {
+      const variablesWithCount = {
+        bookmark_collection_id: folderId,
+        includePromotedContent: true,
+        count,
+      };
+
+      const variablesWithoutCount = {
+        bookmark_collection_id: folderId,
+        includePromotedContent: true,
+      };
+
+      const features = buildBookmarksFeatures();
+
+      const tryOnce = async (variables: Record<string, unknown>) => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getBookmarkFolderQueryIds();
+
+        const params = new URLSearchParams({
+          variables: JSON.stringify(variables),
+          features: JSON.stringify(features),
+        });
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/BookmarkFolderTimeline?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                bookmark_collection_timeline?: {
+                  timeline?: {
+                    instructions?: Array<{
+                      entries?: Array<{
+                        content?: {
+                          itemContent?: {
+                            tweet_results?: {
+                              result?: GraphqlTweetResult;
+                            };
+                          };
+                        };
+                      }>;
+                    }>;
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.bookmark_collection_timeline?.timeline?.instructions;
+            const tweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+
+            return { success: true as const, tweets, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching bookmark folder', had404 };
+      };
+
+      let firstAttempt = await tryOnce(variablesWithCount);
+      if (!firstAttempt.success && firstAttempt.error?.includes('Variable "$count"')) {
+        firstAttempt = await tryOnce(variablesWithoutCount);
+      }
+      if (firstAttempt.success) {
+        return { success: true, tweets: firstAttempt.tweets };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        let secondAttempt = await tryOnce(variablesWithCount);
+        if (!secondAttempt.success && secondAttempt.error?.includes('Variable "$count"')) {
+          secondAttempt = await tryOnce(variablesWithoutCount);
+        }
+        if (secondAttempt.success) {
+          return { success: true, tweets: secondAttempt.tweets };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+  }
+
+  return TwitterClientTimelines;
+}

src/lib/twitter-client-tweet-detail.ts

@@ -0,0 +1,337 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_API_BASE } from './twitter-client-constants.js';
+import { buildArticleFeatures, buildArticleFieldToggles, buildTweetDetailFeatures } from './twitter-client-features.js';
+import type { GetTweetResult, GraphqlTweetResult, SearchResult } from './twitter-client-types.js';
+import {
+  extractArticleText,
+  findTweetInInstructions,
+  firstText,
+  mapTweetResult,
+  parseTweetsFromInstructions,
+} from './twitter-client-utils.js';
+
+export interface TwitterClientTweetDetailMethods {
+  getTweet(tweetId: string): Promise<GetTweetResult>;
+  getReplies(tweetId: string): Promise<SearchResult>;
+  getThread(tweetId: string): Promise<SearchResult>;
+}
+
+export function withTweetDetails<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientTweetDetailMethods> {
+  abstract class TwitterClientTweetDetails extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    private async fetchUserArticlePlainText(
+      userId: string,
+      tweetId: string,
+    ): Promise<{ title?: string; plainText?: string }> {
+      const variables = {
+        userId,
+        count: 20,
+        includePromotedContent: true,
+        withVoice: true,
+        withQuickPromoteEligibilityTweetFields: true,
+        withBirdwatchNotes: true,
+        withCommunity: true,
+        withSafetyModeUserFields: true,
+        withSuperFollowsUserFields: true,
+        withDownvotePerspective: false,
+        withReactionsMetadata: false,
+        withReactionsPerspective: false,
+        withSuperFollowsTweetFields: true,
+        withSuperFollowsReplyCount: false,
+        withClientEventToken: false,
+      };
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(buildArticleFeatures()),
+        fieldToggles: JSON.stringify(buildArticleFieldToggles()),
+      });
+
+      const queryId = await this.getQueryId('UserArticlesTweets');
+      const url = `${TWITTER_API_BASE}/${queryId}/UserArticlesTweets?${params.toString()}`;
+
+      try {
+        const response = await this.fetchWithTimeout(url, { method: 'GET', headers: this.getHeaders() });
+        if (!response.ok) {
+          return {};
+        }
+
+        const data = (await response.json()) as {
+          data?: {
+            user?: {
+              result?: {
+                timeline?: {
+                  timeline?: {
+                    instructions?: Array<{
+                      entries?: Array<{
+                        content?: {
+                          itemContent?: {
+                            tweet_results?: { result?: GraphqlTweetResult };
+                          };
+                        };
+                      }>;
+                    }>;
+                  };
+                };
+              };
+            };
+          };
+        };
+
+        const instructions = data.data?.user?.result?.timeline?.timeline?.instructions ?? [];
+        for (const instruction of instructions) {
+          for (const entry of instruction.entries ?? []) {
+            const result = entry.content?.itemContent?.tweet_results?.result;
+            if (result?.rest_id !== tweetId) {
+              continue;
+            }
+            const articleResult = result.article?.article_results?.result;
+            const title = firstText(articleResult?.title, result.article?.title);
+            const plainText = firstText(articleResult?.plain_text, result.article?.plain_text);
+            return { title, plainText };
+          }
+        }
+      } catch {
+        return {};
+      }
+
+      return {};
+    }
+
+    private async fetchTweetDetail(tweetId: string): Promise<
+      | {
+          success: true;
+          data: {
+            tweetResult?: { result?: GraphqlTweetResult };
+            threaded_conversation_with_injections_v2?: {
+              instructions?: Array<{
+                entries?: Array<{
+                  content?: {
+                    itemContent?: {
+                      tweet_results?: {
+                        result?: GraphqlTweetResult;
+                      };
+                    };
+                  };
+                }>;
+              }>;
+            };
+          };
+        }
+      | { success: false; error: string }
+    > {
+      const variables = {
+        focalTweetId: tweetId,
+        with_rux_injections: false,
+        rankingMode: 'Relevance',
+        includePromotedContent: true,
+        withCommunity: true,
+        withQuickPromoteEligibilityTweetFields: true,
+        withBirdwatchNotes: true,
+        withVoice: true,
+      };
+
+      const features = {
+        ...buildTweetDetailFeatures(),
+        articles_preview_enabled: true,
+        articles_rest_api_enabled: true,
+        responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+        creator_subscriptions_tweet_preview_api_enabled: true,
+        graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+        view_counts_everywhere_api_enabled: true,
+        longform_notetweets_consumption_enabled: true,
+        responsive_web_twitter_article_tweet_consumption_enabled: true,
+        freedom_of_speech_not_reach_fetch_enabled: true,
+        standardized_nudges_misinfo: true,
+        tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+        rweb_video_timestamps_enabled: true,
+      };
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      try {
+        const parseResponse = async (response: Response) => {
+          if (!response.ok) {
+            const text = await response.text();
+            return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}` };
+          }
+
+          const data = (await response.json()) as {
+            data?: {
+              tweetResult?: { result?: GraphqlTweetResult };
+              threaded_conversation_with_injections_v2?: {
+                instructions?: Array<{
+                  entries?: Array<{
+                    content?: {
+                      itemContent?: {
+                        tweet_results?: {
+                          result?: GraphqlTweetResult;
+                        };
+                      };
+                    };
+                  }>;
+                }>;
+              };
+            };
+            errors?: Array<{ message: string; code?: number }>;
+          };
+
+          if (data.errors && data.errors.length > 0) {
+            return { success: false as const, error: data.errors.map((e) => e.message).join(', ') };
+          }
+
+          return { success: true as const, data: data.data ?? {} };
+        };
+
+        let lastError: string | undefined;
+        let had404 = false;
+
+        const tryOnce = async () => {
+          const queryIds = await this.getTweetDetailQueryIds();
+
+          for (const queryId of queryIds) {
+            const url = `${TWITTER_API_BASE}/${queryId}/TweetDetail?${params.toString()}`;
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status !== 404) {
+              return await parseResponse(response);
+            }
+
+            had404 = true;
+
+            const postResponse = await this.fetchWithTimeout(`${TWITTER_API_BASE}/${queryId}/TweetDetail`, {
+              method: 'POST',
+              headers: this.getHeaders(),
+              body: JSON.stringify({ variables, features, queryId }),
+            });
+
+            if (postResponse.status !== 404) {
+              return await parseResponse(postResponse);
+            }
+
+            lastError = 'HTTP 404';
+          }
+
+          return { success: false as const, error: lastError ?? 'Unknown error fetching tweet detail' };
+        };
+
+        const firstAttempt = await tryOnce();
+        if (firstAttempt.success) {
+          return firstAttempt;
+        }
+
+        if (had404) {
+          await this.refreshQueryIds();
+          return await tryOnce();
+        }
+
+        return firstAttempt;
+      } catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+
+    /**
+     * Get tweet details by ID
+     */
+    async getTweet(tweetId: string): Promise<GetTweetResult> {
+      const response = await this.fetchTweetDetail(tweetId);
+      if (!response.success) {
+        return response;
+      }
+
+      const tweetResult =
+        (response.data.tweetResult as { result?: GraphqlTweetResult } | undefined)?.result ??
+        findTweetInInstructions(
+          response.data.threaded_conversation_with_injections_v2?.instructions as
+            | Array<{
+                entries?: Array<{
+                  content?: {
+                    itemContent?: {
+                      tweet_results?: {
+                        result?: GraphqlTweetResult;
+                      };
+                    };
+                  };
+                }>;
+              }>
+            | undefined,
+          tweetId,
+        );
+
+      const mapped = mapTweetResult(tweetResult, this.quoteDepth);
+      if (mapped) {
+        if (tweetResult?.article) {
+          const title = firstText(tweetResult.article.article_results?.result?.title, tweetResult.article.title);
+          const articleText = extractArticleText(tweetResult);
+          if (title && (!articleText || articleText.trim() === title.trim())) {
+            const userId = tweetResult.core?.user_results?.result?.rest_id;
+            if (userId) {
+              const fallback = await this.fetchUserArticlePlainText(userId, tweetId);
+              if (fallback.plainText) {
+                mapped.text = fallback.title ? `${fallback.title}\n\n${fallback.plainText}` : fallback.plainText;
+              }
+            }
+          }
+        }
+        return { success: true, tweet: mapped };
+      }
+      return { success: false, error: 'Tweet not found in response' };
+    }
+
+    /**
+     * Get replies to a tweet by ID
+     */
+    async getReplies(tweetId: string): Promise<SearchResult> {
+      const response = await this.fetchTweetDetail(tweetId);
+      if (!response.success) {
+        return response;
+      }
+
+      const instructions = response.data.threaded_conversation_with_injections_v2?.instructions;
+      const tweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+      const replies = tweets.filter((tweet) => tweet.inReplyToStatusId === tweetId);
+
+      return { success: true, tweets: replies };
+    }
+
+    /**
+     * Get full conversation thread for a tweet ID
+     */
+    async getThread(tweetId: string): Promise<SearchResult> {
+      const response = await this.fetchTweetDetail(tweetId);
+      if (!response.success) {
+        return response;
+      }
+
+      const instructions = response.data.threaded_conversation_with_injections_v2?.instructions;
+      const tweets = parseTweetsFromInstructions(instructions, this.quoteDepth);
+
+      const target = tweets.find((t) => t.id === tweetId);
+      const rootId = target?.conversationId || tweetId;
+      const thread = tweets.filter((tweet) => tweet.conversationId === rootId);
+
+      thread.sort((a, b) => {
+        const aTime = a.createdAt ? Date.parse(a.createdAt) : 0;
+        const bTime = b.createdAt ? Date.parse(b.createdAt) : 0;
+        return aTime - bTime;
+      });
+
+      return { success: true, tweets: thread };
+    }
+  }
+
+  return TwitterClientTweetDetails;
+}

src/lib/twitter-client-types.ts

@@ -0,0 +1,251 @@
+import type { TwitterCookies } from './cookies.js';
+
+export type GraphqlTweetResult = {
+  __typename?: string;
+  rest_id?: string;
+  legacy?: {
+    full_text?: string;
+    created_at?: string;
+    reply_count?: number;
+    retweet_count?: number;
+    favorite_count?: number;
+    conversation_id_str?: string;
+    in_reply_to_status_id_str?: string | null;
+  };
+  core?: {
+    user_results?: {
+      result?: {
+        rest_id?: string;
+        id?: string;
+        legacy?: {
+          screen_name?: string;
+          name?: string;
+        };
+        core?: {
+          screen_name?: string;
+          name?: string;
+        };
+      };
+    };
+  };
+  note_tweet?: {
+    note_tweet_results?: {
+      result?: {
+        text?: string;
+        richtext?: {
+          text?: string;
+        };
+        rich_text?: {
+          text?: string;
+        };
+        content?: {
+          text?: string;
+          richtext?: {
+            text?: string;
+          };
+          rich_text?: {
+            text?: string;
+          };
+        };
+      };
+    };
+  };
+  article?: {
+    article_results?: {
+      result?: {
+        title?: string;
+        plain_text?: string;
+        text?: string;
+        richtext?: {
+          text?: string;
+        };
+        rich_text?: {
+          text?: string;
+        };
+        body?: {
+          text?: string;
+          richtext?: {
+            text?: string;
+          };
+          rich_text?: {
+            text?: string;
+          };
+        };
+        content?: {
+          text?: string;
+          richtext?: {
+            text?: string;
+          };
+          rich_text?: {
+            text?: string;
+          };
+          items?: Array<{
+            text?: string;
+            content?: {
+              text?: string;
+              richtext?: { text?: string };
+              rich_text?: { text?: string };
+            };
+          }>;
+        };
+        sections?: Array<{
+          items?: Array<{
+            text?: string;
+            content?: {
+              text?: string;
+              richtext?: { text?: string };
+              rich_text?: { text?: string };
+            };
+          }>;
+        }>;
+      };
+    };
+    title?: string;
+    plain_text?: string;
+    text?: string;
+    richtext?: {
+      text?: string;
+    };
+    rich_text?: {
+      text?: string;
+    };
+    body?: {
+      text?: string;
+      richtext?: {
+        text?: string;
+      };
+      rich_text?: {
+        text?: string;
+      };
+    };
+    content?: {
+      text?: string;
+      richtext?: {
+        text?: string;
+      };
+      rich_text?: {
+        text?: string;
+      };
+      items?: Array<{
+        text?: string;
+        content?: {
+          text?: string;
+          richtext?: { text?: string };
+          rich_text?: { text?: string };
+        };
+      }>;
+    };
+    sections?: Array<{
+      items?: Array<{
+        text?: string;
+        content?: {
+          text?: string;
+          richtext?: { text?: string };
+          rich_text?: { text?: string };
+        };
+      }>;
+    }>;
+  };
+  tweet?: GraphqlTweetResult;
+  quoted_status_result?: {
+    result?: GraphqlTweetResult;
+  };
+};
+
+export type TweetResult =
+  | {
+      success: true;
+      tweetId: string;
+    }
+  | {
+      success: false;
+      error: string;
+    };
+
+export interface UploadMediaResult {
+  success: boolean;
+  mediaId?: string;
+  error?: string;
+}
+
+export interface TweetData {
+  id: string;
+  text: string;
+  author: {
+    username: string;
+    name: string;
+  };
+  authorId?: string;
+  createdAt?: string;
+  replyCount?: number;
+  retweetCount?: number;
+  likeCount?: number;
+  conversationId?: string;
+  inReplyToStatusId?: string;
+  // Optional quoted tweet; depth controlled by quoteDepth (default: 1).
+  quotedTweet?: TweetData;
+}
+
+export interface GetTweetResult {
+  success: boolean;
+  tweet?: TweetData;
+  error?: string;
+}
+
+export interface SearchResult {
+  success: boolean;
+  tweets?: TweetData[];
+  error?: string;
+}
+
+export interface CurrentUserResult {
+  success: boolean;
+  user?: {
+    id: string;
+    username: string;
+    name: string;
+  };
+  error?: string;
+}
+
+export interface TwitterUser {
+  id: string;
+  username: string;
+  name: string;
+  description?: string;
+  followersCount?: number;
+  followingCount?: number;
+  isBlueVerified?: boolean;
+  profileImageUrl?: string;
+  createdAt?: string;
+}
+
+export interface FollowingResult {
+  success: boolean;
+  users?: TwitterUser[];
+  error?: string;
+}
+
+export interface TwitterClientOptions {
+  cookies: TwitterCookies;
+  userAgent?: string;
+  timeoutMs?: number;
+  // Max depth for quoted tweets (0 disables). Defaults to 1.
+  quoteDepth?: number;
+}
+
+export interface CreateTweetResponse {
+  data?: {
+    create_tweet?: {
+      tweet_results?: {
+        result?: {
+          rest_id?: string;
+          legacy?: {
+            full_text?: string;
+          };
+        };
+      };
+    };
+  };
+  errors?: Array<{ message: string; code?: number }>;
+}

src/lib/twitter-client-users.ts

@@ -0,0 +1,345 @@
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import {
+  SETTINGS_NAME_REGEX,
+  SETTINGS_SCREEN_NAME_REGEX,
+  SETTINGS_USER_ID_REGEX,
+  TWITTER_API_BASE,
+} from './twitter-client-constants.js';
+import { buildFollowingFeatures } from './twitter-client-features.js';
+import type { CurrentUserResult, FollowingResult } from './twitter-client-types.js';
+import { parseUsersFromInstructions } from './twitter-client-utils.js';
+
+export interface TwitterClientUserMethods {
+  getCurrentUser(): Promise<CurrentUserResult>;
+  getFollowing(userId: string, count?: number): Promise<FollowingResult>;
+  getFollowers(userId: string, count?: number): Promise<FollowingResult>;
+}
+
+export function withUsers<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientUserMethods> {
+  abstract class TwitterClientUsers extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    private async getFollowingQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('Following');
+      return Array.from(new Set([primary, 'BEkNpEt5pNETESoqMsTEGA']));
+    }
+
+    private async getFollowersQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('Followers');
+      return Array.from(new Set([primary, 'kuFUYP9eV1FPoEy4N-pi7w']));
+    }
+
+    /**
+     * Fetch the account associated with the current cookies
+     */
+    async getCurrentUser(): Promise<CurrentUserResult> {
+      const candidateUrls = [
+        'https://x.com/i/api/account/settings.json',
+        'https://api.twitter.com/1.1/account/settings.json',
+        'https://x.com/i/api/account/verify_credentials.json?skip_status=true&include_entities=false',
+        'https://api.twitter.com/1.1/account/verify_credentials.json?skip_status=true&include_entities=false',
+      ];
+
+      let lastError: string | undefined;
+
+      for (const url of candidateUrls) {
+        try {
+          const response = await this.fetchWithTimeout(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+          });
+
+          if (!response.ok) {
+            const text = await response.text();
+            lastError = `HTTP ${response.status}: ${text.slice(0, 200)}`;
+            continue;
+          }
+
+          // biome-ignore lint/suspicious/noExplicitAny: Twitter API response is dynamic here
+          let data: any;
+          try {
+            data = await response.json();
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            continue;
+          }
+
+          const username =
+            typeof data?.screen_name === 'string'
+              ? data.screen_name
+              : typeof data?.user?.screen_name === 'string'
+                ? data.user.screen_name
+                : null;
+
+          const name =
+            typeof data?.name === 'string'
+              ? data.name
+              : typeof data?.user?.name === 'string'
+                ? data.user.name
+                : (username ?? '');
+
+          const userId =
+            typeof data?.user_id === 'string'
+              ? data.user_id
+              : typeof data?.user_id_str === 'string'
+                ? data.user_id_str
+                : typeof data?.user?.id_str === 'string'
+                  ? data.user.id_str
+                  : typeof data?.user?.id === 'string'
+                    ? data.user.id
+                    : null;
+
+          if (username && userId) {
+            this.clientUserId = userId;
+            return {
+              success: true,
+              user: {
+                id: userId,
+                username,
+                name: name || username,
+              },
+            };
+          }
+
+          lastError = 'Could not determine current user from response';
+        } catch (error) {
+          lastError = error instanceof Error ? error.message : String(error);
+        }
+      }
+
+      // Fallback: scrape the authenticated settings page (HTML) for screen_name/user_id
+      const profilePages = ['https://x.com/settings/account', 'https://twitter.com/settings/account'];
+      for (const page of profilePages) {
+        try {
+          const response = await this.fetchWithTimeout(page, {
+            headers: {
+              cookie: this.cookieHeader,
+              'user-agent': this.userAgent,
+            },
+          });
+
+          if (!response.ok) {
+            lastError = `HTTP ${response.status} (settings page)`;
+            continue;
+          }
+
+          const html = await response.text();
+          const usernameMatch = SETTINGS_SCREEN_NAME_REGEX.exec(html);
+          const idMatch = SETTINGS_USER_ID_REGEX.exec(html);
+          const nameMatch = SETTINGS_NAME_REGEX.exec(html);
+
+          const username = usernameMatch?.[1];
+          const userId = idMatch?.[1];
+          const name = nameMatch?.[1]?.replace(/\\"/g, '"');
+
+          if (username && userId) {
+            return {
+              success: true,
+              user: {
+                id: userId,
+                username,
+                name: name || username,
+              },
+            };
+          }
+
+          lastError = 'Could not parse settings page for user info';
+        } catch (error) {
+          lastError = error instanceof Error ? error.message : String(error);
+        }
+      }
+
+      return {
+        success: false,
+        error: lastError ?? 'Unknown error fetching current user',
+      };
+    }
+
+    /**
+     * Get users that a user is following
+     */
+    async getFollowing(userId: string, count = 20): Promise<FollowingResult> {
+      const variables = {
+        userId,
+        count,
+        includePromotedContent: false,
+      };
+
+      const features = buildFollowingFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getFollowingQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/Following?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                user?: {
+                  result?: {
+                    timeline?: {
+                      timeline?: {
+                        instructions?: Array<{ type?: string; entries?: Array<unknown> }>;
+                      };
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.user?.result?.timeline?.timeline?.instructions;
+            const users = parseUsersFromInstructions(instructions);
+
+            return { success: true as const, users, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching following', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, users: firstAttempt.users };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, users: secondAttempt.users };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+
+    /**
+     * Get users that follow a user
+     */
+    async getFollowers(userId: string, count = 20): Promise<FollowingResult> {
+      const variables = {
+        userId,
+        count,
+        includePromotedContent: false,
+      };
+
+      const features = buildFollowingFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getFollowersQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/Followers?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                user?: {
+                  result?: {
+                    timeline?: {
+                      timeline?: {
+                        instructions?: Array<{ type?: string; entries?: Array<unknown> }>;
+                      };
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.user?.result?.timeline?.timeline?.instructions;
+            const users = parseUsersFromInstructions(instructions);
+
+            return { success: true as const, users, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching followers', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, users: firstAttempt.users };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, users: secondAttempt.users };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+  }
+
+  return TwitterClientUsers;
+}

src/lib/twitter-client-utils.ts

@@ -0,0 +1,455 @@
+import type { GraphqlTweetResult, TweetData, TwitterUser } from './twitter-client-types.js';
+
+export function normalizeQuoteDepth(value?: number): number {
+  if (value === undefined || value === null) {
+    return 1;
+  }
+  if (!Number.isFinite(value)) {
+    return 1;
+  }
+  return Math.max(0, Math.floor(value));
+}
+
+export function firstText(...values: Array<string | undefined | null>): string | undefined {
+  for (const value of values) {
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      if (trimmed) {
+        return trimmed;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function collectTextFields(value: unknown, keys: Set<string>, output: string[]): void {
+  if (!value) {
+    return;
+  }
+  if (typeof value === 'string') {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectTextFields(item, keys, output);
+    }
+    return;
+  }
+
+  if (typeof value === 'object') {
+    for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+      if (keys.has(key)) {
+        if (typeof nested === 'string') {
+          const trimmed = nested.trim();
+          if (trimmed) {
+            output.push(trimmed);
+          }
+          continue;
+        }
+      }
+      collectTextFields(nested, keys, output);
+    }
+  }
+}
+
+export function uniqueOrdered(values: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
+export function extractArticleText(result: GraphqlTweetResult | undefined): string | undefined {
+  const article = result?.article;
+  if (!article) {
+    return undefined;
+  }
+
+  const articleResult = article.article_results?.result ?? article;
+  if (process.env.BIRD_DEBUG_ARTICLE === '1') {
+    console.error(
+      '[bird][debug][article] payload:',
+      JSON.stringify(
+        {
+          rest_id: result?.rest_id,
+          article: articleResult,
+          note_tweet: result?.note_tweet?.note_tweet_results?.result ?? null,
+        },
+        null,
+        2,
+      ),
+    );
+  }
+  const title = firstText(articleResult.title, article.title);
+  let body = firstText(
+    articleResult.plain_text,
+    article.plain_text,
+    articleResult.body?.text,
+    articleResult.body?.richtext?.text,
+    articleResult.body?.rich_text?.text,
+    articleResult.content?.text,
+    articleResult.content?.richtext?.text,
+    articleResult.content?.rich_text?.text,
+    articleResult.text,
+    articleResult.richtext?.text,
+    articleResult.rich_text?.text,
+    article.body?.text,
+    article.body?.richtext?.text,
+    article.body?.rich_text?.text,
+    article.content?.text,
+    article.content?.richtext?.text,
+    article.content?.rich_text?.text,
+    article.text,
+    article.richtext?.text,
+    article.rich_text?.text,
+  );
+
+  if (body && title && body.trim() === title.trim()) {
+    body = undefined;
+  }
+
+  if (!body) {
+    const collected: string[] = [];
+    collectTextFields(articleResult, new Set(['text', 'title']), collected);
+    collectTextFields(article, new Set(['text', 'title']), collected);
+    const unique = uniqueOrdered(collected);
+    const filtered = title ? unique.filter((value) => value !== title) : unique;
+    if (filtered.length > 0) {
+      body = filtered.join('\n\n');
+    }
+  }
+
+  if (title && body && !body.startsWith(title)) {
+    return `${title}\n\n${body}`;
+  }
+
+  return body ?? title;
+}
+
+export function extractNoteTweetText(result: GraphqlTweetResult | undefined): string | undefined {
+  const note = result?.note_tweet?.note_tweet_results?.result;
+  if (!note) {
+    return undefined;
+  }
+
+  return firstText(
+    note.text,
+    note.richtext?.text,
+    note.rich_text?.text,
+    note.content?.text,
+    note.content?.richtext?.text,
+    note.content?.rich_text?.text,
+  );
+}
+
+export function extractTweetText(result: GraphqlTweetResult | undefined): string | undefined {
+  return extractArticleText(result) ?? extractNoteTweetText(result) ?? firstText(result?.legacy?.full_text);
+}
+
+export function unwrapTweetResult(result: GraphqlTweetResult | undefined): GraphqlTweetResult | undefined {
+  if (!result) {
+    return undefined;
+  }
+  if (result.tweet) {
+    return result.tweet;
+  }
+  return result;
+}
+
+export function mapTweetResult(result: GraphqlTweetResult | undefined, quoteDepth: number): TweetData | undefined {
+  const userResult = result?.core?.user_results?.result;
+  const userLegacy = userResult?.legacy;
+  const userCore = userResult?.core;
+  const username = userLegacy?.screen_name ?? userCore?.screen_name;
+  const name = userLegacy?.name ?? userCore?.name ?? username;
+  const userId = userResult?.rest_id;
+  if (!result?.rest_id || !username) {
+    return undefined;
+  }
+
+  const text = extractTweetText(result);
+  if (!text) {
+    return undefined;
+  }
+
+  let quotedTweet: TweetData | undefined;
+  if (quoteDepth > 0) {
+    const quotedResult = unwrapTweetResult(result.quoted_status_result?.result);
+    if (quotedResult) {
+      quotedTweet = mapTweetResult(quotedResult, quoteDepth - 1);
+    }
+  }
+
+  return {
+    id: result.rest_id,
+    text,
+    createdAt: result.legacy?.created_at,
+    replyCount: result.legacy?.reply_count,
+    retweetCount: result.legacy?.retweet_count,
+    likeCount: result.legacy?.favorite_count,
+    conversationId: result.legacy?.conversation_id_str,
+    inReplyToStatusId: result.legacy?.in_reply_to_status_id_str ?? undefined,
+    author: {
+      username,
+      name: name || username,
+    },
+    authorId: userId,
+    quotedTweet,
+  };
+}
+
+export function findTweetInInstructions(
+  instructions:
+    | Array<{
+        entries?: Array<{
+          content?: {
+            itemContent?: {
+              tweet_results?: {
+                result?: GraphqlTweetResult;
+              };
+            };
+          };
+        }>;
+      }>
+    | undefined,
+  tweetId: string,
+) {
+  if (!instructions) {
+    return undefined;
+  }
+
+  for (const instruction of instructions) {
+    for (const entry of instruction.entries || []) {
+      const result = entry.content?.itemContent?.tweet_results?.result;
+      if (result?.rest_id === tweetId) {
+        return result;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+export function collectTweetResultsFromEntry(entry: {
+  content?: {
+    itemContent?: {
+      tweet_results?: {
+        result?: GraphqlTweetResult;
+      };
+    };
+    item?: {
+      itemContent?: {
+        tweet_results?: {
+          result?: GraphqlTweetResult;
+        };
+      };
+    };
+    items?: Array<{
+      item?: {
+        itemContent?: {
+          tweet_results?: {
+            result?: GraphqlTweetResult;
+          };
+        };
+      };
+      itemContent?: {
+        tweet_results?: {
+          result?: GraphqlTweetResult;
+        };
+      };
+      content?: {
+        itemContent?: {
+          tweet_results?: {
+            result?: GraphqlTweetResult;
+          };
+        };
+      };
+    }>;
+  };
+}): GraphqlTweetResult[] {
+  const results: GraphqlTweetResult[] = [];
+  const pushResult = (result?: GraphqlTweetResult) => {
+    if (result?.rest_id) {
+      results.push(result);
+    }
+  };
+
+  const content = entry.content;
+  pushResult(content?.itemContent?.tweet_results?.result);
+  pushResult(content?.item?.itemContent?.tweet_results?.result);
+
+  for (const item of content?.items ?? []) {
+    pushResult(item?.item?.itemContent?.tweet_results?.result);
+    pushResult(item?.itemContent?.tweet_results?.result);
+    pushResult(item?.content?.itemContent?.tweet_results?.result);
+  }
+
+  return results;
+}
+
+export function parseTweetsFromInstructions(
+  instructions:
+    | Array<{
+        entries?: Array<{
+          content?: {
+            itemContent?: {
+              tweet_results?: {
+                result?: GraphqlTweetResult;
+              };
+            };
+            item?: {
+              itemContent?: {
+                tweet_results?: {
+                  result?: GraphqlTweetResult;
+                };
+              };
+            };
+            items?: Array<{
+              item?: {
+                itemContent?: {
+                  tweet_results?: {
+                    result?: GraphqlTweetResult;
+                  };
+                };
+              };
+              itemContent?: {
+                tweet_results?: {
+                  result?: GraphqlTweetResult;
+                };
+              };
+              content?: {
+                itemContent?: {
+                  tweet_results?: {
+                    result?: GraphqlTweetResult;
+                  };
+                };
+              };
+            }>;
+          };
+        }>;
+      }>
+    | undefined,
+  quoteDepth: number,
+): TweetData[] {
+  const tweets: TweetData[] = [];
+  const seen = new Set<string>();
+
+  for (const instruction of instructions ?? []) {
+    for (const entry of instruction.entries ?? []) {
+      const results = collectTweetResultsFromEntry(entry);
+      for (const result of results) {
+        const mapped = mapTweetResult(result, quoteDepth);
+        if (!mapped || seen.has(mapped.id)) {
+          continue;
+        }
+        seen.add(mapped.id);
+        tweets.push(mapped);
+      }
+    }
+  }
+
+  return tweets;
+}
+
+export function extractCursorFromInstructions(
+  instructions:
+    | Array<{
+        entries?: Array<{
+          content?: unknown;
+        }>;
+      }>
+    | undefined,
+  cursorType = 'Bottom',
+): string | undefined {
+  for (const instruction of instructions ?? []) {
+    for (const entry of instruction.entries ?? []) {
+      const content = entry.content as { cursorType?: unknown; value?: unknown } | undefined;
+      if (content?.cursorType === cursorType && typeof content.value === 'string' && content.value.length > 0) {
+        return content.value;
+      }
+    }
+  }
+  return undefined;
+}
+
+export function parseUsersFromInstructions(
+  instructions: Array<{ type?: string; entries?: Array<unknown> }> | undefined,
+): TwitterUser[] {
+  if (!instructions) {
+    return [];
+  }
+
+  const users: TwitterUser[] = [];
+
+  for (const instruction of instructions) {
+    if (!instruction.entries) {
+      continue;
+    }
+
+    for (const entry of instruction.entries) {
+      const content = (entry as { content?: { itemContent?: { user_results?: { result?: unknown } } } })?.content;
+      const rawUserResult = content?.itemContent?.user_results?.result as
+        | {
+            __typename?: string;
+            rest_id?: string;
+            is_blue_verified?: boolean;
+            user?: unknown;
+            legacy?: {
+              screen_name?: string;
+              name?: string;
+              description?: string;
+              followers_count?: number;
+              friends_count?: number;
+              profile_image_url_https?: string;
+              created_at?: string;
+            };
+            core?: {
+              screen_name?: string;
+              name?: string;
+              created_at?: string;
+            };
+            avatar?: {
+              image_url?: string;
+            };
+          }
+        | undefined;
+
+      const userResult =
+        rawUserResult?.__typename === 'UserWithVisibilityResults' && rawUserResult.user
+          ? (rawUserResult.user as typeof rawUserResult)
+          : rawUserResult;
+
+      if (!userResult || userResult.__typename !== 'User') {
+        continue;
+      }
+
+      const legacy = userResult.legacy;
+      const core = userResult.core;
+      const username = legacy?.screen_name ?? core?.screen_name;
+      if (!userResult.rest_id || !username) {
+        continue;
+      }
+
+      users.push({
+        id: userResult.rest_id,
+        username,
+        name: legacy?.name ?? core?.name ?? username,
+        description: legacy?.description,
+        followersCount: legacy?.followers_count,
+        followingCount: legacy?.friends_count,
+        isBlueVerified: userResult.is_blue_verified,
+        profileImageUrl: legacy?.profile_image_url_https ?? userResult.avatar?.image_url,
+        createdAt: legacy?.created_at ?? core?.created_at,
+      });
+    }
+  }
+
+  return users;
+}

tests/cli-args.test.ts

@@ -11,6 +11,10 @@ describe('cli-args', () => {
     'thread',
     'search',
     'mentions',
+    'bookmarks',
+    'following',
+    'followers',
+    'likes',
     'help',
     'whoami',
     'check',

tests/cli.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { extractBookmarkFolderId } from '../src/lib/extract-bookmark-folder-id.js';
 import { extractTweetId } from '../src/lib/extract-tweet-id.js';
 
 describe('CLI utilities', () => {
@@ -29,4 +30,30 @@ describe('CLI utilities', () => {
       expect(extractTweetId(url)).toBe('1234567890123456789');
     });
   });
+
+  describe('extractBookmarkFolderId', () => {
+    it('should extract ID from x.com bookmarks URL', () => {
+      const url = 'https://x.com/i/bookmarks/1976792203235119344';
+      expect(extractBookmarkFolderId(url)).toBe('1976792203235119344');
+    });
+
+    it('should extract ID from twitter.com bookmarks URL', () => {
+      const url = 'https://twitter.com/i/bookmarks/1976792203235119344';
+      expect(extractBookmarkFolderId(url)).toBe('1976792203235119344');
+    });
+
+    it('should accept a numeric ID as-is', () => {
+      const id = '1976792203235119344';
+      expect(extractBookmarkFolderId(id)).toBe('1976792203235119344');
+    });
+
+    it('should return null for invalid values', () => {
+      expect(extractBookmarkFolderId('not-an-id')).toBeNull();
+    });
+
+    it('should return null for folder_id query URLs', () => {
+      const url = 'https://x.com/i/bookmarks?folder_id=1976792203235119344';
+      expect(extractBookmarkFolderId(url)).toBeNull();
+    });
+  });
 });

tests/cookies.test.ts

@@ -4,11 +4,13 @@ type SweetCookieResult = { cookies: Array<{ name: string; value: string; domain?
 
 const sweet = vi.hoisted(() => ({
   results: new Map<string, SweetCookieResult>(),
+  options: new Map<string, { timeoutMs?: number }>(),
 }));
 
 vi.mock('@steipete/sweet-cookie', () => ({
-  getCookies: vi.fn(async (options: { browsers?: string[] }) => {
+  getCookies: vi.fn(async (options: { browsers?: string[]; timeoutMs?: number }) => {
     const browser = options.browsers?.[0] ?? 'unknown';
+    sweet.options.set(browser, options);
     return (
       sweet.results.get(browser) ?? {
         cookies: [],
@@ -24,6 +26,7 @@ describe('cookies', () => {
   beforeEach(() => {
     vi.resetModules();
     sweet.results.clear();
+    sweet.options.clear();
     process.env = { ...originalEnv };
     process.env.AUTH_TOKEN = undefined;
     process.env.TWITTER_AUTH_TOKEN = undefined;
@@ -186,11 +189,36 @@ describe('cookies', () => {
       });
 
       const { resolveCredentials } = await import('../src/lib/cookies.js');
-      const result = await resolveCredentials({ cookieSource: 'chrome', chromeProfile: 'Default' });
+      const result = await resolveCredentials({
+        cookieSource: 'chrome',
+        chromeProfile: 'Default',
+        cookieTimeoutMs: 15000,
+      });
 
       expect(result.cookies.authToken).toBe('test_auth');
       expect(result.cookies.ct0).toBe('test_ct0');
       expect(result.cookies.source).toContain('Chrome');
+      expect(sweet.options.get('chrome')?.timeoutMs).toBe(15000);
+    });
+
+    it('defaults to a 30s cookie timeout on macOS', async () => {
+      if (process.platform !== 'darwin') {
+        return;
+      }
+      sweet.results.set('chrome', {
+        cookies: [
+          { name: 'auth_token', value: 'test_auth', domain: 'x.com' },
+          { name: 'ct0', value: 'test_ct0', domain: 'x.com' },
+        ],
+        warnings: [],
+      });
+
+      const { resolveCredentials } = await import('../src/lib/cookies.js');
+      const result = await resolveCredentials({ cookieSource: 'chrome' });
+
+      expect(result.cookies.authToken).toBe('test_auth');
+      expect(result.cookies.ct0).toBe('test_ct0');
+      expect(sweet.options.get('chrome')?.timeoutMs).toBe(30000);
     });
 
     it('uses default browser order when cookieSource is omitted', async () => {

tests/library-exports.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+import { resolveCredentials, TwitterClient } from '../src/index.js';
+
+describe('library exports', () => {
+  it('exposes primary library surface', () => {
+    expect(typeof TwitterClient).toBe('function');
+    expect(typeof resolveCredentials).toBe('function');
+  });
+});

tests/twitter-client-coverage.api.test.ts

@@ -17,6 +17,15 @@ type ResponseLike = {
 
 type TwitterClientApiPrivate = TwitterClient & {
   getBookmarksQueryIds: () => Promise<string[]>;
+  getFollowingQueryIds: () => Promise<string[]>;
+  getFollowersQueryIds: () => Promise<string[]>;
+  getLikesQueryIds: () => Promise<string[]>;
+  getCurrentUser: () => Promise<{
+    success: boolean;
+    user?: { id: string; username: string; name: string };
+    error?: string;
+  }>;
+  getBookmarkFolderQueryIds: () => Promise<string[]>;
 };
 
 const makeResponse = (overrides: Partial<ResponseLike> = {}): ResponseLike => ({
@@ -204,4 +213,211 @@ describe('TwitterClient API coverage', () => {
       expect(result.error).toBe('HTTP 404');
     });
   });
+
+  describe('following/followers error paths', () => {
+    it('returns an error for non-ok responses', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(makeResponse({ ok: false, status: 500, text: async () => 'down' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getFollowingQueryIds = async () => ['test'];
+
+      const result = await client.getFollowing('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('HTTP 500');
+    });
+
+    it('returns API errors from payloads', async () => {
+      const mockFetch = vi.fn().mockResolvedValueOnce(
+        makeResponse({
+          json: async () => ({ errors: [{ message: 'bad' }] }),
+        }),
+      );
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getFollowersQueryIds = async () => ['test'];
+
+      const result = await client.getFollowers('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('bad');
+    });
+
+    it('returns unknown error when no query ids are available', async () => {
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getFollowingQueryIds = async () => [];
+
+      const result = await client.getFollowing('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Unknown error fetching following');
+    });
+
+    it('returns the second attempt error after 404s', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeResponse({ ok: false, status: 404, text: async () => 'nope' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getFollowersQueryIds = async () => ['test'];
+
+      const result = await client.getFollowers('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('HTTP 404');
+    });
+  });
+  describe('likes error paths', () => {
+    const stubCurrentUser = async () => ({
+      success: true,
+      user: { id: '123', username: 'tester', name: 'Tester' },
+    });
+
+    it('returns an error for non-ok responses', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(makeResponse({ ok: false, status: 500, text: async () => 'down' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getCurrentUser = stubCurrentUser;
+      clientPrivate.getLikesQueryIds = async () => ['test'];
+
+      const result = await client.getLikes(1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('HTTP 500');
+    });
+
+    it('returns API errors from payloads', async () => {
+      const mockFetch = vi.fn().mockResolvedValueOnce(
+        makeResponse({
+          json: async () => ({ errors: [{ message: 'bad' }] }),
+        }),
+      );
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getCurrentUser = stubCurrentUser;
+      clientPrivate.getLikesQueryIds = async () => ['test'];
+
+      const result = await client.getLikes(1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('bad');
+    });
+
+    it('returns an error when fetching throws', async () => {
+      const mockFetch = vi.fn().mockRejectedValue(new Error('boom'));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getCurrentUser = stubCurrentUser;
+      clientPrivate.getLikesQueryIds = async () => ['test'];
+
+      const result = await client.getLikes(1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('boom');
+    });
+
+    it('returns unknown error when no query ids are available', async () => {
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getCurrentUser = stubCurrentUser;
+      clientPrivate.getLikesQueryIds = async () => [];
+
+      const result = await client.getLikes(1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Unknown error fetching likes');
+    });
+
+    it('returns the second attempt error after 404s', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeResponse({ ok: false, status: 404, text: async () => 'nope' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getCurrentUser = stubCurrentUser;
+      clientPrivate.getLikesQueryIds = async () => ['test'];
+
+      const result = await client.getLikes(1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('HTTP 404');
+    });
+  });
+  describe('bookmark folder error paths', () => {
+    it('returns an error for non-ok responses', async () => {
+      const mockFetch = vi
+        .fn()
+        .mockResolvedValueOnce(makeResponse({ ok: false, status: 500, text: async () => 'down' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getBookmarkFolderTimeline('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('HTTP 500');
+    });
+
+    it('returns API errors from payloads', async () => {
+      const mockFetch = vi.fn().mockResolvedValueOnce(
+        makeResponse({
+          json: async () => ({ errors: [{ message: 'bad' }] }),
+        }),
+      );
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getBookmarkFolderTimeline('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('bad');
+    });
+
+    it('returns an error when fetching throws', async () => {
+      const mockFetch = vi.fn().mockRejectedValue(new Error('boom'));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getBookmarkFolderTimeline('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('boom');
+    });
+
+    it('returns unknown error when no query ids are available', async () => {
+      const client = new TwitterClient({ cookies: validCookies });
+      const clientPrivate = client as unknown as TwitterClientApiPrivate;
+      clientPrivate.getBookmarkFolderQueryIds = async () => [];
+
+      const result = await client.getBookmarkFolderTimeline('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Unknown error fetching bookmark folder');
+    });
+
+    it('returns the second attempt error after 404s', async () => {
+      const mockFetch = vi.fn().mockResolvedValue(makeResponse({ ok: false, status: 404, text: async () => 'nope' }));
+      global.fetch = mockFetch as unknown as typeof fetch;
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getBookmarkFolderTimeline('123', 1);
+
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('HTTP 404');
+    });
+  });
 });

tests/twitter-client-coverage.upload.test.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { TwitterClient } from '../src/lib/twitter-client.js';
+import { extractArticleText } from '../src/lib/twitter-client-utils.js';
 
 const validCookies = {
   authToken: 'test_auth_token',
@@ -17,7 +18,6 @@ type ResponseLike = {
 
 type TwitterClientUploadPrivate = TwitterClient & {
   sleep: (ms: number) => Promise<void>;
-  extractArticleText: (result: unknown) => string | undefined;
 };
 
 const makeResponse = (overrides: Partial<ResponseLike> = {}): ResponseLike => ({
@@ -188,12 +188,10 @@ describe('TwitterClient upload coverage', () => {
 
   describe('article extraction edge cases', () => {
     it('logs article payloads when debug flag is set', () => {
-      const client = new TwitterClient({ cookies: validCookies });
       process.env.BIRD_DEBUG_ARTICLE = '1';
       const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
 
-      const clientPrivate = client as unknown as TwitterClientUploadPrivate;
+      const result = extractArticleText({
-      const result = clientPrivate.extractArticleText({
         rest_id: '1',
         article: {
           title: 'Title',
@@ -207,9 +205,7 @@ describe('TwitterClient upload coverage', () => {
     });
 
     it('drops duplicate body when it matches the title', () => {
-      const client = new TwitterClient({ cookies: validCookies });
+      const result = extractArticleText({
-      const clientPrivate = client as unknown as TwitterClientUploadPrivate;
-      const result = clientPrivate.extractArticleText({
         rest_id: '1',
         article: {
           title: 'Same',

tests/twitter-client-fixtures.ts

@@ -0,0 +1,17 @@
+import type { TwitterClient } from '../src/lib/twitter-client.js';
+
+export const validCookies = {
+  authToken: 'test_auth_token',
+  ct0: 'test_ct0_token',
+  cookieHeader: 'auth_token=test_auth_token; ct0=test_ct0_token',
+  source: 'test',
+};
+
+export type TwitterClientPrivate = TwitterClient & {
+  getCurrentUser: () => Promise<{
+    success: boolean;
+    user?: { id: string; username: string; name: string };
+    error?: string;
+  }>;
+  getLikesQueryIds: () => Promise<string[]>;
+};

tests/twitter-client.constructor-tweet-reply.test.ts

@@ -0,0 +1,400 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient constructor', () => {
+  it('should throw if authToken is missing', () => {
+    expect(
+      () =>
+        new TwitterClient({
+          cookies: { authToken: null, ct0: 'test', cookieHeader: null, source: null },
+        }),
+    ).toThrow('Both authToken and ct0 cookies are required');
+  });
+
+  it('should throw if ct0 is missing', () => {
+    expect(
+      () =>
+        new TwitterClient({
+          cookies: { authToken: 'test', ct0: null, cookieHeader: null, source: null },
+        }),
+    ).toThrow('Both authToken and ct0 cookies are required');
+  });
+
+  it('should create client with valid cookies', () => {
+    const client = new TwitterClient({ cookies: validCookies });
+    expect(client).toBeInstanceOf(TwitterClient);
+  });
+});
+
+describe('TwitterClient tweet', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('should post a tweet successfully', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          create_tweet: {
+            tweet_results: {
+              result: {
+                rest_id: '1234567890',
+                legacy: {
+                  full_text: 'Hello world!',
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(true);
+    expect(result.tweetId).toBe('1234567890');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const [url, options] = mockFetch.mock.calls[0];
+    expect(url).toContain('CreateTweet');
+    expect(options.method).toBe('POST');
+
+    const body = JSON.parse(options.body);
+    expect(body.variables.tweet_text).toBe('Hello world!');
+    expect(body.features.rweb_video_screen_enabled).toBe(true);
+    expect(body.features.creator_subscriptions_tweet_preview_api_enabled).toBe(true);
+  });
+
+  it('supports attaching media IDs', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          create_tweet: {
+            tweet_results: {
+              result: {
+                rest_id: '1234567890',
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!', ['111', '222']);
+
+    expect(result.success).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const [, options] = mockFetch.mock.calls[0];
+    const body = JSON.parse(options.body);
+    expect(body.variables.media.media_entities).toEqual([
+      { media_id: '111', tagged_users: [] },
+      { media_id: '222', tagged_users: [] },
+    ]);
+  });
+
+  it('retries CreateTweet via /i/api/graphql when operation URL 404s', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => '',
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => '',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            create_tweet: {
+              tweet_results: {
+                result: {
+                  rest_id: '1234567890',
+                },
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(true);
+    expect(result.tweetId).toBe('1234567890');
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+
+    const [firstUrl] = mockFetch.mock.calls[0];
+    const [thirdUrl] = mockFetch.mock.calls[2];
+    expect(String(firstUrl)).toContain('/CreateTweet');
+    expect(String(thirdUrl)).toBe('https://x.com/i/api/graphql');
+  });
+
+  it('should handle API errors', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        errors: [{ message: 'Rate limit exceeded', code: 88 }],
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Test');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Rate limit exceeded');
+  });
+
+  it('falls back to statuses/update.json when CreateTweet returns code 226', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [
+            {
+              message: 'Authorization: This request looks like it might be automated.',
+              code: 226,
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          id_str: '1234567890',
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(true);
+    expect(result.tweetId).toBe('1234567890');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(String(mockFetch.mock.calls[1][0])).toContain('statuses/update.json');
+  });
+
+  it('surfaces statuses/update.json failure when CreateTweet returns code 226', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [
+            {
+              message: 'Authorization: This request looks like it might be automated.',
+              code: 226,
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 403,
+        text: async () => 'Forbidden',
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('(226)');
+    expect(result.error).toContain('fallback: HTTP 403');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+    expect(String(mockFetch.mock.calls[1][0])).toContain('statuses/update.json');
+  });
+
+  it('surfaces statuses/update.json API errors when CreateTweet returns code 226', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [
+            {
+              message: 'Authorization: This request looks like it might be automated.',
+              code: 226,
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [{ message: 'Nope', code: 999 }],
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('(226)');
+    expect(result.error).toContain('fallback: Nope (999)');
+  });
+
+  it('surfaces statuses/update.json missing id when CreateTweet returns code 226', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [
+            {
+              message: 'Authorization: This request looks like it might be automated.',
+              code: 226,
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({}),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('(226)');
+    expect(result.error).toContain('fallback: Tweet created but no ID returned');
+  });
+
+  it('should handle HTTP errors', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      text: async () => 'Forbidden',
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Test');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('HTTP 403');
+  });
+
+  it('should handle network errors', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('Network error'));
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Test');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Network error');
+  });
+
+  it('should surface missing tweet ID when API responds without rest_id', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          create_tweet: {
+            tweet_results: {
+              result: {
+                legacy: { full_text: 'No id' },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.tweet('Hello world!');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Tweet created but no ID returned');
+  });
+});
+
+describe('TwitterClient reply', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('should post a reply with correct reply_to_tweet_id', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          create_tweet: {
+            tweet_results: {
+              result: {
+                rest_id: '9876543210',
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.reply('This is a reply', '1234567890');
+
+    expect(result.success).toBe(true);
+    expect(result.tweetId).toBe('9876543210');
+
+    const [, options] = mockFetch.mock.calls[0];
+    const body = JSON.parse(options.body);
+    expect(body.variables.reply.in_reply_to_tweet_id).toBe('1234567890');
+    expect(body.variables.tweet_text).toBe('This is a reply');
+    expect(body.features.rweb_video_screen_enabled).toBe(true);
+    expect(body.features.creator_subscriptions_tweet_preview_api_enabled).toBe(true);
+  });
+
+  it('falls back to statuses/update.json for replies when CreateTweet returns code 226', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          errors: [
+            {
+              message: 'Authorization: This request looks like it might be automated.',
+              code: 226,
+            },
+          ],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          id_str: '999',
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.reply('This is a reply', '1234567890', ['111', '222']);
+
+    expect(result.success).toBe(true);
+    expect(result.tweetId).toBe('999');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    const [, options] = mockFetch.mock.calls[1];
+    expect(String(mockFetch.mock.calls[1][0])).toContain('statuses/update.json');
+    expect(options.method).toBe('POST');
+    expect(options.body).toContain('status=This+is+a+reply');
+    expect(options.body).toContain('in_reply_to_status_id=1234567890');
+    expect(options.body).toContain('auto_populate_reply_metadata=true');
+    expect(options.body).toContain('media_ids=111%2C222');
+  });
+});

tests/twitter-client.conversations.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient conversation helpers', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  const makeConversationPayload = () => ({
+    data: {
+      threaded_conversation_with_injections_v2: {
+        instructions: [
+          {
+            entries: [
+              {
+                content: {
+                  itemContent: {
+                    tweet_results: {
+                      result: {
+                        rest_id: '1',
+                        legacy: {
+                          full_text: 'root',
+                          created_at: '2024-01-01T00:00:00Z',
+                          reply_count: 0,
+                          retweet_count: 0,
+                          favorite_count: 0,
+                          conversation_id_str: '1',
+                        },
+                        core: { user_results: { result: { legacy: { screen_name: 'root', name: 'Root' } } } },
+                      },
+                    },
+                  },
+                },
+              },
+              {
+                content: {
+                  itemContent: {
+                    tweet_results: {
+                      result: {
+                        rest_id: '2',
+                        legacy: {
+                          full_text: 'child reply',
+                          created_at: '2024-01-02T00:00:00Z',
+                          reply_count: 0,
+                          retweet_count: 0,
+                          favorite_count: 0,
+                          conversation_id_str: '1',
+                          in_reply_to_status_id_str: '1',
+                        },
+                        core: { user_results: { result: { legacy: { screen_name: 'child', name: 'Child' } } } },
+                      },
+                    },
+                  },
+                },
+              },
+            ],
+          },
+        ],
+      },
+    },
+  });
+
+  it('getReplies returns only replies to tweet', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => makeConversationPayload(),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getReplies('1');
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.length).toBe(1);
+    expect(result.tweets?.[0].id).toBe('2');
+  });
+
+  it('getThread returns sorted thread by createdAt', async () => {
+    const payload = makeConversationPayload();
+    // swap dates to verify sorting
+    const legacy =
+      payload.data.threaded_conversation_with_injections_v2.instructions[0]?.entries?.[0]?.content?.itemContent
+        ?.tweet_results?.result?.legacy;
+    if (legacy) {
+      legacy.created_at = '2024-01-03T00:00:00Z';
+    }
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => payload,
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getThread('2');
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.map((t) => t.id)).toEqual(['2', '1']); // sorted by createdAt asc
+  });
+
+  it('getThread includes tweets from timeline module items', async () => {
+    const payload = makeConversationPayload();
+    payload.data.threaded_conversation_with_injections_v2.instructions[0]?.entries?.push({
+      content: {
+        items: [
+          {
+            item: {
+              itemContent: {
+                tweet_results: {
+                  result: {
+                    rest_id: '3',
+                    legacy: {
+                      full_text: 'nested reply',
+                      created_at: '2024-01-04T00:00:00Z',
+                      reply_count: 0,
+                      retweet_count: 0,
+                      favorite_count: 0,
+                      conversation_id_str: '1',
+                      in_reply_to_status_id_str: '1',
+                    },
+                    core: {
+                      user_results: { result: { legacy: { screen_name: 'nested', name: 'Nested' } } },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        ],
+      },
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => payload,
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getThread('1');
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.map((t) => t.id)).toEqual(['1', '2', '3']);
+  });
+
+  it('propagates fetchTweetDetail errors', async () => {
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: async () => 'oops',
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getThread('1');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('HTTP 500');
+  });
+});

tests/twitter-client.current-user.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient getCurrentUser', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('returns mapped user details when present', async () => {
+    mockFetch.mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        user_id: '12345',
+        screen_name: 'tester',
+        name: 'Test User',
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(true);
+    expect(result.user).toEqual({ id: '12345', username: 'tester', name: 'Test User' });
+    expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('account/settings'), expect.any(Object));
+  });
+
+  it('returns error when response lacks identifiers', async () => {
+    mockFetch.mockImplementation(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => ({ language: 'en' }),
+      text: async () => '{"language":"en"}',
+    }));
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Could not');
+  });
+
+  it('surfaces HTTP errors', async () => {
+    mockFetch.mockImplementation(async () => ({
+      ok: false,
+      status: 401,
+      text: async () => 'Unauthorized',
+    }));
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('HTTP 401');
+  });
+
+  it('uses HTML fallback when API endpoints 404', async () => {
+    mockFetch
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        text: async () => '<html>"screen_name":"fallback","user_id":"999"</html>',
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(true);
+    expect(result.user?.username).toBe('fallback');
+    expect(result.user?.id).toBe('999');
+    expect(mockFetch).toHaveBeenCalledTimes(5);
+  });
+
+  it('skips an endpoint when JSON parsing fails', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new Error('bad json');
+        },
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          user_id: '12345',
+          screen_name: 'tester',
+          name: 'Test User',
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(true);
+    expect(result.user).toEqual({ id: '12345', username: 'tester', name: 'Test User' });
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('continues on fetch errors and still succeeds via HTML fallback', async () => {
+    mockFetch
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'not found' })
+      .mockRejectedValueOnce(new Error('settings boom'))
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        text: async () => '<html>"screen_name":"fallback","user_id":"999"</html>',
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getCurrentUser();
+
+    expect(result.success).toBe(true);
+    expect(result.user?.username).toBe('fallback');
+    expect(result.user?.id).toBe('999');
+  });
+});

tests/twitter-client.following-likes.test.ts

@@ -0,0 +1,299 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { type TwitterClientPrivate, validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient following/followers', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  const makeUserResult = (id: string, username: string, name = username) => ({
+    __typename: 'User',
+    rest_id: id,
+    is_blue_verified: true,
+    legacy: {
+      screen_name: username,
+      name,
+      description: `bio-${id}`,
+      followers_count: 10,
+      friends_count: 5,
+      profile_image_url_https: `https://example.com/${id}.jpg`,
+      created_at: '2024-01-01T00:00:00Z',
+    },
+  });
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('fetches following users and filters invalid entries', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          user: {
+            result: {
+              timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      type: 'TimelineAddEntries',
+                      entries: [
+                        {
+                          content: {
+                            itemContent: {
+                              user_results: {
+                                result: makeUserResult('1', 'alpha', 'Alpha'),
+                              },
+                            },
+                          },
+                        },
+                        {
+                          content: {
+                            itemContent: {
+                              user_results: {
+                                result: { __typename: 'User', rest_id: '2' },
+                              },
+                            },
+                          },
+                        },
+                        {
+                          content: {
+                            itemContent: {
+                              user_results: {
+                                result: { __typename: 'TimelineUser' },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as unknown as TwitterClient & { getFollowingQueryIds: () => Promise<string[]> };
+    clientPrivate.getFollowingQueryIds = async () => ['test'];
+
+    const result = await client.getFollowing('123', 2);
+
+    expect(result.success).toBe(true);
+    expect(result.users?.length).toBe(1);
+    expect(result.users?.[0].username).toBe('alpha');
+    expect(result.users?.[0].followersCount).toBe(10);
+    expect(result.users?.[0].followingCount).toBe(5);
+    expect(result.users?.[0].isBlueVerified).toBe(true);
+    expect(result.users?.[0].profileImageUrl).toBe('https://example.com/1.jpg');
+    expect(result.users?.[0].createdAt).toBe('2024-01-01T00:00:00Z');
+    const [url] = mockFetch.mock.calls[0];
+    expect(String(url)).toContain('/Following?');
+  });
+
+  it('fetches followers and unwraps visibility results', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          user: {
+            result: {
+              timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [
+                        {
+                          content: {
+                            itemContent: {
+                              user_results: {
+                                result: {
+                                  __typename: 'UserWithVisibilityResults',
+                                  user: makeUserResult('9', 'vis', 'Visible'),
+                                },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as unknown as TwitterClient & { getFollowersQueryIds: () => Promise<string[]> };
+    clientPrivate.getFollowersQueryIds = async () => ['test'];
+
+    const result = await client.getFollowers('123', 1);
+
+    expect(result.success).toBe(true);
+    expect(result.users?.[0].username).toBe('vis');
+    const [url] = mockFetch.mock.calls[0];
+    expect(String(url)).toContain('/Followers?');
+  });
+
+  it('refreshes query IDs after 404s', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 404, text: async () => 'nope' }).mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          user: {
+            result: {
+              timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [
+                        {
+                          content: {
+                            itemContent: {
+                              user_results: {
+                                result: makeUserResult('1', 'alpha', 'Alpha'),
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as unknown as TwitterClient & {
+      getFollowingQueryIds: () => Promise<string[]>;
+      refreshQueryIds: () => Promise<void>;
+    };
+    clientPrivate.getFollowingQueryIds = async () => ['test'];
+    let refreshed = false;
+    clientPrivate.refreshQueryIds = async () => {
+      refreshed = true;
+    };
+
+    const result = await client.getFollowing('123', 1);
+
+    expect(refreshed).toBe(true);
+    expect(result.success).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('TwitterClient likes', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('fetches likes and parses tweet results', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          user: {
+            result: {
+              timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [
+                        {
+                          content: {
+                            itemContent: {
+                              tweet_results: {
+                                result: {
+                                  rest_id: '2',
+                                  legacy: {
+                                    full_text: 'liked',
+                                    created_at: '2024-01-01T00:00:00Z',
+                                    reply_count: 0,
+                                    retweet_count: 0,
+                                    favorite_count: 0,
+                                    conversation_id_str: '2',
+                                  },
+                                  core: {
+                                    user_results: {
+                                      result: {
+                                        rest_id: 'u2',
+                                        legacy: { screen_name: 'root', name: 'Root' },
+                                      },
+                                    },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as unknown as TwitterClientPrivate;
+    clientPrivate.getCurrentUser = async () => ({
+      success: true,
+      user: { id: '42', username: 'tester', name: 'Tester' },
+    });
+    clientPrivate.getLikesQueryIds = async () => ['test'];
+
+    const result = await client.getLikes(2);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.[0].id).toBe('2');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const [url, options] = mockFetch.mock.calls[0];
+    expect(options.method).toBe('GET');
+    expect(String(url)).toContain('/Likes?');
+    const parsedVars = JSON.parse(new URL(url as string).searchParams.get('variables') as string);
+    expect(parsedVars.userId).toBe('42');
+    expect(parsedVars.count).toBe(2);
+    const parsedFeatures = JSON.parse(new URL(url as string).searchParams.get('features') as string);
+    expect(parsedFeatures.graphql_timeline_v2_bookmark_timeline).toBeUndefined();
+  });
+
+  it('returns an error when current user is unavailable', async () => {
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as unknown as TwitterClientPrivate;
+    clientPrivate.getCurrentUser = async () => ({ success: false, error: 'no user' });
+
+    const result = await client.getLikes(1);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('no user');
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});

tests/twitter-client.get-tweet.test.ts

@@ -0,0 +1,417 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { mapTweetResult } from '../src/lib/twitter-client-utils.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient getTweet', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('should return tweet data from root tweetResult', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          tweetResult: {
+            result: {
+              rest_id: '12345',
+              legacy: {
+                full_text: 'Root tweet text',
+                created_at: 'Mon Jan 01 00:00:00 +0000 2024',
+                reply_count: 1,
+                retweet_count: 2,
+                favorite_count: 3,
+              },
+              core: {
+                user_results: {
+                  result: {
+                    legacy: {
+                      screen_name: 'user',
+                      name: 'User Name',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('12345');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.id).toBe('12345');
+    expect(result.tweet?.text).toBe('Root tweet text');
+    expect(result.tweet?.author.username).toBe('user');
+  });
+
+  it('should return tweet data found inside conversation instructions', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                entries: [
+                  {
+                    content: {
+                      itemContent: {
+                        tweet_results: {
+                          result: {
+                            rest_id: '6789',
+                            legacy: {
+                              full_text: 'Nested text',
+                              created_at: 'Mon Jan 01 00:00:00 +0000 2024',
+                              reply_count: 0,
+                              retweet_count: 0,
+                              favorite_count: 0,
+                            },
+                            core: {
+                              user_results: {
+                                result: {
+                                  legacy: {
+                                    screen_name: 'nestuser',
+                                    name: 'Nested User',
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('6789');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.text).toBe('Nested text');
+    expect(result.tweet?.author.username).toBe('nestuser');
+  });
+
+  it('should report HTTP errors from getTweet', async () => {
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 404,
+      text: async () => 'Not Found',
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('missing');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('HTTP 404');
+  });
+
+  it('should return article text when present', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          tweetResult: {
+            result: {
+              rest_id: 'article123',
+              legacy: {
+                full_text: '',
+                created_at: 'Mon Jan 01 00:00:00 +0000 2024',
+              },
+              article: {
+                article_results: {
+                  result: {
+                    title: '2025 LLM Year in Review',
+                    sections: [
+                      {
+                        items: [
+                          { text: 'Intro paragraph of the article.' },
+                          { content: { text: 'Second paragraph.' } },
+                        ],
+                      },
+                    ],
+                  },
+                },
+              },
+              core: {
+                user_results: {
+                  result: {
+                    legacy: {
+                      screen_name: 'author',
+                      name: 'Article Author',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('article123');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.text).toBe('2025 LLM Year in Review\n\nIntro paragraph of the article.\n\nSecond paragraph.');
+  });
+
+  it('should fall back to user article timeline for plain text', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: {
+            tweetResult: {
+              result: {
+                rest_id: 'article123',
+                legacy: {
+                  full_text: '',
+                  created_at: 'Mon Jan 01 00:00:00 +0000 2024',
+                },
+                article: {
+                  article_results: {
+                    result: {
+                      title: '2025 LLM Year in Review',
+                    },
+                  },
+                },
+                core: {
+                  user_results: {
+                    result: {
+                      rest_id: '33836629',
+                      legacy: {
+                        screen_name: 'author',
+                        name: 'Article Author',
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: {
+            user: {
+              result: {
+                timeline: {
+                  timeline: {
+                    instructions: [
+                      {
+                        entries: [
+                          {
+                            content: {
+                              itemContent: {
+                                tweet_results: {
+                                  result: {
+                                    rest_id: 'article123',
+                                    article: {
+                                      article_results: {
+                                        result: {
+                                          title: '2025 LLM Year in Review',
+                                          plain_text: 'Full article body.',
+                                        },
+                                      },
+                                    },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                },
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('article123');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.text).toBe('2025 LLM Year in Review\n\nFull article body.');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('should return note tweet text when present', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        data: {
+          tweetResult: {
+            result: {
+              rest_id: 'note123',
+              legacy: {
+                full_text: '',
+                created_at: 'Mon Jan 01 00:00:00 +0000 2024',
+              },
+              note_tweet: {
+                note_tweet_results: {
+                  result: {
+                    text: 'Long form note content.',
+                  },
+                },
+              },
+              core: {
+                user_results: {
+                  result: {
+                    legacy: {
+                      screen_name: 'noter',
+                      name: 'Note Author',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('note123');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.text).toBe('Long form note content.');
+  });
+
+  it('retries TweetDetail query id on 404', async () => {
+    const payload = {
+      data: {
+        tweetResult: {
+          result: {
+            rest_id: '1',
+            legacy: {
+              full_text: 'hello',
+              created_at: '2024-01-01T00:00:00Z',
+              reply_count: 0,
+              retweet_count: 0,
+              favorite_count: 0,
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'root', name: 'Root' } } } },
+          },
+        },
+      },
+    };
+
+    mockFetch
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => payload });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getTweet('1');
+
+    expect(result.success).toBe(true);
+    expect(result.tweet?.id).toBe('1');
+    expect(mockFetch).toHaveBeenCalledTimes(3);
+  });
+});
+
+describe('TwitterClient quoted tweets', () => {
+  const makeTweetResult = (
+    id: string,
+    text: string,
+    username = `user${id}`,
+    name = `User ${id}`,
+  ): Record<string, unknown> => ({
+    rest_id: id,
+    legacy: {
+      full_text: text,
+      created_at: '2024-01-01T00:00:00Z',
+      reply_count: 0,
+      retweet_count: 0,
+      favorite_count: 0,
+      conversation_id_str: id,
+    },
+    core: {
+      user_results: {
+        result: {
+          rest_id: `u${id}`,
+          legacy: { screen_name: username, name },
+        },
+      },
+    },
+  });
+
+  it('includes one level of quoted tweet by default', () => {
+    const quoted = makeTweetResult('2', 'quoted');
+    const root = makeTweetResult('1', 'root');
+    root.quoted_status_result = { result: quoted };
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const mapped = mapTweetResult(root, (client as { quoteDepth: number }).quoteDepth);
+
+    expect(mapped?.quotedTweet?.id).toBe('2');
+    expect(mapped?.quotedTweet?.quotedTweet).toBeUndefined();
+  });
+
+  it('honors quoteDepth = 0', () => {
+    const quoted = makeTweetResult('2', 'quoted');
+    const root = makeTweetResult('1', 'root');
+    root.quoted_status_result = { result: quoted };
+
+    const client = new TwitterClient({ cookies: validCookies, quoteDepth: 0 });
+    const mapped = mapTweetResult(root, (client as { quoteDepth: number }).quoteDepth);
+
+    expect(mapped?.quotedTweet).toBeUndefined();
+  });
+
+  it('recurses when quoteDepth > 1', () => {
+    const quoted2 = makeTweetResult('3', 'quoted2');
+    const quoted1 = makeTweetResult('2', 'quoted1');
+    quoted1.quoted_status_result = { result: quoted2 };
+    const root = makeTweetResult('1', 'root');
+    root.quoted_status_result = { result: quoted1 };
+
+    const client = new TwitterClient({ cookies: validCookies, quoteDepth: 2 });
+    const mapped = mapTweetResult(root, (client as { quoteDepth: number }).quoteDepth);
+
+    expect(mapped?.quotedTweet?.id).toBe('2');
+    expect(mapped?.quotedTweet?.quotedTweet?.id).toBe('3');
+    expect(mapped?.quotedTweet?.quotedTweet?.quotedTweet).toBeUndefined();
+  });
+
+  it('unwraps quoted tweet visibility wrappers', () => {
+    const quoted = makeTweetResult('2', 'quoted');
+    const root = makeTweetResult('1', 'root');
+    root.quoted_status_result = {
+      result: {
+        __typename: 'TweetWithVisibilityResults',
+        tweet: quoted,
+      },
+    };
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const mapped = mapTweetResult(root, (client as { quoteDepth: number }).quoteDepth);
+
+    expect(mapped?.quotedTweet?.id).toBe('2');
+  });
+});

tests/twitter-client.media.test.ts

@@ -0,0 +1,104 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient uploadMedia', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch;
+  });
+
+  it('uploads an image and sets alt text', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ media_id_string: '999' }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({}),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const data = new Uint8Array([1, 2, 3, 4]);
+    const result = await client.uploadMedia({ data, mimeType: 'image/png', alt: 'alt text' });
+
+    expect(result.success).toBe(true);
+    expect(result.mediaId).toBe('999');
+    expect(mockFetch).toHaveBeenCalledTimes(4);
+
+    const [initUrl, initOptions] = mockFetch.mock.calls[0];
+    expect(String(initUrl)).toContain('upload.twitter.com');
+    expect(initOptions.method).toBe('POST');
+    expect(initOptions.body).toBeInstanceOf(URLSearchParams);
+    expect((initOptions.body as URLSearchParams).get('command')).toBe('INIT');
+    expect((initOptions.body as URLSearchParams).get('media_type')).toBe('image/png');
+
+    const [, appendOptions] = mockFetch.mock.calls[1];
+    expect(appendOptions.method).toBe('POST');
+    expect(appendOptions.body).toBeInstanceOf(FormData);
+    const appendBody = appendOptions.body as FormData;
+    expect(appendBody.get('command')).toBe('APPEND');
+    expect(appendBody.get('media_id')).toBe('999');
+    expect(appendBody.get('segment_index')).toBe('0');
+    expect(appendBody.get('media')).toBeInstanceOf(Blob);
+
+    const [, finalizeOptions] = mockFetch.mock.calls[2];
+    expect(finalizeOptions.body).toBeInstanceOf(URLSearchParams);
+    expect((finalizeOptions.body as URLSearchParams).get('command')).toBe('FINALIZE');
+    expect((finalizeOptions.body as URLSearchParams).get('media_id')).toBe('999');
+
+    const [metaUrl, metaOptions] = mockFetch.mock.calls[3];
+    expect(String(metaUrl)).toContain('/media/metadata/create.json');
+    expect(metaOptions.method).toBe('POST');
+    expect(JSON.parse(metaOptions.body)).toEqual({ media_id: '999', alt_text: { text: 'alt text' } });
+  });
+
+  it('uploads a video and polls processing status', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ media_id_string: '777' }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ processing_info: { state: 'pending', check_after_secs: 0 } }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ processing_info: { state: 'succeeded' } }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const data = new Uint8Array([1, 2, 3, 4, 5]);
+    const result = await client.uploadMedia({ data, mimeType: 'video/mp4', alt: 'ignored' });
+
+    expect(result.success).toBe(true);
+    expect(result.mediaId).toBe('777');
+    expect(mockFetch).toHaveBeenCalledTimes(4);
+
+    const [, finalizeOptions] = mockFetch.mock.calls[2];
+    expect((finalizeOptions.body as URLSearchParams).get('command')).toBe('FINALIZE');
+
+    const [statusUrl] = mockFetch.mock.calls[3];
+    expect(String(statusUrl)).toContain('command=STATUS');
+  });
+});

tests/twitter-client.search-bookmarks.test.ts

@@ -0,0 +1,562 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+import { validCookies } from './twitter-client-fixtures.js';
+
+const originalFetch = global.fetch;
+
+afterEach(() => {
+  global.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe('TwitterClient search', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('retries on 404 and posts search payload', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => '',
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            search_by_raw_query: {
+              search_timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [
+                        {
+                          content: {
+                            itemContent: {
+                              tweet_results: {
+                                result: {
+                                  rest_id: '1',
+                                  legacy: {
+                                    full_text: 'found',
+                                    created_at: '2024-01-01T00:00:00Z',
+                                    reply_count: 0,
+                                    retweet_count: 0,
+                                    favorite_count: 0,
+                                    conversation_id_str: '1',
+                                  },
+                                  core: {
+                                    user_results: {
+                                      result: { legacy: { screen_name: 'root', name: 'Root' } },
+                                    },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.search('needle', 1);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.[0].id).toBe('1');
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    const [url, options] = mockFetch.mock.calls[1];
+    expect(options.method).toBe('POST');
+    const body = JSON.parse(options.body);
+    expect(body.features).toBeDefined();
+    expect(body.queryId).toBeDefined();
+    const urlVars = new URL(url as string).searchParams.get('variables');
+    expect(urlVars).toBeTruthy();
+    const parsed = JSON.parse(urlVars as string) as { rawQuery?: string };
+    expect(parsed.rawQuery).toBe('needle');
+  });
+
+  it('refreshes query IDs when all search endpoints 404', async () => {
+    mockFetch
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({ ok: false, status: 404, text: async () => '' })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            search_by_raw_query: {
+              search_timeline: {
+                timeline: {
+                  instructions: [],
+                },
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.search('hello', 5);
+
+    expect(result.success).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(5);
+  });
+
+  it('returns an unknown error when no query IDs are available', async () => {
+    const client = new TwitterClient({ cookies: validCookies });
+    (client as unknown as { getSearchTimelineQueryIds: () => Promise<string[]> }).getSearchTimelineQueryIds =
+      async () => [];
+
+    const result = await client.search('hello', 5);
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Unknown error fetching search results');
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it('paginates search results using the bottom cursor', async () => {
+    const makeSearchEntry = (id: string, text: string) => ({
+      content: {
+        itemContent: {
+          tweet_results: {
+            result: {
+              rest_id: id,
+              legacy: {
+                full_text: text,
+                created_at: '2024-01-01T00:00:00Z',
+                reply_count: 0,
+                retweet_count: 0,
+                favorite_count: 0,
+                conversation_id_str: id,
+              },
+              core: {
+                user_results: {
+                  result: { legacy: { screen_name: 'root', name: 'Root' } },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const makeResponse = (ids: string[], cursor?: string) => ({
+      data: {
+        search_by_raw_query: {
+          search_timeline: {
+            timeline: {
+              instructions: [
+                {
+                  entries: [
+                    ...ids.map((id) => makeSearchEntry(id, `tweet-${id}`)),
+                    ...(cursor ? [{ content: { cursorType: 'Bottom', value: cursor } }] : []),
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      },
+    });
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => makeResponse(['1', '2'], 'cursor-1'),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => makeResponse(['2', '3']),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.search('needle', 3);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.map((tweet) => tweet.id)).toEqual(['1', '2', '3']);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    const firstVars = JSON.parse(
+      new URL(mockFetch.mock.calls[0][0] as string).searchParams.get('variables') as string,
+    ) as { cursor?: string };
+    const secondVars = JSON.parse(
+      new URL(mockFetch.mock.calls[1][0] as string).searchParams.get('variables') as string,
+    ) as { cursor?: string };
+
+    expect(firstVars.cursor).toBeUndefined();
+    expect(secondVars.cursor).toBe('cursor-1');
+  });
+
+  it('stops paginating when the cursor repeats', async () => {
+    const makeSearchEntry = (id: string) => ({
+      content: {
+        itemContent: {
+          tweet_results: {
+            result: {
+              rest_id: id,
+              legacy: {
+                full_text: `tweet-${id}`,
+                created_at: '2024-01-01T00:00:00Z',
+                reply_count: 0,
+                retweet_count: 0,
+                favorite_count: 0,
+                conversation_id_str: id,
+              },
+              core: {
+                user_results: {
+                  result: { legacy: { screen_name: 'root', name: 'Root' } },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    const makeResponse = (ids: string[], cursor: string) => ({
+      data: {
+        search_by_raw_query: {
+          search_timeline: {
+            timeline: {
+              instructions: [
+                {
+                  entries: [
+                    ...ids.map((id) => makeSearchEntry(id)),
+                    { content: { cursorType: 'Bottom', value: cursor } },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      },
+    });
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => makeResponse(['1', '2'], 'same-cursor'),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => makeResponse(['3'], 'same-cursor'),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.search('needle', 4);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.map((tweet) => tweet.id)).toEqual(['1', '2', '3']);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('stops paginating when the next page is empty', async () => {
+    const makeSearchEntry = (id: string) => ({
+      content: {
+        itemContent: {
+          tweet_results: {
+            result: {
+              rest_id: id,
+              legacy: {
+                full_text: `tweet-${id}`,
+                created_at: '2024-01-01T00:00:00Z',
+                reply_count: 0,
+                retweet_count: 0,
+                favorite_count: 0,
+                conversation_id_str: id,
+              },
+              core: {
+                user_results: {
+                  result: { legacy: { screen_name: 'root', name: 'Root' } },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            search_by_raw_query: {
+              search_timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [makeSearchEntry('1'), { content: { cursorType: 'Bottom', value: 'cursor-1' } }],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            search_by_raw_query: {
+              search_timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      entries: [{ content: { cursorType: 'Bottom', value: 'cursor-2' } }],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.search('needle', 3);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.map((tweet) => tweet.id)).toEqual(['1']);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('TwitterClient bookmarks', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('fetches bookmarks and parses tweet results', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          bookmark_timeline_v2: {
+            timeline: {
+              instructions: [
+                {
+                  entries: [
+                    {
+                      content: {
+                        itemContent: {
+                          tweet_results: {
+                            result: {
+                              rest_id: '1',
+                              legacy: {
+                                full_text: 'saved',
+                                created_at: '2024-01-01T00:00:00Z',
+                                reply_count: 0,
+                                retweet_count: 0,
+                                favorite_count: 0,
+                                conversation_id_str: '1',
+                              },
+                              core: {
+                                user_results: {
+                                  result: {
+                                    rest_id: 'u1',
+                                    legacy: { screen_name: 'root', name: 'Root' },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getBookmarks(2);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.[0].id).toBe('1');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const [url, options] = mockFetch.mock.calls[0];
+    expect(options.method).toBe('GET');
+    expect(String(url)).toContain('/Bookmarks?');
+    const parsedVars = JSON.parse(new URL(url as string).searchParams.get('variables') as string);
+    expect(parsedVars.count).toBe(2);
+    const parsedFeatures = JSON.parse(new URL(url as string).searchParams.get('features') as string);
+    expect(parsedFeatures.graphql_timeline_v2_bookmark_timeline).toBe(true);
+  });
+});
+
+describe('TwitterClient bookmark folders', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  it('fetches bookmark folder timeline and parses tweet results', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({
+        data: {
+          bookmark_collection_timeline: {
+            timeline: {
+              instructions: [
+                {
+                  entries: [
+                    {
+                      content: {
+                        itemContent: {
+                          tweet_results: {
+                            result: {
+                              rest_id: '9',
+                              legacy: {
+                                full_text: 'saved in folder',
+                                created_at: '2024-01-01T00:00:00Z',
+                                reply_count: 0,
+                                retweet_count: 0,
+                                favorite_count: 0,
+                                conversation_id_str: '9',
+                              },
+                              core: {
+                                user_results: {
+                                  result: {
+                                    rest_id: 'u9',
+                                    legacy: { screen_name: 'folder', name: 'Folder' },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        },
+      }),
+    });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const result = await client.getBookmarkFolderTimeline('123', 2);
+
+    expect(result.success).toBe(true);
+    expect(result.tweets?.[0].id).toBe('9');
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+
+    const [url, options] = mockFetch.mock.calls[0];
+    expect(options.method).toBe('GET');
+    expect(String(url)).toContain('/BookmarkFolderTimeline?');
+    const parsedVars = JSON.parse(new URL(url as string).searchParams.get('variables') as string);
+    expect(parsedVars.bookmark_collection_id).toBe('123');
+    expect(parsedVars.count).toBe(2);
+    const parsedFeatures = JSON.parse(new URL(url as string).searchParams.get('features') as string);
+    expect(parsedFeatures.graphql_timeline_v2_bookmark_timeline).toBe(true);
+  });
+
+  it('retries without count when API rejects the count variable', async () => {
+    mockFetch
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          errors: [{ message: 'Variable "$count" is not defined by operation' }],
+        }),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => ({
+          data: {
+            bookmark_collection_timeline: {
+              timeline: {
+                instructions: [
+                  {
+                    entries: [
+                      {
+                        content: {
+                          itemContent: {
+                            tweet_results: {
+                              result: {
+                                rest_id: '9',
+                                legacy: {
+                                  full_text: 'saved in folder',
+                                  created_at: '2024-01-01T00:00:00Z',
+                                  reply_count: 0,
+                                  retweet_count: 0,
+                                  favorite_count: 0,
+                                  conversation_id_str: '9',
+                                },
+                                core: {
+                                  user_results: {
+                                    result: {
+                                      rest_id: 'u9',
+                                      legacy: { screen_name: 'folder', name: 'Folder' },
+                                    },
+                                  },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          },
+        }),
+      });
+
+    const client = new TwitterClient({ cookies: validCookies });
+    const clientPrivate = client as TwitterClient & { getBookmarkFolderQueryIds: () => Promise<string[]> };
+    clientPrivate.getBookmarkFolderQueryIds = async () => ['test'];
+
+    const result = await client.getBookmarkFolderTimeline('123', 2);
+
+    expect(result.success).toBe(true);
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+
+    const firstVars = JSON.parse(new URL(mockFetch.mock.calls[0][0] as string).searchParams.get('variables') as string);
+    const secondVars = JSON.parse(
+      new URL(mockFetch.mock.calls[1][0] as string).searchParams.get('variables') as string,
+    );
+
+    expect(firstVars.count).toBe(2);
+    expect(secondVars.count).toBeUndefined();
+  });
+});

vitest.config.ts

@@ -9,7 +9,7 @@ export default defineConfig({
       provider: 'v8',
       reporter: ['text', 'html'],
       include: ['src/**/*.ts'],
-      exclude: ['src/index.ts'],
+      exclude: ['src/cli.ts'],
       thresholds: {
         statements: 90,
         branches: 80,