birdapi 0.0.1__py3-none-any.whl

bird/__init__.py

@@ -0,0 +1,16 @@
+"""bird — X/Twitter GraphQL client library."""
+
+from .client import TwitterClient
+from ._models import AboutProfile, ArticleMetadata, Author, MediaItem, NewsItem, Tweet, TwitterList, User
+
+__all__ = [
+    "TwitterClient",
+    "Tweet",
+    "User",
+    "Author",
+    "MediaItem",
+    "ArticleMetadata",
+    "TwitterList",
+    "AboutProfile",
+    "NewsItem",
+]

bird/_config.py

@@ -0,0 +1,63 @@
+"""Credential storage for bird — ~/.config/bird/credentials.json."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+
+_CREDS_PATH = Path.home() / ".config" / "bird" / "credentials.json"
+
+
+def _creds_path() -> Path:
+    return _CREDS_PATH
+
+
+def load_credentials() -> dict[str, str]:
+    """Return saved credentials, or an empty dict if none exist."""
+    try:
+        return json.loads(_creds_path().read_text())
+    except Exception:
+        return {}
+
+
+def save_credentials(auth_token: str, ct0: str) -> Path:
+    """Write credentials to disk and return the file path."""
+    path = _creds_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"auth_token": auth_token, "ct0": ct0}, indent=2) + "\n")
+    # Restrict permissions on non-Windows (best effort)
+    try:
+        path.chmod(0o600)
+    except Exception:
+        pass
+    return path
+
+
+def resolve_credentials(
+    auth_token: Optional[str] = None,
+    ct0: Optional[str] = None,
+) -> tuple[Optional[str], Optional[str]]:
+    """Return (auth_token, ct0) from the first source that has both values.
+
+    Priority: explicit args → env vars → saved credentials file.
+    """
+    import os
+
+    tok = (
+        auth_token
+        or os.environ.get("AUTH_TOKEN")
+        or os.environ.get("TWITTER_AUTH_TOKEN")
+    )
+    csrf = (
+        ct0
+        or os.environ.get("CT0")
+        or os.environ.get("TWITTER_CT0")
+    )
+
+    if tok and csrf:
+        return tok, csrf
+
+    saved = load_credentials()
+    return saved.get("auth_token") or tok, saved.get("ct0") or csrf

bird/_constants.py

@@ -0,0 +1,48 @@
+import re
+
+TWITTER_API_BASE = "https://x.com/i/api/graphql"
+TWITTER_GRAPHQL_POST_URL = "https://x.com/i/api/graphql"
+TWITTER_STATUS_UPDATE_URL = "https://x.com/i/api/1.1/statuses/update.json"
+
+# Public bearer token used by the X/Twitter web client
+BEARER_TOKEN = (
+    "AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs"
+    "%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA"
+)
+
+# Fallback query IDs — refreshed at runtime from x.com bundles; these keep
+# the client usable if the cache is missing or stale.
+FALLBACK_QUERY_IDS: dict[str, str] = {
+    "CreateTweet": "TAJw1rBsjAtdNgTdlo2oeg",
+    "CreateRetweet": "ojPdsZsimiJrUGLR1sjUtA",
+    "DeleteRetweet": "iQtK4dl5hBmXewYZuEOKVw",
+    "CreateFriendship": "8h9JVdV8dlSyqyRDJEPCsA",
+    "DestroyFriendship": "ppXWuagMNXgvzx6WoXBW0Q",
+    "FavoriteTweet": "lI07N6Otwv1PhnEgXILM7A",
+    "UnfavoriteTweet": "ZYKSe-w7KEslx3JhSIk5LA",
+    "CreateBookmark": "aoDbu3RHznuiSkQ9aNM67Q",
+    "DeleteBookmark": "Wlmlj2-xzyS1GN3a6cj-mQ",
+    "TweetDetail": "97JF30KziU00483E_8elBA",
+    "SearchTimeline": "M1jEez78PEfVfbQLvlWMvQ",
+    "UserArticlesTweets": "8zBy9h4L90aDL02RsBcCFg",
+    "UserTweets": "Wms1GvIiHXAPBaCr9KblaA",
+    "Bookmarks": "RV1g3b8n_SGOHwkqKYSCFw",
+    "Following": "BEkNpEt5pNETESoqMsTEGA",
+    "Followers": "kuFUYP9eV1FPoEy4N-pi7w",
+    "Likes": "JR2gceKucIKcVNB_9JkhsA",
+    "BookmarkFolderTimeline": "KJIQpsvxrTfRIlbaRIySHQ",
+    "ListOwnerships": "wQcOSjSQ8NtgxIwvYl1lMg",
+    "ListMemberships": "BlEXXdARdSeL_0KyKHHvvg",
+    "ListLatestTweetsTimeline": "2TemLyqrMpTeAmysdbnVqw",
+    "HomeTimeline": "edseUwk9sP5Phz__9TIRnA",
+    "HomeLatestTimeline": "iOEZpOdfekFsxSlPQCQtPg",
+    "ExploreSidebar": "lpSN4M6qpimkF4nRFPE3nQ",
+    "ExplorePage": "kheAINB_4pzRDqkzG3K-ng",
+    "GenericTimelineById": "uGSr7alSjR9v6QJAIaqSKQ",
+    "TrendHistory": "Sj4T-jSB9pr0Mxtsc1UKZQ",
+    "AboutAccountQuery": "zs_jFPFT78rBpXv9Z3U2YQ",
+}
+
+SETTINGS_SCREEN_NAME_RE = re.compile(r'"screen_name":"([^"]+)"')
+SETTINGS_USER_ID_RE = re.compile(r'"user_id"\s*:\s*"(\d+)"')
+SETTINGS_NAME_RE = re.compile(r'"name":"([^"\\]*(?:\\.[^"\\]*)*)"')

bird/_features.py

@@ -0,0 +1,256 @@
+"""GraphQL feature flag payloads, mirroring the X/Twitter web client."""
+
+from __future__ import annotations
+
+
+def _article_features() -> dict:
+    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,
+    }
+
+
+def tweet_detail_features() -> dict:
+    return {
+        **_article_features(),
+        "responsive_web_graphql_exclude_directive_enabled": True,
+        "communities_web_enable_tweet_community_results_fetch": True,
+        "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,
+        "longform_notetweets_rich_text_read_enabled": True,
+        "longform_notetweets_inline_media_enabled": True,
+        "responsive_web_edit_tweet_api_enabled": True,
+        "tweet_awards_web_tipping_enabled": False,
+        "creator_subscriptions_quote_tweet_preview_enabled": False,
+        "verified_phone_label_enabled": False,
+    }
+
+
+def article_field_toggles() -> dict:
+    return {
+        "withPayments": False,
+        "withAuxiliaryUserLabels": False,
+        "withArticleRichContentState": True,
+        "withArticlePlainText": True,
+        "withGrokAnalyze": False,
+        "withDisallowedReplyControls": False,
+    }
+
+
+def search_features() -> dict:
+    return {
+        **_article_features(),
+        "rweb_video_timestamps_enabled": True,
+        "responsive_web_enhance_cards_enabled": False,
+    }
+
+
+def tweet_create_features() -> dict:
+    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,
+    }
+
+
+def _timeline_features() -> dict:
+    return {
+        **search_features(),
+        "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,
+    }
+
+
+def bookmarks_features() -> dict:
+    return {
+        **_timeline_features(),
+        "graphql_timeline_v2_bookmark_timeline": True,
+    }
+
+
+def likes_features() -> dict:
+    return _timeline_features()
+
+
+def lists_features() -> dict:
+    return {
+        **_article_features(),
+        "blue_business_profile_image_shape_enabled": False,
+        "responsive_web_text_conversations_enabled": False,
+        "tweetypie_unmention_optimization_enabled": True,
+        "vibe_api_enabled": False,
+        "interactive_text_enabled": False,
+    }
+
+
+def home_timeline_features() -> dict:
+    return _timeline_features()
+
+
+def user_tweets_features() -> dict:
+    return {
+        "rweb_video_screen_enabled": False,
+        "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,
+        "creator_subscriptions_tweet_preview_api_enabled": True,
+        "responsive_web_graphql_timeline_navigation_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": True,
+        "responsive_web_jetfuel_frame": True,
+        "post_ctas_fetch_enabled": True,
+        "responsive_web_grok_share_attachment_enabled": True,
+        "responsive_web_grok_annotations_enabled": False,
+        "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": True,
+        "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,
+    }
+
+
+def following_features() -> dict:
+    return {
+        "rweb_video_screen_enabled": True,
+        "profile_label_improvements_pcf_label_in_post_enabled": False,
+        "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_skip_user_profile_image_extensions_enabled": False,
+        "premium_content_api_read_enabled": True,
+        "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": False,
+        "post_ctas_fetch_enabled": True,
+        "responsive_web_grok_share_attachment_enabled": False,
+        "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": True,
+        "responsive_web_grok_show_grok_translated_post": False,
+        "responsive_web_grok_analysis_button_from_backend": 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,
+        "longform_notetweets_rich_text_read_enabled": True,
+        "longform_notetweets_inline_media_enabled": True,
+        "responsive_web_grok_image_annotation_enabled": False,
+        "responsive_web_grok_imagine_annotation_enabled": False,
+        "responsive_web_grok_community_note_auto_translation_is_enabled": False,
+        "responsive_web_enhance_cards_enabled": False,
+    }
+
+
+def explore_features() -> dict:
+    return {
+        **_article_features(),
+        "responsive_web_grok_analyze_button_fetch_trends_enabled": True,
+        "responsive_web_grok_analyze_post_followups_enabled": True,
+        "responsive_web_grok_annotations_enabled": True,
+        "responsive_web_grok_show_grok_translated_post": True,
+        "responsive_web_grok_community_note_auto_translation_is_enabled": True,
+        "rweb_video_timestamps_enabled": True,
+    }

bird/_models.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Author:
+    username: str
+    name: str
+
+
+@dataclass
+class MediaItem:
+    type: str  # "photo", "video", "animated_gif"
+    url: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+    preview_url: Optional[str] = None
+    video_url: Optional[str] = None
+    duration_ms: Optional[int] = None
+
+
+@dataclass
+class ArticleMetadata:
+    title: str
+    preview_text: Optional[str] = None
+
+
+@dataclass
+class Tweet:
+    id: str
+    text: str
+    author: Author
+    created_at: Optional[str] = None
+    reply_count: Optional[int] = None
+    retweet_count: Optional[int] = None
+    like_count: Optional[int] = None
+    conversation_id: Optional[str] = None
+    in_reply_to_status_id: Optional[str] = None
+    author_id: Optional[str] = None
+    quoted_tweet: Optional[Tweet] = None
+    media: Optional[list[MediaItem]] = None
+    article: Optional[ArticleMetadata] = None
+    _raw: Optional[Any] = field(default=None, repr=False)
+
+
+@dataclass
+class User:
+    id: str
+    username: str
+    name: str
+    description: Optional[str] = None
+    followers_count: Optional[int] = None
+    following_count: Optional[int] = None
+    is_blue_verified: Optional[bool] = None
+    profile_image_url: Optional[str] = None
+    created_at: Optional[str] = None
+
+
+@dataclass
+class TwitterList:
+    id: str
+    name: str
+    description: Optional[str] = None
+    member_count: Optional[int] = None
+    subscriber_count: Optional[int] = None
+    is_private: bool = False
+    created_at: Optional[str] = None
+    owner: Optional[Author] = None
+
+
+@dataclass
+class AboutProfile:
+    account_based_in: Optional[str] = None
+    source: Optional[str] = None
+    created_country_accurate: Optional[str] = None
+    location_accurate: Optional[str] = None
+    learn_more_url: Optional[str] = None
+
+
+@dataclass
+class NewsItem:
+    id: str
+    headline: str
+    category: Optional[str] = None
+    time_ago: Optional[str] = None
+    post_count: Optional[int] = None
+    description: Optional[str] = None
+    url: Optional[str] = None
+    tweets: Optional[list[Tweet]] = None
+    _raw: Optional[Any] = field(default=None, repr=False)

bird/_query_ids.py

@@ -0,0 +1,211 @@
+"""Runtime query ID store — fetches and caches X/Twitter GraphQL query IDs.
+
+X rotates these IDs frequently; this module scrapes them from the public
+x.com JavaScript bundles so the client stays functional without manual updates.
+Cache lives at ~/.config/bird/query-ids-cache.json (24 h TTL by default).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+from ._constants import FALLBACK_QUERY_IDS
+
+_DEFAULT_TTL = 24 * 60 * 60  # seconds
+_CACHE_FILENAME = "query-ids-cache.json"
+_DISCOVERY_PAGES = [
+    "https://x.com/?lang=en",
+    "https://x.com/explore",
+    "https://x.com/notifications",
+    "https://x.com/settings/profile",
+]
+_BUNDLE_URL_RE = re.compile(
+    r"https://abs\.twimg\.com/responsive-web/client-web(?:-legacy)?/[A-Za-z0-9.\-]+\.js"
+)
+_QUERY_ID_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+_OPERATION_PATTERNS: list[tuple[re.Pattern, int, int]] = [
+    # (pattern, operation_group, query_id_group)
+    (re.compile(r'e\.exports=\{queryId\s*:\s*["\']([^"\']+)["\']\s*,\s*operationName\s*:\s*["\']([^"\']+)["\']'), 2, 1),
+    (re.compile(r'e\.exports=\{operationName\s*:\s*["\']([^"\']+)["\']\s*,\s*queryId\s*:\s*["\']([^"\']+)["\']'), 1, 2),
+    (re.compile(r'operationName\s*[:=]\s*["\']([^"\']+)["\'].{0,4000}?queryId\s*[:=]\s*["\']([^"\']+)["\']', re.DOTALL), 1, 2),
+    (re.compile(r'queryId\s*[:=]\s*["\']([^"\']+)["\'].{0,4000}?operationName\s*[:=]\s*["\']([^"\']+)["\']', re.DOTALL), 2, 1),
+]
+_FETCH_HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) "
+        "Chrome/129.0.0.0 Safari/537.36"
+    ),
+    "Accept": "text/html,application/json;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+
+def _default_cache_path() -> Path:
+    import os
+    override = os.environ.get("BIRD_QUERY_IDS_CACHE", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / ".config" / "bird" / _CACHE_FILENAME
+
+
+def _load_cache(path: Path) -> Optional[dict]:
+    try:
+        data = json.loads(path.read_text())
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    for key in ("fetchedAt", "ttl", "ids"):
+        if key not in data:
+            return None
+    if not isinstance(data["ids"], dict):
+        return None
+    return data
+
+
+def _save_cache(path: Path, snapshot: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(snapshot, indent=2) + "\n")
+
+
+def _discover_bundles(client: httpx.Client) -> list[str]:
+    bundles: set[str] = set()
+    for page in _DISCOVERY_PAGES:
+        try:
+            r = client.get(page, headers=_FETCH_HEADERS, timeout=20)
+            if r.is_success:
+                bundles.update(_BUNDLE_URL_RE.findall(r.text))
+        except Exception:
+            pass
+    if not bundles:
+        raise RuntimeError("No X/Twitter client bundles discovered; layout may have changed.")
+    return list(bundles)
+
+
+def _extract_operations(js: str, targets: set[str], discovered: dict[str, str]) -> None:
+    for pattern, op_group, qid_group in _OPERATION_PATTERNS:
+        for m in pattern.finditer(js):
+            op_name = m.group(op_group)
+            query_id = m.group(qid_group)
+            if not op_name or not query_id:
+                continue
+            if op_name not in targets or op_name in discovered:
+                continue
+            if not _QUERY_ID_RE.match(query_id):
+                continue
+            discovered[op_name] = query_id
+            if len(discovered) == len(targets):
+                return
+
+
+def _fetch_and_extract(
+    client: httpx.Client, bundle_urls: list[str], targets: set[str]
+) -> dict[str, str]:
+    discovered: dict[str, str] = {}
+    CONCURRENCY = 6
+
+    def fetch_one(url: str) -> Optional[str]:
+        try:
+            r = client.get(url, headers=_FETCH_HEADERS, timeout=30)
+            return r.text if r.is_success else None
+        except Exception:
+            return None
+
+    for i in range(0, len(bundle_urls), CONCURRENCY):
+        if len(discovered) == len(targets):
+            break
+        chunk = bundle_urls[i : i + CONCURRENCY]
+        with ThreadPoolExecutor(max_workers=CONCURRENCY) as ex:
+            futures = {ex.submit(fetch_one, url): url for url in chunk}
+            for fut in as_completed(futures):
+                js = fut.result()
+                if js:
+                    _extract_operations(js, targets, discovered)
+                if len(discovered) == len(targets):
+                    break
+    return discovered
+
+
+class QueryIdStore:
+    """Thread-safe, disk-backed cache for X/Twitter GraphQL query IDs."""
+
+    def __init__(
+        self,
+        cache_path: Optional[Path] = None,
+        ttl: int = _DEFAULT_TTL,
+    ) -> None:
+        self._cache_path = cache_path or _default_cache_path()
+        self._ttl = ttl
+        self._snapshot: Optional[dict] = None
+
+    def _load(self) -> None:
+        if self._snapshot is None:
+            self._snapshot = _load_cache(self._cache_path)
+
+    def _is_fresh(self) -> bool:
+        if not self._snapshot:
+            return False
+        try:
+            age = time.time() - self._snapshot["fetchedAt"]
+            return age <= self._snapshot.get("ttl", self._ttl)
+        except Exception:
+            return False
+
+    def get(self, operation: str) -> str:
+        self._load()
+        if self._snapshot:
+            cached = self._snapshot.get("ids", {}).get(operation)
+            if cached:
+                return cached
+        return FALLBACK_QUERY_IDS.get(operation, "")
+
+    def refresh(self, operations: list[str], force: bool = False) -> None:
+        self._load()
+        if not force and self._is_fresh():
+            return
+        targets = set(operations)
+        try:
+            with httpx.Client() as client:
+                bundle_urls = _discover_bundles(client)
+                found = _fetch_and_extract(client, bundle_urls, targets)
+        except Exception:
+            return  # silently keep using fallbacks
+        if not found:
+            return
+        snapshot = {
+            "fetchedAt": time.time(),
+            "ttl": self._ttl,
+            "ids": found,
+        }
+        try:
+            _save_cache(self._cache_path, snapshot)
+        except Exception:
+            pass
+        self._snapshot = snapshot
+
+    def info(self) -> dict:
+        self._load()
+        if not self._snapshot:
+            return {"cached": False, "cachePath": str(self._cache_path)}
+        age = time.time() - self._snapshot.get("fetchedAt", 0)
+        return {
+            "cached": True,
+            "cachePath": str(self._cache_path),
+            "fetchedAt": self._snapshot.get("fetchedAt"),
+            "ttl": self._snapshot.get("ttl", self._ttl),
+            "ageSeconds": int(age),
+            "fresh": self._is_fresh(),
+            "ids": self._snapshot.get("ids", {}),
+        }
+
+
+# Module-level singleton — shared across all TwitterClient instances
+query_id_store = QueryIdStore()