xbird-mcp 0.1.0

package/src/lib/constants.ts

@@ -0,0 +1,55 @@
+export const BEARER_TOKEN =
+  "AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA";
+
+export const TWITTER_API_BASE = "https://x.com/i/api/graphql";
+export const TWITTER_V1_BASE = "https://x.com/i/api/1.1";
+export const TWITTER_UPLOAD_URL =
+  "https://upload.twitter.com/i/media/upload.json";
+
+export const DEFAULT_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+
+export const CACHE_DIR = `${process.env.HOME ?? "~"}/.config/xbird`;
+export const QUERY_IDS_CACHE_FILE = `${CACHE_DIR}/query-ids-cache.json`;
+export const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+
+/** Fallback query IDs — updated periodically, used when cache is empty */
+export const FALLBACK_QUERY_IDS: Record<string, string> = {
+  CreateTweet: "nmdAQXJDxw6-0KKF2on7eA",
+  CreateRetweet: "LFho5rIi4xcKO90p9jwG7A",
+  DeleteRetweet: "iQtK4dl5hBmXewYZuEOKVw",
+  CreateFriendship: "8h9JVdV8dlSyqyRDJEPCsA",
+  DestroyFriendship: "ppXWuagMNXgvzx6WoXBW0Q",
+  FavoriteTweet: "lI07N6Otwv1PhnEgXILM7A",
+  UnfavoriteTweet: "ZYKSe-w7KEslx3JhSIk5LA",
+  CreateBookmark: "aoDbu3RHznuiSkQ9aNM67Q",
+  DeleteBookmark: "Wlmlj2-xzyS1GN3a6cj-mQ",
+  TweetDetail: "_NvJCnIjOW__EP5-RF197A",
+  SearchTimeline: "6AAys3t42mosm_yTI_QENg",
+  HomeTimeline: "edseUwk9sP5Phz__9TIRnA",
+  HomeLatestTimeline: "iOEZpOdfekFsxSlPQCQtPg",
+  UserByScreenName: "xmU6X_CKcnQ5lSrCbAmJsg",
+  Viewer: "pVrmNaXcxPjisIvKtLDMEA",
+  UserTweets: "Wms1GvIiHXAPBaCr9KblaA",
+  Bookmarks: "RV1g3b8n_SGOHwkqKYSCFw",
+  Following: "mWYeougg_ocJS2Vr1Vt28w",
+  Followers: "SFYY3WsgwjlXSLlfnEUE4A",
+  Likes: "ETJflBunfqNa1uE1mBPCaw",
+  ListOwnerships: "wQcOSjSQ8NtgxIwvYl1lMg",
+  ListMemberships: "BlEXXdARdSeL_0KyKHHvvg",
+  ListLatestTweetsTimeline: "2TemLyqrMpTeAmysdbnVqw",
+  GenericTimelineById: "SpoeI4hKtSMEjhBjQl8rFA",
+};
+
+export const TARGET_OPERATIONS = Object.keys(FALLBACK_QUERY_IDS);
+
+/** Bundle URL regex for discovering query IDs from Twitter JS bundles */
+export const BUNDLE_URL_REGEX =
+  /https:\/\/abs\.twimg\.com\/responsive-web\/client-web(?:-legacy)?\/[A-Za-z0-9.-]+\.js/g;
+
+/** Discovery pages to scrape for bundle URLs */
+export const DISCOVERY_PAGES = [
+  "https://x.com/?lang=en",
+  "https://x.com/explore",
+  "https://x.com/notifications",
+];

package/src/lib/cookies.ts

