@jackwener/opencli 1.7.14 → 1.7.16

package/clis/openreview/openreview.test.js

@@ -8,11 +8,13 @@ import {
     requireBoundedInt,
     requireForumId,
     requireNonNegativeInt,
+    requireProfileId,
 } from './utils.js';
 import './search.js';
 import './venue.js';
 import './paper.js';
 import './reviews.js';
+import './author.js';
 
 const SAMPLE_NOTE = {
     id: 'abc123XYZ_',
@@ -37,21 +39,24 @@ afterEach(() => {
 });
 
 describe('openreview adapter', () => {
-    it('registers all four commands with the expected columns', () => {
+    it('registers all five commands with the expected columns', () => {
         const search = getRegistry().get('openreview/search');
         const venue = getRegistry().get('openreview/venue');
         const paper = getRegistry().get('openreview/paper');
         const reviews = getRegistry().get('openreview/reviews');
+        const author = getRegistry().get('openreview/author');
 
         expect(search).toBeDefined();
         expect(venue).toBeDefined();
         expect(paper).toBeDefined();
         expect(reviews).toBeDefined();
+        expect(author).toBeDefined();
 
         expect(search.columns).toEqual(['rank', 'id', 'title', 'authors', 'venue', 'pdate', 'url']);
         expect(venue.columns).toEqual(['rank', 'id', 'title', 'authors', 'keywords', 'primary_area', 'pdate', 'pdf', 'url']);
         expect(paper.columns).toEqual(['id', 'title', 'authors', 'keywords', 'venue', 'venueid', 'primary_area', 'abstract', 'pdate', 'pdf', 'url']);
         expect(reviews.columns).toEqual(['type', 'author', 'rating', 'confidence', 'text']);
+        expect(author.columns).toEqual(['rank', 'id', 'title', 'authors', 'venue', 'pdate', 'url']);
     });
 
     it('noteToRow extracts every wrapped v2 field, joins lists, and builds absolute URLs', () => {
@@ -109,6 +114,30 @@ describe('openreview adapter', () => {
         expect(() => requireForumId('short')).toThrow('not a valid forum id');
     });
 
+    it('requireProfileId accepts canonical profile ids and rejects malformed input', () => {
+        expect(requireProfileId('~Yoshua_Bengio1')).toBe('~Yoshua_Bengio1');
+        expect(requireProfileId('~Bo_Liu17')).toBe('~Bo_Liu17');
+        expect(requireProfileId('~Geoffrey_Everest_Hinton1')).toBe('~Geoffrey_Everest_Hinton1');
+        expect(requireProfileId('~Anne-Christin_Hauschild1')).toBe('~Anne-Christin_Hauschild1');
+        expect(requireProfileId('~S.Aruna_Deepthi1')).toBe('~S.Aruna_Deepthi1');
+        expect(requireProfileId('~Andrzej_Czyżewski1')).toBe('~Andrzej_Czyżewski1');
+        expect(requireProfileId('~August_Bøgh_Rønberg1')).toBe('~August_Bøgh_Rønberg1');
+        expect(requireProfileId('~Wagner_Meira_Jr.1')).toBe('~Wagner_Meira_Jr.1');
+        expect(() => requireProfileId('')).toThrow('required');
+        expect(() => requireProfileId('   ')).toThrow('required');
+        // Missing leading tilde.
+        expect(() => requireProfileId('Bo_Liu17')).toThrow('not a valid profile id');
+        // Missing trailing disambiguator number.
+        expect(() => requireProfileId('~Bo_Liu')).toThrow('not a valid profile id');
+        // Spaces / non-letter characters break the underscore-joined name.
+        expect(() => requireProfileId('~Bo Liu1')).toThrow('not a valid profile id');
+        // dblp-style PID must not silently fall through.
+        expect(() => requireProfileId('56/953')).toThrow('not a valid profile id');
+        expect(() => requireProfileId('~Bo_Liu1?evil=1')).toThrow('not a valid profile id');
+        expect(() => requireProfileId('~Bo/Liu1')).toThrow('not a valid profile id');
+        expect(() => requireProfileId('~123')).toThrow('not a valid profile id');
+    });
+
     it('formatDate handles ms-since-epoch and rejects invalid input', () => {
         expect(formatDate(1727524853394)).toBe('2024-09-28');
         expect(formatDate(0)).toBe('');
@@ -342,4 +371,57 @@ describe('openreview adapter', () => {
         expect(rows[1].text.length).toBe(500);
         expect(rows[1].text.endsWith('...')).toBe(true);
     });
+
+    it('author rejects invalid profile ids before calling the network', async () => {
+        const fetchMock = vi.fn();
+        vi.stubGlobal('fetch', fetchMock);
+        const author = getRegistry().get('openreview/author');
+        await expect(author.func({ profile: 'Bo_Liu17', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+        await expect(author.func({ profile: '', limit: 5 })).rejects.toMatchObject({ code: 'ARGUMENT' });
+        expect(fetchMock).not.toHaveBeenCalled();
+    });
+
+    it('author throws EmptyResult when the profile has no submissions', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({ notes: [] }), { status: 200 })));
+        const author = getRegistry().get('openreview/author');
+        await expect(author.func({ profile: '~No_Submissions1', limit: 5 })).rejects.toMatchObject({ code: 'EMPTY_RESULT' });
+    });
+
+    it('author wraps non-200 responses as CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response('rate limited', { status: 429 })));
+        const author = getRegistry().get('openreview/author');
+        await expect(author.func({ profile: '~Bo_Liu17', limit: 5 })).rejects.toMatchObject({ code: 'COMMAND_EXEC' });
+    });
+
+    it('author wraps fetch network errors as CommandExecutionError', async () => {
+        vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNRESET')));
+        const author = getRegistry().get('openreview/author');
+        await expect(author.func({ profile: '~Bo_Liu17', limit: 5 })).rejects.toMatchObject({
+            code: 'COMMAND_EXEC',
+            message: expect.stringContaining('Network failure'),
+        });
+    });
+
+    it('author hits /notes?content.authorids and returns rank-ordered rows', async () => {
+        const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({ notes: [SAMPLE_NOTE, SAMPLE_NOTE] }), { status: 200 }));
+        vi.stubGlobal('fetch', fetchMock);
+        const author = getRegistry().get('openreview/author');
+        const rows = await author.func({ profile: '~Bo_Liu17', limit: 50 });
+        expect(rows).toHaveLength(2);
+        expect(rows[0]).toEqual({
+            rank: 1,
+            id: 'abc123XYZ_',
+            title: 'Test Paper Title with spaces',
+            authors: 'Alice Smith, Bob Jones',
+            venue: 'ICLR 2024 oral',
+            pdate: '2024-09-28',
+            url: 'https://openreview.net/forum?id=abc123XYZ_',
+        });
+        expect(rows[1].rank).toBe(2);
+        // Confirm the request shape: canonical authorids filter + cdate sort.
+        const url = fetchMock.mock.calls[0][0];
+        expect(url).toContain('content.authorids=');
+        expect(url).toContain(encodeURIComponent('~Bo_Liu17'));
+        expect(url).toContain('sort=cdate:desc');
+    });
 });

package/clis/openreview/utils.js

@@ -55,6 +55,20 @@ export function requireForumId(value, label = 'id') {
     return id;
 }
 
+/** OpenReview profile ids are `~...N` slugs and may include dots, hyphens, and Unicode letters. */
+const PROFILE_ID_PATTERN = /^~(?=.*\p{L})[\p{L}\p{M}0-9._-]+\d+$/u;
+
+export function requireProfileId(value, label = 'profile') {
+    const id = String(value ?? '').trim();
+    if (!id) {
+        throw new ArgumentError(`openreview ${label} is required`);
+    }
+    if (!PROFILE_ID_PATTERN.test(id)) {
+        throw new ArgumentError(`openreview ${label} "${value}" is not a valid profile id (expected "~First_Last1" or similar; find it on the author's openreview.net profile URL)`);
+    }
+    return id;
+}
+
 /** Wrap fetch + json with typed errors so failures never look like empty results. */
 export async function openreviewFetch(path, label) {
     const url = `${OPENREVIEW_API}${path}`;

package/clis/reddit/comment.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'post-id', type: 'string', required: true, positional: true, help: 'Post ID (e.g. 1abc123) or fullname (t3_xxx)' },
         { name: 'text', type: 'string', required: true, positional: true, help: 'Comment text' },

package/clis/reddit/frontpage.js

@@ -7,6 +7,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 15 },
     ],

package/clis/reddit/popular.js

@@ -7,6 +7,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 20 },
     ],

