refactor: unify pagination helpers

src/lib/paginate-cursor.ts

@@ -0,0 +1,73 @@
+export type CursorPage<T> =
+  | {
+      success: true;
+      items: T[];
+      cursor?: string;
+    }
+  | {
+      success: false;
+      error: string;
+    };
+
+export type CursorPaginationResult<T> =
+  | {
+      success: true;
+      items: T[];
+      nextCursor?: string;
+    }
+  | {
+      success: false;
+      error: string;
+      items?: T[];
+      nextCursor?: string;
+    };
+
+export async function paginateCursor<T>(opts: {
+  cursor?: string;
+  maxPages?: number;
+  pageDelayMs?: number;
+  sleep: (ms: number) => Promise<void>;
+  getKey: (item: T) => string;
+  fetchPage: (cursor?: string) => Promise<CursorPage<T>>;
+}): Promise<CursorPaginationResult<T>> {
+  const { maxPages, pageDelayMs = 1000 } = opts;
+  const seen = new Set<string>();
+  const items: T[] = [];
+  let cursor: string | undefined = opts.cursor;
+  let pagesFetched = 0;
+
+  while (true) {
+    if (pagesFetched > 0 && pageDelayMs > 0) {
+      await opts.sleep(pageDelayMs);
+    }
+
+    const page = await opts.fetchPage(cursor);
+    if (!page.success) {
+      if (items.length > 0) {
+        return { success: false, error: page.error, items, nextCursor: cursor };
+      }
+      return page;
+    }
+    pagesFetched += 1;
+
+    for (const item of page.items) {
+      const key = opts.getKey(item);
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      items.push(item);
+    }
+
+    const pageCursor = page.cursor;
+    if (!pageCursor || pageCursor === cursor) {
+      return { success: true, items, nextCursor: undefined };
+    }
+
+    if (maxPages !== undefined && pagesFetched >= maxPages) {
+      return { success: true, items, nextCursor: pageCursor };
+    }
+
+    cursor = pageCursor;
+  }
+}

src/lib/twitter-client-base.ts

@@ -41,6 +41,10 @@ export abstract class TwitterClientBase {
 
   protected abstract getCurrentUser(): Promise<CurrentUserResult>;
 
+  protected async sleep(ms: number): Promise<void> {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
   protected async getQueryId(operationName: OperationName): Promise<string> {
     const cached = await runtimeQueryIds.getQueryId(operationName);
     return cached ?? QUERY_IDS[operationName];

src/lib/twitter-client-media.ts

@@ -28,10 +28,6 @@ export function withMedia<TBase extends AbstractConstructor<TwitterClientBase>>(
       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) {

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

@@ -1,3 +1,4 @@
+import { paginateCursor } from './paginate-cursor.js';
 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';
@@ -123,10 +124,6 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
       return {};
     }
 
-    private async sleep(ms: number): Promise<void> {
-      return new Promise((resolve) => setTimeout(resolve, ms));
-    }
-
     private async fetchTweetDetail(
       tweetId: string,
       cursor?: string,
@@ -367,56 +364,37 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
      */
     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 };
+      const result = await paginateCursor<TweetData>({
+        cursor: options.cursor,
+        maxPages,
+        pageDelayMs,
+        sleep: async (ms) => this.sleep(ms),
+        getKey: (tweet) => tweet.id,
+        fetchPage: async (cursor) => {
+          const response = await this.fetchTweetDetail(tweetId, cursor);
+          if (!response.success) {
+            return response;
           }
-          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);
+          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);
+          const pageCursor = extractCursorFromInstructions(instructions);
 
-        for (const reply of replies) {
-          if (seen.has(reply.id)) {
-            continue;
-          }
-          seen.add(reply.id);
-          allReplies.push(reply);
-        }
+          return { success: true as const, items: replies, cursor: pageCursor };
+        },
+      });
 
-        const pageCursor = extractCursorFromInstructions(instructions);
-        if (!pageCursor || pageCursor === cursor) {
-          nextCursor = undefined;
-          break;
-        }
-
-        if (maxPages && pagesFetched >= maxPages) {
-          nextCursor = pageCursor;
-          break;
-        }
-
-        cursor = pageCursor;
-        nextCursor = pageCursor;
+      if (result.success) {
+        return { success: true, tweets: result.items, nextCursor: result.nextCursor };
       }
 
-      return { success: true, tweets: allReplies, nextCursor };
+      if (result.items) {
+        return { success: false, tweets: result.items, nextCursor: result.nextCursor, error: result.error };
+      }
+
+      return { success: false, error: result.error };
     }
 
     /**
@@ -424,71 +402,50 @@ export function withTweetDetails<TBase extends AbstractConstructor<TwitterClient
      */
     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 };
