feat(lists): add support for Twitter Lists

Add commands to fetch owned lists, list memberships, and list timelines: - `bird lists` shows lists you own - `bird lists --member-of` shows lists you're a member of - `bird list-timeline <id-or-url>` fetches tweets from a list Includes full --json and --json-full support for list timeline output. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
2026-01-03 16:55:29 +01:00
parent 3db3aca0a0
commit 7818440d65
9 changed files with 1141 additions and 2 deletions
@@ -8,5 +8,9 @@
  "BookmarkFolderTimeline": "KJIQpsvxrTfRIlbaRIySHQ",
  "Following": "BEkNpEt5pNETESoqMsTEGA",
  "Followers": "kuFUYP9eV1FPoEy4N-pi7w",
-  "Likes": "JR2gceKucIKcVNB_9JkhsA"
+  "Likes": "JR2gceKucIKcVNB_9JkhsA",
+  "ListOwnerships": "wQcOSjSQ8NtgxIwvYl1lMg",
+  "ListMemberships": "BlEXXdARdSeL_0KyKHHvvg",
+  "ListLatestTweetsTimeline": "2TemLyqrMpTeAmysdbnVqw",
+  "ListByRestId": "wXzyA5vM_aVkBL9G8Vp3kw"
 }
@@ -25,6 +25,10 @@ export const FALLBACK_QUERY_IDS = {
  Followers: 'kuFUYP9eV1FPoEy4N-pi7w',
  Likes: 'JR2gceKucIKcVNB_9JkhsA',
  BookmarkFolderTimeline: 'KJIQpsvxrTfRIlbaRIySHQ',
+  ListOwnerships: 'wQcOSjSQ8NtgxIwvYl1lMg',
+  ListMemberships: 'BlEXXdARdSeL_0KyKHHvvg',
+  ListLatestTweetsTimeline: '2TemLyqrMpTeAmysdbnVqw',
+  ListByRestId: 'wXzyA5vM_aVkBL9G8Vp3kw',
 } as const;

 export type OperationName = keyof typeof FALLBACK_QUERY_IDS;
@@ -170,6 +170,46 @@ export function buildLikesFeatures(): Record<string, boolean> {
  return buildTimelineFeatures();
 }