package/clis/reddit/read.js

@@ -15,6 +15,8 @@ cli({
     description: 'Read a Reddit post and its comments',
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'post-id', required: true, positional: true, help: 'Post ID (e.g. 1abc123) or full URL' },
         { name: 'sort', default: 'best', help: 'Comment sort: best, top, new, controversial, old, qa' },

package/clis/reddit/read.test.js

@@ -3,6 +3,10 @@ import { getRegistry } from '@jackwener/opencli/registry';
 import './read.js';
 describe('reddit read adapter', () => {
     const command = getRegistry().get('reddit/read');
+    it('opts into the Reddit site browser session lease', () => {
+        expect(command?.browser).toBe(true);
+        expect(command?.browserSession).toEqual({ reuse: 'site' });
+    });
     it('returns threaded rows from the browser-evaluated payload', async () => {
         const page = {
             goto: vi.fn().mockResolvedValue(undefined),

package/clis/reddit/save.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'post-id', type: 'string', required: true, positional: true, help: 'Post ID (e.g. 1abc123) or fullname (t3_xxx)' },
         { name: 'undo', type: 'boolean', default: false, help: 'Unsave instead of save' },

package/clis/reddit/saved.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 15 },
     ],

package/clis/reddit/search.js

@@ -7,8 +7,9 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
-        { name: 'query', type: 'string', required: true, positional: true },
+        { name: 'query', type: 'string', required: true, positional: true, help: 'Reddit search query' },
         {
             name: 'subreddit',
             type: 'string',

package/clis/reddit/subreddit.js

@@ -7,8 +7,9 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
-        { name: 'name', type: 'string', required: true, positional: true },
+        { name: 'name', type: 'string', required: true, positional: true, help: 'Subreddit name (no `r/` prefix; e.g. `python`)' },
         {
             name: 'sort',
             type: 'string',

package/clis/reddit/subscribe.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'subreddit', type: 'string', required: true, positional: true, help: 'Subreddit name (e.g. python)' },
         { name: 'undo', type: 'boolean', default: false, help: 'Unsubscribe instead of subscribe' },

package/clis/reddit/upvote.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'post-id', type: 'string', required: true, positional: true, help: 'Post ID (e.g. 1abc123) or fullname (t3_xxx)' },
         { name: 'direction', type: 'string', default: 'up', help: 'Vote direction: up, down, none' },

package/clis/reddit/upvoted.js

@@ -8,6 +8,7 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'limit', type: 'int', default: 15 },
     ],

package/clis/reddit/user-comments.js

@@ -7,8 +7,9 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
-        { name: 'username', type: 'string', required: true, positional: true },
+        { name: 'username', type: 'string', required: true, positional: true, help: 'Reddit username (no `u/` prefix needed)' },
         { name: 'limit', type: 'int', default: 15 },
     ],
     columns: ['subreddit', 'score', 'body', 'url'],

