@zenalexa/unicli 0.207.1

package/src/adapters/twitter/client.ts

@@ -0,0 +1,451 @@
+/**
+ * Twitter GraphQL client — authenticated API access via browser cookies.
+ *
+ * Uses the public GraphQL endpoint at x.com with cookie-based authentication.
+ * Requires ct0 (CSRF token) and auth_token cookies in ~/.unicli/cookies/twitter.json
+ */
+
+import { loadCookies, formatCookieHeader } from "../../engine/cookies.js";
+import { USER_AGENT } from "../../constants.js";
+
+// Public bearer token — same for all Twitter web clients, not a secret
+const BEARER_TOKEN =
+  "AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA";
+
+const GRAPHQL_BASE = "https://x.com/i/api/graphql";
+
+/** Standard Twitter GraphQL feature flags */
+export const FEATURES: Record<string, boolean> = {
+  rweb_tipjar_consumption_enabled: true,
+  responsive_web_graphql_exclude_directive_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,
+  communities_web_enable_tweet_community_results_featuring: true,
+  c9s_tweet_anatomy_moderator_badge_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,
+  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,
+  rweb_video_timestamps_enabled: true,
+  longform_notetweets_rich_text_read_enabled: true,
+  longform_notetweets_inline_media_enabled: true,
+  responsive_web_enhance_cards_enabled: false,
+};
+
+/**
+ * Make an authenticated GraphQL GET request to the Twitter API.
+ *
+ * @param endpoint - GraphQL operation name (e.g. "SearchTimeline")
+ * @param queryId - GraphQL query ID (e.g. "nK1dw4oV3k4w5TdtcAdSww")
+ * @param variables - GraphQL variables object
+ * @param features - GraphQL feature flags (defaults to FEATURES)
+ * @returns Parsed JSON response
+ */
+export async function twitterFetch(
+  endpoint: string,
+  queryId: string,
+  variables: Record<string, unknown>,
+  features: Record<string, boolean> = FEATURES,
+): Promise<unknown> {
+  const cookies = loadCookies("twitter");
+  if (!cookies) {
+    throw new Error(
+      'No cookies found for "twitter". Run: unicli auth setup twitter',
+    );
+  }
+
+  const ct0 = cookies.ct0;
+  if (!ct0) {
+    throw new Error(
+      "Missing ct0 cookie (CSRF token). " +
+        "Ensure ~/.unicli/cookies/twitter.json contains ct0 and auth_token.",
+    );
+  }
+
+  const params = new URLSearchParams({
+    variables: JSON.stringify(variables),
+    features: JSON.stringify(features),
+  });
+
+  const url = `${GRAPHQL_BASE}/${queryId}/${endpoint}?${params.toString()}`;
+
+  const resp = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${BEARER_TOKEN}`,
+      "X-Csrf-Token": ct0,
+      "X-Twitter-Auth-Type": "OAuth2Session",
+      "X-Twitter-Active-User": "yes",
+      "User-Agent": USER_AGENT,
+      Cookie: formatCookieHeader(cookies),
+    },
+  });
+
+  if (!resp.ok) {
+    const preview = await resp.text().catch(() => "");
+    throw new Error(
+      `Twitter API error: HTTP ${resp.status} on ${endpoint}\n` +
+        `${preview.slice(0, 200)}`,
+    );
+  }
+
+  return resp.json();
+}
+
+/**
+ * Make an authenticated GraphQL POST request (for mutations).
+ */
+export async function twitterPostFetch(
+  endpoint: string,
+  queryId: string,
+  variables: Record<string, unknown>,
+  features: Record<string, boolean> = FEATURES,
+): Promise<unknown> {
+  const cookies = loadCookies("twitter");
+  if (!cookies) {
+    throw new Error(
+      'No cookies found for "twitter". Run: unicli auth setup twitter',
+    );
+  }
+
+  const ct0 = cookies.ct0;
+  if (!ct0) {
+    throw new Error(
+      "Missing ct0 cookie (CSRF token). " +
+        "Ensure ~/.unicli/cookies/twitter.json contains ct0 and auth_token.",
+    );
+  }
+
+  const url = `${GRAPHQL_BASE}/${queryId}/${endpoint}`;
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${BEARER_TOKEN}`,
+      "X-Csrf-Token": ct0,
+      "X-Twitter-Auth-Type": "OAuth2Session",
+      "X-Twitter-Active-User": "yes",
+      "User-Agent": USER_AGENT,
+      "Content-Type": "application/json",
+      Cookie: formatCookieHeader(cookies),
+    },
+    body: JSON.stringify({ variables, features, queryId }),
+  });
+
+  if (!resp.ok) {
+    const preview = await resp.text().catch(() => "");
+    throw new Error(
+      `Twitter API error: HTTP ${resp.status} on ${endpoint}\n` +
+        `${preview.slice(0, 200)}`,
+    );
+  }
+
+  return resp.json();
+}
+
+/**
+ * Make an authenticated REST API request to the Twitter v1.1 API.
+ *
+ * @param path - API path (e.g. "/1.1/users/show.json")
+ * @param params - URL query parameters
+ * @returns Parsed JSON response
+ */
+export async function twitterRestFetch(
+  path: string,
+  params: Record<string, string> = {},
+): Promise<unknown> {
+  const cookies = loadCookies("twitter");
+  if (!cookies) {
+    throw new Error(
+      'No cookies found for "twitter". Run: unicli auth setup twitter',
+    );
+  }
+
+  const ct0 = cookies.ct0;
+  if (!ct0) {
+    throw new Error(
+      "Missing ct0 cookie (CSRF token). " +
+        "Ensure ~/.unicli/cookies/twitter.json contains ct0 and auth_token.",
+    );
+  }
+
+  const searchParams = new URLSearchParams(params);
+  const url = `https://x.com${path}?${searchParams.toString()}`;
+
+  const resp = await fetch(url, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${BEARER_TOKEN}`,
+      "X-Csrf-Token": ct0,
+      "X-Twitter-Auth-Type": "OAuth2Session",
+      "X-Twitter-Active-User": "yes",
+      "User-Agent": USER_AGENT,
+      Cookie: formatCookieHeader(cookies),
+    },
+  });
+
+  if (!resp.ok) {
+    const preview = await resp.text().catch(() => "");
+    throw new Error(
+      `Twitter REST API error: HTTP ${resp.status} on ${path}\n` +
+        `${preview.slice(0, 200)}`,
+    );
+  }
+
+  return resp.json();
+}
+
+/**
+ * Make an authenticated request to the Twitter v2 guide API.
+ *
+ * @param url - Full API URL
+ * @param params - URL query parameters
+ * @returns Parsed JSON response
+ */
+export async function twitterGuideFetch(
+  url: string,
+  params: Record<string, string> = {},
+): Promise<unknown> {
+  const cookies = loadCookies("twitter");
+  if (!cookies) {
+    throw new Error(
+      'No cookies found for "twitter". Run: unicli auth setup twitter',
+    );
+  }
+
+  const ct0 = cookies.ct0;
+  if (!ct0) {
+    throw new Error(
+      "Missing ct0 cookie (CSRF token). " +
+        "Ensure ~/.unicli/cookies/twitter.json contains ct0 and auth_token.",
+    );
+  }
+
+  const searchParams = new URLSearchParams(params);
+  const fullUrl = `${url}?${searchParams.toString()}`;
+
+  const resp = await fetch(fullUrl, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${BEARER_TOKEN}`,
+      "X-Csrf-Token": ct0,
+      "X-Twitter-Auth-Type": "OAuth2Session",
+      "X-Twitter-Active-User": "yes",
+      "User-Agent": USER_AGENT,
+      Cookie: formatCookieHeader(cookies),
+    },
+  });
+
+  if (!resp.ok) {
+    const preview = await resp.text().catch(() => "");
+    throw new Error(
+      `Twitter Guide API error: HTTP ${resp.status}\n` +
+        `${preview.slice(0, 200)}`,
+    );
+  }
+
+  return resp.json();
+}
+
+interface TweetData {
+  id: string;
+  author: string;
+  text: string;
+  likes: number;
+  retweets: number;
+  views: string;
+  url: string;
+}
+
+/**
+ * Extract tweet data from a GraphQL tweet result object.
+ *
+ * Handles both regular tweets and tweets with visibility results.
+ * Returns null if the result is not a valid tweet.
+ */
+export function extractTweet(
+  result: Record<string, unknown>,
+): TweetData | null {
+  // Handle tweet_with_visibility_results wrapper
+  let tweetResult = result;
+  if (result.tweet) {
+    tweetResult = result.tweet as Record<string, unknown>;
+  }
+
+  const typename = tweetResult.__typename as string | undefined;
+  if (typename !== "Tweet" && typename !== "TweetWithVisibilityResults") {
+    return null;
+  }
+
+  const restId = tweetResult.rest_id as string | undefined;
+  if (!restId) return null;
+
+  const core = tweetResult.core as Record<string, unknown> | undefined;
+  const userResults = core?.user_results as Record<string, unknown> | undefined;
+  const userResult = userResults?.result as Record<string, unknown> | undefined;
+  const userLegacy = userResult?.legacy as Record<string, unknown> | undefined;
+  const screenName = (userLegacy?.screen_name as string) ?? "unknown";
+
+  const legacy = tweetResult.legacy as Record<string, unknown> | undefined;
+  const fullText = (legacy?.full_text as string) ?? "";
+  const favoriteCount = (legacy?.favorite_count as number) ?? 0;
+  const retweetCount = (legacy?.retweet_count as number) ?? 0;
+
+  const views = tweetResult.views as Record<string, unknown> | undefined;
+  const viewCount = (views?.count as string) ?? "0";
+
+  return {
+    id: restId,
+    author: screenName,
+    text: fullText,
+    likes: favoriteCount,
+    retweets: retweetCount,
+    views: viewCount,
+    url: `https://x.com/${screenName}/status/${restId}`,
+  };
+}
+
+/**
+ * Extract tweets from timeline instructions (common pattern for search, home, bookmarks).
+ *
+ * Timeline instructions contain entries with tweet results nested inside.
+ */
+export function extractTweetsFromInstructions(
+  instructions: unknown[],
+): TweetData[] {
+  const tweets: TweetData[] = [];
+
+  for (const instruction of instructions) {
+    const inst = instruction as Record<string, unknown>;
+    const type = inst.type as string | undefined;
+
+    // Handle TimelineAddEntries
+    if (type === "TimelineAddEntries") {
+      const entries = (inst.entries as unknown[]) ?? [];
+      for (const entry of entries) {
+        const e = entry as Record<string, unknown>;
+        const content = e.content as Record<string, unknown> | undefined;
+        if (!content) continue;
+
+        const entryType = content.entryType as string | undefined;
+
+        if (entryType === "TimelineTimelineItem") {
+          const itemContent = content.itemContent as
+            | Record<string, unknown>
+            | undefined;
+          if (
+            itemContent &&
+            (itemContent.itemType as string) === "TimelineTweet"
+          ) {
+            const tweetResults = itemContent.tweet_results as
+              | Record<string, unknown>
+              | undefined;
+            if (tweetResults?.result) {
+              const tweet = extractTweet(
+                tweetResults.result as Record<string, unknown>,
+              );
+              if (tweet) tweets.push(tweet);
+            }
+          }
+        } else if (entryType === "TimelineTimelineModule") {
+          // Module entries (e.g. conversations) contain nested items
+          const items = (content.items as unknown[]) ?? [];
+          for (const item of items) {
+            const i = item as Record<string, unknown>;
+            const itemObj = i.item as Record<string, unknown> | undefined;
+            const itemContent = itemObj?.itemContent as
+              | Record<string, unknown>
+              | undefined;
+            if (
+              itemContent &&
+              (itemContent.itemType as string) === "TimelineTweet"
+            ) {
+              const tweetResults = itemContent.tweet_results as
+                | Record<string, unknown>
+                | undefined;
+              if (tweetResults?.result) {
+                const tweet = extractTweet(
+                  tweetResults.result as Record<string, unknown>,
+                );
+                if (tweet) tweets.push(tweet);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  return tweets;
+}
+
+interface UserData {
+  id: string;
+  name: string;
+  screen_name: string;
+  followers: number;
+  following: number;
+  description: string;
+}
+
+/**
+ * Extract user entries from timeline instructions (followers/following endpoints).
+ */
+export function extractUsersFromInstructions(
+  instructions: unknown[],
+): UserData[] {
+  const users: UserData[] = [];
+
+  for (const instruction of instructions) {
+    const inst = instruction as Record<string, unknown>;
+    const type = inst.type as string | undefined;
+
+    if (type === "TimelineAddEntries") {
+      const entries = (inst.entries as unknown[]) ?? [];
+      for (const entry of entries) {
+        const e = entry as Record<string, unknown>;
+        const content = e.content as Record<string, unknown> | undefined;
+        if (!content) continue;
+
+        const itemContent = content.itemContent as
+          | Record<string, unknown>
+          | undefined;
+        if (!itemContent) continue;
+
+        const itemType = itemContent.itemType as string | undefined;
+        if (itemType !== "TimelineUser") continue;
+
+        const userResults = itemContent.user_results as
+          | Record<string, unknown>
+          | undefined;
+        const result = userResults?.result as
+          | Record<string, unknown>
+          | undefined;
+        if (!result) continue;
+
+        const legacy = result.legacy as Record<string, unknown> | undefined;
+        if (!legacy) continue;
+
+        users.push({
+          id: (result.rest_id as string) ?? "",
+          name: (legacy.name as string) ?? "",
+          screen_name: (legacy.screen_name as string) ?? "",
+          followers: (legacy.followers_count as number) ?? 0,
+          following: (legacy.friends_count as number) ?? 0,
+          description: (legacy.description as string) ?? "",
+        });
+      }
+    }
+  }
+
+  return users;
+}

package/src/adapters/twitter/delete.ts

@@ -0,0 +1,39 @@
+/**
+ * Twitter delete — delete own tweet via GraphQL DeleteTweet mutation.
+ */
+
+import { cli } from "../../registry.js";
+import { Strategy } from "../../types.js";
+import { twitterPostFetch, FEATURES } from "./client.js";
+
+const QUERY_ID = "VaenaVgh5q5ih7kvyVjgtg";
+const ENDPOINT = "DeleteTweet";
+
+cli({
+  site: "twitter",
+  name: "delete",
+  description: "Delete your own tweet",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  args: [
+    {
+      name: "tweet_id",
+      required: true,
+      positional: true,
+      description: "Tweet ID to delete",
+    },
+  ],
+  columns: ["status", "id"],
+  func: async (_page, kwargs) => {
+    const tweetId = String(kwargs.tweet_id);
+
+    const variables = {
+      tweet_id: tweetId,
+      dark_request: false,
+    };
+
+    await twitterPostFetch(ENDPOINT, QUERY_ID, variables, FEATURES);
+
+    return [{ status: "ok", id: tweetId }];
+  },
+});

package/src/adapters/twitter/download.ts

@@ -0,0 +1,151 @@
+/**
+ * Twitter download — download media (images/video) from a tweet via GraphQL TweetDetail.
+ */
+
+import { cli } from "../../registry.js";
+import { Strategy } from "../../types.js";
+import { twitterFetch, FEATURES } from "./client.js";
+
+const QUERY_ID = "xOhkmRac04YFZmOzU9PJHg";
+const ENDPOINT = "TweetDetail";
+
+interface MediaItem {
+  type: string;
+  url: string;
+  width: number;
+  height: number;
+}
+
+cli({
+  site: "twitter",
+  name: "download",
+  description: "Get media URLs from a tweet (images and video)",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  args: [
+    {
+      name: "tweet_id",
+      required: true,
+      positional: true,
+      description: "Tweet ID to download media from",
+    },
+  ],
+  columns: ["type", "url", "width", "height"],
+  func: async (_page, kwargs) => {
+    const tweetId = String(kwargs.tweet_id);
+
+    const variables = {
+      focalTweetId: tweetId,
+      with_rux_injections: false,
+      includePromotedContent: false,
+      withCommunity: true,
+      withQuickPromoteEligibilityTweetFields: false,
+      withBirdwatchNotes: false,
+      withVoice: true,
+      withV2Timeline: true,
+    };
+
+    const data = (await twitterFetch(
+      ENDPOINT,
+      QUERY_ID,
+      variables,
+      FEATURES,
+    )) as Record<string, unknown>;
+
+    // Navigate: data.threaded_conversation_with_injections_v2.instructions
+    const root = data.data as Record<string, unknown> | undefined;
+    const conversation = root?.threaded_conversation_with_injections_v2 as
+      | Record<string, unknown>
+      | undefined;
+    const instructions = (conversation?.instructions as unknown[]) ?? [];
+
+    const media: MediaItem[] = [];
+
+    for (const instruction of instructions) {
+      const inst = instruction as Record<string, unknown>;
+      if ((inst.type as string) !== "TimelineAddEntries") continue;
+
+      const entries = (inst.entries as unknown[]) ?? [];
+      for (const entry of entries) {
+        const e = entry as Record<string, unknown>;
+        const content = e.content as Record<string, unknown> | undefined;
+        if (!content) continue;
+
+        const itemContent = content.itemContent as
+          | Record<string, unknown>
+          | undefined;
+        if (!itemContent) continue;
+
+        const tweetResults = itemContent.tweet_results as
+          | Record<string, unknown>
+          | undefined;
+        const result = tweetResults?.result as
+          | Record<string, unknown>
+          | undefined;
+        if (!result) continue;
+
+        // Unwrap tweet_with_visibility_results
+        const tweetObj = (result.tweet ?? result) as Record<string, unknown>;
+        const restId = tweetObj.rest_id as string | undefined;
+        if (restId !== tweetId) continue;
+
+        const legacy = tweetObj.legacy as Record<string, unknown> | undefined;
+        const extendedEntities = legacy?.extended_entities as
+          | Record<string, unknown>
+          | undefined;
+        const mediaEntities = (extendedEntities?.media as unknown[]) ?? [];
+
+        for (const m of mediaEntities) {
+          const mediaObj = m as Record<string, unknown>;
+          const mediaType = mediaObj.type as string;
+
+          if (mediaType === "photo") {
+            media.push({
+              type: "photo",
+              url: (mediaObj.media_url_https as string) ?? "",
+              width:
+                ((mediaObj.original_info as Record<string, unknown>)
+                  ?.width as number) ?? 0,
+              height:
+                ((mediaObj.original_info as Record<string, unknown>)
+                  ?.height as number) ?? 0,
+            });
+          } else if (mediaType === "video" || mediaType === "animated_gif") {
+            const videoInfo = mediaObj.video_info as
+              | Record<string, unknown>
+              | undefined;
+            const variants = (videoInfo?.variants as unknown[]) ?? [];
+
+            // Pick highest bitrate mp4 variant
+            let bestUrl = "";
+            let bestBitrate = -1;
+            for (const v of variants) {
+              const variant = v as Record<string, unknown>;
+              if ((variant.content_type as string) !== "video/mp4") continue;
+              const bitrate = (variant.bitrate as number) ?? 0;
+              if (bitrate > bestBitrate) {
+                bestBitrate = bitrate;
+                bestUrl = (variant.url as string) ?? "";
+              }
+            }
+
+            if (bestUrl) {
+              media.push({
+                type: mediaType,
+                url: bestUrl,
+                width:
+                  ((mediaObj.original_info as Record<string, unknown>)
+                    ?.width as number) ?? 0,
+                height:
+                  ((mediaObj.original_info as Record<string, unknown>)
+                    ?.height as number) ?? 0,
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return media;
+  },
+});

package/src/adapters/twitter/follow.ts

@@ -0,0 +1,38 @@
+/**
+ * Twitter follow — follow a user via GraphQL mutation.
+ */
+
+import { cli } from "../../registry.js";
+import { Strategy } from "../../types.js";
+import { twitterPostFetch, FEATURES } from "./client.js";
+
+const QUERY_ID = "7r2SMmFpVfyJITgSjEBPDA";
+const ENDPOINT = "Follow";
+
+cli({
+  site: "twitter",
+  name: "follow",
+  description: "Follow a user",
+  domain: "x.com",
+  strategy: Strategy.COOKIE,
+  args: [
+    {
+      name: "user_id",
+      required: true,
+      positional: true,
+      description: "User numeric ID to follow",
+    },
+  ],
+  columns: ["status", "id"],
+  func: async (_page, kwargs) => {
+    const userId = String(kwargs.user_id);
+
+    const variables = {
+      user_id: userId,
+    };
+
+    await twitterPostFetch(ENDPOINT, QUERY_ID, variables, FEATURES);
+
+    return [{ status: "ok", id: userId }];
+  },
+});