+export function buildListsFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_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: false,
+    responsive_web_grok_annotations_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    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: true,
+    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_grok_imagine_annotation_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}
+
 export function buildFollowingFeatures(): Record<string, boolean> {
  return {
    rweb_video_screen_enabled: true,
@@ -0,0 +1,429 @@
+// ABOUTME: Mixin for Twitter Lists GraphQL operations.
+// ABOUTME: Provides methods to fetch user's owned lists, memberships, and list timelines.
+
+import type { AbstractConstructor, Mixin, TwitterClientBase } from './twitter-client-base.js';
+import { TWITTER_API_BASE } from './twitter-client-constants.js';
+import { buildListsFeatures } from './twitter-client-features.js';
+import type { TimelineFetchOptions } from './twitter-client-timelines.js';
+import type { GraphqlTweetResult, ListsResult, SearchResult, TwitterList } from './twitter-client-types.js';
+import { parseTweetsFromInstructions } from './twitter-client-utils.js';
+
+export interface TwitterClientListMethods {
+  getOwnedLists(count?: number): Promise<ListsResult>;
+  getListMemberships(count?: number): Promise<ListsResult>;
+  getListTimeline(listId: string, count?: number, options?: TimelineFetchOptions): Promise<SearchResult>;
+}
+
+interface GraphqlListResult {
+  id_str?: string;
+  name?: string;
+  description?: string;
+  member_count?: number;
+  subscriber_count?: number;
+  mode?: string;
+  created_at?: string;
+  user_results?: {
+    result?: {
+      rest_id?: string;
+      legacy?: {
+        screen_name?: string;
+        name?: string;
+      };
+    };
+  };
+}
+
+function parseList(listResult: GraphqlListResult): TwitterList | null {
+  if (!listResult.id_str || !listResult.name) {
+    return null;
+  }
+
+  const owner = listResult.user_results?.result;
+  return {
+    id: listResult.id_str,
+    name: listResult.name,
+    description: listResult.description,
+    memberCount: listResult.member_count,
+    subscriberCount: listResult.subscriber_count,
+    isPrivate: listResult.mode === 'Private',
+    createdAt: listResult.created_at,
+    owner: owner
+      ? {
+          id: owner.rest_id ?? '',
+          username: owner.legacy?.screen_name ?? '',
+          name: owner.legacy?.name ?? '',
+        }
+      : undefined,
+  };
+}
+
+function parseListsFromInstructions(
+  instructions:
+    | Array<{
+        entries?: Array<{
+          content?: {
+            itemContent?: {
+              list?: GraphqlListResult;
+            };
+          };
+        }>;
+      }>
+    | undefined,
+): TwitterList[] {
+  const lists: TwitterList[] = [];
+  if (!instructions) {
+    return lists;
+  }
+
+  for (const instruction of instructions) {
+    if (!instruction.entries) {
+      continue;
+    }
+    for (const entry of instruction.entries) {
+      const listResult = entry.content?.itemContent?.list;
+      if (listResult) {
+        const parsed = parseList(listResult);
+        if (parsed) {
+          lists.push(parsed);
+        }
+      }
+    }
+  }
+
+  return lists;
+}
+
+export function withLists<TBase extends AbstractConstructor<TwitterClientBase>>(
+  Base: TBase,
+): Mixin<TBase, TwitterClientListMethods> {
+  abstract class TwitterClientLists extends Base {
+    // biome-ignore lint/complexity/noUselessConstructor lint/suspicious/noExplicitAny: TS mixin constructor requirement.
+    constructor(...args: any[]) {
+      super(...args);
+    }
+
+    private async getListOwnershipsQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('ListOwnerships');
+      return Array.from(new Set([primary, 'wQcOSjSQ8NtgxIwvYl1lMg']));
+    }
+
+    private async getListMembershipsQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('ListMemberships');
+      return Array.from(new Set([primary, 'BlEXXdARdSeL_0KyKHHvvg']));
+    }
+
+    private async getListTimelineQueryIds(): Promise<string[]> {
+      const primary = await this.getQueryId('ListLatestTweetsTimeline');
+      return Array.from(new Set([primary, '2TemLyqrMpTeAmysdbnVqw']));
+    }
+
+    /**
+     * Get lists owned by the authenticated user
+     */
+    async getOwnedLists(count = 100): Promise<ListsResult> {
+      const userResult = await this.getCurrentUser();
+      if (!userResult.success || !userResult.user) {
+        return { success: false, error: userResult.error ?? 'Could not determine current user' };
+      }
+
+      const variables = {
+        userId: userResult.user.id,
+        count,
+        isListMembershipShown: true,
+        isListMemberTargetUserId: userResult.user.id,
+      };
+
+      const features = buildListsFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getListOwnershipsQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/ListOwnerships?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                user?: {
+                  result?: {
+                    timeline?: {
+                      timeline?: {
+                        instructions?: Array<{
+                          entries?: Array<{
+                            content?: {
+                              itemContent?: {
+                                list?: GraphqlListResult;
+                              };
+                            };
+                          }>;
+                        }>;
+                      };
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.user?.result?.timeline?.timeline?.instructions;
+            const lists = parseListsFromInstructions(instructions);
+
+            return { success: true as const, lists, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching owned lists', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, lists: firstAttempt.lists };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, lists: secondAttempt.lists };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+
+    /**
+     * Get lists the authenticated user is a member of
+     */
+    async getListMemberships(count = 100): Promise<ListsResult> {
+      const userResult = await this.getCurrentUser();
+      if (!userResult.success || !userResult.user) {
+        return { success: false, error: userResult.error ?? 'Could not determine current user' };
+      }
+
+      const variables = {
+        userId: userResult.user.id,
+        count,
+        isListMembershipShown: true,
+        isListMemberTargetUserId: userResult.user.id,
+      };
+
+      const features = buildListsFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getListMembershipsQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/ListMemberships?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                user?: {
+                  result?: {
+                    timeline?: {
+                      timeline?: {
+                        instructions?: Array<{
+                          entries?: Array<{
+                            content?: {
+                              itemContent?: {
+                                list?: GraphqlListResult;
+                              };
+                            };
+                          }>;
+                        }>;
+                      };
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.user?.result?.timeline?.timeline?.instructions;
+            const lists = parseListsFromInstructions(instructions);
+
+            return { success: true as const, lists, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching list memberships', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, lists: firstAttempt.lists };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, lists: secondAttempt.lists };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+
+    /**
+     * Get tweets from a list timeline
+     */
+    async getListTimeline(listId: string, count = 20, options: TimelineFetchOptions = {}): Promise<SearchResult> {
+      const { includeRaw = false } = options;
+
+      const variables = {
+        listId,
+        count,
+      };
+
+      const features = buildListsFeatures();
+
+      const params = new URLSearchParams({
+        variables: JSON.stringify(variables),
+        features: JSON.stringify(features),
+      });
+
+      const tryOnce = async () => {
+        let lastError: string | undefined;
+        let had404 = false;
+        const queryIds = await this.getListTimelineQueryIds();
+
+        for (const queryId of queryIds) {
+          const url = `${TWITTER_API_BASE}/${queryId}/ListLatestTweetsTimeline?${params.toString()}`;
+
+          try {
+            const response = await this.fetchWithTimeout(url, {
+              method: 'GET',
+              headers: this.getHeaders(),
+            });
+
+            if (response.status === 404) {
+              had404 = true;
+              lastError = `HTTP ${response.status}`;
+              continue;
+            }
+
+            if (!response.ok) {
+              const text = await response.text();
+              return { success: false as const, error: `HTTP ${response.status}: ${text.slice(0, 200)}`, had404 };
+            }
+
+            const data = (await response.json()) as {
+              data?: {
+                list?: {
+                  tweets_timeline?: {
+                    timeline?: {
+                      instructions?: Array<{
+                        entries?: Array<{
+                          content?: {
+                            itemContent?: {
+                              tweet_results?: {
+                                result?: GraphqlTweetResult;
+                              };
+                            };
+                          };
+                        }>;
+                      }>;
+                    };
+                  };
+                };
+              };
+              errors?: Array<{ message: string }>;
+            };
+
+            if (data.errors && data.errors.length > 0) {
+              return { success: false as const, error: data.errors.map((e) => e.message).join(', '), had404 };
+            }
+
+            const instructions = data.data?.list?.tweets_timeline?.timeline?.instructions;
+            const tweets = parseTweetsFromInstructions(instructions, { quoteDepth: this.quoteDepth, includeRaw });
+
+            return { success: true as const, tweets, had404 };
+          } catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+          }
+        }
+
+        return { success: false as const, error: lastError ?? 'Unknown error fetching list timeline', had404 };
+      };
+
+      const firstAttempt = await tryOnce();
+      if (firstAttempt.success) {
+        return { success: true, tweets: firstAttempt.tweets };
+      }
+
+      if (firstAttempt.had404) {
+        await this.refreshQueryIds();
+        const secondAttempt = await tryOnce();
+        if (secondAttempt.success) {
+          return { success: true, tweets: secondAttempt.tweets };
+        }
+        return { success: false, error: secondAttempt.error };
+      }
+
+      return { success: false, error: firstAttempt.error };
+    }
+  }
+
+  return TwitterClientLists;
+}
@@ -237,6 +237,27 @@ export interface TwitterClientOptions {
  quoteDepth?: number;
 }

+export interface TwitterList {
+  id: string;
+  name: string;
+  description?: string;
+  memberCount?: number;
+  subscriberCount?: number;
+  isPrivate?: boolean;
+  createdAt?: string;
+  owner?: {
+    id: string;
+    username: string;
+    name: string;
+  };
+}
+
+export interface ListsResult {
+  success: boolean;
+  lists?: TwitterList[];
+  error?: string;
+}
+
 export interface CreateTweetResponse {
  data?: {
    create_tweet?: {
@@ -1,5 +1,6 @@
 import type { AbstractConstructor } from './twitter-client-base.js';
 import { TwitterClientBase } from './twitter-client-base.js';
+import { type TwitterClientListMethods, withLists } from './twitter-client-lists.js';
 import { type TwitterClientMediaMethods, withMedia } from './twitter-client-media.js';
 import { type TwitterClientPostingMethods, withPosting } from './twitter-client-posting.js';
 import { type TwitterClientSearchMethods, withSearch } from './twitter-client-search.js';
@@ -8,6 +9,7 @@ import { type TwitterClientTweetDetailMethods, withTweetDetails } from './twitte
 import { type TwitterClientUserMethods, withUsers } from './twitter-client-users.js';

 type TwitterClientInstance = TwitterClientBase &
+  TwitterClientListMethods &
  TwitterClientMediaMethods &
  TwitterClientPostingMethods &
  TwitterClientSearchMethods &
@@ -16,7 +18,7 @@ type TwitterClientInstance = TwitterClientBase &
  TwitterClientUserMethods;

 const MixedTwitterClient = withUsers(
-  withTimelines(withSearch(withTweetDetails(withPosting(withMedia(TwitterClientBase))))),
+  withLists(withTimelines(withSearch(withTweetDetails(withPosting(withMedia(TwitterClientBase)))))),
 ) as AbstractConstructor<TwitterClientInstance>;

 export class TwitterClient extends MixedTwitterClient {}
@@ -25,10 +27,12 @@ export type {
  CurrentUserResult,
  FollowingResult,
  GetTweetResult,
+  ListsResult,
  SearchResult,
  TweetData,
  TweetResult,
  TwitterClientOptions,
+  TwitterList,
  TwitterUser,
  UploadMediaResult,
 } from './twitter-client-types.js';