@jackwener/opencli 1.7.5 → 1.7.7

package/clis/jianyu/shared/procurement-detail.js

@@ -7,6 +7,13 @@ const RETRYABLE_DETAIL_ERROR_PATTERNS = [
     /cannot find context with specified id/i,
     /\[taxonomy=empty_result\]/i,
 ];
+const DETAIL_AUTH_CHALLENGE_PATTERNS = [
+    /请在下图依次点击/i,
+    /验证码/i,
+    /请完成验证/i,
+    /验证登录/i,
+    /登录即可获得更多浏览权限/i,
+];
 function isRetryableDetailError(error) {
     const message = error instanceof Error
         ? cleanText(error.message)
@@ -61,6 +68,14 @@ export async function runProcurementDetail(page, { url, site, query = '', }) {
             const title = cleanText(row.title);
             const detailText = cleanText(row.detailText);
             const publishTime = cleanText(row.publishTime);
+            const authGateText = cleanText(`${title} ${detailText}`);
+            if (DETAIL_AUTH_CHALLENGE_PATTERNS.some((pattern) => pattern.test(authGateText))) {
+                throw taxonomyError('selector_drift', {
+                    site,
+                    command: 'detail',
+                    detail: `detail page blocked by verification challenge: ${targetUrl}`,
+                });
+            }
             if (!title && !detailText) {
                 throw taxonomyError('empty_result', {
                     site,

package/clis/jianyu/shared/procurement-detail.test.js

@@ -69,4 +69,16 @@ describe('procurement detail runner', () => {
         })).rejects.toThrow('[taxonomy=extraction_drift]');
         expect(attempts).toBe(1);
     });
+    it('rejects captcha/verification pages as selector_drift', async () => {
+        const page = createPage(async () => ({
+            title: '验证码',
+            detailText: '请在下图依次点击：槨畽黛',
+            publishTime: '',
+        }));
+        await expect(runProcurementDetail(page, {
+            url: 'https://www.jianyu360.cn/nologin/content/ABC.html',
+            site: 'jianyu',
+            query: '电梯',
+        })).rejects.toThrow('[taxonomy=selector_drift]');
+    });
 });

package/clis/twitter/likes.js

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
-import { resolveTwitterQueryId, sanitizeQueryId } from './shared.js';
+import { resolveTwitterQueryId, sanitizeQueryId, extractMedia } from './shared.js';
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const LIKES_QUERY_ID = 'RozQdCp4CilQzrcuU0NY5w';
 const USER_BY_SCREEN_NAME_QUERY_ID = 'qRednkZG-rn1P6b48NINmQ';
