From f76595511647a5d2c2f9b6c6b078d8eebe6010f4 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 5 Jan 2026 00:34:07 +0100 Subject: [PATCH] fix: stabilize bookmark pagination cursors --- CHANGELOG.md | 1 + src/commands/bookmarks.ts | 11 ++-- src/lib/twitter-client-timelines.ts | 24 +++++--- tests/commands.bookmarks.test.ts | 4 +- tests/twitter-client.search-bookmarks.test.ts | 58 +++++++++++++++++++ 5 files changed, 82 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6efd8df..fa055c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ - Bookmark exports now support pagination (`--all`, `--max-pages`) with retries (#15) — thanks @Nano1337. - `lists` + `list-timeline` commands for Twitter Lists (#21) — thanks @harperreed - Tweet JSON output now includes media items (photos, videos, GIFs) (#14) — thanks @Hormold +- Bookmarks can resume pagination from a cursor (#26) — thanks @leonho ## 0.5.1 — 2026-01-01 ### Changed diff --git a/src/commands/bookmarks.ts b/src/commands/bookmarks.ts index 8a9bc20..ab55e27 100644 --- a/src/commands/bookmarks.ts +++ b/src/commands/bookmarks.ts @@ -40,11 +40,11 @@ export function registerBookmarksCommand(program: Command, ctx: CliContext): voi process.exit(1); } - if (maxPages !== undefined && !cmdOpts.all) { - console.error(`${ctx.p('err')}--max-pages requires --all.`); + const usePagination = cmdOpts.all || cmdOpts.cursor; + if (maxPages !== undefined && !usePagination) { + console.error(`${ctx.p('err')}--max-pages requires --all or --cursor.`); process.exit(1); } - const usePagination = cmdOpts.all || cmdOpts.cursor; if (!usePagination && (!Number.isFinite(count) || count <= 0)) { console.error(`${ctx.p('err')}Invalid --count. Expected a positive integer.`); process.exit(1); @@ -74,9 +74,8 @@ export function registerBookmarksCommand(program: Command, ctx: CliContext): voi if (result.success && result.tweets) { const emptyMessage = folderId ? 'No bookmarks found in folder.' : 'No bookmarks found.'; const isJson = cmdOpts.json || cmdOpts.jsonFull; - if (isJson && result.nextCursor) { - // Output with nextCursor for pagination - console.log(JSON.stringify({ tweets: result.tweets, nextCursor: result.nextCursor }, null, 2)); + if (isJson && usePagination) { + console.log(JSON.stringify({ tweets: result.tweets, nextCursor: result.nextCursor ?? null }, null, 2)); } else { ctx.printTweets(result.tweets, { json: isJson, emptyMessage }); } diff --git a/src/lib/twitter-client-timelines.ts b/src/lib/twitter-client-timelines.ts index 825f7d0..4786c6e 100644 --- a/src/lib/twitter-client-timelines.ts +++ b/src/lib/twitter-client-timelines.ts @@ -201,6 +201,7 @@ export function withTimelines(); const tweets: TweetData[] = []; let cursor: string | undefined = options.cursor; + let nextCursor: string | undefined; let pagesFetched = 0; const { includeRaw = false, maxPages } = options; @@ -339,17 +340,20 @@ export function withTimelines= maxPages) { - cursor = page.cursor; + nextCursor = pageCursor; break; } - cursor = page.cursor; + cursor = pageCursor; + nextCursor = pageCursor; } - return { success: true, tweets, nextCursor: cursor }; + return { success: true, tweets, nextCursor }; } private async getBookmarkFolderTimelinePaged( @@ -362,6 +366,7 @@ export function withTimelines(); const tweets: TweetData[] = []; let cursor: string | undefined = options.cursor; + let nextCursor: string | undefined; let pagesFetched = 0; const { includeRaw = false, maxPages } = options; @@ -516,17 +521,20 @@ export function withTimelines= maxPages) { - cursor = page.cursor; + nextCursor = pageCursor; break; } - cursor = page.cursor; + cursor = pageCursor; + nextCursor = pageCursor; } - return { success: true, tweets, nextCursor: cursor }; + return { success: true, tweets, nextCursor }; } private async fetchWithRetry(url: string, init: RequestInit): Promise { diff --git a/tests/commands.bookmarks.test.ts b/tests/commands.bookmarks.test.ts index 177edb1..37ac8e7 100644 --- a/tests/commands.bookmarks.test.ts +++ b/tests/commands.bookmarks.test.ts @@ -4,7 +4,7 @@ import type { CliContext } from '../src/cli/shared.js'; import { registerBookmarksCommand } from '../src/commands/bookmarks.js'; describe('bookmarks command', () => { - it('requires --all when --max-pages is provided', async () => { + it('requires --all or --cursor when --max-pages is provided', async () => { const program = new Command(); const ctx = { resolveTimeoutFromOptions: () => undefined, @@ -24,7 +24,7 @@ describe('bookmarks command', () => { try { await expect(program.parseAsync(['node', 'bird', 'bookmarks', '--max-pages', '2'])).rejects.toThrow('exit 1'); - expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--max-pages requires --all')); + expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('--max-pages requires --all or --cursor')); } finally { exitSpy.mockRestore(); errorSpy.mockRestore(); diff --git a/tests/twitter-client.search-bookmarks.test.ts b/tests/twitter-client.search-bookmarks.test.ts index 7f90ef2..197aa3a 100644 --- a/tests/twitter-client.search-bookmarks.test.ts +++ b/tests/twitter-client.search-bookmarks.test.ts @@ -630,9 +630,67 @@ describe('TwitterClient bookmarks', () => { expect(result.success).toBe(true); expect(result.tweets?.map((tweet) => tweet.id)).toEqual(['1']); + expect(result.nextCursor).toBe('cursor-1'); expect(mockFetch).toHaveBeenCalledTimes(1); }); + it('does not return a stale cursor when pagination ends', 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 page 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: { + rest_id: 'u1', + legacy: { screen_name: 'root', name: 'Root' }, + }, + }, + }, + }, + }, + }, + }, + }, + ], + }, + ], + }, + }, + }, + }), + }); + + const client = new TwitterClient({ cookies: validCookies }); + const result = await client.getAllBookmarks({ cursor: 'cursor-1' }); + + expect(result.success).toBe(true); + expect(result.nextCursor).toBeUndefined(); + expect(mockFetch).toHaveBeenCalledTimes(1); + const vars = JSON.parse(new URL(mockFetch.mock.calls[0][0] as string).searchParams.get('variables') as string); + expect(vars.cursor).toBe('cursor-1'); + }); + it('treats graphql errors as non-fatal when instructions are present', async () => { mockFetch.mockResolvedValueOnce({ ok: true,