+      const result = await paginateCursor<TweetData>({
+        cursor: options.cursor,
+        maxPages,
+        pageDelayMs,
+        sleep: async (ms) => this.sleep(ms),
+        getKey: (tweet) => tweet.id,
+        fetchPage: async (cursor) => {
+          const response = await this.fetchTweetDetail(tweetId, cursor);
+          if (!response.success) {
+            return response;
           }
-          return response;
-        }
-        pagesFetched += 1;
 
-        const instructions = response.data.threaded_conversation_with_injections_v2?.instructions;
-        const tweets = parseTweetsFromInstructions(instructions, { quoteDepth: this.quoteDepth, includeRaw });
+          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;
+          if (!rootId) {
+            const target = tweets.find((t) => t.id === tweetId);
+            rootId = target?.conversationId || tweetId;
           }
-          seen.add(tweet.id);
-          allTweets.push(tweet);
-        }
 
-        const pageCursor = extractCursorFromInstructions(instructions);
-        if (!pageCursor || pageCursor === cursor) {
-          nextCursor = undefined;
-          break;
-        }
+          const threadTweets = tweets.filter((tweet) => tweet.conversationId === rootId);
+          const pageCursor = extractCursorFromInstructions(instructions);
 
-        if (maxPages && pagesFetched >= maxPages) {
-          nextCursor = pageCursor;
-          break;
-        }
+          return { success: true as const, items: threadTweets, cursor: pageCursor };
+        },
+      });
 
-        cursor = pageCursor;
-        nextCursor = pageCursor;
-      }
-
-      // Sort by creation time
-      allTweets.sort((a, b) => {
+      const sortedTweets = (result.items ?? []).slice().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 };
+      if (result.success) {
+        return { success: true, tweets: sortedTweets, nextCursor: result.nextCursor };
+      }
+
+      if (result.items) {
+        return { success: false, tweets: sortedTweets, nextCursor: result.nextCursor, error: result.error };
+      }
+
+      return { success: false, error: result.error };
     }
   }
 

src/lib/twitter-client-types.ts

@@ -253,13 +253,20 @@ export interface GetTweetResult {
   error?: string;
 }
 
-export interface SearchResult {
-  success: boolean;
-  tweets?: TweetData[];
-  error?: string;
-  /** Cursor for fetching the next page of results */
-  nextCursor?: string;
-}
+export type SearchResult =
+  | {
+      success: true;
+      tweets: TweetData[];
+      /** Cursor for fetching the next page of results */
+      nextCursor?: string;
+    }
+  | {
+      success: false;
+      error: string;
+      tweets?: TweetData[];
+      /** Cursor for fetching the next page of results */
+      nextCursor?: string;
+    };
 
 export interface CurrentUserResult {
   success: boolean;

src/lib/twitter-client-user-tweets.ts

@@ -40,10 +40,6 @@ export function withUserTweets<TBase extends AbstractConstructor<TwitterClientBa
       return Array.from(new Set([primary, 'Wms1GvIiHXAPBaCr9KblaA']));
     }
 
-    private async sleep(ms: number): Promise<void> {
-      await new Promise((resolve) => setTimeout(resolve, ms));
-    }
-
     /**
      * Get tweets from a user's profile timeline (single page).
      */