xbird-mcp 0.1.0

package/src/lib/client-user.ts

@@ -0,0 +1,518 @@
+import { TwitterClient } from "./client.ts";
+import { tweetDetailFeatures, viewerFeatures, userTweetsFeatures } from "./features.ts";
+import { fieldToggles } from "./features.ts";
+import { parseTweetsFromInstructions } from "./client-reading.ts";
+import { extractCursorFromInstructions, parseUsersFromInstructions } from "./utils.ts";
+import { TWITTER_V1_BASE } from "./constants.ts";
+import type { Tweet, TwitterUser, AboutInfo } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withUser<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Fetch the currently authenticated user from the account settings
+     * and verify_credentials endpoints.
+     */
+    async getCurrentUser(): Promise<{
+      success: boolean;
+      user?: { id: string; screenName: string; name: string };
+      error?: string;
+    }> {
+      // Try GraphQL Viewer query first
+      try {
+        const { data, errors: gqlErrors } = await this.graphqlGet(
+          "Viewer",
+          { withCommunitiesMemberships: false },
+          viewerFeatures()
+        );
+
+        if (!gqlErrors?.length && data) {
+          const viewer = (data as Record<string, unknown>).viewer as
+            | Record<string, unknown>
+            | undefined;
+          const userResults = viewer?.user_results as
+            | Record<string, unknown>
+            | undefined;
+          const result = userResults?.result as
+            | Record<string, unknown>
+            | undefined;
+
+          if (result) {
+            const core = result.core as Record<string, unknown> | undefined;
+            const legacy = result.legacy as Record<string, unknown> | undefined;
+            const screenName = String(
+              core?.screen_name ?? legacy?.screen_name ?? ""
+            );
+            const name = String(core?.name ?? legacy?.name ?? screenName);
+            const id = String(result.rest_id ?? "");
+
+            if (screenName) {
+              return { success: true, user: { id, screenName, name } };
+            }
+          }
+        }
+      } catch {
+        // Fall through to REST endpoints
+      }
+
+      // Fallback: try REST endpoints
+      const candidateUrls = [
+        "https://x.com/i/api/account/settings.json",
+        "https://api.twitter.com/1.1/account/settings.json",
+        "https://x.com/i/api/account/verify_credentials.json?skip_status=true&include_entities=false",
+        "https://api.twitter.com/1.1/account/verify_credentials.json?skip_status=true&include_entities=false",
+      ];
+
+      const headers = this.getHeaders();
+      const errors: string[] = [];
+
+      for (const url of candidateUrls) {
+        try {
+          const res = await this.fetchWithTimeout(url, {
+            method: "GET",
+            headers,
+          });
+
+          if (!res.ok) {
+            errors.push(`${url}: HTTP ${res.status}`);
+            continue;
+          }
+
+          const json = (await res.json()) as Record<string, unknown>;
+          const screenName = String(
+            json.screen_name ??
+              (json.user as Record<string, unknown>)?.screen_name ??
+              ""
+          );
+          const name = String(
+            json.name ??
+              (json.user as Record<string, unknown>)?.name ??
+              screenName
+          );
+          const id = String(
+            json.id_str ?? json.user_id_str ?? json.id ?? json.user_id ?? ""
+          );
+
+          if (screenName) {
+            return { success: true, user: { id, screenName, name } };
+          }
+
+          errors.push(`${url}: no screen_name in response`);
+        } catch (err) {
+          errors.push(
+            `${url}: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+
+      return {
+        success: false,
+        error: `All endpoints failed: ${errors.join("; ")}`,
+      };
+    }
+
+    /**
+     * Fetch a Twitter user by their screen name (handle).
+     */
+    async getUserByHandle(
+      handle: string
+    ): Promise<{ success: boolean; user?: TwitterUser; error?: string }> {
+      try {
+        const { data, errors } = await this.graphqlGet(
+          "UserByScreenName",
+          {
+            screen_name: handle,
+            withSafetyModeUserFields: true,
+          },
+          tweetDetailFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        const result = (data as Record<string, unknown>)?.user as
+          | Record<string, unknown>
+          | undefined;
+        const userResult = result?.result as Record<string, unknown> | undefined;
+
+        if (!userResult) {
+          return { success: false, error: "User not found" };
+        }
+
+        const legacy = userResult.legacy as Record<string, unknown> | undefined;
+        const core = userResult.core as Record<string, unknown> | undefined;
+        const avatar = userResult.avatar as Record<string, unknown> | undefined;
+        const locationObj = userResult.location as Record<string, unknown> | undefined;
+
+        if (!legacy && !core) {
+          return { success: false, error: "User data unavailable" };
+        }
+
+        const user: TwitterUser = {
+          id: String(userResult.rest_id ?? ""),
+          screenName: String(core?.screen_name ?? legacy?.screen_name ?? ""),
+          name: String(core?.name ?? legacy?.name ?? ""),
+          description: String(legacy?.description ?? ""),
+          followersCount: Number(legacy?.followers_count ?? 0),
+          followingCount: Number(legacy?.friends_count ?? 0),
+          tweetCount: Number(legacy?.statuses_count ?? 0),
+          verified: Boolean(legacy?.verified),
+          profileImageUrl: String(
+            avatar?.image_url ?? legacy?.profile_image_url_https ?? legacy?.profile_image_url ?? ""
+          ),
+          createdAt: String(core?.created_at ?? legacy?.created_at ?? ""),
+          location: locationObj?.location
+            ? String(locationObj.location)
+            : legacy?.location
+              ? String(legacy.location)
+              : undefined,
+          url: legacy?.url ? String(legacy.url) : undefined,
+          isBlueVerified: Boolean(userResult.is_blue_verified),
+        };
+
+        return { success: true, user };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Fetch tweets by a specific user.
+     */
+    async getUserTweets(
+      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,
+          withQuickPromoteEligibilityTweetFields: true,
+          withVoice: true,
+        };
+        if (cursor) variables.cursor = cursor;
+
+        const { data, errors } = await this.graphqlGet(
+          "UserTweets",
+          variables,
+          userTweetsFeatures(),
+          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),
+        };
+      }
+    }
+
+    /**
+     * Fetch followers of a user.
+     */
+    async getFollowers(
+      userId: string,
+      count?: number,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      users: TwitterUser[];
+      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(
+          "Followers",
+          variables,
+          tweetDetailFeatures()
+        );
+
+        if (errors?.length) {
+          // GraphQL fallback to REST
+          return this._getFollowersREST(userId, cursor);
+        }
+
+        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, users: [] };
+
+        const users = parseUsersFromInstructions(instructions);
+        const nextCursor = extractCursorFromInstructions(instructions);
+        return { success: true, users, cursor: nextCursor };
+      } catch {
+        return this._getFollowersREST(userId, cursor);
+      }
+    }
+
+    private async _getFollowersREST(
+      userId: string,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      users: TwitterUser[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const params = new URLSearchParams({
+          user_id: userId,
+          count: "200",
+          skip_status: "true",
+          include_user_entities: "false",
+        });
+        if (cursor) params.set("cursor", cursor);
+
+        const url = `${TWITTER_V1_BASE}/followers/list.json?${params}`;
+        const res = await this.fetchWithTimeout(url, {
+          method: "GET",
+          headers: this.getHeaders(),
+        });
+
+        if (!res.ok) {
+          return { success: false, users: [], error: `HTTP ${res.status}` };
+        }
+
+        const json = (await res.json()) as Record<string, unknown>;
+        const rawUsers = json.users as Array<Record<string, unknown>> | undefined;
+        const users: TwitterUser[] = (rawUsers ?? []).map((u) => ({
+          id: String(u.id_str ?? u.id ?? ""),
+          screenName: String(u.screen_name ?? ""),
+          name: String(u.name ?? ""),
+          description: String(u.description ?? ""),
+          followersCount: Number(u.followers_count ?? 0),
+          followingCount: Number(u.friends_count ?? 0),
+          tweetCount: Number(u.statuses_count ?? 0),
+          verified: Boolean(u.verified),
+          profileImageUrl: String(u.profile_image_url_https ?? ""),
+          createdAt: String(u.created_at ?? ""),
+          location: u.location ? String(u.location) : undefined,
+          url: u.url ? String(u.url) : undefined,
+          isBlueVerified: Boolean(u.ext_is_blue_verified),
+        }));
+
+        const nextCursor = String(json.next_cursor_str ?? json.next_cursor ?? "");
+        return {
+          success: true,
+          users,
+          cursor: nextCursor && nextCursor !== "0" ? nextCursor : undefined,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          users: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Fetch users that a user is following.
+     */
+    async getFollowing(
+      userId: string,
+      count?: number,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      users: TwitterUser[];
+      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(
+          "Following",
+          variables,
+          tweetDetailFeatures()
+        );
+
+        if (errors?.length) {
+          return this._getFollowingREST(userId, cursor);
+        }
+
+        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, users: [] };
+
+        const users = parseUsersFromInstructions(instructions);
+        const nextCursor = extractCursorFromInstructions(instructions);
+        return { success: true, users, cursor: nextCursor };
+      } catch {
+        return this._getFollowingREST(userId, cursor);
+      }
+    }
+
+    /**
+     * Fetch about/transparency info for a user by screen name.
+     */
+    async getAbout(
+      screenName: string
+    ): Promise<{
+      success: boolean;
+      about?: AboutInfo;
+      error?: string;
+    }> {
+      try {
+        // Try the UserByScreenName query — it may include about data in legacy
+        const { data, errors } = await this.graphqlGet(
+          "UserByScreenName",
+          {
+            screen_name: screenName,
+            withSafetyModeUserFields: true,
+          },
+          tweetDetailFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        const result = (data as Record<string, unknown>)?.user as
+          | Record<string, unknown>
+          | undefined;
+        const userResult = result?.result as Record<string, unknown> | undefined;
+
+        if (!userResult) {
+          return { success: false, error: "User not found" };
+        }
+
+        const legacy = userResult.legacy as Record<string, unknown> | undefined;
+        const core = userResult.core as Record<string, unknown> | undefined;
+        const locationObj = userResult.location as Record<string, unknown> | undefined;
+
+        const about: AboutInfo = {
+          createdAt: core?.created_at
+            ? String(core.created_at)
+            : legacy?.created_at
+              ? String(legacy.created_at)
+              : undefined,
+          accountBasedIn: locationObj?.location
+            ? String(locationObj.location)
+            : legacy?.location
+              ? String(legacy.location)
+              : undefined,
+          source: legacy?.source ? String(legacy.source) : undefined,
+        };
+
+        return { success: true, about };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    private async _getFollowingREST(
+      userId: string,
+      cursor?: string
+    ): Promise<{
+      success: boolean;
+      users: TwitterUser[];
+      cursor?: string;
+      error?: string;
+    }> {
+      try {
+        const params = new URLSearchParams({
+          user_id: userId,
+          count: "200",
+          skip_status: "true",
+          include_user_entities: "false",
+        });
+        if (cursor) params.set("cursor", cursor);
+
+        const url = `${TWITTER_V1_BASE}/friends/list.json?${params}`;
+        const res = await this.fetchWithTimeout(url, {
+          method: "GET",
+          headers: this.getHeaders(),
+        });
+
+        if (!res.ok) {
+          return { success: false, users: [], error: `HTTP ${res.status}` };
+        }
+
+        const json = (await res.json()) as Record<string, unknown>;
+        const rawUsers = json.users as Array<Record<string, unknown>> | undefined;
+        const users: TwitterUser[] = (rawUsers ?? []).map((u) => ({
+          id: String(u.id_str ?? u.id ?? ""),
+          screenName: String(u.screen_name ?? ""),
+          name: String(u.name ?? ""),
+          description: String(u.description ?? ""),
+          followersCount: Number(u.followers_count ?? 0),
+          followingCount: Number(u.friends_count ?? 0),
+          tweetCount: Number(u.statuses_count ?? 0),
+          verified: Boolean(u.verified),
+          profileImageUrl: String(u.profile_image_url_https ?? ""),
+          createdAt: String(u.created_at ?? ""),
+          location: u.location ? String(u.location) : undefined,
+          url: u.url ? String(u.url) : undefined,
+          isBlueVerified: Boolean(u.ext_is_blue_verified),
+        }));
+
+        const nextCursor = String(json.next_cursor_str ?? json.next_cursor ?? "");
+        return {
+          success: true,
+          users,
+          cursor: nextCursor && nextCursor !== "0" ? nextCursor : undefined,
+        };
+      } catch (err) {
+        return {
+          success: false,
+          users: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client.ts

@@ -0,0 +1,134 @@
+import type { Credentials } from "./types.ts";
+import { buildHeaders } from "./headers.ts";
+import { getQueryId, refreshQueryIds } from "./query-ids.ts";
+import { TWITTER_API_BASE } from "./constants.ts";
+
+/** Residential proxy URL from env (e.g. http://user:pass@proxy.example.com:8080) */
+const PROXY_URL = process.env.XBIRD_PROXY_URL || process.env.HTTPS_PROXY || undefined;
+
+export class TwitterClient {
+  credentials: Credentials;
+  protected timeoutMs: number;
+
+  constructor(credentials: Credentials, timeoutMs = 30_000) {
+    this.credentials = credentials;
+    this.timeoutMs = timeoutMs;
+  }
+
+  getHeaders(): Record<string, string> {
+    return buildHeaders(this.credentials);
+  }
+
+  protected async getQueryId(op: string): Promise<string> {
+    return getQueryId(op);
+  }
+
+  protected async refreshIds(): Promise<void> {
+    await refreshQueryIds({ force: true });
+  }
+
+  async fetchWithTimeout(
+    url: string,
+    init?: RequestInit
+  ): Promise<Response> {
+    const opts: RequestInit & { proxy?: string } = { ...init };
+    if (PROXY_URL) opts.proxy = PROXY_URL;
+
+    if (this.timeoutMs <= 0) return fetch(url, opts);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...opts, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * GraphQL GET request — used for read operations.
+   */
+  async graphqlGet<T = unknown>(
+    operationName: string,
+    variables: Record<string, unknown>,
+    features: Record<string, boolean>,
+    fieldToggles?: Record<string, boolean>
+  ): Promise<{ data?: T; errors?: Array<{ message: string; code?: number }> }> {
+    const queryId = await this.getQueryId(operationName);
+    const params = new URLSearchParams({
+      variables: JSON.stringify(variables),
+      features: JSON.stringify(features),
+    });
+    if (fieldToggles) {
+      params.set("fieldToggles", JSON.stringify(fieldToggles));
+    }
+
+    const url = `${TWITTER_API_BASE}/${queryId}/${operationName}?${params.toString()}`;
+    let res = await this.fetchWithTimeout(url, {
+      method: "GET",
+      headers: this.getHeaders(),
+    });
+
+    // Auto-refresh query IDs on 404
+    if (res.status === 404) {
+      await this.refreshIds();
+      const newQueryId = await this.getQueryId(operationName);
+      const newUrl = `${TWITTER_API_BASE}/${newQueryId}/${operationName}?${params.toString()}`;
+      res = await this.fetchWithTimeout(newUrl, {
+        method: "GET",
+        headers: this.getHeaders(),
+      });
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      return { errors: [{ message: `HTTP ${res.status}: ${text.slice(0, 200)}` }] };
+    }
+
+    return (await res.json()) as { data?: T; errors?: Array<{ message: string; code?: number }> };
+  }
+
+  /**
+   * GraphQL POST request — used for mutations.
+   */
+  async graphqlPost<T = unknown>(
+    operationName: string,
+    variables: Record<string, unknown>,
+    features?: Record<string, boolean>
+  ): Promise<{ data?: T; errors?: Array<{ message: string; code?: number }> }> {
+    const queryId = await this.getQueryId(operationName);
+    const url = `${TWITTER_API_BASE}/${queryId}/${operationName}`;
+    const body = JSON.stringify({ variables, features, queryId });
+
+    let res = await this.fetchWithTimeout(url, {
+      method: "POST",
+      headers: this.getHeaders(),
+      body,
+    });
+
+    // Auto-refresh query IDs on 404
+    if (res.status === 404) {
+      await this.refreshIds();
+      const newQueryId = await this.getQueryId(operationName);
+      const newUrl = `${TWITTER_API_BASE}/${newQueryId}/${operationName}`;
+      const newBody = JSON.stringify({ variables, features, queryId: newQueryId });
+      res = await this.fetchWithTimeout(newUrl, {
+        method: "POST",
+        headers: this.getHeaders(),
+        body: newBody,
+      });
+    }
+
+    if (!res.ok) {
+      const text = await res.text();
+      return { errors: [{ message: `HTTP ${res.status}: ${text.slice(0, 500)}` }] };
+    }
+
+    return (await res.json()) as { data?: T; errors?: Array<{ message: string; code?: number }> };
+  }
+
+  formatErrors(
+    errors: Array<{ message: string; code?: number }>
+  ): string {
+    return errors.map((e) => e.message).join(", ");
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,22 @@
+import type { XbirdConfig } from "./types.ts";
+
+const GLOBAL_CONFIG_PATH = `${process.env.HOME}/.config/xbird/config.json`;
+const PROJECT_CONFIG_PATH = ".xbirdrc.json";
+
+async function loadJsonFile(path: string): Promise<Partial<XbirdConfig>> {
+  try {
+    const file = Bun.file(path);
+    if (!(await file.exists())) return {};
+    return (await file.json()) as Partial<XbirdConfig>;
+  } catch {
+    return {};
+  }
+}
+
+export async function loadConfig(): Promise<XbirdConfig> {
+  const [global, project] = await Promise.all([
+    loadJsonFile(GLOBAL_CONFIG_PATH),
+    loadJsonFile(PROJECT_CONFIG_PATH),
+  ]);
+  return { ...global, ...project };
+}