@jackwener/opencli 1.7.18 → 1.7.20

package/clis/reddit/whoami.js

@@ -0,0 +1,84 @@
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+    site: 'reddit',
+    name: 'whoami',
+    access: 'read',
+    description: 'Show the currently logged-in Reddit user',
+    domain: 'reddit.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    siteSession: 'persistent',
+    args: [],
+    columns: ['field', 'value'],
+    func: async (page) => {
+        await page.goto('https://www.reddit.com');
+        // Probe identity via /api/me.json. Reddit returns 200 with an empty
+        // body for stale anonymous sessions, so 401/403 alone is not a
+        // sufficient logged-out signal — we also verify `data.name` exists
+        // (two-pronged auth detection from PR #1428).
+        //
+        // Intermediate object keys deliberately avoid `field` / `value` to
+        // sidestep the silent-column-drop audit (columns are ['field',
+        // 'value']) — see PR #1329 sediment "中间解析对象 key 不能跟 columns
+        // 任一项重叠".
+        const result = await page.evaluate(`(async () => {
+      try {
+        const res = await fetch('/api/me.json?raw_json=1', { credentials: 'include' });
+        if (res.status === 401 || res.status === 403) {
+          return { kind: 'auth', detail: 'Reddit /api/me.json returned HTTP ' + res.status };
+        }
+        if (!res.ok) {
+          return { kind: 'http', httpStatus: res.status, where: '/api/me.json' };
+        }
+        const d = await res.json();
+        const me = d?.data;
+        if (!me?.name) {
+          return { kind: 'auth', detail: 'Not logged in to reddit.com (no identity in /api/me.json)' };
+        }
+        return { kind: 'ok', identity: me };
+      } catch (e) {
+        return { kind: 'exception', detail: String(e && e.message || e) };
+      }
+    })()`);
+
+        if (result?.kind === 'auth') {
+            throw new AuthRequiredError('reddit.com', result.detail);
+        }
+        if (result?.kind === 'http') {
+            throw new CommandExecutionError(`HTTP ${result.httpStatus} from ${result.where}`);
+        }
+        if (result?.kind === 'exception') {
+            throw new CommandExecutionError(`whoami failed: ${result.detail}`);
+        }
+        if (result?.kind !== 'ok') {
+            throw new CommandExecutionError(`Unexpected result from reddit whoami: ${JSON.stringify(result)}`);
+        }
+
+        const u = result.identity;
+        const created = u.created_utc
+            ? new Date(u.created_utc * 1000).toISOString().split('T')[0]
+            : null;
+        const linkKarma = typeof u.link_karma === 'number' ? u.link_karma : null;
+        const commentKarma = typeof u.comment_karma === 'number' ? u.comment_karma : null;
+        const totalKarma = typeof u.total_karma === 'number'
+            ? u.total_karma
+            : (linkKarma != null && commentKarma != null ? linkKarma + commentKarma : null);
+        const inboxCount = typeof u.inbox_count === 'number' ? u.inbox_count : null;
+
+        return [
+            { field: 'Username', value: 'u/' + u.name },
+            { field: 'ID', value: u.id ? 't2_' + u.id : null },
+            { field: 'Post Karma', value: linkKarma != null ? String(linkKarma) : null },
+            { field: 'Comment Karma', value: commentKarma != null ? String(commentKarma) : null },
+            { field: 'Total Karma', value: totalKarma != null ? String(totalKarma) : null },
+            { field: 'Account Created', value: created },
+            { field: 'Gold', value: u.is_gold ? 'Yes' : 'No' },
+            { field: 'Mod', value: u.is_mod ? 'Yes' : 'No' },
+            { field: 'Verified Email', value: u.has_verified_email ? 'Yes' : 'No' },
+            { field: 'Has Mail', value: u.has_mail ? 'Yes' : 'No' },
+            { field: 'Inbox Count', value: inboxCount != null ? String(inboxCount) : null },
+        ];
+    },
+});

