Merge pull request #35 from crcatala/feat/thread-replies-pagination

feat: add pagination support for thread and replies commands

CHANGELOG.md

@@ -7,6 +7,7 @@
 - `home` command for the "For You" and "Following" home timelines (#31) — thanks @odysseus0.
 - Rich text output now shows article previews, quoted tweets, and media links (#32) — thanks @odysseus0.
 - `user-tweets` command to fetch a user's profile timeline (#34) — thanks @crcatala.
+- `replies` and `thread` now support pagination (`--all`, `--max-pages`, `--cursor`, `--delay`) (#35) — thanks @crcatala.
 
 ### Fixed
 - macOS cookie extraction now supports Brave keychain storage (#40) — thanks @gakonst.

README.md

@@ -42,6 +42,8 @@ bird 1234567890123456789 --json
 # Thread + replies
 bird thread https://x.com/user/status/1234567890123456789
 bird replies 1234567890123456789
+bird replies 1234567890123456789 --max-pages 3 --json
+bird thread 1234567890123456789 --max-pages 3 --json
 
 # Search + mentions
 bird search "from:steipete" -n 5
@@ -100,8 +102,8 @@ const result = await client.search('from:steipete', 50);
 - `bird query-ids [--fresh] [--json]` — inspect or refresh cached GraphQL query IDs.
 - `bird read <tweet-id-or-url> [--json]` — fetch tweet content as text or JSON.
 - `bird <tweet-id-or-url> [--json]` — shorthand for `read` when only a URL or ID is provided.
-- `bird replies <tweet-id-or-url> [--json]` — list replies to a tweet.
+- `bird replies <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]` — list replies to a tweet.
-- `bird thread <tweet-id-or-url> [--json]` — show the full conversation thread.
+- `bird thread <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--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 user-tweets <@handle> [-n count] [--cursor string] [--max-pages n] [--delay ms] [--json]` — get tweets from a user's profile timeline.
@@ -177,7 +179,7 @@ Environment shortcuts:
 ## Output
 
 - `--json` prints raw tweet objects for read/replies/thread/search/mentions/user-tweets/bookmarks/likes.
-- When using `--json` with pagination (`--cursor`, `--max-pages`, or `-n > 20`), `user-tweets` prints `{ tweets, nextCursor }`.
+- When using `--json` with pagination (`--all`, `--cursor`, `--max-pages`, or for `user-tweets` when `-n > 20`), output is `{ tweets, nextCursor }`.
 - `read` returns full text for Notes and Articles when present.
 - Use `--plain` for stable, script-friendly output (no emoji, no color).
 

src/commands/read.ts

@@ -49,72 +49,165 @@ export function registerReadCommands(program: Command, ctx: CliContext): void {
     .command('replies')
     .description('List replies to a tweet (by ID or URL)')
     .argument('<tweet-id-or-url>', 'Tweet ID or URL')
+    .option('--all', 'Fetch all replies (paged)')
+    .option('--max-pages <number>', 'Fetch N pages (implies pagination)')
+    .option('--delay <ms>', 'Delay in ms between page fetches', '1000')
+    .option('--cursor <string>', 'Resume pagination from a cursor')
     .option('--json', 'Output as JSON')
     .option('--json-full', 'Output as JSON with full raw API response in _raw field')
-    .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean; jsonFull?: boolean }) => {
+    .action(
-      const opts = program.opts();
+      async (
-      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+        tweetIdOrUrl: string,
-      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+        cmdOpts: {
-      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+          all?: boolean;
+          maxPages?: string;
+          delay?: string;
+          cursor?: string;
+          json?: boolean;
+          jsonFull?: boolean;
+        },
+      ) => {
+        const opts = program.opts();
+        const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+        const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+        const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+        const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
+        const pageDelayMs = Number.parseInt(cmdOpts.delay || '1000', 10);
 
-      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+        const usePagination = Boolean(cmdOpts.all || cmdOpts.cursor || maxPages !== undefined);
+        if (maxPages !== undefined && (!Number.isFinite(maxPages) || maxPages <= 0)) {
+          console.error(`${ctx.p('err')}Invalid --max-pages. Expected a positive integer.`);
+          process.exit(1);
+        }
+        if (!Number.isFinite(pageDelayMs) || pageDelayMs < 0) {
+          console.error(`${ctx.p('err')}Invalid --delay. Expected a non-negative integer.`);
+          process.exit(1);
+        }
 
-      for (const warning of warnings) {
+        const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
-        console.error(`${ctx.p('warn')}${warning}`);
-      }
 
-      if (!cookies.authToken || !cookies.ct0) {
+        for (const warning of warnings) {
-        console.error(`${ctx.p('err')}Missing required credentials`);
+          console.error(`${ctx.p('warn')}${warning}`);
-        process.exit(1);
+        }
-      }
 
-      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+        if (!cookies.authToken || !cookies.ct0) {
-      const includeRaw = cmdOpts.jsonFull ?? false;
+          console.error(`${ctx.p('err')}Missing required credentials`);
-      const result = await client.getReplies(tweetId, { includeRaw });
+          process.exit(1);
+        }
 
-      if (result.success && result.tweets) {
+        const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
-        ctx.printTweets(result.tweets, { json: cmdOpts.json || cmdOpts.jsonFull, emptyMessage: 'No replies found.' });
+        const includeRaw = cmdOpts.jsonFull ?? false;
-      } else {
+
-        console.error(`${ctx.p('err')}Failed to fetch replies: ${result.error}`);
+        const result = usePagination
-        process.exit(1);
+          ? await client.getRepliesPaged(tweetId, {
-      }
+              includeRaw,
-    });
+              maxPages,
+              cursor: cmdOpts.cursor,
+              pageDelayMs,
+            })
+          : await client.getReplies(tweetId, { includeRaw });
+
+        if (result.tweets) {
+          const isJson = Boolean(cmdOpts.json || cmdOpts.jsonFull);
+          ctx.printTweetsResult(result, { json: isJson, usePagination, emptyMessage: 'No replies found.' });
+
+          // Show pagination hint if there's more
+          if (result.nextCursor && !isJson) {
+            console.error(`${ctx.p('info')}More replies available. Use --cursor "${result.nextCursor}" to continue.`);
+          }
+
+          if (!result.success) {
+            console.error(`${ctx.p('err')}Failed to fetch replies: ${result.error}`);
+            process.exit(1);
+          }
+        } 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('--all', 'Fetch all thread tweets (paged)')
+    .option('--max-pages <number>', 'Fetch N pages (implies pagination)')
+    .option('--delay <ms>', 'Delay in ms between page fetches', '1000')
+    .option('--cursor <string>', 'Resume pagination from a cursor')
     .option('--json', 'Output as JSON')
     .option('--json-full', 'Output as JSON with full raw API response in _raw field')
-    .action(async (tweetIdOrUrl: string, cmdOpts: { json?: boolean; jsonFull?: boolean }) => {
+    .action(
-      const opts = program.opts();
+      async (
-      const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+        tweetIdOrUrl: string,
-      const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+        cmdOpts: {
-      const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+          all?: boolean;
+          maxPages?: string;
+          delay?: string;
+          cursor?: string;
+          json?: boolean;
+          jsonFull?: boolean;
+        },
+      ) => {
+        const opts = program.opts();
+        const timeoutMs = ctx.resolveTimeoutFromOptions(opts);
+        const quoteDepth = ctx.resolveQuoteDepthFromOptions(opts);
+        const tweetId = ctx.extractTweetId(tweetIdOrUrl);
+        const maxPages = cmdOpts.maxPages ? Number.parseInt(cmdOpts.maxPages, 10) : undefined;
+        const pageDelayMs = Number.parseInt(cmdOpts.delay || '1000', 10);
 
-      const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
+        const usePagination = Boolean(cmdOpts.all || cmdOpts.cursor || maxPages !== undefined);
+        if (maxPages !== undefined && (!Number.isFinite(maxPages) || maxPages <= 0)) {
+          console.error(`${ctx.p('err')}Invalid --max-pages. Expected a positive integer.`);
+          process.exit(1);
+        }
+        if (!Number.isFinite(pageDelayMs) || pageDelayMs < 0) {
+          console.error(`${ctx.p('err')}Invalid --delay. Expected a non-negative integer.`);
+          process.exit(1);
+        }
 
-      for (const warning of warnings) {
+        const { cookies, warnings } = await ctx.resolveCredentialsFromOptions(opts);
-        console.error(`${ctx.p('warn')}${warning}`);
-      }
 
-      if (!cookies.authToken || !cookies.ct0) {
+        for (const warning of warnings) {
-        console.error(`${ctx.p('err')}Missing required credentials`);
+          console.error(`${ctx.p('warn')}${warning}`);
-        process.exit(1);
+        }
-      }
 
-      const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
+        if (!cookies.authToken || !cookies.ct0) {
-      const includeRaw = cmdOpts.jsonFull ?? false;
+          console.error(`${ctx.p('err')}Missing required credentials`);
-      const result = await client.getThread(tweetId, { includeRaw });
+          process.exit(1);
+        }
 
-      if (result.success && result.tweets) {
+        const client = new TwitterClient({ cookies, timeoutMs, quoteDepth });
-        ctx.printTweets(result.tweets, {
+        const includeRaw = cmdOpts.jsonFull ?? false;
-          json: cmdOpts.json || cmdOpts.jsonFull,
+
-          emptyMessage: 'No thread tweets found.',
+        const result = usePagination
-        });
+          ? await client.getThreadPaged(tweetId, {
-      } else {
+              includeRaw,
-        console.error(`${ctx.p('err')}Failed to fetch thread: ${result.error}`);
+              maxPages,
-        process.exit(1);
+              cursor: cmdOpts.cursor,
-      }
+              pageDelayMs,
-    });
+            })
+          : await client.getThread(tweetId, { includeRaw });
+
+        if (result.tweets) {
+          const isJson = Boolean(cmdOpts.json || cmdOpts.jsonFull);
+          ctx.printTweetsResult(result, { json: isJson, usePagination, emptyMessage: 'No thread tweets found.' });
+
+          // Show pagination hint if there's more
+          if (result.nextCursor && !isJson) {
+            console.error(
+              `${ctx.p('info')}More thread tweets available. Use --cursor "${result.nextCursor}" to continue.`,
+            );
+          }
+
+          if (!result.success) {
+            console.error(`${ctx.p('err')}Failed to fetch thread: ${result.error}`);
+            process.exit(1);
+          }
+        } else {
+          console.error(`${ctx.p('err')}Failed to fetch thread: ${result.error}`);
+          process.exit(1);
+        }
+      },
+    );
 }

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

@@ -1,9 +1,10 @@
 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 type { GetTweetResult, GraphqlTweetResult, SearchResult, TweetData } from './twitter-client-types.js';
 import {
   extractArticleText,
+  extractCursorFromInstructions,
   findTweetInInstructions,
   firstText,
   mapTweetResult,
@@ -16,10 +17,22 @@ export interface TweetFetchOptions {
   includeRaw?: boolean;
 }
 
+/** Options for paginated tweet detail fetch */
+export interface TweetDetailPaginationOptions extends TweetFetchOptions {
+  /** Maximum number of pages to fetch (default: unlimited when using pagination) */
+  maxPages?: number;
+  /** Starting cursor for pagination (resume from previous fetch) */
+  cursor?: string;
+  /** Delay in milliseconds between page fetches (default: 1000) */
+  pageDelayMs?: number;
+}
+
 export interface TwitterClientTweetDetailMethods {
   getTweet(tweetId: string, options?: TweetFetchOptions): Promise<GetTweetResult>;
   getReplies(tweetId: string, options?: TweetFetchOptions): Promise<SearchResult>;
   getThread(tweetId: string, options?: TweetFetchOptions): Promise<SearchResult>;
+  getRepliesPaged(tweetId: string, options?: TweetDetailPaginationOptions): Promise<SearchResult>;
+  getThreadPaged(tweetId: string, options?: TweetDetailPaginationOptions): Promise<SearchResult>;
 }
 
 export function withTweetDetails<TBase extends AbstractConstructor<TwitterClientBase>>(
@@ -110,7 +123,14 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
       return {};
     }
 
-    private async fetchTweetDetail(tweetId: string): Promise<
+    private async sleep(ms: number): Promise<void> {
+      return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+
+    private async fetchTweetDetail(
+      tweetId: string,
+      cursor?: string,
+    ): Promise<
       | {
           success: true;
           data: {
@@ -141,6 +161,7 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
         withQuickPromoteEligibilityTweetFields: true,
         withBirdwatchNotes: true,
         withVoice: true,
+        ...(cursor ? { cursor } : {}),
       };
 
       const features = {
@@ -340,6 +361,135 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
 
       return { success: true, tweets: thread };
     }
+
+    /**
+     * Get replies to a tweet with pagination support
+     */
+    async getRepliesPaged(tweetId: string, options: TweetDetailPaginationOptions = {}): Promise<SearchResult> {
+      const { includeRaw = false, maxPages, pageDelayMs = 1000 } = options;
+      const seen = new Set<string>();
+      const allReplies: TweetData[] = [];
+      let cursor: string | undefined = options.cursor;
+      let nextCursor: string | undefined;
+      let pagesFetched = 0;
+
+      while (true) {
+        // Add delay between pages (but not before the first page)
+        if (pagesFetched > 0 && pageDelayMs > 0) {
+          await this.sleep(pageDelayMs);
+        }
+
+        const response = await this.fetchTweetDetail(tweetId, cursor);
+        if (!response.success) {
+          // If we have some replies already, return them with the error
+          if (allReplies.length > 0) {
+            return { success: false, tweets: allReplies, nextCursor: cursor, error: response.error };
+          }
+          return response;
+        }
+        pagesFetched += 1;
+
+        const instructions = response.data.threaded_conversation_with_injections_v2?.instructions;
+        const tweets = parseTweetsFromInstructions(instructions, { quoteDepth: this.quoteDepth, includeRaw });
+        const replies = tweets.filter((tweet) => tweet.inReplyToStatusId === tweetId);
+
+        for (const reply of replies) {
+          if (seen.has(reply.id)) {
+            continue;
+          }
+          seen.add(reply.id);
+          allReplies.push(reply);
+        }
+
+        const pageCursor = extractCursorFromInstructions(instructions);
+        if (!pageCursor || pageCursor === cursor) {
+          nextCursor = undefined;
+          break;
+        }
+
+        if (maxPages && pagesFetched >= maxPages) {
+          nextCursor = pageCursor;
+          break;
+        }
+
+        cursor = pageCursor;
+        nextCursor = pageCursor;
+      }
+
+      return { success: true, tweets: allReplies, nextCursor };
+    }
+
+    /**
+     * Get full conversation thread with pagination support
+     */
+    async getThreadPaged(tweetId: string, options: TweetDetailPaginationOptions = {}): Promise<SearchResult> {
+      const { includeRaw = false, maxPages, pageDelayMs = 1000 } = options;
+      const seen = new Set<string>();
+      const allTweets: TweetData[] = [];
+      let cursor: string | undefined = options.cursor;
+      let nextCursor: string | undefined;
+      let pagesFetched = 0;
+      let rootId: string | undefined;
+
+      while (true) {
+        // Add delay between pages (but not before the first page)
+        if (pagesFetched > 0 && pageDelayMs > 0) {
+          await this.sleep(pageDelayMs);
+        }
+
+        const response = await this.fetchTweetDetail(tweetId, cursor);
+        if (!response.success) {
+          // If we have some tweets already, return them with the error
+          if (allTweets.length > 0) {
+            return { success: false, tweets: allTweets, nextCursor: cursor, error: response.error };
+          }
+          return response;
+        }
+        pagesFetched += 1;
+
+        const instructions = response.data.threaded_conversation_with_injections_v2?.instructions;
+        const tweets = parseTweetsFromInstructions(instructions, { quoteDepth: this.quoteDepth, includeRaw });
+
+        // Determine root conversation ID from first page
+        if (!rootId) {
+          const target = tweets.find((t) => t.id === tweetId);
+          rootId = target?.conversationId || tweetId;
+        }
+
+        const threadTweets = tweets.filter((tweet) => tweet.conversationId === rootId);
+
+        for (const tweet of threadTweets) {
+          if (seen.has(tweet.id)) {
+            continue;
+          }
+          seen.add(tweet.id);
+          allTweets.push(tweet);
+        }
+
+        const pageCursor = extractCursorFromInstructions(instructions);
+        if (!pageCursor || pageCursor === cursor) {
+          nextCursor = undefined;
+          break;
+        }
+
+        if (maxPages && pagesFetched >= maxPages) {
+          nextCursor = pageCursor;
+          break;
+        }
+
+        cursor = pageCursor;
+        nextCursor = pageCursor;
+      }
+
+      // Sort by creation time
+      allTweets.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: allTweets, nextCursor };
+    }
   }
 
   return TwitterClientTweetDetails;

tests/commands.read.test.ts

@@ -0,0 +1,155 @@
+import { Command } from 'commander';
+import { describe, expect, it, vi } from 'vitest';
+import type { CliContext } from '../src/cli/shared.js';
+import { registerReadCommands } from '../src/commands/read.js';
+import { TwitterClient } from '../src/lib/twitter-client.js';
+
+describe('replies command', () => {
+  const createMockContext = () =>
+    ({
+      resolveTimeoutFromOptions: () => undefined,
+      resolveQuoteDepthFromOptions: () => 1,
+      extractTweetId: (input: string) => input,
+      resolveCredentialsFromOptions: async () => ({
+        cookies: { authToken: 'auth', ct0: 'ct0', cookieHeader: 'auth=auth; ct0=ct0' },
+        warnings: [],
+      }),
+      p: () => '',
+      printTweets: () => undefined,
+      printTweetsResult: () => undefined,
+    }) as unknown as CliContext;
+
+  it('uses pagination when --max-pages is provided', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const pagedSpy = vi
+      .spyOn(TwitterClient.prototype, 'getRepliesPaged')
+      .mockResolvedValue({ success: true, tweets: [], nextCursor: undefined });
+    const unpagedSpy = vi.spyOn(TwitterClient.prototype, 'getReplies').mockResolvedValue({ success: true, tweets: [] });
+
+    try {
+      await program.parseAsync(['node', 'bird', 'replies', '123', '--max-pages', '2', '--json']);
+      expect(pagedSpy).toHaveBeenCalledTimes(1);
+      expect(unpagedSpy).toHaveBeenCalledTimes(0);
+    } finally {
+      pagedSpy.mockRestore();
+      unpagedSpy.mockRestore();
+    }
+  });
+
+  it('validates --max-pages is a positive integer', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit ${code}`);
+    }) as never);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    try {
+      await expect(
+        program.parseAsync(['node', 'bird', 'replies', '123', '--all', '--max-pages', '-1']),
+      ).rejects.toThrow('exit 1');
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid --max-pages'));
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it('validates --delay is a non-negative integer', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit ${code}`);
+    }) as never);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    try {
+      await expect(program.parseAsync(['node', 'bird', 'replies', '123', '--all', '--delay', '-100'])).rejects.toThrow(
+        'exit 1',
+      );
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid --delay'));
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+});
+
+describe('thread command', () => {
+  const createMockContext = () =>
+    ({
+      resolveTimeoutFromOptions: () => undefined,
+      resolveQuoteDepthFromOptions: () => 1,
+      extractTweetId: (input: string) => input,
+      resolveCredentialsFromOptions: async () => ({
+        cookies: { authToken: 'auth', ct0: 'ct0', cookieHeader: 'auth=auth; ct0=ct0' },
+        warnings: [],
+      }),
+      p: () => '',
+      printTweets: () => undefined,
+      printTweetsResult: () => undefined,
+    }) as unknown as CliContext;
+
+  it('uses pagination when --max-pages is provided', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const pagedSpy = vi
+      .spyOn(TwitterClient.prototype, 'getThreadPaged')
+      .mockResolvedValue({ success: true, tweets: [], nextCursor: undefined });
+    const unpagedSpy = vi.spyOn(TwitterClient.prototype, 'getThread').mockResolvedValue({ success: true, tweets: [] });
+
+    try {
+      await program.parseAsync(['node', 'bird', 'thread', '123', '--max-pages', '2', '--json']);
+      expect(pagedSpy).toHaveBeenCalledTimes(1);
+      expect(unpagedSpy).toHaveBeenCalledTimes(0);
+    } finally {
+      pagedSpy.mockRestore();
+      unpagedSpy.mockRestore();
+    }
+  });
+
+  it('validates --max-pages is a positive integer', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit ${code}`);
+    }) as never);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    try {
+      await expect(program.parseAsync(['node', 'bird', 'thread', '123', '--all', '--max-pages', '0'])).rejects.toThrow(
+        'exit 1',
+      );
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid --max-pages'));
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it('validates --delay is a non-negative integer', async () => {
+    const program = new Command();
+    registerReadCommands(program, createMockContext());
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit ${code}`);
+    }) as never);
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    try {
+      await expect(program.parseAsync(['node', 'bird', 'thread', '123', '--all', '--delay', 'abc'])).rejects.toThrow(
+        'exit 1',
+      );
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid --delay'));
+    } finally {
+      exitSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+});