@@ -0,0 +1,132 @@
+import { getCookies, toCookieHeader } from "@steipete/sweet-cookie";
+import type { BrowserName } from "@steipete/sweet-cookie";
+import type { ExtendedBrowserName } from "./types.ts";
+
+const TWITTER_URL = "https://x.com/";
+const TWITTER_ORIGINS = ["https://x.com/", "https://twitter.com/"];
+const TWITTER_COOKIE_NAMES = ["auth_token", "ct0"];
+
+const CHROMIUM_PROFILES: Record<string, string> = {
+  arc: `${process.env.HOME}/Library/Application Support/Arc/User Data/Default`,
+  brave: `${process.env.HOME}/Library/Application Support/BraveSoftware/Brave-Browser/Default`,
+};
+
+export interface BrowserMapping {
+  browserName: BrowserName;
+  chromeProfile?: string;
+}
+
+export function mapBrowserName(source?: ExtendedBrowserName): BrowserMapping | undefined {
+  if (!source) return undefined;
+  if (source === "arc" || source === "brave") {
+    return { browserName: "chrome", chromeProfile: CHROMIUM_PROFILES[source] };
+  }
+  return { browserName: source as BrowserName };
+}
+
+export interface BrowserCookieResult {
+  authToken: string | null;
+  ct0: string | null;
+  source: string | null;
+  warnings: string[];
+}
+
+function pickValue(
+  cookies: Array<{ name: string; value: string; domain?: string }>,
+  name: string
+): string | null {
+  const matches = cookies.filter(
+    (c) => c.name === name && typeof c.value === "string" && c.value.length > 0
+  );
+  if (matches.length === 0) return null;
+  const preferred = matches.find((c) => (c.domain ?? "").endsWith("x.com"));
+  if (preferred) return preferred.value;
+  const twitter = matches.find((c) =>
+    (c.domain ?? "").endsWith("twitter.com")
+  );
+  if (twitter) return twitter.value;
+  return matches[0]?.value ?? null;
+}
+
+interface BrowserAttempt {
+  browser: BrowserName;
+  chromeProfile?: string;
+  displayName?: string;
+}
+
+const DEFAULT_ATTEMPTS: BrowserAttempt[] = [
+  { browser: "safari" },
+  { browser: "chrome" },
+  { browser: "chrome", chromeProfile: CHROMIUM_PROFILES.arc, displayName: "Arc" },
+  { browser: "chrome", chromeProfile: CHROMIUM_PROFILES.brave, displayName: "Brave" },
+  { browser: "firefox" },
+];
+
+export async function extractBrowserCookies(
+  browsers?: BrowserName[],
+  chromeProfile?: string,
+): Promise<BrowserCookieResult> {
+  const warnings: string[] = [];
+
+  // If specific browsers provided, use them directly
+  if (browsers) {
+    for (const browser of browsers) {
+      try {
+        const { cookies, warnings: w } = await getCookies({
+          url: TWITTER_URL,
+          origins: TWITTER_ORIGINS,
+          names: [...TWITTER_COOKIE_NAMES],
+          browsers: [browser],
+          mode: "merge",
+          timeoutMs: 30_000,
+          ...(chromeProfile && browser === "chrome" ? { chromeProfile } : {}),
+        } as Parameters<typeof getCookies>[0]);
+        warnings.push(...w);
+
+        const authToken = pickValue(cookies as Array<{ name: string; value: string; domain?: string }>, "auth_token");
+        const ct0 = pickValue(cookies as Array<{ name: string; value: string; domain?: string }>, "ct0");
+
+        if (authToken && ct0) {
+          return {
+            authToken,
+            ct0,
+            source: browser.charAt(0).toUpperCase() + browser.slice(1),
+            warnings,
+          };
+        }
+      } catch {
+        warnings.push(`Failed to read cookies from ${browser}`);
+      }
+    }
+    return { authToken: null, ct0: null, source: null, warnings };
+  }
+
+  // Default: try multiple browsers including Arc/Brave
+  for (const attempt of DEFAULT_ATTEMPTS) {
+    try {
+      const { cookies, warnings: w } = await getCookies({
+        url: TWITTER_URL,
+        origins: TWITTER_ORIGINS,
+        names: [...TWITTER_COOKIE_NAMES],
+        browsers: [attempt.browser],
+        mode: "merge",
+        timeoutMs: 30_000,
+        ...(attempt.chromeProfile ? { chromeProfile: attempt.chromeProfile } : {}),
+      } as Parameters<typeof getCookies>[0]);
+      warnings.push(...w);
+
+      const authToken = pickValue(cookies as Array<{ name: string; value: string; domain?: string }>, "auth_token");
+      const ct0 = pickValue(cookies as Array<{ name: string; value: string; domain?: string }>, "ct0");
+
+      if (authToken && ct0) {
+        const displayName = attempt.displayName ?? (attempt.browser.charAt(0).toUpperCase() + attempt.browser.slice(1));
+        return { authToken, ct0, source: displayName, warnings };
+      }
+    } catch {
+      const name = attempt.displayName ?? attempt.browser;
+      warnings.push(`Failed to read cookies from ${name}`);
+    }
+  }
+
+  return { authToken: null, ct0: null, source: null, warnings };
+}

package/src/lib/features.ts