@@ -99,6 +99,7 @@ function extractLikedTweet(result, seen) {
         retweets: legacy.retweet_count || 0,
         created_at: legacy.created_at || '',
         url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+        ...extractMedia(legacy),
     };
 }
 function parseLikes(data, seen) {
@@ -144,7 +145,7 @@ cli({
         { name: 'username', type: 'string', positional: true, help: 'Twitter screen name (without @). Defaults to logged-in user.' },
         { name: 'limit', type: 'int', default: 20 },
     ],
-    columns: ['author', 'name', 'text', 'likes', 'url'],
+    columns: ['author', 'name', 'text', 'likes', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 20;
         let username = (kwargs.username || '').replace(/^@/, '');

package/clis/twitter/search.js

@@ -1,5 +1,6 @@
 import { CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { extractMedia } from './shared.js';
 /**
  * Trigger Twitter search SPA navigation with fallback strategies.
  *
@@ -102,7 +103,7 @@ cli({
         { name: 'filter', type: 'string', default: 'top', choices: ['top', 'live'] },
         { name: 'limit', type: 'int', default: 15 },
     ],
-    columns: ['id', 'author', 'text', 'created_at', 'likes', 'views', 'url'],
+    columns: ['id', 'author', 'text', 'created_at', 'likes', 'views', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         const query = kwargs.query;
         const filter = kwargs.filter === 'live' ? 'live' : 'top';
@@ -156,7 +157,8 @@ cli({
                         created_at: tweet.legacy?.created_at || '',
                         likes: tweet.legacy?.favorite_count || 0,
                         views: tweet.views?.count || '0',
-                        url: `https://x.com/i/status/${tweet.rest_id}`
+                        url: `https://x.com/i/status/${tweet.rest_id}`,
+                        ...extractMedia(tweet.legacy),
                     });
                 }
             }

package/clis/twitter/search.test.js

@@ -75,6 +75,8 @@ describe('twitter search command', () => {
                 likes: 7,
                 views: '12',
                 url: 'https://x.com/i/status/1',
+                has_media: false,
+                media_urls: [],
             },
         ]);
         expect(page.installInterceptor).toHaveBeenCalledWith('SearchTimeline');
@@ -203,6 +205,8 @@ describe('twitter search command', () => {
                 likes: 3,
                 views: '5',
                 url: 'https://x.com/i/status/99',
+                has_media: false,
+                media_urls: [],
             },
         ]);
         // 6 evaluate calls: 2x pushState + 2x pathname check + 1x fallback + 1x pathname check

package/clis/twitter/shared.js

@@ -5,14 +5,19 @@ export function sanitizeQueryId(resolved, fallbackId) {
 export async function resolveTwitterQueryId(page, operationName, fallbackId) {
     const resolved = await page.evaluate(`async () => {
     const operationName = ${JSON.stringify(operationName)};
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5000);
     try {
-      const ghResp = await fetch('https://raw.githubusercontent.com/fa0311/twitter-openapi/refs/heads/main/src/config/placeholder.json');
+      const ghResp = await fetch('https://raw.githubusercontent.com/fa0311/twitter-openapi/refs/heads/main/src/config/placeholder.json', { signal: controller.signal });
+      clearTimeout(timeout);
       if (ghResp.ok) {
         const data = await ghResp.json();
         const entry = data?.[operationName];
         if (entry && entry.queryId) return entry.queryId;
       }
-    } catch {}
+    } catch {
+      clearTimeout(timeout);
+    }
     try {
       const scripts = performance.getEntriesByType('resource')
         .filter(r => r.name.includes('client-web') && r.name.endsWith('.js'))
@@ -30,6 +35,34 @@ export async function resolveTwitterQueryId(page, operationName, fallbackId) {
   }`);
     return sanitizeQueryId(resolved, fallbackId);
 }
+/**
+ * Extract media flags and URLs from a tweet's `legacy` object.
+ *
+ * Prefers `extended_entities.media` (superset with full video_info) and falls
+ * back to `entities.media` when the extended form is missing. For videos and
+ * animated GIFs, returns the mp4 variant URL; for photos, returns
+ * `media_url_https`.
+ */
+export function extractMedia(legacy) {
+    const media = legacy?.extended_entities?.media || legacy?.entities?.media;
+    if (!Array.isArray(media) || media.length === 0) {
+        return { has_media: false, media_urls: [] };
+    }
+    const urls = [];
+    for (const m of media) {
+        if (!m) continue;
+        if (m.type === 'video' || m.type === 'animated_gif') {
+            const variants = m.video_info?.variants || [];
+            const mp4 = variants.find((v) => v?.content_type === 'video/mp4');
+            const url = mp4?.url || m.media_url_https;
+            if (url) urls.push(url);
+        } else {
+            if (m.media_url_https) urls.push(m.media_url_https);
+        }
+    }
+    return { has_media: urls.length > 0, media_urls: urls };
+}
 export const __test__ = {
     sanitizeQueryId,
+    extractMedia,
 };

package/clis/twitter/shared.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './shared.js';
+
+const { extractMedia } = __test__;
+
+describe('twitter extractMedia', () => {
+    it('returns false + empty list when legacy has no media', () => {
+        expect(extractMedia({})).toEqual({ has_media: false, media_urls: [] });
+        expect(extractMedia(undefined)).toEqual({ has_media: false, media_urls: [] });
+        expect(extractMedia({ extended_entities: { media: [] } })).toEqual({
+            has_media: false,
+            media_urls: [],
+        });
+    });
+
+    it('extracts photo urls from extended_entities', () => {
+        const result = extractMedia({
+            extended_entities: {
+                media: [
+                    { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/a.jpg' },
+                    { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/b.jpg' },
+                ],
+            },
+        });
+        expect(result.has_media).toBe(true);
+        expect(result.media_urls).toEqual([
+            'https://pbs.twimg.com/media/a.jpg',
+            'https://pbs.twimg.com/media/b.jpg',
+        ]);
+    });
+
+    it('prefers mp4 variant for video and animated_gif', () => {
+        const result = extractMedia({
+            extended_entities: {
+                media: [
+                    {
+                        type: 'video',
+                        media_url_https: 'https://pbs.twimg.com/media/thumb.jpg',
+                        video_info: {
+                            variants: [
+                                { content_type: 'application/x-mpegURL', url: 'https://video.twimg.com/x.m3u8' },
+                                { content_type: 'video/mp4', url: 'https://video.twimg.com/x.mp4' },
+                            ],
+                        },
+                    },
+                    {
+                        type: 'animated_gif',
+                        media_url_https: 'https://pbs.twimg.com/tweet_video_thumb/g.jpg',
+                        video_info: {
+                            variants: [
+                                { content_type: 'video/mp4', url: 'https://video.twimg.com/g.mp4' },
+                            ],
+                        },
+                    },
+                ],
+            },
+        });
+        expect(result.has_media).toBe(true);
+        expect(result.media_urls).toEqual([
+            'https://video.twimg.com/x.mp4',
+            'https://video.twimg.com/g.mp4',
+        ]);
+    });
+
+    it('falls back to media_url_https when no mp4 variant is available', () => {
+        const result = extractMedia({
+            extended_entities: {
+                media: [
+                    {
+                        type: 'video',
+                        media_url_https: 'https://pbs.twimg.com/media/thumb.jpg',
+                        video_info: { variants: [] },
+                    },
+                ],
+            },
+        });
+        expect(result).toEqual({
+            has_media: true,
+            media_urls: ['https://pbs.twimg.com/media/thumb.jpg'],
+        });
+    });
+
+    it('falls back to entities.media when extended_entities is missing', () => {
+        const result = extractMedia({
+            entities: {
+                media: [
+                    { type: 'photo', media_url_https: 'https://pbs.twimg.com/media/c.jpg' },
+                ],
+            },
+        });
+        expect(result).toEqual({
+            has_media: true,
+            media_urls: ['https://pbs.twimg.com/media/c.jpg'],
+        });
+    });
+});

package/clis/twitter/thread.js

@@ -1,5 +1,6 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
+import { extractMedia } from './shared.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const TWEET_DETAIL_QUERY_ID = 'nBS-WpgA6ZG0CyNHD517JQ';
@@ -54,6 +55,7 @@ function extractTweet(r, seen) {
         in_reply_to: l.in_reply_to_status_id_str || undefined,
         created_at: l.created_at,
         url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+        ...extractMedia(l),
     };
 }
 function parseTweetDetail(data, seen) {
@@ -101,7 +103,7 @@ cli({
         { name: 'tweet-id', positional: true, type: 'string', required: true },
         { name: 'limit', type: 'int', default: 50 },
     ],
-    columns: ['id', 'author', 'text', 'likes', 'retweets', 'url'],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         let tweetId = kwargs['tweet-id'];
         const urlMatch = tweetId.match(/\/status\/(\d+)/);

package/clis/twitter/timeline.js

@@ -1,6 +1,6 @@
 import { AuthRequiredError, CommandExecutionError } from '@jackwener/opencli/errors';
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { resolveTwitterQueryId } from './shared.js';
+import { resolveTwitterQueryId, extractMedia } from './shared.js';
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const HOME_TIMELINE_QUERY_ID = 'c-CzHF1LboFilMpsx4ZCrQ';
@@ -85,6 +85,7 @@ function extractTweet(result, seen) {
         views,
         created_at: l.created_at || '',
         url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+        ...extractMedia(l),
     };
 }
 function parseHomeTimeline(data, seen) {
@@ -148,7 +149,7 @@ cli({
         },
         { name: 'limit', type: 'int', default: 20 },
     ],
-    columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url'],
+    columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url', 'has_media', 'media_urls'],
     func: async (page, kwargs) => {
         const limit = kwargs.limit || 20;
         const timelineType = kwargs.type === 'following' ? 'following' : 'for-you';

package/clis/twitter/tweets.js

@@ -0,0 +1,219 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { resolveTwitterQueryId, sanitizeQueryId, extractMedia } from './shared.js';
+
+const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+const USER_TWEETS_QUERY_ID = '6fWQaBPK51aGyC_VC7t9GQ';
+const USER_BY_SCREEN_NAME_QUERY_ID = 'IGgvgiOx4QZndDHuD3x9TQ';
+
+const USER_TWEETS_FEATURES = {
+    rweb_video_screen_enabled: false,
+    payments_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: true,
+    responsive_web_grok_share_attachment_enabled: true,
+    responsive_web_grok_annotations_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,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    post_ctas_fetch_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_grok_imagine_annotation_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+};
+
+const USER_BY_SCREEN_NAME_FEATURES = {
+    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,
+};
+
+function buildUserTweetsUrl(queryId, userId, count, cursor) {
+    const vars = {
+        userId,
+        count,
+        includePromotedContent: false,
+        withQuickPromoteEligibilityTweetFields: true,
+        withVoice: true,
+    };
+    if (cursor) vars.cursor = cursor;
+    return `/i/api/graphql/${queryId}/UserTweets`
+        + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
+        + `&features=${encodeURIComponent(JSON.stringify(USER_TWEETS_FEATURES))}`;
+}
+
+function buildUserByScreenNameUrl(queryId, screenName) {
+    const vars = { screen_name: screenName, withSafetyModeUserFields: true };
+    return `/i/api/graphql/${queryId}/UserByScreenName`
+        + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
+        + `&features=${encodeURIComponent(JSON.stringify(USER_BY_SCREEN_NAME_FEATURES))}`;
+}
+
+function extractTweet(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;
+    const isRetweet = Boolean(legacy.retweeted_status_result || legacy.full_text?.startsWith('RT @'));
+    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,
+        views: Number(tw.views?.count) || 0,
+        is_retweet: isRetweet,
+        created_at: legacy.created_at || '',
+        url: `https://x.com/${screenName}/status/${tw.rest_id}`,
+        ...extractMedia(legacy),
+    };
+}
+
+function parseUserTweets(data, seen) {
+    const tweets = [];
+    let nextCursor = null;
+    const instructions = data?.data?.user?.result?.timeline_v2?.timeline?.instructions
+        || data?.data?.user?.result?.timeline?.timeline?.instructions
+        || [];
+    for (const inst of instructions) {
+        if (inst.type === 'TimelinePinEntry') continue;
+        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 = extractTweet(content?.itemContent?.tweet_results?.result, seen);
+            if (direct) {
+                tweets.push(direct);
+                continue;
+            }
+            for (const item of content?.items || []) {
+                const nested = extractTweet(item.item?.itemContent?.tweet_results?.result, seen);
+                if (nested) tweets.push(nested);
+            }
+        }
+    }
+    return { tweets, nextCursor };
+}
+
+cli({
+    site: 'twitter',
+    name: 'tweets',
+    description: "Fetch a Twitter user's most recent tweets (chronological, excludes pinned)",
+    domain: 'x.com',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [
+        { name: 'username', type: 'string', positional: true, required: true, help: 'Twitter screen name (with or without @)' },
+        { name: 'limit', type: 'int', default: 20, help: 'Max tweets to return' },
+    ],
+    columns: ['author', 'created_at', 'is_retweet', 'text', 'likes', 'retweets', 'replies', 'views', 'url', 'has_media', 'media_urls'],
+    func: async (page, kwargs) => {
+        const limit = Math.max(1, Math.min(200, kwargs.limit || 20));
+        const username = String(kwargs.username || '').replace(/^@/, '').trim();
+        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 userTweetsQueryId = await resolveTwitterQueryId(page, 'UserTweets', USER_TWEETS_QUERY_ID);
+        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 ubsUrl = buildUserByScreenNameUrl(userByScreenNameQueryId, username);
+        const userId = await page.evaluate(`async () => {
+      const resp = await fetch("${ubsUrl}", { 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 @${username}`);
+
+        const seen = new Set();
+        const all = [];
+        let cursor = null;
+        for (let i = 0; i < 5 && all.length < limit; i++) {
+            const fetchCount = Math.min(100, limit - all.length + 10);
+            const url = buildUserTweetsUrl(userTweetsQueryId, userId, fetchCount, cursor);
+            const data = await page.evaluate(`async () => {
+        const r = await fetch("${url}", { headers: ${headers}, credentials: 'include' });
+        return r.ok ? await r.json() : { error: r.status };
+      }`);
+            if (data?.error) {
+                if (all.length === 0) throw new CommandExecutionError(`HTTP ${data.error}: UserTweets fetch failed — queryId may have expired`);
+                break;
+            }
+            const { tweets, nextCursor } = parseUserTweets(data, seen);
+            all.push(...tweets);
+            if (!nextCursor || nextCursor === cursor) break;
+            cursor = nextCursor;
+        }
+
+        if (all.length === 0) throw new EmptyResultError(`@${username} has no recent tweets`, 'Account may be private or suspended');
+        return all.slice(0, limit);
+    },
+});
+
+export const __test__ = {
+    sanitizeQueryId,
+    buildUserTweetsUrl,
+    buildUserByScreenNameUrl,
+    extractTweet,
+    parseUserTweets,
+};

package/clis/twitter/tweets.test.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { __test__ } from './tweets.js';
+
+describe('twitter tweets helpers', () => {
+    it('registers is_retweet in the default columns', () => {
+        const cmd = getRegistry().get('twitter/tweets');
+        expect(cmd?.columns).toEqual(['author', 'created_at', 'is_retweet', 'text', 'likes', 'retweets', 'replies', 'views', 'url', 'has_media', 'media_urls']);
+    });
+
+    it('falls back when queryId contains unsafe characters', () => {
+        expect(__test__.sanitizeQueryId('safe_Query-123', 'fallback')).toBe('safe_Query-123');
+        expect(__test__.sanitizeQueryId('bad"id', 'fallback')).toBe('fallback');
+        expect(__test__.sanitizeQueryId('bad/id', 'fallback')).toBe('fallback');
+        expect(__test__.sanitizeQueryId(null, 'fallback')).toBe('fallback');
+    });
+
+    it('builds UserTweets url with cursor and features', () => {
+        const url = __test__.buildUserTweetsUrl('query123', '42', 20, 'cursor-1');
+        expect(url).toContain('/i/api/graphql/query123/UserTweets');
+        const decoded = decodeURIComponent(url);
+        expect(decoded).toContain('"userId":"42"');
+        expect(decoded).toContain('"count":20');
+        expect(decoded).toContain('"cursor":"cursor-1"');
+        expect(decoded).toContain('longform_notetweets_consumption_enabled');
+    });
+
+    it('builds UserByScreenName url for the given handle', () => {
+        const url = __test__.buildUserByScreenNameUrl('uquery', 'jakevin7');
+        expect(url).toContain('/i/api/graphql/uquery/UserByScreenName');
+        expect(decodeURIComponent(url)).toContain('"screen_name":"jakevin7"');
+    });
+
+    it('prefers note_tweet text over legacy.full_text for long posts', () => {
+        const seen = new Set();
+        const tweet = __test__.extractTweet({
+            rest_id: '99',
+            legacy: { full_text: 'short truncated…', favorite_count: 1, retweet_count: 0, reply_count: 0, created_at: 'now' },
+            note_tweet: { note_tweet_results: { result: { text: 'full long-form body' } } },
+            core: { user_results: { result: { legacy: { screen_name: 'bob', name: 'Bob' } } } },
+            views: { count: '42' },
+        }, seen);
+        expect(tweet.text).toBe('full long-form body');
+        expect(tweet.views).toBe(42);
+    });
+
+    it('flags retweets via RT prefix or retweeted_status_result', () => {
+        const a = __test__.extractTweet({
+            rest_id: '1',
+            legacy: { full_text: 'RT @foo: hi', favorite_count: 0, retweet_count: 0, reply_count: 0, created_at: '' },
+            core: { user_results: { result: { legacy: { screen_name: 'u', name: 'U' } } } },
+        }, new Set());
+        expect(a.is_retweet).toBe(true);
+
+        const b = __test__.extractTweet({
+            rest_id: '2',
+            legacy: { full_text: 'hello', favorite_count: 0, retweet_count: 0, reply_count: 0, created_at: '', retweeted_status_result: { result: {} } },
+            core: { user_results: { result: { legacy: { screen_name: 'u', name: 'U' } } } },
+        }, new Set());
+        expect(b.is_retweet).toBe(true);
+    });
+
+    it('parses chronological tweets and skips pinned instruction', () => {
+        const chronEntry = {
+            entryId: 'tweet-1',
+            content: {
+                itemContent: {
+                    tweet_results: {
+                        result: {
+                            rest_id: '1',
+                            legacy: { full_text: 'chronological post', favorite_count: 5, retweet_count: 1, reply_count: 2, created_at: 'now' },
+                            core: { user_results: { result: { legacy: { screen_name: 'alice', name: 'Alice' } } } },
+                            views: { count: '100' },
+                        },
+                    },
+                },
+            },
+        };
+        const cursorEntry = {
+            entryId: 'cursor-bottom-1',
+            content: { entryType: 'TimelineTimelineCursor', cursorType: 'Bottom', value: 'cursor-next' },
+        };
+        const pinnedEntry = {
+            entryId: 'tweet-pinned-999',
+            content: {
+                itemContent: {
+                    tweet_results: {
+                        result: {
+                            rest_id: '999',
+                            legacy: { full_text: 'pinned post', favorite_count: 0, retweet_count: 0, reply_count: 0, created_at: 'old' },
+                            core: { user_results: { result: { legacy: { screen_name: 'alice', name: 'Alice' } } } },
+                        },
+                    },
+                },
+            },
+        };
+        const payload = {
+            data: {
+                user: {
+                    result: {
+                        timeline_v2: {
+                            timeline: {
+                                instructions: [
+                                    { type: 'TimelinePinEntry', entries: [pinnedEntry] },
+                                    { entries: [chronEntry, cursorEntry] },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        const result = __test__.parseUserTweets(payload, new Set());
+        expect(result.nextCursor).toBe('cursor-next');
+        expect(result.tweets).toHaveLength(1);
+        expect(result.tweets[0]).toMatchObject({
+            id: '1',
+            author: 'alice',
+            text: 'chronological post',
+            likes: 5,
+            views: 100,
+            url: 'https://x.com/alice/status/1',
+        });
+    });
+});