tests/twitter-client.pagination.test.ts

@@ -0,0 +1,424 @@
+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 pagination for thread and replies', () => {
+  let mockFetch: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    mockFetch = vi.fn();
+    global.fetch = mockFetch as unknown as typeof fetch;
+  });
+
+  const makeConversationPayload = (tweetIds: string[], cursor?: string, inReplyTo?: string, conversationId = '1') => ({
+    data: {
+      threaded_conversation_with_injections_v2: {
+        instructions: [
+          {
+            type: 'TimelineAddEntries',
+            entries: [
+              ...tweetIds.map((id, i) => ({
+                entryId: `tweet-${id}`,
+                content: {
+                  itemContent: {
+                    tweet_results: {
+                      result: {
+                        rest_id: id,
+                        legacy: {
+                          full_text: `tweet ${id}`,
+                          created_at: `2024-01-0${i + 1}T00:00:00Z`,
+                          reply_count: 0,
+                          retweet_count: 0,
+                          favorite_count: 0,
+                          conversation_id_str: conversationId,
+                          ...(inReplyTo ? { in_reply_to_status_id_str: inReplyTo } : {}),
+                        },
+                        core: {
+                          user_results: { result: { legacy: { screen_name: `user${id}`, name: `User ${id}` } } },
+                        },
+                      },
+                    },
+                  },
+                },
+              })),
+              // Add cursor entry if provided
+              ...(cursor
+                ? [
+                    {
+                      entryId: `cursor-bottom-${Date.now()}`,
+                      content: {
+                        cursorType: 'Bottom',
+                        value: cursor,
+                      },
+                    },
+                  ]
+                : []),
+            ],
+          },
+        ],
+      },
+    },
+  });
+
+  describe('getRepliesPaged', () => {
+    it('returns replies from single page when no cursor in response', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => makeConversationPayload(['2', '3'], undefined, '1'),
+      });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1');
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(2);
+      expect(result.nextCursor).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    it('fetches multiple pages when cursor is present and --all is used', async () => {
+      // First page returns cursor, second page does not
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['2', '3'], 'cursor-page-2', '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['4', '5'], undefined, '1'),
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(4);
+      expect(result.tweets?.map((t) => t.id)).toEqual(['2', '3', '4', '5']);
+      expect(result.nextCursor).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('respects maxPages option', async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['2', '3'], 'cursor-page-2', '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['4', '5'], 'cursor-page-3', '1'),
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { maxPages: 2, pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(4);
+      expect(result.nextCursor).toBe('cursor-page-3');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('resumes from provided cursor', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => makeConversationPayload(['4', '5'], undefined, '1'),
+      });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { cursor: 'resume-cursor', pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(2);
+      // Verify cursor was passed in the request
+      const url = mockFetch.mock.calls[0][0] as string;
+      expect(url).toContain('resume-cursor');
+    });
+
+    it('deduplicates tweets across pages', async () => {
+      // Second page returns a duplicate tweet
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['2', '3'], 'cursor-page-2', '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['3', '4'], undefined, '1'), // '3' is duplicate
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(3); // 2, 3, 4 (no duplicate)
+      expect(result.tweets?.map((t) => t.id)).toEqual(['2', '3', '4']);
+    });
+
+    it('returns partial results on error after first page', async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['2', '3'], 'cursor-page-2', '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: false,
+          status: 500,
+          text: async () => 'Internal Server Error',
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { pageDelayMs: 0 });
+
+      expect(result.success).toBe(false);
+      expect(result.tweets?.length).toBe(2);
+      expect(result.error).toContain('500');
+      expect(result.nextCursor).toBe('cursor-page-2');
+    });
+
+    it('continues pagination even when a page contains no replies', async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['2'], 'cursor-page-2', '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['10'], 'cursor-page-3', undefined),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['3'], undefined, '1'),
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getRepliesPaged('1', { pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.map((t) => t.id)).toEqual(['2', '3']);
+      expect(result.nextCursor).toBeUndefined();
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe('getThreadPaged', () => {
+    it('returns thread tweets from single page', async () => {
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => makeConversationPayload(['1', '2', '3'], undefined, undefined, '1'),
+      });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getThreadPaged('1');
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(3);
+      expect(result.nextCursor).toBeUndefined();
+    });
+
+    it('fetches multiple pages for thread', async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['1', '2'], 'cursor-page-2', undefined, '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['3', '4'], undefined, undefined, '1'),
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getThreadPaged('1', { pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(4);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('sorts thread tweets by creation time', async () => {
+      // Return tweets in non-chronological order
+      const payload = {
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                type: 'TimelineAddEntries',
+                entries: [
+                  {
+                    entryId: 'tweet-3',
+                    content: {
+                      itemContent: {
+                        tweet_results: {
+                          result: {
+                            rest_id: '3',
+                            legacy: {
+                              full_text: 'tweet 3',
+                              created_at: '2024-01-03T00:00:00Z',
+                              reply_count: 0,
+                              retweet_count: 0,
+                              favorite_count: 0,
+                              conversation_id_str: '1',
+                            },
+                            core: { user_results: { result: { legacy: { screen_name: 'user3', name: 'User 3' } } } },
+                          },
+                        },
+                      },
+                    },
+                  },
+                  {
+                    entryId: 'tweet-1',
+                    content: {
+                      itemContent: {
+                        tweet_results: {
+                          result: {
+                            rest_id: '1',
+                            legacy: {
+                              full_text: 'tweet 1',
+                              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: 'user1', name: 'User 1' } } } },
+                          },
+                        },
+                      },
+                    },
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => payload,
+      });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getThreadPaged('1');
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.map((t) => t.id)).toEqual(['1', '3']); // Sorted by date
+    });
+
+    it('filters by conversation ID', async () => {
+      // Include a tweet from a different conversation
+      const payload = {
+        data: {
+          threaded_conversation_with_injections_v2: {
+            instructions: [
+              {
+                type: 'TimelineAddEntries',
+                entries: [
+                  {
+                    entryId: 'tweet-1',
+                    content: {
+                      itemContent: {
+                        tweet_results: {
+                          result: {
+                            rest_id: '1',
+                            legacy: {
+                              full_text: 'tweet 1',
+                              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: 'user1', name: 'User 1' } } } },
+                          },
+                        },
+                      },
+                    },
+                  },
+                  {
+                    entryId: 'tweet-99',
+                    content: {
+                      itemContent: {
+                        tweet_results: {
+                          result: {
+                            rest_id: '99',
+                            legacy: {
+                              full_text: 'different conversation',
+                              created_at: '2024-01-02T00:00:00Z',
+                              reply_count: 0,
+                              retweet_count: 0,
+                              favorite_count: 0,
+                              conversation_id_str: '99', // Different conversation
+                            },
+                            core: { user_results: { result: { legacy: { screen_name: 'user99', name: 'User 99' } } } },
+                          },
+                        },
+                      },
+                    },
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      };
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => payload,
+      });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getThreadPaged('1');
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(1);
+      expect(result.tweets?.[0].id).toBe('1');
+    });
+
+    it('respects maxPages for thread', async () => {
+      mockFetch
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['1', '2'], 'cursor-page-2', undefined, '1'),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          status: 200,
+          json: async () => makeConversationPayload(['3', '4'], 'cursor-page-3', undefined, '1'),
+        });
+
+      const client = new TwitterClient({ cookies: validCookies });
+      const result = await client.getThreadPaged('1', { maxPages: 2, pageDelayMs: 0 });
+
+      expect(result.success).toBe(true);
+      expect(result.tweets?.length).toBe(4);
+      expect(result.nextCursor).toBe('cursor-page-3');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+});