@@ -0,0 +1,175 @@
+/** Feature flags for TweetDetail requests */
+export function tweetDetailFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: true,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_graphql_exclude_directive_enabled: true,
+    responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+    premium_content_api_read_enabled: false,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_grok_annotations_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    post_ctas_fetch_enabled: true,
+    responsive_web_grok_share_attachment_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,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    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,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_grok_imagine_annotation_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_enhance_cards_enabled: false,
+    responsive_web_twitter_article_plain_text_enabled: true,
+    responsive_web_twitter_article_seed_tweet_detail_enabled: true,
+    responsive_web_twitter_article_seed_tweet_summary_enabled: true,
+    rweb_video_timestamps_enabled: true,
+    subscriptions_feature_can_gift_premium: false,
+    subscriptions_verification_info_is_identity_verified_enabled: true,
+    highlights_tweets_tab_ui_enabled: true,
+    subscriptions_verification_info_verified_since_enabled: true,
+    responsive_web_twitter_article_notes_tab_enabled: true,
+    hidden_profile_subscriptions_enabled: true,
+  };
+}
+
+/** Feature flags for CreateTweet requests */
+export function createTweetFeatures(): Record<string, boolean> {
+  return {
+    rweb_video_screen_enabled: true,
+    creator_subscriptions_tweet_preview_api_enabled: true,
+    premium_content_api_read_enabled: false,
+    communities_web_enable_tweet_community_results_fetch: true,
+    c9s_tweet_anatomy_moderator_badge_enabled: true,
+    responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+    responsive_web_grok_analyze_post_followups_enabled: false,
+    responsive_web_grok_annotations_enabled: false,
+    responsive_web_jetfuel_frame: true,
+    post_ctas_fetch_enabled: true,
+    responsive_web_grok_share_attachment_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,
+    responsive_web_grok_show_grok_translated_post: false,
+    responsive_web_grok_analysis_button_from_backend: true,
+    creator_subscriptions_quote_tweet_preview_enabled: false,
+    longform_notetweets_rich_text_read_enabled: true,
+    longform_notetweets_inline_media_enabled: true,
+    profile_label_improvements_pcf_label_in_post_enabled: true,
+    responsive_web_profile_redirect_enabled: false,
+    rweb_tipjar_consumption_enabled: true,
+    verified_phone_label_enabled: false,
+    articles_preview_enabled: true,
+    responsive_web_grok_community_note_auto_translation_is_enabled: false,
+    responsive_web_graphql_skip_user_profile_image_extensions_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,
+    responsive_web_grok_image_annotation_enabled: true,
+    responsive_web_grok_imagine_annotation_enabled: true,
+    responsive_web_graphql_timeline_navigation_enabled: true,
+    responsive_web_enhance_cards_enabled: false,
+  };
+}
+
+/** Feature flags for SearchTimeline requests */
+export function searchFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    rweb_video_timestamps_enabled: true,
+  };
+}
+
+/** Feature flags for HomeTimeline requests */
+export function timelineFeatures(): Record<string, boolean> {
+  return {
+    ...searchFeatures(),
+    blue_business_profile_image_shape_enabled: true,
+    responsive_web_text_conversations_enabled: false,
+    tweetypie_unmention_optimization_enabled: true,
+    vibe_api_enabled: true,
+    responsive_web_twitter_blue_verified_badge_is_enabled: true,
+    interactive_text_enabled: true,
+    longform_notetweets_richtext_consumption_enabled: true,
+    responsive_web_media_download_video_enabled: false,
+  };
+}
+
+/** Feature flags for Viewer (whoami) requests */
+export function viewerFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    subscriptions_upsells_api_enabled: true,
+  };
+}
+
+/** Field toggles for tweet detail */
+export function fieldToggles(): Record<string, boolean> {
+  return {
+    withArticleRichContentState: true,
+    withArticlePlainText: true,
+    withGrokAnalyze: false,
+    withDisallowedReplyControls: false,
+  };
+}
+
+/** Feature flags for List operations */
+export function listFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    rweb_video_timestamps_enabled: true,
+  };
+}
+
+/** Feature flags for News/Explore (GenericTimelineById) */
+export function newsFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    rweb_video_timestamps_enabled: true,
+  };
+}
+
+/** Feature flags for Bookmarks */
+export function bookmarksFeatures(): Record<string, boolean> {
+  return {
+    ...timelineFeatures(),
+    graphql_timeline_v2_bookmark_timeline: true,
+  };
+}
+
+/** Feature flags for Likes */
+export function likesFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    rweb_video_timestamps_enabled: true,
+  };
+}
+
+/** Feature flags for UserTweets */
+export function userTweetsFeatures(): Record<string, boolean> {
+  return {
+    ...tweetDetailFeatures(),
+    rweb_video_timestamps_enabled: true,
+  };
+}

