feat(twitter): add --type flag to timeline command (#83) (#232)

Support switching between For You (algorithmic) and Following
(chronological) timelines via `--type for-you|following`.

Both endpoints share the same response structure; only the GraphQL
endpoint name and queryId differ. QueryId is resolved dynamically
from fa0311/twitter-openapi with a hardcoded fallback, and validated
against /^[A-Za-z0-9_-]+$/ to prevent injection from upstream.

Author: Astro-Han

src/clis/twitter/timeline.ts

@@ -2,8 +2,16 @@ import { cli, Strategy } from '../../registry.js';
 
 // ── Twitter GraphQL constants ──────────────────────────────────────────
 
-const BEARER_TOKEN = 'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+const BEARER_TOKEN =
+  'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
 const HOME_TIMELINE_QUERY_ID = 'c-CzHF1LboFilMpsx4ZCrQ';
+const HOME_LATEST_TIMELINE_QUERY_ID = 'BKB7oi212Fi7kQtCBGE4zA';
+
+// Endpoint config: for-you uses GET HomeTimeline, following uses POST HomeLatestTimeline
+const TIMELINE_ENDPOINTS: Record<string, { endpoint: string; method: string; fallbackQueryId: string }> = {
+  'for-you': { endpoint: 'HomeTimeline', method: 'GET', fallbackQueryId: HOME_TIMELINE_QUERY_ID },
+  following: { endpoint: 'HomeLatestTimeline', method: 'POST', fallbackQueryId: HOME_LATEST_TIMELINE_QUERY_ID },
+};
 
 const FEATURES = {
   rweb_video_screen_enabled: false,
@@ -53,7 +61,7 @@ interface TimelineTweet {
   url: string;
 }
 
-function buildHomeTimelineUrl(count: number, cursor?: string | null): string {
+function buildHomeTimelineUrl(queryId: string, endpoint: string, count: number, cursor?: string | null): string {
   const vars: Record<string, any> = {
     count,
     includePromotedContent: false,
@@ -63,9 +71,11 @@ function buildHomeTimelineUrl(count: number, cursor?: string | null): string {
   };
   if (cursor) vars.cursor = cursor;
 
-  return `/i/api/graphql/${HOME_TIMELINE_QUERY_ID}/HomeTimeline`
-    + `?variables=${encodeURIComponent(JSON.stringify(vars))}`
-    + `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`;
+  return (
+    `/i/api/graphql/${queryId}/${endpoint}` +
+    `?variables=${encodeURIComponent(JSON.stringify(vars))}` +
+    `&features=${encodeURIComponent(JSON.stringify(FEATURES))}`
+  );
 }
 
 function extractTweet(result: any, seen: Set<string>): TimelineTweet | null {
@@ -97,8 +107,8 @@ function parseHomeTimeline(data: any, seen: Set<string>): { tweets: TimelineTwee
   const tweets: TimelineTweet[] = [];
   let nextCursor: string | null = null;
 
-  const instructions =
-    data?.data?.home?.home_timeline_urt?.instructions || [];
+  // Both HomeTimeline and HomeLatestTimeline share the same response envelope
+  const instructions = data?.data?.home?.home_timeline_urt?.instructions || [];
 
   for (const inst of instructions) {
     for (const entry of inst.entries || []) {
@@ -144,16 +154,23 @@ function parseHomeTimeline(data: any, seen: Set<string>): { tweets: TimelineTwee
 cli({
   site: 'twitter',
   name: 'timeline',
-  description: 'Fetch Twitter Home Timeline',
+  description: 'Fetch Twitter timeline (for-you or following)',
   domain: 'x.com',
   strategy: Strategy.COOKIE,
   browser: true,
   args: [
+    {
+      name: 'type',
+      default: 'for-you',
+      choices: ['for-you', 'following'],
+      help: 'Timeline type: for-you (algorithmic) or following (chronological)',
+    },
     { name: 'limit', type: 'int', default: 20 },
   ],
   columns: ['id', 'author', 'text', 'likes', 'retweets', 'replies', 'views', 'created_at', 'url'],
   func: async (page, kwargs) => {
     const limit = kwargs.limit || 20;
+    const { endpoint, method, fallbackQueryId } = TIMELINE_ENDPOINTS[kwargs.type || 'for-you'];
 
     // Navigate to x.com for cookie context
     await page.goto('https://x.com');
@@ -165,22 +182,24 @@ cli({
     }`);
     if (!ct0) throw new Error('Not logged into x.com (no ct0 cookie)');
 
-    // Dynamically resolve queryId
-    const queryId = await page.evaluate(`async () => {
+    // Dynamically resolve queryId for the selected endpoint
+    const resolved = 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['HomeTimeline'];
+          const entry = data['${endpoint}'];
           if (entry && entry.queryId) return entry.queryId;
         }
       } catch {}
       return null;
-    }`) || HOME_TIMELINE_QUERY_ID;
+    }`);
+    // Validate queryId format to prevent injection from untrusted upstream
+    const queryId = typeof resolved === 'string' && /^[A-Za-z0-9_-]+$/.test(resolved) ? resolved : fallbackQueryId;
 
     // Build auth headers
     const headers = JSON.stringify({
-      'Authorization': `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
+      Authorization: `Bearer ${decodeURIComponent(BEARER_TOKEN)}`,
       'X-Csrf-Token': ct0,
       'X-Twitter-Auth-Type': 'OAuth2Session',
       'X-Twitter-Active-User': 'yes',
@@ -193,16 +212,16 @@ cli({
 
     for (let i = 0; i < 5 && allTweets.length < limit; i++) {
       const fetchCount = Math.min(40, limit - allTweets.length + 5); // over-fetch slightly for promoted filtering
-      const apiUrl = buildHomeTimelineUrl(fetchCount, cursor)
-        .replace(HOME_TIMELINE_QUERY_ID, queryId);
+      const apiUrl = buildHomeTimelineUrl(queryId, endpoint, fetchCount, cursor);
 
       const data = await page.evaluate(`async () => {
-        const r = await fetch("${apiUrl}", { headers: ${headers}, credentials: 'include' });
+        const r = await fetch("${apiUrl}", { method: "${method}", headers: ${headers}, credentials: 'include' });
         return r.ok ? await r.json() : { error: r.status };
       }`);
 
       if (data?.error) {
-        if (allTweets.length === 0) throw new Error(`HTTP ${data.error}: Failed to fetch timeline. queryId may have expired.`);
+        if (allTweets.length === 0)
+          throw new Error(`HTTP ${data.error}: Failed to fetch timeline. queryId may have expired.`);
         break;
       }