xbird-mcp 0.1.0

package/src/lib/client-engagement.ts

@@ -0,0 +1,152 @@
+import { TwitterClient } from "./client.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withEngagement<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Like a tweet.
+     */
+    async like(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("FavoriteTweet", {
+          tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Unlike a tweet.
+     */
+    async unlike(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("UnfavoriteTweet", {
+          tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Retweet a tweet.
+     */
+    async retweet(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("CreateRetweet", {
+          tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Undo a retweet.
+     */
+    async unretweet(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("DeleteRetweet", {
+          source_tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Bookmark a tweet.
+     */
+    async bookmark(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("CreateBookmark", {
+          tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Remove a tweet from bookmarks.
+     */
+    async unbookmark(
+      tweetId: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const { errors } = await this.graphqlPost("DeleteBookmark", {
+          tweet_id: tweetId,
+        });
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-follow.ts

@@ -0,0 +1,90 @@
+import { TwitterClient } from "./client.ts";
+import { TWITTER_V1_BASE } from "./constants.ts";
+import { buildBaseHeaders } from "./headers.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withFollow<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Follow a user by their screen name.
+     */
+    async follow(
+      handle: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const headers = buildBaseHeaders(this.credentials);
+        headers["content-type"] = "application/x-www-form-urlencoded";
+
+        const body = new URLSearchParams({
+          screen_name: handle,
+        });
+
+        const res = await this.fetchWithTimeout(
+          `${TWITTER_V1_BASE}/friendships/create.json`,
+          {
+            method: "POST",
+            headers,
+            body: body.toString(),
+          }
+        );
+
+        if (!res.ok) {
+          const text = await res.text();
+          return {
+            success: false,
+            error: `HTTP ${res.status}: ${text.slice(0, 200)}`,
+          };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Unfollow a user by their screen name.
+     */
+    async unfollow(
+      handle: string
+    ): Promise<{ success: boolean; error?: string }> {
+      try {
+        const headers = buildBaseHeaders(this.credentials);
+        headers["content-type"] = "application/x-www-form-urlencoded";
+
+        const body = new URLSearchParams({
+          screen_name: handle,
+        });
+
+        const res = await this.fetchWithTimeout(
+          `${TWITTER_V1_BASE}/friendships/destroy.json`,
+          {
+            method: "POST",
+            headers,
+            body: body.toString(),
+          }
+        );
+
+        if (!res.ok) {
+          const text = await res.text();
+          return {
+            success: false,
+            error: `HTTP ${res.status}: ${text.slice(0, 200)}`,
+          };
+        }
+
+        return { success: true };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-full.ts

@@ -0,0 +1,48 @@
+import { TwitterClient } from "./client.ts";
+import { withUser } from "./client-user.ts";
+import { withReading } from "./client-reading.ts";
+import { withPosting } from "./client-posting.ts";
+import { withSearch } from "./client-search.ts";
+import { withTimeline } from "./client-timeline.ts";
+import { withEngagement } from "./client-engagement.ts";
+import { withFollow } from "./client-follow.ts";
+import { withLists } from "./client-lists.ts";
+import { withNews } from "./client-news.ts";
+import { withBookmarks } from "./client-bookmarks.ts";
+import { withLikes } from "./client-likes.ts";
+import { withMedia } from "./client-media.ts";
+
+/**
+ * Full-featured Twitter/X client composed from all mixins.
+ *
+ * Composition order matters: withTimeline depends on withSearch (for mentions()),
+ * so withSearch must be applied before withTimeline.
+ */
+const FullClient = withMedia(
+  withLikes(
+    withBookmarks(
+      withNews(
+        withLists(
+          withFollow(
+            withEngagement(
+              withTimeline(
+                withSearch(
+                  withPosting(
+                    withReading(
+                      withUser(TwitterClient)
+                    )
+                  )
+                )
+              )
+            )
+          )
+        )
+      )
+    )
+  )
+);
+
+export class XClient extends FullClient {}
+
+// Re-export the parsers for use elsewhere
+export { parseTweetResult, parseTweetsFromInstructions } from "./client-reading.ts";

package/src/lib/client-likes.ts

@@ -0,0 +1,62 @@
+import { TwitterClient } from "./client.ts";
+import { likesFeatures, fieldToggles } 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 withLikes<T extends Constructor>(Base: T) {
+  return class extends Base {
+    async getLikes(
+      userId: string,
+      count?: number,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      tweets: Tweet[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const variables: Record<string, unknown> = {
+          userId,
+          count: count ?? 20,
+          includePromotedContent: false,
+        };
+        if (cursor) variables.cursor = cursor;
+
+        const { data, errors } = await this.graphqlGet(
+          "Likes",
+          variables,
+          likesFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return { success: false, tweets: [], error: this.formatErrors(errors) };
+        }
+
+        const userResult = (data as Record<string, unknown>)?.user as Record<string, unknown> | undefined;
+        const result = userResult?.result as Record<string, unknown> | undefined;
+        const timeline = result?.timeline_v2 as Record<string, unknown> | undefined
+          ?? result?.timeline as Record<string, unknown> | undefined;
+        const tl = timeline?.timeline as Record<string, unknown> | undefined;
+        const instructions = tl?.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),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-lists.ts

@@ -0,0 +1,227 @@
+import { TwitterClient } from "./client.ts";
+import { listFeatures, fieldToggles } from "./features.ts";
+import { parseTweetsFromInstructions } from "./client-reading.ts";
+import { extractCursorFromInstructions } from "./utils.ts";
+import type { Tweet, TwitterList, PaginatedResult } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+function parseListResult(result: unknown): TwitterList | null {
+  const raw = result as Record<string, unknown> | null | undefined;
+  if (!raw) return null;
+
+  const legacy = raw.legacy as Record<string, unknown> | undefined;
+  if (!legacy) return null;
+
+  const ownerResults = (raw.core ?? raw.user_results) as Record<string, unknown> | undefined;
+  const ownerResultA = (ownerResults?.user_results as Record<string, unknown> | undefined)?.result as Record<string, unknown> | undefined;
+  const ownerResult = ownerResultA ?? ownerResults?.result as Record<string, unknown> | undefined;
+  const ownerLegacy = ownerResult?.legacy as Record<string, unknown> | undefined;
+  const ownerCore = ownerResult?.core as Record<string, unknown> | undefined;
+
+  let owner: TwitterList["owner"];
+  if (ownerResult) {
+    owner = {
+      id: String(ownerResult.rest_id ?? ""),
+      screenName: String(ownerCore?.screen_name ?? ownerLegacy?.screen_name ?? ""),
+      name: String(ownerCore?.name ?? ownerLegacy?.name ?? ""),
+    };
+  }
+
+  return {
+    id: String(raw.id_str ?? raw.rest_id ?? legacy.id_str ?? ""),
+    name: String(legacy.name ?? raw.name ?? ""),
+    description: String(legacy.description ?? ""),
+    memberCount: Number(legacy.member_count ?? 0),
+    subscriberCount: Number(legacy.subscriber_count ?? 0),
+    isPrivate: String(legacy.mode ?? "public") === "private",
+    createdAt: String(legacy.created_at ?? ""),
+    owner,
+  };
+}
+
+function parseListsFromInstructions(instructions: unknown[]): TwitterList[] {
+  const lists: TwitterList[] = [];
+
+  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;
+      const itemContent = content?.itemContent as Record<string, unknown> | undefined;
+      const listResults = itemContent?.list_results as Record<string, unknown> | undefined;
+      const listResult = (itemContent?.list as Record<string, unknown> | undefined)
+        ?? (listResults?.result as Record<string, unknown> | undefined);
+
+      if (listResult) {
+        const list = parseListResult(listResult);
+        if (list) lists.push(list);
+      }
+    }
+  }
+
+  return lists;
+}
+
+export function withLists<T extends Constructor>(Base: T) {
+  return class extends Base {
+    async getOwnedLists(): Promise<{
+      success: boolean;
+      lists: TwitterList[];
+      error?: string;
+    }> {
+      try {
+        // First get current user ID
+        const self = this as unknown as {
+          getCurrentUser: () => Promise<{
+            success: boolean;
+            user?: { id: string };
+          }>;
+        };
+
+        let userId: string | undefined;
+        if (typeof self.getCurrentUser === "function") {
+          const current = await self.getCurrentUser();
+          userId = current.user?.id;
+        }
+        if (!userId) {
+          return { success: false, lists: [], error: "Could not determine user ID" };
+        }
+
+        const { data, errors } = await this.graphqlGet(
+          "ListOwnerships",
+          {
+            userId,
+            count: 100,
+            isListMemberTargetUserId: "0",
+          },
+          listFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, lists: [], error: this.formatErrors(errors) };
+        }
+
+        const userResult = (data as Record<string, unknown>)?.user as Record<string, unknown> | undefined;
+        const result = userResult?.result as Record<string, unknown> | undefined;
+        const timeline = result?.timeline as Record<string, unknown> | undefined;
+        const tl = timeline?.timeline as Record<string, unknown> | undefined;
+        const instructions = tl?.instructions as unknown[] | undefined;
+
+        if (!instructions) return { success: true, lists: [] };
+
+        const lists = parseListsFromInstructions(instructions);
+        return { success: true, lists };
+      } catch (err) {
+        return {
+          success: false,
+          lists: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    async getListMemberships(): Promise<{
+      success: boolean;
+      lists: TwitterList[];
+      error?: string;
+    }> {
+      try {
+        const self = this as unknown as {
+          getCurrentUser: () => Promise<{
+            success: boolean;
+            user?: { id: string };
+          }>;
+        };
+
+        let userId: string | undefined;
+        if (typeof self.getCurrentUser === "function") {
+          const current = await self.getCurrentUser();
+          userId = current.user?.id;
+        }
+        if (!userId) {
+          return { success: false, lists: [], error: "Could not determine user ID" };
+        }
+
+        const { data, errors } = await this.graphqlGet(
+          "ListMemberships",
+          {
+            userId,
+            count: 100,
+          },
+          listFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, lists: [], error: this.formatErrors(errors) };
+        }
+
+        const userResult = (data as Record<string, unknown>)?.user as Record<string, unknown> | undefined;
+        const result = userResult?.result as Record<string, unknown> | undefined;
+        const timeline = result?.timeline as Record<string, unknown> | undefined;
+        const tl = timeline?.timeline as Record<string, unknown> | undefined;
+        const instructions = tl?.instructions as unknown[] | undefined;
+
+        if (!instructions) return { success: true, lists: [] };
+
+        const lists = parseListsFromInstructions(instructions);
+        return { success: true, lists };
+      } catch (err) {
+        return {
+          success: false,
+          lists: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    async getListTimeline(
+      listId: string,
+      count?: number,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      tweets: Tweet[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const variables: Record<string, unknown> = {
+          listId,
+          count: count ?? 20,
+        };
+        if (cursor) variables.cursor = cursor;
+
+        const { data, errors } = await this.graphqlGet(
+          "ListLatestTweetsTimeline",
+          variables,
+          listFeatures(),
+          fieldToggles()
+        );
+
+        if (errors?.length) {
+          return { success: false, tweets: [], error: this.formatErrors(errors) };
+        }
+
+        const list = (data as Record<string, unknown>)?.list as Record<string, unknown> | undefined;
+        const tweetsTimeline = list?.tweets_timeline as Record<string, unknown> | undefined;
+        const timeline = tweetsTimeline?.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) {
+        return {
+          success: false,
+          tweets: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}