@jackwener/opencli 1.7.4 → 1.7.5

package/clis/twitter/list-remove.js

@@ -0,0 +1,297 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { resolveTwitterQueryId } from './shared.js';
+import { parseListsManagement } from './lists.js';
+
+const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
+const LISTS_MANAGEMENT_QUERY_ID = '78UbkyXwXBD98IgUWXOy9g';
+
+const LISTS_MANAGEMENT_FEATURES = {
+    rweb_video_screen_enabled: false,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    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,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: true,
+    responsive_web_jetfuel_frame: false,
+    responsive_web_grok_share_attachment_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,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: false,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    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: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+};
+
+function buildUserByScreenNameUrl(queryId, screenName) {
+    const vars = JSON.stringify({ screen_name: screenName, withSafetyModeUserFields: true });
+    const feats = JSON.stringify({
+        hidden_profile_subscriptions_enabled: true,
+        rweb_tipjar_consumption_enabled: true,
+        responsive_web_graphql_exclude_directive_enabled: true,
+        verified_phone_label_enabled: false,
+        subscriptions_verification_info_is_identity_verified_enabled: true,
+        subscriptions_verification_info_verified_since_enabled: true,
+        highlights_tweets_tab_ui_enabled: true,
+        responsive_web_twitter_article_notes_tab_enabled: true,
+        subscriptions_feature_can_gift_premium: true,
+        creator_subscriptions_tweet_preview_api_enabled: true,
+        responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+        responsive_web_graphql_timeline_navigation_enabled: true,
+    });
+    return `/i/api/graphql/${queryId}/UserByScreenName`
+        + `?variables=${encodeURIComponent(vars)}`
+        + `&features=${encodeURIComponent(feats)}`;
+}
+
+export function interpretRemoveResponse(status, json) {
+    if (status === 200 && json && (json.id_str || json.id || json.slug)) return { ok: true };
+    if (json && Array.isArray(json.errors) && json.errors.length > 0) {
+        const err = json.errors[0];
+        return { ok: false, error: `${err.code ? '[' + err.code + '] ' : ''}${err.message || 'Unknown error'}` };
+    }
+    return { ok: false, error: `HTTP ${status}` };
+}
+
+cli({
+    site: 'twitter',
+    name: 'list-remove',
+    description: 'Remove a user from a Twitter/X list you own (toggles via UI; no-op if not currently a member)',
+    domain: 'x.com',
+    strategy: Strategy.UI,
+    browser: true,
+    args: [
+        { name: 'listId', positional: true, type: 'string', required: true },
+        { name: 'username', positional: true, type: 'string', required: true },
+    ],
+    columns: ['listId', 'username', 'userId', 'status', 'message'],
+    func: async (page, kwargs) => {
+        const listId = String(kwargs.listId || '').trim();
+        const username = String(kwargs.username || '').replace(/^@/, '').trim();
+        if (!listId || !/^\d+$/.test(listId)) {
+            throw new CommandExecutionError(`Invalid listId: ${JSON.stringify(kwargs.listId)}`);
+        }
+        if (!username) throw new CommandExecutionError('Username is required');
+
+        await page.goto('https://x.com');
+        await page.wait(3);
+        const ct0 = await page.evaluate(`() => {
+            return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
+        }`);
+        if (!ct0) throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
+
+        const userByScreenNameQueryId = await resolveTwitterQueryId(page, 'UserByScreenName', USER_BY_SCREEN_NAME_QUERY_ID);
+        const headers = JSON.stringify({
+            'Authorization': `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+            'X-Csrf-Token': ct0,
+            'X-Twitter-Auth-Type': 'OAuth2Session',
+            'X-Twitter-Active-User': 'yes',
+        });
+
+        const userLookupUrl = buildUserByScreenNameUrl(userByScreenNameQueryId, username);
+        const userId = await page.evaluate(`async () => {
+            const resp = await fetch(${JSON.stringify(userLookupUrl)}, { headers: ${headers}, credentials: 'include' });
+            if (!resp.ok) return null;
+            const d = await resp.json();
+            return d.data?.user?.result?.rest_id || null;
+        }`);
+        if (!userId) throw new CommandExecutionError(`Could not resolve user @${username}`);
+
+        // Resolve listId → name so we can match the dialog row.
+        const listsQueryId = await resolveTwitterQueryId(page, 'ListsManagementPageTimeline', LISTS_MANAGEMENT_QUERY_ID);
+        const listsUrl = `/i/api/graphql/${listsQueryId}/ListsManagementPageTimeline?features=${encodeURIComponent(JSON.stringify(LISTS_MANAGEMENT_FEATURES))}`;
+        const listsData = await page.evaluate(`async () => {
+            const r = await fetch(${JSON.stringify(listsUrl)}, { headers: ${headers}, credentials: 'include' });
+            if (!r.ok) return { __error: 'HTTP ' + r.status };
+            return await r.json();
+        }`);
+        if (listsData && listsData.__error) {
+            throw new CommandExecutionError(`Could not fetch lists: ${listsData.__error}`);
+        }
+        const parsedLists = parseListsManagement(listsData, new Set());
+        const targetList = parsedLists.find((l) => l.id === listId);
+        if (!targetList) {
+            throw new CommandExecutionError(`List ${listId} not found among your lists.`);
+        }
+        const targetName = targetList.name;
+
+        await page.goto(`https://x.com/${username}`);
+        await page.wait({ selector: '[data-testid="primaryColumn"]' });
+        const uiResult = await page.evaluate(`(async () => {
+            const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+            const findOne = (sel, root = document) => root.querySelector(sel);
+            const waitFor = async (fn, { timeoutMs = 8000, intervalMs = 200 } = {}) => {
+                const t0 = Date.now();
+                while (Date.now() - t0 < timeoutMs) { const v = fn(); if (v) return v; await sleep(intervalMs); }
+                return null;
+            };
+            try {
+                if (!window.__opencliListMutations) {
+                    window.__opencliListMutations = [];
+                    const origFetch = window.fetch.bind(window);
+                    window.fetch = async function(...args) {
+                        const url = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url) || '';
+                        const method = (args[1] && args[1].method) || 'GET';
+                        let resp;
+                        try { resp = await origFetch(...args); } catch (err) {
+                            if (/ListAddMember|ListRemoveMember|lists\\/members\\/(create|destroy)/.test(url)) {
+                                window.__opencliListMutations.push({ url, method, status: 0, error: String(err), ts: Date.now() });
+                            }
+                            throw err;
+                        }
+                        if (/ListAddMember|ListRemoveMember|lists\\/members\\/(create|destroy)/.test(url)) {
+                            window.__opencliListMutations.push({ url, method, status: resp.status, ts: Date.now() });
+                        }
+                        return resp;
+                    };
+                }
+                window.__opencliListMutations.length = 0;
+
+                const caret = await waitFor(() => findOne('[data-testid="userActions"]'));
+                if (!caret) return { ok: false, message: 'Could not find user actions (…) button' };
+                caret.click();
+                await sleep(600);
+                const menuItems = Array.from(document.querySelectorAll('[role="menuitem"]'));
+                const addToListItem = menuItems.find(el => /add\\/remove|从列表|列表|add to list|add or remove/i.test(el.innerText));
+                if (!addToListItem) return { ok: false, message: 'Could not find "Add/remove from Lists" menu item' };
+                addToListItem.click();
+                await sleep(1200);
+                const dialog = await waitFor(() => findOne('[role="dialog"]'));
+                if (!dialog) return { ok: false, message: 'List selection dialog did not open' };
+
+                const targetName = ${JSON.stringify(targetName)};
+                const scrollCandidates = [
+                    dialog.querySelector('[data-viewportview="true"]'),
+                    ...Array.from(dialog.querySelectorAll('div')).filter(d => d.scrollHeight > d.clientHeight + 10),
+                ].filter(Boolean);
+                let scrollEl = scrollCandidates[0] || dialog;
+                for (const se of scrollCandidates) {
+                    if (se.scrollHeight > se.clientHeight + 10) { scrollEl = se; break; }
+                }
+                let row = null;
+                let lastScrollTop = -1;
+                for (let i = 0; i < 12; i++) {
+                    const cells = Array.from(dialog.querySelectorAll('[data-testid="cellInnerDiv"]'));
+                    row = cells.find(c => (c.innerText || '').split('\\n')[0].trim() === targetName);
+                    if (row) break;
+                    const prev = scrollEl.scrollTop;
+                    scrollEl.scrollTop = prev + Math.max(200, scrollEl.clientHeight - 100);
+                    if (scrollEl.scrollTop === prev && scrollEl.scrollTop === lastScrollTop) break;
+                    lastScrollTop = scrollEl.scrollTop;
+                    await sleep(500);
+                }
+                if (!row) {
+                    const names = Array.from(dialog.querySelectorAll('[data-testid="cellInnerDiv"]'))
+                        .map(c => (c.innerText || '').split('\\n')[0].trim()).filter(Boolean);
+                    return { ok: false, message: 'List "' + targetName + '" not found in dialog. Saw: ' + names.join(' | ') };
+                }
+
+                // Determine current membership: row has a filled checkmark (svg inside a specific container) when member.
+                // Heuristic: look for an aria-checked attribute, or an svg with specific fill on the row's right side.
+                // The listCell itself carries aria-checked. Require a stable reading
+                // (same value twice ~500ms apart) to avoid the X dialog's occasional
+                // flash of stale state when re-opened shortly after a toggle.
+                const listCell = row.querySelector('[data-testid="listCell"]') || row.querySelector('[role="checkbox"]') || row;
+                const readChecked = () => {
+                    const v = listCell.getAttribute('aria-checked');
+                    return v === 'true' || v === 'false' ? v : null;
+                };
+                await sleep(600);
+                let ariaChecked = readChecked();
+                for (let i = 0; i < 8; i++) {
+                    await sleep(500);
+                    const next = readChecked();
+                    if (next && next === ariaChecked) break;
+                    ariaChecked = next || ariaChecked;
+                }
+                const isMember = ariaChecked === 'true';
+                if (!isMember) {
+                    const closeBtn = findOne('[data-testid="app-bar-close"]') || findOne('[aria-label="Close"]');
+                    if (closeBtn) closeBtn.click();
+                    return { ok: true, noop: true };
+                }
+                try { listCell.scrollIntoView({ block: 'center' }); } catch {}
+                await sleep(400);
+                const rowRect = listCell.getBoundingClientRect();
+                const saveButton = Array.from(dialog.querySelectorAll('[role="button"], button')).find(b => {
+                    const txt = (b.innerText || '').trim();
+                    return /^(Save|Done|保存|完成|儲存)$/i.test(txt);
+                });
+                const saveRect = saveButton ? saveButton.getBoundingClientRect() : null;
+                return {
+                    ok: true,
+                    needsNativeInteraction: true,
+                    rowClickX: Math.round(rowRect.left + rowRect.width / 2),
+                    rowClickY: Math.round(rowRect.top + rowRect.height / 2),
+                    saveClickX: saveRect ? Math.round(saveRect.left + saveRect.width / 2) : null,
+                    saveClickY: saveRect ? Math.round(saveRect.top + saveRect.height / 2) : null,
+                    mutationsBefore: window.__opencliListMutations.length,
+                };
+            } catch (e) {
+                return { ok: false, message: 'UI error: ' + (e?.message || String(e)) };
+            }
+        })()`);
+
+        if (!uiResult.ok) {
+            throw new CommandExecutionError(`Failed to remove @${username} from list ${listId}: ${uiResult.message}`);
+        }
+
+        let verifiedBy = null;
+        if (uiResult.needsNativeInteraction) {
+            if (typeof page.nativeClick !== 'function') {
+                throw new CommandExecutionError('Requires up-to-date Chrome extension (nativeClick).');
+            }
+            if (!uiResult.saveClickX) {
+                throw new CommandExecutionError('Save button not found in dialog.');
+            }
+            const memberCountBefore = Number(targetList.members) || 0;
+            await page.nativeClick(uiResult.rowClickX, uiResult.rowClickY);
+            await new Promise((r) => setTimeout(r, 800));
+            await page.nativeClick(uiResult.saveClickX, uiResult.saveClickY);
+            await new Promise((r) => setTimeout(r, 3500));
+            const listsAfter = await page.evaluate(`async () => {
+                const r = await fetch(${JSON.stringify(listsUrl)}, { headers: ${headers}, credentials: 'include' });
+                if (!r.ok) return { __error: 'HTTP ' + r.status };
+                return await r.json();
+            }`);
+            const parsedAfter = listsAfter && !listsAfter.__error
+                ? parseListsManagement(listsAfter, new Set())
+                : [];
+            const afterList = parsedAfter.find((l) => l.id === listId);
+            const memberCountAfter = afterList ? Number(afterList.members) || 0 : -1;
+            if (memberCountAfter < memberCountBefore) {
+                verifiedBy = `member_count ${memberCountBefore} → ${memberCountAfter}`;
+            } else {
+                throw new CommandExecutionError(`Failed to remove @${username} from list ${listId}: member_count unchanged (${memberCountBefore} → ${memberCountAfter}).`);
+            }
+        }
+
+        return [{
+            listId,
+            username,
+            userId: String(userId),
+            status: uiResult.noop ? 'noop' : 'success',
+            message: uiResult.noop
+                ? `@${username} was not a member of list ${listId}`
+                : `Removed @${username} from list ${listId} (verified via ${verifiedBy})`,
+        }];
+    },
+});

package/clis/twitter/list-remove.test.js

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './list-remove.js';
+
+describe('twitter list-remove registration', () => {
+    it('registers the list-remove command with the expected shape', () => {
+        const cmd = getRegistry().get('twitter/list-remove');
+        expect(cmd?.func).toBeTypeOf('function');
+        expect(cmd?.columns).toEqual(['listId', 'username', 'userId', 'status', 'message']);
+        const listIdArg = cmd?.args?.find((a) => a.name === 'listId');
+        expect(listIdArg).toBeTruthy();
+        expect(listIdArg?.required).toBe(true);
+    });
+});

package/clis/twitter/list-tweets.js

@@ -0,0 +1,185 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+
+const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+const LIST_TWEETS_QUERY_ID = 'RlZzktZY_9wJynoepm8ZsA';
+const OPERATION_NAME = 'ListLatestTweetsTimeline';
+
+const FEATURES = {
+    rweb_video_screen_enabled: false,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    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,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: true,
+    responsive_web_jetfuel_frame: false,
+    responsive_web_grok_share_attachment_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,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: false,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    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: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+};
+
+function buildUrl(queryId, listId, count, cursor) {
+    const vars = { listId: String(listId), count };
+    if (cursor)
+        vars.cursor = cursor;
+    return `/i/api/graphql/${queryId}/${OPERATION_NAME}`
+        + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
+        + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
+}
+
+export function extractTimelineTweet(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 || 'unknown';
+    const displayName = user?.legacy?.name || user?.core?.name || '';
+    const noteText = tw.note_tweet?.note_tweet_results?.result?.text;
+    return {
+        id: tw.rest_id,
+        author: screenName,
+        name: displayName,
+        text: noteText || legacy.full_text || '',
+        likes: legacy.favorite_count || 0,
+        retweets: legacy.retweet_count || 0,
+        replies: legacy.reply_count || 0,
+        created_at: legacy.created_at || '',
+        url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+    };
+}
+
+export function parseListTimeline(data, seen) {
+    const tweets = [];
+    let nextCursor = null;
+    const instructions = data?.data?.list?.tweets_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 = extractTimelineTweet(content?.itemContent?.tweet_results?.result, seen);
+            if (direct) {
+                tweets.push(direct);
+                continue;
+            }
+            for (const item of content?.items || []) {
+                const nested = extractTimelineTweet(item.item?.itemContent?.tweet_results?.result, seen);
+                if (nested)
+                    tweets.push(nested);
+            }
+        }
+    }
+    return { tweets, nextCursor };
+}
+
+cli({
+    site: 'twitter',
+    name: 'list-tweets',
+    description: 'Fetch tweets from a Twitter/X list timeline',
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'listId', positional: true, type: 'string', required: true },
+        { name: 'limit', type: 'int', default: 50 },
+    ],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'created_at', 'url'],
+    func: async (page, kwargs) => {
+        const listId = String(kwargs.listId || '').trim();
+        if (!listId || !/^\d+$/.test(listId)) {
+            throw new CommandExecutionError(`Invalid listId: ${JSON.stringify(kwargs.listId)}. Expected a numeric ID (see \`opencli twitter lists\`).`);
+        }
+        const limit = kwargs.limit || 50;
+        await page.goto('https://x.com');
+        await page.wait(3);
+        const ct0 = await page.evaluate(`() => {
+            return document.cookie.split(';').map(c => c.trim()).find(c => c.startsWith('ct0='))?.split('=')[1] || null;
+        }`);
+        if (!ct0)
+            throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
+        const queryId = await page.evaluate(`async () => {
+            try {
+                const ghResp = await fetch('https://raw.githubusercontent.com/fa0311/twitter-openapi/refs/heads/main/src/config/placeholder.json');
+                if (ghResp.ok) {
+                    const data = await ghResp.json();
+                    const entry = data['${OPERATION_NAME}'];
+                    if (entry && entry.queryId) return entry.queryId;
+                }
+            } catch {}
+            try {
+                const scripts = performance.getEntriesByType('resource')
+                    .filter(r => r.name.includes('client-web') && r.name.endsWith('.js'))
+                    .map(r => r.name);
+                for (const scriptUrl of scripts.slice(0, 15)) {
+                    try {
+                        const text = await (await fetch(scriptUrl)).text();
+                        const re = /queryId:"([A-Za-z0-9_-]+)"[^}]{0,200}operationName:"${OPERATION_NAME}"/;
+                        const m = text.match(re);
+                        if (m) return m[1];
+                    } catch {}
+                }
+            } catch {}
+            return null;
+        }`) || LIST_TWEETS_QUERY_ID;
+        const headers = JSON.stringify({
+            'Authorization': `Bearer ${decodeURIComponent(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 < 10 && allTweets.length < limit; i++) {
+            const fetchCount = Math.min(100, limit - allTweets.length + 10);
+            const apiUrl = buildUrl(queryId, listId, 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 list timeline. queryId may have expired or list may be private.`);
+                break;
+            }
+            const { tweets, nextCursor } = parseListTimeline(data, seen);
+            allTweets.push(...tweets);
+            if (!nextCursor || nextCursor === cursor || tweets.length === 0)
+                break;
+            cursor = nextCursor;
+        }
+        return allTweets.slice(0, limit);
+    },
+});