package/src/lib/headers.ts

@@ -0,0 +1,28 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { BEARER_TOKEN, DEFAULT_USER_AGENT } from "./constants.ts";
+import type { Credentials } from "./types.ts";
+
+export function buildHeaders(creds: Credentials): Record<string, string> {
+  return {
+    accept: "*/*",
+    "accept-language": "en-US,en;q=0.9",
+    authorization: `Bearer ${BEARER_TOKEN}`,
+    "x-csrf-token": creds.ct0,
+    "x-twitter-auth-type": "OAuth2Session",
+    "x-twitter-active-user": "yes",
+    "x-twitter-client-language": "en",
+    "x-client-uuid": randomUUID(),
+    "x-client-transaction-id": randomBytes(16).toString("hex"),
+    cookie: `auth_token=${creds.authToken}; ct0=${creds.ct0}`,
+    "user-agent": DEFAULT_USER_AGENT,
+    origin: "https://x.com",
+    referer: "https://x.com/",
+    "content-type": "application/json",
+  };
+}
+
+export function buildBaseHeaders(creds: Credentials): Record<string, string> {
+  const headers = buildHeaders(creds);
+  delete headers["content-type"];
+  return headers;
+}

package/src/lib/paginate.ts

@@ -0,0 +1,39 @@
+export interface AutoPaginateOpts {
+  all?: boolean;
+  maxPages?: number;
+  delay?: number;
+}
+
+export async function autoPaginate<T>(
+  fetchPage: (cursor?: string) => Promise<{ items: T[]; cursor?: string }>,
+  opts: AutoPaginateOpts = {}
+): Promise<{ items: T[]; cursor?: string }> {
+  const allItems: T[] = [];
+  let cursor: string | undefined;
+  let pages = 0;
+  const seenCursors = new Set<string>();
+
+  // If not paginating, just fetch one page
+  if (!opts.all && !opts.maxPages) {
+    const result = await fetchPage();
+    return result;
+  }
+
+  const maxPages = opts.all ? Infinity : (opts.maxPages ?? 1);
+
+  while (pages < maxPages) {
+    const result = await fetchPage(cursor);
+    allItems.push(...result.items);
+    pages++;
+
+    if (!result.cursor || seenCursors.has(result.cursor)) break;
+    seenCursors.add(result.cursor);
+    cursor = result.cursor;
+
+    if (pages < maxPages && opts.delay) {
+      await new Promise(r => setTimeout(r, opts.delay));
+    }
+  }
+
+  return { items: allItems, cursor };
+}

package/src/lib/query-ids.ts