package/clis/reddit/whoami.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import './whoami.js';
+
+function makePage(result) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(result),
+    };
+}
+
+describe('reddit whoami command', () => {
+    const command = getRegistry().get('reddit/whoami');
+
+    it('registers with the expected shape', () => {
+        expect(command).toBeDefined();
+        expect(command.access).toBe('read');
+        expect(command.browser).toBe(true);
+        expect(command.columns).toEqual(['field', 'value']);
+        expect(command.args).toEqual([]);
+    });
+
+    it('throws AuthRequiredError on 401/403 from /api/me.json', async () => {
+        const page = makePage({ kind: 'auth', detail: 'Reddit /api/me.json returned HTTP 401' });
+        await expect(command.func(page, {})).rejects.toBeInstanceOf(AuthRequiredError);
+        expect(page.goto).toHaveBeenCalledWith('https://www.reddit.com');
+    });
+
+    it('throws AuthRequiredError on 200 with missing data.name (stale anon session)', async () => {
+        const page = makePage({ kind: 'auth', detail: 'Not logged in to reddit.com (no identity in /api/me.json)' });
+        await expect(command.func(page, {})).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('throws CommandExecutionError on HTTP / exception failure modes', async () => {
+        await expect(command.func(makePage({ kind: 'http', httpStatus: 500, where: '/api/me.json' }), {}))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(command.func(makePage({ kind: 'exception', detail: 'bad json' }), {}))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('maps a full identity payload into the field/value rows', async () => {
+        const identity = {
+            name: 'alice',
+            id: 'abcdef',
+            link_karma: 1234,
+            comment_karma: 5678,
+            total_karma: 6912,
+            created_utc: 1577836800, // 2020-01-01
+            is_gold: true,
+            is_mod: false,
+            has_verified_email: true,
+            has_mail: false,
+            inbox_count: 0,
+        };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField.Username).toBe('u/alice');
+        expect(byField.ID).toBe('t2_abcdef');
+        expect(byField['Post Karma']).toBe('1234');
+        expect(byField['Comment Karma']).toBe('5678');
+        expect(byField['Total Karma']).toBe('6912');
+        expect(byField['Account Created']).toBe('2020-01-01');
+        expect(byField.Gold).toBe('Yes');
+        expect(byField.Mod).toBe('No');
+        expect(byField['Verified Email']).toBe('Yes');
+        expect(byField['Has Mail']).toBe('No');
+        expect(byField['Inbox Count']).toBe('0');
+
+        // Row shape must match the declared columns exactly so the
+        // silent-column-drop audit can't be triggered.
+        for (const row of rows) {
+            expect(Object.keys(row).sort()).toEqual(['field', 'value']);
+        }
+    });
+
+    it('falls back to null for missing numeric karma fields rather than 0 sentinels', async () => {
+        const identity = {
+            name: 'bob',
+            id: 'xyz',
+            created_utc: null,
+            is_gold: false,
+            is_mod: false,
+            has_verified_email: false,
+            has_mail: false,
+        };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+        const byField = Object.fromEntries(rows.map((r) => [r.field, r.value]));
+        expect(byField['Post Karma']).toBeNull();
+        expect(byField['Comment Karma']).toBeNull();
+        expect(byField['Total Karma']).toBeNull();
+        expect(byField['Account Created']).toBeNull();
+        expect(byField['Inbox Count']).toBeNull();
+    });
+
+    it('does not throw on `data.name` present even if optional booleans are missing', async () => {
+        const identity = { name: 'carol', id: 'i1' };
+        const page = makePage({ kind: 'ok', identity });
+        const rows = await command.func(page, {});
+        expect(rows[0]).toEqual({ field: 'Username', value: 'u/carol' });
+    });
+});

package/clis/rednote/search.js

@@ -7,7 +7,7 @@
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { ArgumentError, AuthRequiredError } from '@jackwener/opencli/errors';
-import { buildSearchExtractJs, noteIdToDate } from '../xiaohongshu/search.js';
+import { buildScrollUntilJs, buildSearchExtractJs, noteIdToDate } from '../xiaohongshu/search.js';
 
 function parseLimit(raw) {
     const parsed = Number(raw);
@@ -82,7 +82,11 @@ cli({
         if (waitResult === 'login_wall') {
             throw new AuthRequiredError('www.rednote.com', 'Rednote search results are blocked behind a login wall');
         }
-        await page.autoScroll({ times: 2 });
+        // Scroll until enough rows are rendered or the lazy-load plateaus.
+        // Same fix as xiaohongshu/search (#1471): the previous fixed
+        // `autoScroll({ times: 2 })` capped extraction at ~13 notes regardless
+        // of `--limit`.
+        await page.evaluate(buildScrollUntilJs(limit));
         const payload = await page.evaluate(buildSearchExtractJs('www.rednote.com'));
         const data = Array.isArray(payload) ? payload : [];
         return data

package/clis/twitter/bookmark-folder.js

@@ -1,7 +1,7 @@
 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';
+import { extractMedia, resolveTwitterQueryId } from './shared.js';
 
 // Companion to bookmark-folders.js: reads tweets inside a single folder.
 // X exposes folder contents through a separate timeline operation
@@ -11,6 +11,7 @@ import { resolveTwitterQueryId } from './shared.js';
 const OPERATION_NAME = 'BookmarkFolderTimeline';
 const FALLBACK_QUERY_ID = '13H7EUATwethsj_jZ6QQAQ';
 const FOLDER_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const MAX_PAGINATION_PAGES = 100;
 
 const FEATURES = {
     rweb_video_screen_enabled: false,
@@ -53,7 +54,7 @@ function buildFolderTimelineUrl(queryId, folderId, count, cursor) {
         + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
 }
 
-function extractFolderTweet(result, seen) {
+export function extractFolderTweet(result, seen) {
     if (!result) return null;
     const tw = result.tweet || result;
     const legacy = tw.legacy || {};
@@ -71,6 +72,7 @@ function extractFolderTweet(result, seen) {
         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}`,
+        ...extractMedia(legacy),
     };
 }
 
@@ -128,7 +130,7 @@ cli({
         { 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'],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'bookmarks', 'created_at', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         const folderId = String(kwargs['folder-id'] || '').trim();
         if (!folderId || !FOLDER_ID_PATTERN.test(folderId)) {
@@ -158,7 +160,8 @@ cli({
         const allTweets = [];
         const seen = new Set();
         let cursor = null;
-        for (let i = 0; i < 5 && allTweets.length < limit; i++) {
+        // Runaway guard only; --limit and cursor exhaustion control normal pagination.
+        for (let i = 0; i < MAX_PAGINATION_PAGES && 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 () => {
@@ -182,6 +185,7 @@ cli({
 
 export const __test__ = {
     parseBookmarkFolderTimeline,
+    extractFolderTweet,
     buildFolderTimelineUrl,
     FOLDER_ID_PATTERN,
 };

package/clis/twitter/bookmark-folder.test.js

@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';
 import { getRegistry } from '@jackwener/opencli/registry';
 import { __test__ } from './bookmark-folder.js';
 
-const { parseBookmarkFolderTimeline, buildFolderTimelineUrl, FOLDER_ID_PATTERN } = __test__;
+const { parseBookmarkFolderTimeline, extractFolderTweet, buildFolderTimelineUrl, FOLDER_ID_PATTERN } = __test__;
 
 describe('twitter bookmark-folder URL builder', () => {
     it('embeds the folder id and count in the variables payload', () => {
@@ -97,6 +97,8 @@ describe('twitter bookmark-folder timeline parser', () => {
                 bookmarks: 3,
                 created_at: 'Tue Mar 17 09:00:00 +0000 2026',
                 url: 'https://x.com/alice/status/1',
+                has_media: false,
+                media_urls: [],
             },
         ]);
         expect(nextCursor).toBe('NEXT_CURSOR');
@@ -247,6 +249,62 @@ describe('twitter bookmark-folder timeline parser', () => {
     it('returns empty array + null cursor for unknown envelope', () => {
         expect(parseBookmarkFolderTimeline({}, new Set())).toEqual({ tweets: [], nextCursor: null });
     });
+
+    it('includes photo media URLs from extended_entities', () => {
+        const tweet = extractFolderTweet({
+            rest_id: '101',
+            legacy: {
+                full_text: 'pic folder tweet',
+                extended_entities: {
+                    media: [
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/abc.jpg' },
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/def.jpg' },
+                    ],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'eve' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls).toEqual([
+            'https://pbs.twimg.com/media/abc.jpg',
+            'https://pbs.twimg.com/media/def.jpg',
+        ]);
+    });
+
+    it('extracts mp4 variant URL for video media', () => {
+        const tweet = extractFolderTweet({
+            rest_id: '102',
+            legacy: {
+                full_text: 'video folder tweet',
+                extended_entities: {
+                    media: [{
+                        type: 'video',
+                        media_url_https: 'https://pbs.twimg.com/amplify_video_thumb/thumb.jpg',
+                        video_info: {
+                            variants: [
+                                { content_type: 'application/x-mpegURL', url: 'https://video.twimg.com/playlist.m3u8' },
+                                { content_type: 'video/mp4', bitrate: 832000, url: 'https://video.twimg.com/low.mp4' },
+                                { content_type: 'video/mp4', bitrate: 2176000, url: 'https://video.twimg.com/high.mp4' },
+                            ],
+                        },
+                    }],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'frank' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls?.[0]).toMatch(/\.mp4$/);
+    });
+
+    it('returns has_media false / media_urls empty when no media present', () => {
+        const tweet = extractFolderTweet({
+            rest_id: '103',
+            legacy: { full_text: 'text only', favorite_count: 0, retweet_count: 0, bookmark_count: 0 },
+            core: { user_results: { result: { legacy: { screen_name: 'gail' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(false);
+        expect(tweet?.media_urls).toEqual([]);
+    });
 });
 
 describe('twitter bookmark-folder id validation', () => {

package/clis/twitter/bookmarks.js

@@ -1,7 +1,9 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { extractMedia } from './shared.js';
 import { TWITTER_BEARER_TOKEN, applyTopByEngagement } from './utils.js';
 const BOOKMARKS_QUERY_ID = 'Fy0QMy4q_aZCpkO0PnyLYw';
+const MAX_PAGINATION_PAGES = 100;
 const FEATURES = {
     rweb_video_screen_enabled: false,
     profile_label_improvements_pcf_label_in_post_enabled: true,
@@ -41,7 +43,7 @@ function buildBookmarksUrl(count, cursor) {
         + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
         + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
 }
-function extractBookmarkTweet(result, seen) {
+export function extractBookmarkTweet(result, seen) {
     if (!result)
         return null;
     const tw = result.tweet || result;
@@ -63,9 +65,10 @@ function extractBookmarkTweet(result, seen) {
         bookmarks: legacy.bookmark_count || 0,
         created_at: legacy.created_at || '',
         url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+        ...extractMedia(legacy),
     };
 }
-function parseBookmarks(data, seen) {
+export function parseBookmarks(data, seen) {
     const tweets = [];
     let nextCursor = null;
     const instructions = data?.data?.bookmark_timeline_v2?.timeline?.instructions
@@ -110,7 +113,7 @@ cli({
         { 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 bookmarks 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'],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'bookmarks', 'created_at', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 20;
         const cookies = await page.getCookies({ url: 'https://x.com' });
@@ -150,7 +153,8 @@ cli({
         const allTweets = [];
         const seen = new Set();
         let cursor = null;
-        for (let i = 0; i < 5 && allTweets.length < limit; i++) {
+        // Runaway guard only; --limit and cursor exhaustion control normal pagination.
+        for (let i = 0; i < MAX_PAGINATION_PAGES && allTweets.length < limit; i++) {
             const fetchCount = Math.min(100, limit - allTweets.length + 10);
             const apiUrl = buildBookmarksUrl(fetchCount, cursor).replace(BOOKMARKS_QUERY_ID, queryId);
             const data = await page.evaluate(`async () => {
@@ -172,3 +176,7 @@ cli({
         return applyTopByEngagement(trimmed, kwargs['top-by-engagement']);
     },
 });
+export const __test__ = {
+    parseBookmarks,
+    extractBookmarkTweet,
+};

package/clis/twitter/bookmarks.test.js

@@ -0,0 +1,205 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './bookmarks.js';
+
+const { parseBookmarks, extractBookmarkTweet } = __test__;
+
+describe('twitter bookmarks parser', () => {
+    it('extracts a baseline tweet with no media (has_media false, media_urls empty)', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '1',
+            legacy: {
+                full_text: 'plain bookmark',
+                favorite_count: 5,
+                retweet_count: 1,
+                bookmark_count: 2,
+                created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'alice', name: 'Alice' } } } },
+        }, new Set());
+        expect(tweet).toEqual({
+            id: '1',
+            author: 'alice',
+            name: 'Alice',
+            text: 'plain bookmark',
+            likes: 5,
+            retweets: 1,
+            bookmarks: 2,
+            created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            url: 'https://x.com/alice/status/1',
+            has_media: false,
+            media_urls: [],
+        });
+    });
+
+    it('includes photo media URLs from extended_entities', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '101',
+            legacy: {
+                full_text: 'pic bookmark',
+                extended_entities: {
+                    media: [
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/abc.jpg' },
+                        { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/def.jpg' },
+                    ],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'bob' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls).toEqual([
+            'https://pbs.twimg.com/media/abc.jpg',
+            'https://pbs.twimg.com/media/def.jpg',
+        ]);
+    });
+
+    it('extracts mp4 variant URL for video media', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '102',
+            legacy: {
+                full_text: 'video bookmark',
+                extended_entities: {
+                    media: [{
+                        type: 'video',
+                        media_url_https: 'https://pbs.twimg.com/amplify_video_thumb/thumb.jpg',
+                        video_info: {
+                            variants: [
+                                { content_type: 'application/x-mpegURL', url: 'https://video.twimg.com/playlist.m3u8' },
+                                { content_type: 'video/mp4', bitrate: 832000, url: 'https://video.twimg.com/low.mp4' },
+                                { content_type: 'video/mp4', bitrate: 2176000, url: 'https://video.twimg.com/high.mp4' },
+                            ],
+                        },
+                    }],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'carol' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls?.[0]).toMatch(/\.mp4$/);
+    });
+
+    it('falls back to entities.media when extended_entities is absent', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '103',
+            legacy: {
+                full_text: 'entities-only media',
+                entities: {
+                    media: [{ type: 'photo', media_url_https: 'https://pbs.twimg.com/media/legacy.jpg' }],
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'dave' } } } },
+        }, new Set());
+        expect(tweet?.has_media).toBe(true);
+        expect(tweet?.media_urls).toEqual(['https://pbs.twimg.com/media/legacy.jpg']);
+    });
+
+    it('prefers note_tweet text over truncated full_text', () => {
+        const tweet = extractBookmarkTweet({
+            rest_id: '2',
+            legacy: { full_text: 'short text…', favorite_count: 0, retweet_count: 0, bookmark_count: 0 },
+            note_tweet: { note_tweet_results: { result: { text: 'full long-form text body' } } },
+            core: { user_results: { result: { core: { screen_name: 'erin' } } } },
+        }, new Set());
+        expect(tweet?.text).toBe('full long-form text body');
+    });
+
+    it('deduplicates tweets across the seen Set', () => {
+        const data = {
+            data: {
+                bookmark_timeline_v2: {
+                    timeline: {
+                        instructions: [{
+                            entries: [
+                                {
+                                    entryId: 'tweet-3',
+                                    content: {
+                                        itemContent: {
+                                            tweet_results: {
+                                                result: {
+                                                    rest_id: '3',
+                                                    legacy: { full_text: 'first', favorite_count: 0, retweet_count: 0, bookmark_count: 0 },
+                                                    core: { user_results: { result: { legacy: { screen_name: 'frank' } } } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                                {
+                                    entryId: 'tweet-3-dup',
+                                    content: {
+                                        itemContent: {
+                                            tweet_results: {
+                                                result: {
+                                                    rest_id: '3',
+                                                    legacy: { full_text: 'duplicate' },
+                                                    core: { user_results: { result: { legacy: { screen_name: 'frank' } } } },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            ],
+                        }],
+                    },
+                },
+            },
+        };
+        const seen = new Set();
+        const { tweets } = parseBookmarks(data, seen);
+        expect(tweets).toHaveLength(1);
+        expect(tweets[0].text).toBe('first');
+    });
+
+    it('extracts cursor + tweets from the bookmark_timeline_v2 envelope', () => {
+        const data = {
+            data: {
+                bookmark_timeline_v2: {
+                    timeline: {
+                        instructions: [
+                            {
+                                type: 'TimelineAddEntries',
+                                entries: [
+                                    {
+                                        entryId: 'tweet-4',
+                                        content: {
+                                            itemContent: {
+                                                tweet_results: {
+                                                    result: {
+                                                        rest_id: '4',
+                                                        legacy: {
+                                                            full_text: 'envelope tweet',
+                                                            favorite_count: 1,
+                                                            retweet_count: 0,
+                                                            bookmark_count: 0,
+                                                            extended_entities: {
+                                                                media: [{ type: 'photo', media_url_https: 'https://pbs.twimg.com/media/x.jpg' }],
+                                                            },
+                                                        },
+                                                        core: { user_results: { result: { legacy: { screen_name: 'gina' } } } },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                    {
+                                        entryId: 'cursor-bottom-Y',
+                                        content: { __typename: 'TimelineTimelineCursor', cursorType: 'Bottom', value: 'NEXT' },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                },
+            },
+        };
+        const { tweets, nextCursor } = parseBookmarks(data, new Set());
+        expect(tweets).toHaveLength(1);
+        expect(tweets[0].id).toBe('4');
+        expect(tweets[0].has_media).toBe(true);
+        expect(tweets[0].media_urls).toEqual(['https://pbs.twimg.com/media/x.jpg']);
+        expect(nextCursor).toBe('NEXT');
+    });
+
+    it('returns empty tweets + null cursor for unknown envelope', () => {
+        expect(parseBookmarks({}, new Set())).toEqual({ tweets: [], nextCursor: null });
+    });
+});