xbird-mcp 0.1.0

package/src/lib/client-reading.ts

@@ -0,0 +1,452 @@
+import { TwitterClient } from "./client.ts";
+import { tweetDetailFeatures, fieldToggles } from "./features.ts";
+import type { Tweet, TweetMedia, TweetUrl } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+/**
+ * Parse a single tweet from a GraphQL tweet result object.
+ * @param result - raw tweet result from GraphQL
+ * @param maxQuoteDepth - max recursion depth for quoted tweets (default 1)
+ */
+export function parseTweetResult(result: unknown, maxQuoteDepth = 1): Tweet | null {
+  const raw = result as Record<string, unknown> | null | undefined;
+  if (!raw) return null;
+
+  const tweet = (raw.tweet ?? raw) as Record<string, unknown>;
+  const legacy = tweet?.legacy as Record<string, unknown> | undefined;
+  const core = tweet?.core as Record<string, unknown> | undefined;
+  const userResults = core?.user_results as Record<string, unknown> | undefined;
+  const user = userResults?.result as Record<string, unknown> | undefined;
+
+  if (!legacy || !user) return null;
+
+  const userLegacy = user.legacy as Record<string, unknown> | undefined;
+  const userCore = user.core as Record<string, unknown> | undefined;
+  const views = tweet.views as Record<string, unknown> | undefined;
+
+  // Note tweets (long posts) — use note text if longer than legacy text
+  const noteTweet = tweet.note_tweet as Record<string, unknown> | undefined;
+  const noteResults = noteTweet?.note_tweet_results as Record<string, unknown> | undefined;
+  const noteResult = noteResults?.result as Record<string, unknown> | undefined;
+  const noteText = noteResult?.text as string | undefined;
+  const legacyText = String(legacy.full_text ?? legacy.text ?? "");
+  const text = noteText && noteText.length > legacyText.length ? noteText : legacyText;
+
+  // Parse media with video info
+  const extMedia = (
+    (legacy.extended_entities as Record<string, unknown>)?.media ??
+    (legacy.entities as Record<string, unknown>)?.media
+  ) as Array<Record<string, unknown>> | undefined;
+
+  const media: TweetMedia[] | undefined = extMedia?.map((m) => {
+    const videoInfo = m.video_info as Record<string, unknown> | undefined;
+    const variants = videoInfo?.variants as Array<Record<string, unknown>> | undefined;
+    // Pick highest bitrate mp4 variant
+    const mp4Variants = variants?.filter((v) => String(v.content_type ?? "") === "video/mp4") ?? [];
+    mp4Variants.sort((a, b) => Number(b.bitrate ?? 0) - Number(a.bitrate ?? 0));
+    const bestVariant = mp4Variants[0];
+
+    return {
+      type: String(m.type ?? "photo") as TweetMedia["type"],
+      url: String(m.media_url_https ?? m.media_url ?? ""),
+      width: m.original_info
+        ? Number((m.original_info as Record<string, unknown>).width ?? 0)
+        : undefined,
+      height: m.original_info
+        ? Number((m.original_info as Record<string, unknown>).height ?? 0)
+        : undefined,
+      videoUrl: bestVariant ? String(bestVariant.url ?? "") : undefined,
+      durationMs: videoInfo?.duration_millis != null
+        ? Number(videoInfo.duration_millis)
+        : undefined,
+    };
+  });
+
+  // Parse URLs
+  const entityUrls = (legacy.entities as Record<string, unknown>)?.urls as
+    | Array<Record<string, unknown>>
+    | undefined;
+  const urls: TweetUrl[] | undefined = entityUrls?.map((u) => ({
+    url: String(u.url ?? ""),
+    expandedUrl: String(u.expanded_url ?? ""),
+    displayUrl: String(u.display_url ?? ""),
+  }));
+
+  // Parse quoted tweet with depth limit
+  let quotedTweet: Tweet | undefined;
+  if (maxQuoteDepth > 0) {
+    const quotedResult = legacy.quoted_status_result as
+      | Record<string, unknown>
+      | undefined;
+    quotedTweet = quotedResult
+      ? (parseTweetResult(quotedResult.result ?? quotedResult, maxQuoteDepth - 1) ?? undefined)
+      : undefined;
+  }
+
+  return {
+    id: String(tweet.rest_id ?? legacy.id_str ?? ""),
+    text,
+    authorId: String(user.rest_id ?? userLegacy?.id_str ?? ""),
+    authorName: String(userCore?.name ?? userLegacy?.name ?? ""),
+    authorHandle: String(userCore?.screen_name ?? userLegacy?.screen_name ?? ""),
+    createdAt: String(legacy.created_at ?? ""),
+    likeCount: Number(legacy.favorite_count ?? 0),
+    retweetCount: Number(legacy.retweet_count ?? 0),
+    replyCount: Number(legacy.reply_count ?? 0),
+    quoteCount: Number(legacy.quote_count ?? 0),
+    bookmarkCount: Number(legacy.bookmark_count ?? 0),
+    viewCount: parseInt(String(views?.count ?? "0"), 10),
+    isRetweet: !!legacy.retweeted_status_result,
+    isReply: !!legacy.in_reply_to_status_id_str,
+    inReplyToId: legacy.in_reply_to_status_id_str
+      ? String(legacy.in_reply_to_status_id_str)
+      : undefined,
+    conversationId: legacy.conversation_id_str
+      ? String(legacy.conversation_id_str)
+      : undefined,
+    lang: legacy.lang ? String(legacy.lang) : undefined,
+    media: media?.length ? media : undefined,
+    urls: urls?.length ? urls : undefined,
+    quotedTweet: quotedTweet ?? undefined,
+  };
+}
+
+/**
+ * Parse multiple tweets from GraphQL timeline/search instructions.
+ */
+export function parseTweetsFromInstructions(instructions: unknown[]): Tweet[] {
+  const tweets: Tweet[] = [];
+
+  for (const inst of instructions ?? []) {
+    const instruction = inst as Record<string, unknown>;
+    const entries = (instruction.entries ?? instruction.moduleItems ?? []) as Array<
+      Record<string, unknown>
+    >;
+
+    for (const entry of entries) {
+      const content = entry.content as Record<string, unknown> | undefined;
+      const item = entry.item as Record<string, unknown> | undefined;
+
+      const itemContent =
+        (content?.itemContent as Record<string, unknown>) ??
+        (item?.itemContent as Record<string, unknown>);
+
+      const tweetResults = itemContent?.tweet_results as
+        | Record<string, unknown>
+        | undefined;
+      const result = tweetResults?.result;
+
+      if (result) {
+        const t = parseTweetResult(result);
+        if (t) tweets.push(t);
+      }
+    }
+  }
+
+  return tweets;
+}
+
+export function withReading<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Fetch a single tweet by its ID.
+     */
+    async getTweet(
+      tweetId: string
+    ): Promise<{ success: boolean; tweet?: Tweet; error?: string }> {
+      try {
+        const { data, errors } = await this.graphqlGet(
+          "TweetDetail",
+          {
+            focalTweetId: tweetId,
+            with_rux_injections: false,
+            rankingMode: "Relevance",
+            includePromotedContent: true,
+            withCommunity: true,
+            withQuickPromoteEligibilityTweetFields: true,
+            withBirdwatchNotes: true,
+            withVoice: true,
+          },
+          tweetDetailFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        const conversation = (data as Record<string, unknown>)
+          ?.threaded_conversation_with_injections_v2 as
+          | Record<string, unknown>
+          | undefined;
+        const instructions = conversation?.instructions as
+          | unknown[]
+          | undefined;
+
+        if (!instructions) {
+          return { success: false, error: "No tweet data in response" };
+        }
+
+        // Find the focal tweet — first entry whose entryId starts with "tweet-"
+        for (const inst of instructions) {
+          const instruction = inst as Record<string, unknown>;
+          const entries = (instruction.entries ?? []) as Array<
+            Record<string, unknown>
+          >;
+
+          for (const entry of entries) {
+            const entryId = entry.entryId as string | undefined;
+            if (!entryId?.startsWith("tweet-")) continue;
+
+            const content = entry.content as
+              | Record<string, unknown>
+              | undefined;
+            const itemContent = content?.itemContent as
+              | Record<string, unknown>
+              | undefined;
+            const tweetResults = itemContent?.tweet_results as
+              | Record<string, unknown>
+              | undefined;
+            const result = tweetResults?.result;
+
+            if (result) {
+              const tweet = parseTweetResult(result);
+              if (tweet) {
+                return { success: true, tweet };
+              }
+            }
+          }
+        }
+
+        return { success: false, error: "Tweet not found in response" };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Fetch replies to a specific tweet.
+     * Uses the same TweetDetail query as getThread but filters to only reply entries.
+     */
+    async getReplies(
+      tweetId: string,
+      count = 20,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      tweets: Tweet[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const variables: Record<string, unknown> = {
+          focalTweetId: tweetId,
+          with_rux_injections: false,
+          rankingMode: "Relevance",
+          includePromotedContent: true,
+          withCommunity: true,
+          withQuickPromoteEligibilityTweetFields: true,
+          withBirdwatchNotes: true,
+          withVoice: true,
+        };
+        if (cursor) variables.cursor = cursor;
+
+        const { data, errors } = await this.graphqlGet(
+          "TweetDetail",
+          variables,
+          tweetDetailFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return {
+            success: false,
+            tweets: [],
+            error: this.formatErrors(errors),
+          };
+        }
+
+        const conversation = (data as Record<string, unknown>)
+          ?.threaded_conversation_with_injections_v2 as
+          | Record<string, unknown>
+          | undefined;
+        const instructions = conversation?.instructions as
+          | unknown[]
+          | undefined;
+
+        if (!instructions) {
+          return { success: false, tweets: [], error: "No reply data in response" };
+        }
+
+        const tweets: Tweet[] = [];
+        let nextCursor: string | undefined;
+
+        for (const inst of instructions) {
+          const instruction = inst as Record<string, unknown>;
+          const entries = (instruction.entries ?? []) as Array<
+            Record<string, unknown>
+          >;
+
+          for (const entry of entries) {
+            const entryId = entry.entryId as string | undefined;
+
+            // Extract cursor from cursor entries
+            if (entryId?.startsWith("cursor-bottom-")) {
+              const content = entry.content as Record<string, unknown> | undefined;
+              const value = content?.value as string | undefined;
+              if (value) nextCursor = value;
+              continue;
+            }
+
+            // Only process conversationthread- entries (replies)
+            if (!entryId?.startsWith("conversationthread-")) continue;
+
+            const content = entry.content as Record<string, unknown> | undefined;
+            const items = content?.items as Array<Record<string, unknown>> | undefined;
+
+            if (items) {
+              for (const moduleItem of items) {
+                const moduleItemContent = (
+                  moduleItem.item as Record<string, unknown> | undefined
+                )?.itemContent as Record<string, unknown> | undefined;
+                const tweetResults = moduleItemContent?.tweet_results as
+                  | Record<string, unknown>
+                  | undefined;
+                const result = tweetResults?.result;
+                if (result) {
+                  const t = parseTweetResult(result);
+                  // Filter out the main tweet itself
+                  if (t && t.id !== tweetId) tweets.push(t);
+                }
+              }
+            }
+          }
+        }
+
+        return {
+          success: true,
+          tweets: tweets.slice(0, count),
+          cursor: nextCursor,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          tweets: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Fetch a full thread (all tweets in the conversation).
+     */
+    async getThread(
+      tweetId: string
+    ): Promise<{ success: boolean; tweets: Tweet[]; error?: string }> {
+      try {
+        const { data, errors } = await this.graphqlGet(
+          "TweetDetail",
+          {
+            focalTweetId: tweetId,
+            with_rux_injections: false,
+            rankingMode: "Relevance",
+            includePromotedContent: true,
+            withCommunity: true,
+            withQuickPromoteEligibilityTweetFields: true,
+            withBirdwatchNotes: true,
+            withVoice: true,
+          },
+          tweetDetailFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return {
+            success: false,
+            tweets: [],
+            error: this.formatErrors(errors),
+          };
+        }
+
+        const conversation = (data as Record<string, unknown>)
+          ?.threaded_conversation_with_injections_v2 as
+          | Record<string, unknown>
+          | undefined;
+        const instructions = conversation?.instructions as
+          | unknown[]
+          | undefined;
+
+        if (!instructions) {
+          return {
+            success: false,
+            tweets: [],
+            error: "No thread data in response",
+          };
+        }
+
+        const tweets: Tweet[] = [];
+
+        for (const inst of instructions) {
+          const instruction = inst as Record<string, unknown>;
+          const entries = (instruction.entries ?? []) as Array<
+            Record<string, unknown>
+          >;
+
+          for (const entry of entries) {
+            const content = entry.content as
+              | Record<string, unknown>
+              | undefined;
+
+            // Direct tweet entries
+            const itemContent = content?.itemContent as
+              | Record<string, unknown>
+              | undefined;
+            if (itemContent) {
+              const tweetResults = itemContent.tweet_results as
+                | Record<string, unknown>
+                | undefined;
+              const result = tweetResults?.result;
+              if (result) {
+                const t = parseTweetResult(result);
+                if (t) tweets.push(t);
+              }
+            }
+
+            // Conversational module entries (thread items)
+            const items = content?.items as
+              | Array<Record<string, unknown>>
+              | undefined;
+            if (items) {
+              for (const moduleItem of items) {
+                const moduleItemContent = (
+                  moduleItem.item as Record<string, unknown> | undefined
+                )?.itemContent as Record<string, unknown> | undefined;
+                const tweetResults = moduleItemContent?.tweet_results as
+                  | Record<string, unknown>
+                  | undefined;
+                const result = tweetResults?.result;
+                if (result) {
+                  const t = parseTweetResult(result);
+                  if (t) tweets.push(t);
+                }
+              }
+            }
+          }
+        }
+
+        return { success: true, tweets };
+      } catch (err) {
+        return {
+          success: false,
+          tweets: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-search.ts

@@ -0,0 +1,156 @@
+import { TwitterClient } from "./client.ts";
+import { TWITTER_API_BASE } from "./constants.ts";
+import { searchFeatures } from "./features.ts";
+import { parseTweetsFromInstructions } from "./client-reading.ts";
+import { extractCursorFromInstructions } from "./utils.ts";
+import type { Tweet } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+/** Extra query IDs to try if the primary one fails */
+const SEARCH_FALLBACK_IDS = [
+  "M1jEez78PEfVfbQLvlWMvQ",
+  "5h0kNbk3ii97rmfY6CdgAA",
+  "Tp1sewRU1AsZpBWhqCZicQ",
+];
+
+export function withSearch<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Search for tweets matching a query.
+     * Uses POST method as required by Twitter's SearchTimeline endpoint.
+     */
+    async search(
+      query: string,
+      count?: number,
+      cursor?: string
+    ): Promise<{ success: boolean; tweets: Tweet[]; cursor?: string; error?: string }> {
+      const variables: Record<string, unknown> = {
+        rawQuery: query,
+        count: count ?? 20,
+        querySource: "typed_query",
+        product: "Latest",
+      };
+      if (cursor) variables.cursor = cursor;
+      const features = searchFeatures();
+
+      // Build list of query IDs to try
+      const primaryId = await this.getQueryId("SearchTimeline");
+      const queryIds = Array.from(
+        new Set([primaryId, ...SEARCH_FALLBACK_IDS])
+      );
+
+      let lastError = "";
+      let had404 = false;
+
+      for (const queryId of queryIds) {
+        try {
+          const params = new URLSearchParams({
+            variables: JSON.stringify(variables),
+          });
+          const url = `${TWITTER_API_BASE}/${queryId}/SearchTimeline?${params}`;
+
+          const res = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.getHeaders(),
+            body: JSON.stringify({ features, queryId }),
+          });
+
+          if (res.status === 404) {
+            had404 = true;
+            lastError = `HTTP 404`;
+            continue;
+          }
+
+          if (!res.ok) {
+            const text = await res.text();
+            lastError = `HTTP ${res.status}: ${text.slice(0, 300)}`;
+            continue;
+          }
+
+          const json = (await res.json()) as {
+            data?: Record<string, unknown>;
+            errors?: Array<{ message: string }>;
+          };
+
+          if (json.errors?.length) {
+            lastError = json.errors.map((e) => e.message).join(", ");
+            continue;
+          }
+
+          const searchByRawQuery = json.data?.search_by_raw_query as
+            | Record<string, unknown>
+            | undefined;
+          const searchTimeline = searchByRawQuery?.search_timeline as
+            | Record<string, unknown>
+            | undefined;
+          const timeline = searchTimeline?.timeline as
+            | Record<string, unknown>
+            | undefined;
+          const instructions = timeline?.instructions as
+            | unknown[]
+            | undefined;
+
+          if (!instructions) {
+            return { success: true, tweets: [] };
+          }
+
+          const tweets = parseTweetsFromInstructions(instructions);
+          const nextCursor = extractCursorFromInstructions(instructions);
+          return { success: true, tweets, cursor: nextCursor };
+        } catch (err) {
+          lastError = err instanceof Error ? err.message : String(err);
+        }
+      }
+
+      // If we had 404s, try refreshing query IDs and retry with new primary
+      if (had404) {
+        try {
+          await this.refreshIds();
+          const newId = await this.getQueryId("SearchTimeline");
+          const params = new URLSearchParams({
+            variables: JSON.stringify(variables),
+          });
+          const url = `${TWITTER_API_BASE}/${newId}/SearchTimeline?${params}`;
+
+          const res = await this.fetchWithTimeout(url, {
+            method: "POST",
+            headers: this.getHeaders(),
+            body: JSON.stringify({ features, queryId: newId }),
+          });
+
+          if (res.ok) {
+            const json = (await res.json()) as {
+              data?: Record<string, unknown>;
+            };
+            const searchByRawQuery = json.data?.search_by_raw_query as
+              | Record<string, unknown>
+              | undefined;
+            const searchTimeline = searchByRawQuery?.search_timeline as
+              | Record<string, unknown>
+              | undefined;
+            const timeline = searchTimeline?.timeline as
+              | Record<string, unknown>
+              | undefined;
+            const instructions = timeline?.instructions as
+              | unknown[]
+              | undefined;
+
+            const tweets = instructions
+              ? parseTweetsFromInstructions(instructions)
+              : [];
+            const nextCursor = instructions
+              ? extractCursorFromInstructions(instructions)
+              : undefined;
+            return { success: true, tweets, cursor: nextCursor };
+          }
+        } catch {
+          // fall through to error
+        }
+      }
+
+      return { success: false, tweets: [], error: lastError };
+    }
+  };
+}

package/src/lib/client-timeline.ts

@@ -0,0 +1,98 @@
+import { TwitterClient } from "./client.ts";
+import { timelineFeatures } from "./features.ts";
+import { parseTweetsFromInstructions } from "./client-reading.ts";
+import { extractCursorFromInstructions } from "./utils.ts";
+import type { Tweet } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withTimeline<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Fetch the authenticated user's home timeline.
+     * @param following - when true or undefined, uses HomeLatestTimeline (chronological/following feed).
+     *   When false, also uses HomeLatestTimeline for now. "For You" would need the HomeTimeline operation.
+     */
+    async home(
+      count?: number,
+      cursor?: string,
+      following?: boolean
+    ): Promise<{ success: boolean; tweets: Tweet[]; cursor?: string; error?: string }> {
+      try {
+        const variables: Record<string, unknown> = {
+          count: count ?? 20,
+          includePromotedContent: false,
+          latestControlAvailable: true,
+        };
+        if (cursor) variables.cursor = cursor;
+
+        const { data, errors } = await this.graphqlGet(
+          "HomeLatestTimeline",
+          variables,
+          timelineFeatures()
+        );
+
+        if (errors?.length) {
+          return {
+            success: false,
+            tweets: [],
+            error: this.formatErrors(errors),
+          };
+        }
+
+        const home = (data as Record<string, unknown>)?.home as
+          | Record<string, unknown>
+          | undefined;
+        const homeTimeline = home?.home_timeline_urt as
+          | Record<string, unknown>
+          | undefined;
+        const instructions = homeTimeline?.instructions as
+          | unknown[]
+          | undefined;
+
+        if (!instructions) {
+          return { success: true, tweets: [] };
+        }
+
+        const tweets = parseTweetsFromInstructions(instructions);
+        const nextCursor = extractCursorFromInstructions(instructions);
+        return { success: true, tweets, cursor: nextCursor };
+      } catch (err) {
+        return {
+          success: false,
+          tweets: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Fetch recent mentions for a given handle.
+     * Uses search with the `to:handle` operator.
+     */
+    async mentions(
+      handle: string,
+      count?: number
+    ): Promise<{ success: boolean; tweets: Tweet[]; error?: string }> {
+      // This relies on the search mixin being composed before timeline.
+      // We cast to access the search method.
+      const self = this as unknown as {
+        search: (
+          query: string,
+          count?: number
+        ) => Promise<{ success: boolean; tweets: Tweet[]; error?: string }>;
+      };
+
+      if (typeof self.search !== "function") {
+        return {
+          success: false,
+          tweets: [],
+          error: "Search mixin is required for mentions()",
+        };
+      }
+
+      return self.search(`to:${handle}`, count);
+    }
+  };
+}