package/clis/reddit/user-posts.js

@@ -7,8 +7,9 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
-        { name: 'username', type: 'string', required: true, positional: true },
+        { name: 'username', type: 'string', required: true, positional: true, help: 'Reddit username (no `u/` prefix needed)' },
         { name: 'limit', type: 'int', default: 15 },
     ],
     columns: ['title', 'subreddit', 'score', 'comments', 'url'],

package/clis/reddit/user.js

@@ -7,8 +7,9 @@ cli({
     domain: 'reddit.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
-        { name: 'username', type: 'string', required: true, positional: true },
+        { name: 'username', type: 'string', required: true, positional: true, help: 'Reddit username (no `u/` prefix needed)' },
     ],
     columns: ['field', 'value'],
     pipeline: [

package/clis/twitter/article.js

@@ -1,6 +1,7 @@
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { resolveTwitterQueryId } from './shared.js';
+import { TWITTER_BEARER_TOKEN } from './utils.js';
 const TWEET_RESULT_BY_REST_ID_QUERY_ID = '7xflPyRiUxGVbJd4uWmbfg';
 cli({
     site: 'twitter',
@@ -10,6 +11,7 @@ cli({
     domain: 'x.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    browserSession: { reuse: 'site' },
     args: [
         { name: 'tweet-id', type: 'string', positional: true, required: true, help: 'Tweet ID or URL containing the article' },
     ],
@@ -50,14 +52,18 @@ cli({
         // Navigate to the tweet page for cookie context
         await page.goto(`https://x.com/i/status/${tweetId}`);
         await page.wait(3);
+        // Read CSRF token directly from the cookie store via CDP — zero page.evaluate round-trip
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
+        if (!ct0)
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         const queryId = await resolveTwitterQueryId(page, 'TweetResultByRestId', TWEET_RESULT_BY_REST_ID_QUERY_ID);
         const result = await page.evaluate(`
       async () => {
         const tweetId = "${tweetId}";
-        const ct0 = document.cookie.split(';').map(c=>c.trim()).find(c=>c.startsWith('ct0='))?.split('=')[1];
-        if (!ct0) return {error: 'No ct0 cookie — not logged into x.com'};
+        const ct0 = ${JSON.stringify(ct0)};
 
-        const bearer = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+        const bearer = ${JSON.stringify(TWITTER_BEARER_TOKEN)};
         const headers = {
           'Authorization': 'Bearer ' + decodeURIComponent(bearer),
           'X-Csrf-Token': ct0,
@@ -155,8 +161,6 @@ cli({
       }
     `);
         if (result?.error) {
-            if (String(result.error).includes('No ct0 cookie'))
-                throw new AuthRequiredError('x.com', result.error);
             throw new CommandExecutionError(result.error + (result.hint ? ` (${result.hint})` : ''));
         }
         return result || [];

package/clis/twitter/bookmark-folder.js

@@ -0,0 +1,187 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
+import { resolveTwitterQueryId } from './shared.js';
+
+// Companion to bookmark-folders.js: reads tweets inside a single folder.
+// X exposes folder contents through a separate timeline operation
+// (BookmarkFolderTimeline). The shape is essentially the same as the
+// global bookmarks timeline (bookmark_timeline_v2.timeline.instructions),
+// just scoped to one folder via the bookmark_collection_id variable.
+const OPERATION_NAME = 'BookmarkFolderTimeline';
+const FALLBACK_QUERY_ID = '13H7EUATwethsj_jZ6QQAQ';
+const FOLDER_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+const FEATURES = {
+    rweb_video_screen_enabled: false,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: false,
+    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,
+    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,
+    content_disclosure_indicator_enabled: true,
+    content_disclosure_ai_generated_indicator_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,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+};
+
+function buildFolderTimelineUrl(queryId, folderId, count, cursor) {
+    const vars = {
+        bookmark_collection_id: String(folderId),
+        count,
+        includePromotedContent: false,
+    };
+    if (cursor) vars.cursor = cursor;
+    return `/i/api/graphql/${queryId}/${OPERATION_NAME}`
+        + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
+        + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
+}
+
+function extractFolderTweet(result, seen) {
+    if (!result) return null;
+    const tw = result.tweet || result;
+    const legacy = tw.legacy || {};
+    if (!tw.rest_id || seen.has(tw.rest_id)) return null;
+    seen.add(tw.rest_id);
+    const user = tw.core?.user_results?.result;
+    const screenName = user?.legacy?.screen_name || user?.core?.screen_name || '';
+    const noteText = tw.note_tweet?.note_tweet_results?.result?.text;
+    return {
+        id: tw.rest_id,
+        author: screenName,
+        text: noteText || legacy.full_text || '',
+        likes: legacy.favorite_count || 0,
+        retweets: legacy.retweet_count || 0,
+        bookmarks: legacy.bookmark_count || 0,
+        created_at: legacy.created_at || '',
+        url: screenName ? `https://x.com/${screenName}/status/${tw.rest_id}` : `https://x.com/i/status/${tw.rest_id}`,
+    };
+}
+
+/**
+ * Parse the bookmark-folder timeline payload. Same instruction-walking
+ * pattern as the global bookmarks timeline; X re-uses the
+ * `bookmark_timeline_v2` envelope for folder-scoped queries.
+ *
+ * Exported via __test__.
+ */
+export function parseBookmarkFolderTimeline(data, seen) {
+    const tweets = [];
+    let nextCursor = null;
+    const instructions = data?.data?.bookmark_collection_timeline?.timeline?.instructions
+        || data?.data?.bookmark_timeline_v2?.timeline?.instructions
+        || data?.data?.bookmark_timeline?.timeline?.instructions
+        || [];
+    for (const inst of instructions) {
+        for (const entry of inst.entries || []) {
+            const content = entry.content;
+            if (content?.entryType === 'TimelineTimelineCursor' || content?.__typename === 'TimelineTimelineCursor') {
+                if (content.cursorType === 'Bottom' || content.cursorType === 'ShowMore')
+                    nextCursor = content.value;
+                continue;
+            }
+            if (entry.entryId?.startsWith('cursor-bottom-') || entry.entryId?.startsWith('cursor-showMore-')) {
+                nextCursor = content?.value || content?.itemContent?.value || nextCursor;
+                continue;
+            }
+            const direct = extractFolderTweet(content?.itemContent?.tweet_results?.result, seen);
+            if (direct) {
+                tweets.push(direct);
+                continue;
+            }
+            for (const item of content?.items || []) {
+                const nested = extractFolderTweet(item.item?.itemContent?.tweet_results?.result, seen);
+                if (nested) tweets.push(nested);
+            }
+        }
+    }
+    return { tweets, nextCursor };
+}
+
+cli({
+    site: 'twitter',
+    name: 'bookmark-folder',
+    access: 'read',
+    description: 'Read the tweets inside a single Twitter/X bookmark folder. Get the folder id from `opencli twitter bookmark-folders`.',
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    args: [
+        { name: 'folder-id', positional: true, type: 'string', required: true, help: 'Folder id from `opencli twitter bookmark-folders`.' },
+        { name: 'limit', type: 'int', default: 20, help: 'Maximum number of bookmarks to return (default 20).' },
+        { name: 'top-by-engagement', type: 'int', default: 0, help: 'When set to N>0, re-rank the folder by weighted engagement (likes×1 + retweets×3 + replies×2 + bookmarks×5 + log10(views+1)×0.5) and return the top N. Default 0 keeps the API\'s native (saved-time) ordering.' },
+    ],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'bookmarks', 'created_at', 'url'],
+    func: async (page, kwargs) => {
+        const folderId = String(kwargs['folder-id'] || '').trim();
+        if (!folderId || !FOLDER_ID_PATTERN.test(folderId)) {
+            throw new ArgumentError(
+                `Invalid folder-id: ${JSON.stringify(kwargs['folder-id'])}. Expected a safe folder ID from \`opencli twitter bookmark-folders\`.`,
+            );
+        }
+        const limit = Number(kwargs.limit ?? 20);
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new ArgumentError(`Invalid --limit: ${JSON.stringify(kwargs.limit)}. Expected a positive integer.`);
+        }
+
+        const cookies = await page.getCookies({ url: 'https://x.com' });
+        const ct0 = cookies.find((c) => c.name === 'ct0')?.value || null;
+        if (!ct0)
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
+
+        const queryId = await resolveTwitterQueryId(page, OPERATION_NAME, FALLBACK_QUERY_ID);
+
+        const headers = JSON.stringify({
+            'Authorization': `Bearer ${decodeURIComponent(TWITTER_BEARER_TOKEN)}`,
+            'X-Csrf-Token': ct0,
+            'X-Twitter-Auth-Type': 'OAuth2Session',
+            'X-Twitter-Active-User': 'yes',
+        });
+
+        const allTweets = [];
+        const seen = new Set();
+        let cursor = null;
+        for (let i = 0; i < 5 && allTweets.length < limit; i++) {
+            const fetchCount = Math.min(100, limit - allTweets.length + 10);
+            const apiUrl = buildFolderTimelineUrl(queryId, folderId, fetchCount, cursor);
+            const data = await page.evaluate(`async () => {
+                const r = await fetch(${JSON.stringify(apiUrl)}, { headers: ${headers}, credentials: 'include' });
+                return r.ok ? await r.json() : { error: r.status };
+            }`);
+            if (data?.error) {
+                if (allTweets.length === 0)
+                    throw new CommandExecutionError(`HTTP ${data.error}: Failed to fetch folder ${folderId}. queryId may have expired, or the folder may not exist.`);
+                break;
+            }
+            const { tweets, nextCursor } = parseBookmarkFolderTimeline(data, seen);
+            allTweets.push(...tweets);
+            if (!nextCursor || nextCursor === cursor) break;
+            cursor = nextCursor;
+        }
+        const trimmed = allTweets.slice(0, limit);
+        return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
+    },
+});
+
+export const __test__ = {
+    parseBookmarkFolderTimeline,
+    buildFolderTimelineUrl,
+    FOLDER_ID_PATTERN,
+};