xbird-mcp 0.1.0

package/src/lib/client-media.ts

@@ -0,0 +1,162 @@
+import { TwitterClient } from "./client.ts";
+import { TWITTER_UPLOAD_URL } 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;
+
+const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB
+const MAX_STATUS_POLLS = 20;
+
+export function withMedia<T extends Constructor>(Base: T) {
+  return class extends Base {
+    async uploadMedia(opts: {
+      data: Uint8Array | Buffer;
+      mimeType: string;
+      alt?: string;
+    }): Promise<{ success: boolean; mediaId?: string; error?: string }> {
+      try {
+        const headers = buildBaseHeaders(this.credentials);
+        const totalBytes = opts.data.length;
+
+        // Determine media category from mime type
+        const category = opts.mimeType.startsWith("video/")
+          ? "tweet_video"
+          : opts.mimeType === "image/gif"
+            ? "tweet_gif"
+            : "tweet_image";
+
+        // INIT
+        const initParams = new URLSearchParams({
+          command: "INIT",
+          total_bytes: String(totalBytes),
+          media_type: opts.mimeType,
+          media_category: category,
+        });
+
+        const initRes = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+          method: "POST",
+          headers: { ...headers, "content-type": "application/x-www-form-urlencoded" },
+          body: initParams.toString(),
+        });
+
+        if (!initRes.ok) {
+          const text = await initRes.text();
+          return { success: false, error: `INIT failed: HTTP ${initRes.status}: ${text.slice(0, 200)}` };
+        }
+
+        const initJson = (await initRes.json()) as Record<string, unknown>;
+        const mediaId = String(initJson.media_id_string ?? initJson.media_id ?? "");
+
+        if (!mediaId) {
+          return { success: false, error: "No media_id in INIT response" };
+        }
+
+        // APPEND — upload in chunks
+        let segmentIndex = 0;
+        for (let offset = 0; offset < totalBytes; offset += CHUNK_SIZE) {
+          const chunk = opts.data.slice(offset, offset + CHUNK_SIZE);
+          const formData = new FormData();
+          formData.append("command", "APPEND");
+          formData.append("media_id", mediaId);
+          formData.append("segment_index", String(segmentIndex));
+          formData.append("media", new Blob([chunk], { type: opts.mimeType }));
+
+          const appendRes = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+            method: "POST",
+            headers,
+            body: formData,
+          });
+
+          if (!appendRes.ok) {
+            const text = await appendRes.text();
+            return { success: false, error: `APPEND failed (segment ${segmentIndex}): HTTP ${appendRes.status}: ${text.slice(0, 200)}` };
+          }
+
+          segmentIndex++;
+        }
+
+        // FINALIZE
+        const finalizeParams = new URLSearchParams({
+          command: "FINALIZE",
+          media_id: mediaId,
+        });
+
+        const finalizeRes = await this.fetchWithTimeout(TWITTER_UPLOAD_URL, {
+          method: "POST",
+          headers: { ...headers, "content-type": "application/x-www-form-urlencoded" },
+          body: finalizeParams.toString(),
+        });
+
+        if (!finalizeRes.ok) {
+          const text = await finalizeRes.text();
+          return { success: false, error: `FINALIZE failed: HTTP ${finalizeRes.status}: ${text.slice(0, 200)}` };
+        }
+
+        const finalizeJson = (await finalizeRes.json()) as Record<string, unknown>;
+        const processingInfo = finalizeJson.processing_info as Record<string, unknown> | undefined;
+
+        // Poll STATUS if processing is required (videos)
+        if (processingInfo) {
+          let state = String(processingInfo.state ?? "");
+          let checkAfterMs = Number(processingInfo.check_after_secs ?? 5) * 1000;
+          let polls = 0;
+
+          while (state !== "succeeded" && state !== "failed" && polls < MAX_STATUS_POLLS) {
+            await new Promise((r) => setTimeout(r, checkAfterMs));
+            polls++;
+
+            const statusUrl = `${TWITTER_UPLOAD_URL}?command=STATUS&media_id=${mediaId}`;
+            const statusRes = await this.fetchWithTimeout(statusUrl, {
+              method: "GET",
+              headers,
+            });
+
+            if (!statusRes.ok) {
+              return { success: false, error: `STATUS poll failed: HTTP ${statusRes.status}` };
+            }
+
+            const statusJson = (await statusRes.json()) as Record<string, unknown>;
+            const info = statusJson.processing_info as Record<string, unknown> | undefined;
+            state = String(info?.state ?? "succeeded");
+            checkAfterMs = Number(info?.check_after_secs ?? 5) * 1000;
+
+            if (state === "failed") {
+              const errorInfo = info?.error as Record<string, unknown> | undefined;
+              return {
+                success: false,
+                error: `Media processing failed: ${errorInfo?.message ?? "unknown error"}`,
+              };
+            }
+          }
+        }
+
+        // Set alt text if provided
+        if (opts.alt) {
+          const altRes = await this.fetchWithTimeout(
+            "https://x.com/i/api/1.1/media/metadata/create.json",
+            {
+              method: "POST",
+              headers: { ...headers, "content-type": "application/json" },
+              body: JSON.stringify({
+                media_id: mediaId,
+                alt_text: { text: opts.alt },
+              }),
+            }
+          );
+          // Alt text failure is non-fatal
+          if (!altRes.ok) {
+            console.error(`Warning: Failed to set alt text: HTTP ${altRes.status}`);
+          }
+        }
+
+        return { success: true, mediaId };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-news.ts