package/clis/twitter/list-tweets.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { extractTimelineTweet, parseListTimeline } from './list-tweets.js';
+
+describe('twitter list-tweets parser', () => {
+    it('extracts core tweet fields from a ListLatestTweetsTimeline result', () => {
+        const tweet = extractTimelineTweet({
+            rest_id: '99',
+            legacy: {
+                full_text: 'hello list',
+                favorite_count: 3,
+                retweet_count: 1,
+                reply_count: 2,
+                created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            },
+            core: {
+                user_results: {
+                    result: {
+                        legacy: { screen_name: 'bob', name: 'Bob' },
+                    },
+                },
+            },
+        }, new Set());
+        expect(tweet).toEqual({
+            id: '99',
+            author: 'bob',
+            name: 'Bob',
+            text: 'hello list',
+            likes: 3,
+            retweets: 1,
+            replies: 2,
+            created_at: 'Wed Apr 16 10:00:00 +0000 2026',
+            url: 'https://x.com/bob/status/99',
+        });
+    });
+
+    it('prefers long-form note_tweet text over truncated legacy full_text', () => {
+        const tweet = extractTimelineTweet({
+            rest_id: '100',
+            legacy: { full_text: 'short…' },
+            note_tweet: {
+                note_tweet_results: {
+                    result: { text: 'the full long-form body' },
+                },
+            },
+            core: { user_results: { result: { legacy: { screen_name: 'carol' } } } },
+        }, new Set());
+        expect(tweet?.text).toBe('the full long-form body');
+    });
+
+    it('deduplicates on rest_id', () => {
+        const seen = new Set();
+        const first = extractTimelineTweet({ rest_id: '1', legacy: {}, core: {} }, seen);
+        const second = extractTimelineTweet({ rest_id: '1', legacy: {}, core: {} }, seen);
+        expect(first).not.toBeNull();
+        expect(second).toBeNull();
+    });
+
+    it('parses entries and bottom cursor from the list timeline payload', () => {
+        const payload = {
+            data: {
+                list: {
+                    tweets_timeline: {
+                        timeline: {
+                            instructions: [
+                                {
+                                    entries: [
+                                        {
+                                            entryId: 'tweet-1',
+                                            content: {
+                                                itemContent: {
+                                                    tweet_results: {
+                                                        result: {
+                                                            rest_id: '1',
+                                                            legacy: { full_text: 't1' },
+                                                            core: { user_results: { result: { legacy: { screen_name: 'a' } } } },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                        {
+                                            entryId: 'cursor-bottom-1',
+                                            content: {
+                                                entryType: 'TimelineTimelineCursor',
+                                                cursorType: 'Bottom',
+                                                value: 'cursor-next',
+                                            },
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    },
+                },
+            },
+        };
+        const result = parseListTimeline(payload, new Set());
+        expect(result.nextCursor).toBe('cursor-next');
+        expect(result.tweets).toHaveLength(1);
+        expect(result.tweets[0]).toMatchObject({ id: '1', author: 'a', text: 't1' });
+    });
+
+    it('returns empty tweets and null cursor for malformed payload', () => {
+        const result = parseListTimeline({}, new Set());
+        expect(result.tweets).toEqual([]);
+        expect(result.nextCursor).toBeNull();
+    });
+});