@@ -0,0 +1,190 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  BUNDLE_URL_REGEX,
+  CACHE_TTL_MS,
+  DISCOVERY_PAGES,
+  FALLBACK_QUERY_IDS,
+  QUERY_IDS_CACHE_FILE,
+  TARGET_OPERATIONS,
+} from "./constants.ts";
+
+interface CacheSnapshot {
+  fetchedAt: string;
+  ttlMs: number;
+  ids: Record<string, string>;
+}
+
+const OPERATION_PATTERNS = [
+  {
+    regex:
+      /e\.exports=\{queryId\s*:\s*["']([^"']+)["']\s*,\s*operationName\s*:\s*["']([^"']+)["']/gs,
+    opGroup: 2,
+    idGroup: 1,
+  },
+  {
+    regex:
+      /e\.exports=\{operationName\s*:\s*["']([^"']+)["']\s*,\s*queryId\s*:\s*["']([^"']+)["']/gs,
+    opGroup: 1,
+    idGroup: 2,
+  },
+  {
+    regex:
+      /operationName\s*[:=]\s*["']([^"']+)["'](.{0,4000}?)queryId\s*[:=]\s*["']([^"']+)["']/gs,
+    opGroup: 1,
+    idGroup: 3,
+  },
+  {
+    regex:
+      /queryId\s*[:=]\s*["']([^"']+)["'](.{0,4000}?)operationName\s*[:=]\s*["']([^"']+)["']/gs,
+    opGroup: 3,
+    idGroup: 1,
+  },
+];
+
+const QUERY_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+
+let memoryCache: CacheSnapshot | null = null;
+let loadPromise: Promise<CacheSnapshot | null> | null = null;
+
+async function readCache(): Promise<CacheSnapshot | null> {
+  try {
+    const raw = await readFile(QUERY_IDS_CACHE_FILE, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.fetchedAt && parsed?.ids) {
+      return parsed as CacheSnapshot;
+    }
+  } catch {
+    // no cache yet
+  }
+  return null;
+}
+
+async function writeCache(snapshot: CacheSnapshot): Promise<void> {
+  await mkdir(path.dirname(QUERY_IDS_CACHE_FILE), { recursive: true });
+  await writeFile(
+    QUERY_IDS_CACHE_FILE,
+    JSON.stringify(snapshot, null, 2) + "\n",
+    "utf8"
+  );
+}
+
+function isFresh(snapshot: CacheSnapshot): boolean {
+  const age = Date.now() - new Date(snapshot.fetchedAt).getTime();
+  return age <= (snapshot.ttlMs || CACHE_TTL_MS);
+}
+
+async function loadSnapshot(): Promise<CacheSnapshot | null> {
+  if (memoryCache) return memoryCache;
+  if (!loadPromise) {
+    loadPromise = readCache().then((s) => {
+      memoryCache = s;
+      return s;
+    });
+  }
+  return loadPromise;
+}
+
+/**
+ * Get a query ID for the given operation name.
+ * Checks cache first, then falls back to hardcoded IDs.
+ */
+export async function getQueryId(operationName: string): Promise<string> {
+  const snapshot = await loadSnapshot();
+  const cached = snapshot?.ids[operationName];
+  if (cached) return cached;
+  return FALLBACK_QUERY_IDS[operationName] ?? operationName;
+}
+
+/**
+ * Discover fresh query IDs from Twitter's JS bundles.
+ */
+export async function refreshQueryIds(
+  options: { force?: boolean } = {}
+): Promise<void> {
+  const snapshot = await loadSnapshot();
+  if (!options.force && snapshot && isFresh(snapshot)) return;
+
+  const targets = new Set(TARGET_OPERATIONS);
+  const discovered = new Map<string, string>();
+
+  // Step 1: Discover bundle URLs from Twitter HTML pages
+  const bundleUrls = new Set<string>();
+  for (const page of DISCOVERY_PAGES) {
+    try {
+      const res = await fetch(page, {
+        headers: {
+          "User-Agent":
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+          Accept: "text/html",
+        },
+      });
+      if (!res.ok) continue;
+      const html = await res.text();
+      for (const match of html.matchAll(BUNDLE_URL_REGEX)) {
+        bundleUrls.add(match[0]);
+      }
+    } catch {
+      // ignore individual page failures
+    }
+  }
+
+  if (bundleUrls.size === 0) return;
+
+  // Step 2: Fetch bundles and extract query IDs (concurrency: 6)
+  const urls = [...bundleUrls];
+  const CONCURRENCY = 6;
+  for (let i = 0; i < urls.length && discovered.size < targets.size; i += CONCURRENCY) {
+    const chunk = urls.slice(i, i + CONCURRENCY);
+    await Promise.all(
+      chunk.map(async (url) => {
+        if (discovered.size >= targets.size) return;
+        try {
+          const res = await fetch(url);
+          if (!res.ok) return;
+          const js = await res.text();
+          for (const pattern of OPERATION_PATTERNS) {
+            pattern.regex.lastIndex = 0;
+            let match: RegExpExecArray | null;
+            while ((match = pattern.regex.exec(js)) !== null) {
+              const op = match[pattern.opGroup];
+              const id = match[pattern.idGroup];
+              if (!op || !id || !targets.has(op) || discovered.has(op)) continue;
+              if (!QUERY_ID_REGEX.test(id)) continue;
+              discovered.set(op, id);
+            }
+          }
+        } catch {
+          // ignore individual bundle failures
+        }
+      })
+    );
+  }
+
+  if (discovered.size === 0) return;
+
+  // Step 3: Save to cache
+  const ids: Record<string, string> = {};
+  for (const name of TARGET_OPERATIONS) {
+    const id = discovered.get(name);
+    if (id) ids[name] = id;
+  }
+
+  const newSnapshot: CacheSnapshot = {
+    fetchedAt: new Date().toISOString(),
+    ttlMs: CACHE_TTL_MS,
+    ids,
+  };
+
+  await writeCache(newSnapshot);
+  memoryCache = newSnapshot;
+  loadPromise = null;
+}
+
+/**
+ * Clear in-memory cache (useful for tests).
+ */
+export function clearCache(): void {
+  memoryCache = null;
+  loadPromise = null;
+}