@@ -0,0 +1,185 @@
+import { TwitterClient } from "./client.ts";
+import { newsFeatures } from "./features.ts";
+import { TWITTER_V1_BASE } from "./constants.ts";
+import type { NewsItem } from "./types.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+/** Timeline IDs for GenericTimelineById GraphQL */
+const TIMELINE_IDS: Record<string, string> = {
+  trending: "trends_home",
+  forYou: "trending",
+  news: "news",
+  sports: "sports",
+  entertainment: "entertainment",
+};
+
+function parseNewsFromGraphQL(instructions: unknown[]): NewsItem[] {
+  const items: NewsItem[] = [];
+
+  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;
+
+      if (itemContent) {
+        const trend = itemContent.trend as Record<string, unknown> | undefined;
+        const name = trend?.name as string | undefined
+          ?? itemContent.name as string | undefined
+          ?? itemContent.title as string | undefined;
+
+        if (name) {
+          const socialContext = itemContent.socialContext as Record<string, unknown> | undefined
+            ?? trend?.trendMetadata as Record<string, unknown> | undefined;
+
+          items.push({
+            id: String(entry.entryId ?? items.length),
+            headline: name,
+            category: String(socialContext?.text ?? socialContext?.domainContext ?? "Trending"),
+            postCount: socialContext?.metaDescription ? parsePostCount(String(socialContext.metaDescription)) : undefined,
+            description: socialContext?.metaDescription as string | undefined,
+          });
+        }
+      }
+
+      // Module items (grouped trends)
+      const moduleItems = content?.items as Array<Record<string, unknown>> | undefined;
+      if (moduleItems) {
+        for (const moduleItem of moduleItems) {
+          const modContent = (moduleItem.item as Record<string, unknown>)?.itemContent as Record<string, unknown> | undefined;
+          const trend = modContent?.trend as Record<string, unknown> | undefined;
+          const name = trend?.name as string | undefined ?? modContent?.name as string | undefined;
+
+          if (name) {
+            const meta = trend?.trendMetadata as Record<string, unknown> | undefined;
+            items.push({
+              id: String((moduleItem.item as Record<string, unknown>)?.entryId ?? items.length),
+              headline: name,
+              category: String(meta?.domainContext ?? "Trending"),
+              postCount: meta?.metaDescription ? parsePostCount(String(meta.metaDescription)) : undefined,
+              description: meta?.metaDescription as string | undefined,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  return items;
+}
+
+function parsePostCount(text: string): number | undefined {
+  const match = text.match(/([\d,.]+)\s*([KkMm])?/);
+  if (!match) return undefined;
+  let num = parseFloat(match[1]!.replace(/,/g, ""));
+  const suffix = match[2]?.toUpperCase();
+  if (suffix === "K") num *= 1_000;
+  if (suffix === "M") num *= 1_000_000;
+  return Math.round(num);
+}
+
+export function withNews<T extends Constructor>(Base: T) {
+  return class extends Base {
+    async getNews(
+      count?: number,
+      opts?: {
+        tab?: string;
+        aiOnly?: boolean;
+        withTweets?: boolean;
+        trendingOnly?: boolean;
+      }
+    ): Promise<{
+      success: boolean;
+      items: NewsItem[];
+      error?: string;
+    }> {
+      const tab = opts?.trendingOnly ? "trending" : (opts?.tab ?? "trending");
+
+      // Try GraphQL first
+      try {
+        const timelineId = TIMELINE_IDS[tab] ?? TIMELINE_IDS.trending!;
+
+        const { data, errors } = await this.graphqlGet(
+          "GenericTimelineById",
+          {
+            timelineId,
+            count: count ?? 20,
+            withQuickPromoteEligibilityTweetFields: true,
+          },
+          newsFeatures()
+        );
+
+        if (!errors?.length && data) {
+          const timeline = (data as Record<string, unknown>)?.timeline_by_id as Record<string, unknown> | undefined
+            ?? (data as Record<string, unknown>)?.timeline as Record<string, unknown> | undefined;
+          const tl = timeline?.timeline as Record<string, unknown> | undefined ?? timeline;
+          const instructions = tl?.instructions as unknown[] | undefined;
+
+          if (instructions) {
+            let items = parseNewsFromGraphQL(instructions);
+            if (opts?.aiOnly) {
+              items = items.filter(item => item.description && item.description.length > 0);
+            }
+            if (items.length > 0) return { success: true, items };
+          }
+        }
+      } catch {
+        // Fall through to REST
+      }
+
+      // Fallback: REST v1.1 trends/place.json
+      const result = await this._getNewsREST(count);
+      if (opts?.aiOnly && result.success) {
+        result.items = result.items.filter(item => item.description && item.description.length > 0);
+      }
+      return result;
+    }
+
+    private async _getNewsREST(
+      count?: number
+    ): Promise<{
+      success: boolean;
+      items: NewsItem[];
+      error?: string;
+    }> {
+      try {
+        const url = `${TWITTER_V1_BASE}/trends/place.json?id=1`;
+        const res = await this.fetchWithTimeout(url, {
+          method: "GET",
+          headers: this.getHeaders(),
+        });
+
+        if (!res.ok) {
+          return { success: false, items: [], error: `HTTP ${res.status}` };
+        }
+
+        const json = (await res.json()) as Array<Record<string, unknown>>;
+        const trendsData = json[0] as Record<string, unknown> | undefined;
+        const trends = trendsData?.trends as Array<Record<string, unknown>> | undefined;
+
+        if (!trends) return { success: true, items: [] };
+
+        const maxItems = count ?? 20;
+        const items: NewsItem[] = trends.slice(0, maxItems).map((t, i) => ({
+          id: String(i),
+          headline: String(t.name ?? ""),
+          category: "Trending",
+          postCount: t.tweet_volume != null ? Number(t.tweet_volume) : undefined,
+          url: t.url ? String(t.url) : undefined,
+        }));
+
+        return { success: true, items };
+      } catch (err) {
+        return {
+          success: false,
+          items: [],
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+  };
+}

package/src/lib/client-posting.ts

@@ -0,0 +1,163 @@
+import { TwitterClient } from "./client.ts";
+import { createTweetFeatures } from "./features.ts";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Constructor<T = TwitterClient> = new (...args: any[]) => T;
+
+export function withPosting<T extends Constructor>(Base: T) {
+  return class extends Base {
+    /**
+     * Post a new tweet, optionally with media.
+     */
+    async tweet(
+      text: string,
+      mediaIds?: string[]
+    ): Promise<{ success: boolean; tweetId?: string; error?: string }> {
+      try {
+        const mediaEntities = (mediaIds ?? []).map((id) => ({
+          media_id: id,
+          tagged_users: [],
+        }));
+
+        const { data, errors } = await this.graphqlPost(
+          "CreateTweet",
+          {
+            tweet_text: text,
+            dark_request: false,
+            media: {
+              media_entities: mediaEntities,
+              possibly_sensitive: false,
+            },
+            semantic_annotation_ids: [],
+          },
+          createTweetFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        const createTweet = (data as Record<string, unknown>)
+          ?.create_tweet as Record<string, unknown> | undefined;
+        const tweetResults = createTweet?.tweet_results as
+          | Record<string, unknown>
+          | undefined;
+        const result = tweetResults?.result as
+          | Record<string, unknown>
+          | undefined;
+        const tweetId = result?.rest_id as string | undefined;
+
+        if (!tweetId) {
+          return { success: false, error: "No tweet ID in response" };
+        }
+
+        return { success: true, tweetId };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Reply to an existing tweet, optionally with media.
+     */
+    async reply(
+      text: string,
+      replyToId: string,
+      mediaIds?: string[]
+    ): Promise<{ success: boolean; tweetId?: string; error?: string }> {
+      try {
+        const mediaEntities = (mediaIds ?? []).map((id) => ({
+          media_id: id,
+          tagged_users: [],
+        }));
+
+        const { data, errors } = await this.graphqlPost(
+          "CreateTweet",
+          {
+            tweet_text: text,
+            dark_request: false,
+            media: {
+              media_entities: mediaEntities,
+              possibly_sensitive: false,
+            },
+            semantic_annotation_ids: [],
+            reply: {
+              in_reply_to_tweet_id: replyToId,
+              exclude_reply_user_ids: [],
+            },
+          },
+          createTweetFeatures()
+        );
+
+        if (errors?.length) {
+          return { success: false, error: this.formatErrors(errors) };
+        }
+
+        const createTweet = (data as Record<string, unknown>)
+          ?.create_tweet as Record<string, unknown> | undefined;
+        const tweetResults = createTweet?.tweet_results as
+          | Record<string, unknown>
+          | undefined;
+        const result = tweetResults?.result as
+          | Record<string, unknown>
+          | undefined;
+        const tweetId = result?.rest_id as string | undefined;
+
+        if (!tweetId) {
+          return { success: false, error: "No tweet ID in response" };
+        }
+
+        return { success: true, tweetId };
+      } catch (err) {
+        return {
+          success: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }
+
+    /**
+     * Post a thread (multiple tweets in sequence).
+     * Returns all tweet IDs in order.
+     */
+    async thread(
+      texts: string[]
+    ): Promise<{ success: boolean; tweetIds: string[]; error?: string }> {
+      if (texts.length === 0) {
+        return { success: false, tweetIds: [], error: "No texts provided" };
+      }
+
+      const tweetIds: string[] = [];
+
+      // Post the first tweet
+      const first = await this.tweet(texts[0]!);
+      if (!first.success || !first.tweetId) {
+        return {
+          success: false,
+          tweetIds,
+          error: first.error ?? "Failed to post first tweet",
+        };
+      }
+      tweetIds.push(first.tweetId);
+
+      // Post subsequent tweets as replies
+      for (let i = 1; i < texts.length; i++) {
+        const previousId = tweetIds[tweetIds.length - 1]!;
+        const result = await this.reply(texts[i]!, previousId);
+        if (!result.success || !result.tweetId) {
+          return {
+            success: false,
+            tweetIds,
+            error: result.error ?? `Failed to post tweet ${i + 1} in thread`,
+          };
+        }
+        tweetIds.push(result.tweetId);
+      }
+
+      return { success: true, tweetIds };
+    }
+  };
+}