xapiweb 1.5.0__py3-none-any.whl

xapiweb/resources/tweets.py

@@ -0,0 +1,288 @@
+"""Tweets: read, post, delete, pin, reply-controls, disclosures."""
+from .. import errors as E
+from ._base import BaseResource
+from .media import parse_media_entities
+
+REPLY_MODES = ("ByInvitation", "Verified", "Subscribers", "Community", "MyNetwork", "CountryOfOrigin")
+
+
+class Tweets(BaseResource):
+    # ---------------- read ----------------
+    def get(self, tweet_id):
+        """Tweet by id. Proven: test_tweet_by_id.py"""
+        return self._s.gql_get("TweetResultByRestId", {
+            "tweetId": str(tweet_id), "withCommunity": False,
+            "withVoice": True, "includePromotedContent": False})
+
+    def get_many(self, tweet_ids):
+        """Batch tweets by ids. Proven: test_tweet_results_by_rest_ids.py"""
+        return self._s.gql_get("TweetResultsByRestIds", {
+            "tweetIds": [str(i) for i in tweet_ids], "includePromotedContent": False,
+            "withVoice": True, "withCommunity": False})
+
+    def detail(self, focal_tweet_id):
+        """Conversation/detail (thread + replies). Proven: test_tweet_detail.py"""
+        return self._s.gql_get("TweetDetail", {
+            "focalTweetId": str(focal_tweet_id), "with_rux_injections": False,
+            "rankingMode": "Relevance", "includePromotedContent": True,
+            "withCommunity": True, "withQuickPromoteEligibilityTweetFields": True,
+            "withVoice": True, "withBirdwatchNotes": False})
+
+    def oembed(self, tweet_url):
+        """oEmbed card for a tweet URL. Proven: test_oembed.py"""
+        return self._s.rest_get("statuses/oembed.json", {"url": tweet_url})
+
+    def quick_promote_eligibility(self, tweet_id):
+        """Proven: test_quick_promote_eligibility.py"""
+        return self._s.gql_get("QuickPromoteEligibility", {"tweetId": str(tweet_id)},
+                               with_features=False, with_toggles=False)
+
+    def moderated_view(self, root_tweet_id, count=5):
+        """Proven: test_moderated_timeline.py"""
+        return self._s.gql_get("ModeratedTimeline", {
+            "rootTweetId": str(root_tweet_id), "count": count, "includePromotedContent": False})
+
+    def similar(self, tweet_id):
+        """Similar posts (snake_case var!). Proven: test_similar_posts.py"""
+        return self._s.gql_get("SimilarPosts", {"tweet_id": str(tweet_id)})
+
+    def views(self, tweet_id):
+        """Impressions/views count (int) or None if unavailable.
+        Lives at result.views.count (sibling of legacy, NOT inside it).
+        Proven live by xapiweb 2026-09-20."""
+        r = self.get(tweet_id)
+        v = r.get("data", "tweetResult", "result", "views", default=None) or {}
+        try:
+            return int(v.get("count"))
+        except (TypeError, ValueError):
+            return None
+
+    def stats(self, tweet_id):
+        """All public counts in ONE call: views/likes/retweets/replies/quotes/bookmarks.
+        Proven live by xapiweb 2026-09-20."""
+        r = self.get(tweet_id)
+        res = r.get("data", "tweetResult", "result", default={}) or {}
+        leg = res.get("legacy", {}) or {}
+        views = None
+        try:
+            views = int((res.get("views") or {}).get("count"))
+        except (TypeError, ValueError):
+            pass
+        return {"views": views,
+                "likes": leg.get("favorite_count"),
+                "retweets": leg.get("retweet_count"),
+                "replies": leg.get("reply_count"),
+                "quotes": leg.get("quote_count"),
+                "bookmarks": leg.get("bookmark_count")}
+
+    def media(self, tweet_id):
+        """Attached media: [{type, url, thumb, width, height, duration_ms, bitrate, ...}].
+
+        type: photo | video | animated_gif. url = direct image url, or best mp4
+        (max bitrate) for video/gif. Empty list when no media.
+        Proven live by xapiweb 2026-09-20."""
+        r = self.get(tweet_id)
+        leg = r.get("data", "tweetResult", "result", "legacy", default={}) or {}
+        return parse_media_entities(leg)
+
+    def drafts(self):
+        """Draft tweets. Proven: test_draft_tweets.py"""
+        return self._s.gql_get("FetchDraftTweets", {"ascending": False},
+                               with_features=False, with_toggles=False)
+
+    def scheduled(self):
+        """Scheduled tweets (read). Proven: test_scheduled_tweets.py"""
+        return self._s.gql_get("FetchScheduledTweets", {"ascending": True},
+                               with_features=False, with_toggles=False)
+
+    # ---------------- write ----------------
+    def post(self, text, reply_to=None, media_ids=None, possibly_sensitive=False, verify=True):
+        """Post a tweet; optionally as a reply and/or with uploaded media.
+
+        reply_to: tweet id this is a reply to (proven live by xapiweb).
+        media_ids: list from media.upload_image() (proven live by xapiweb self-test).
+        Returns Response; new id at .get("data","create_tweet","tweet_results","result","rest_id").
+        No rest_id => NOT posted (bad txn) => raises XTxnError.
+        Proven: test_post_and_delete_tweet.py (+ xapiweb reply/media proofs).
+        """
+        media = {"media_entities": [], "possibly_sensitive": bool(possibly_sensitive)}
+        if media_ids:
+            media["media_entities"] = [{"media_id": str(m), "tagged_users": []} for m in media_ids]
+        variables = {"tweet_text": text, "media": media,
+                     "semantic_annotation_ids": [], "disallowed_reply_options": None}
+        if reply_to:
+            variables["reply"] = {"in_reply_to_tweet_id": str(reply_to), "exclude_reply_user_ids": []}
+        resp = self._s.gql_post("CreateTweet", variables, with_features=True)
+        E.guard(resp, "CreateTweet")
+        nid = resp.get("data", "create_tweet", "tweet_results", "result", "rest_id")
+        if not nid:
+            raise E.XTxnError("CreateTweet 200 with empty tweet_results: bad/missing txn-id; NOT posted.")
+        resp.tweet_id = nid
+        if verify and reply_to:
+            back = self.get(nid)
+            got = back.get("data", "tweetResult", "result", "legacy", "in_reply_to_status_id_str")
+            if got != str(reply_to):
+                self.delete(nid, verify=False)
+                raise E.XVerifyError(f"Reply posted standalone (in_reply_to={got}); stray tweet deleted.")
+        return resp
+
+    def create_poll_card(self, choices, duration_minutes=1440):
+        """Create a poll card (caps API). choices: 2-4 labels (1-25 chars each).
+        duration_minutes: 5..10080. Returns card_uri like 'card://...'.
+        Proven live by xapiweb 2026-09-20 (2- and 4-choice, full post cycle)."""
+        import json as _json
+        import urllib.parse as _up
+        labels = list(choices)
+        if not (2 <= len(labels) <= 4):
+            raise ValueError("polls need 2-4 choices")
+        for c in labels:
+            if not c or len(c) > 25:
+                raise ValueError("poll choice labels must be 1-25 chars")
+        if not (5 <= int(duration_minutes) <= 10080):
+            raise ValueError("duration_minutes must be 5..10080")
+        n = len(labels)
+        card = {"twitter:card": f"poll{n}choice_text_only",
+                f"twitter:api:poll{n}choice_text_only": True,
+                "twitter:api:api:endpoint": "1",
+                "twitter:long:duration_minutes": str(int(duration_minutes))}
+        for i, c in enumerate(labels, 1):
+            card[f"twitter:string:choice{i}_label"] = c
+        r = self._s.call("POST", "https://caps.twitter.com/v2/cards/create",
+                         _up.urlencode({"card_data": _json.dumps(card)}),
+                         "application/x-www-form-urlencoded; charset=UTF-8")
+        uri = r.get("card_uri")
+        if r.status != 200 or not uri:
+            raise E.XError(f"Poll card create failed: {r.status} {r.raw[:200]}")
+        return uri
+
+    def post_poll(self, text, choices, duration_minutes=1440, verify=True):
+        """Post a tweet with an attached poll. Returns Response (id at .tweet_id,
+        card at .poll_card). Cards are single-use. Proven live by xapiweb 2026-09-20."""
+        uri = self.create_poll_card(choices, duration_minutes)
+        resp = self._s.gql_post("CreateTweet", {
+            "tweet_text": text, "card_uri": uri,
+            "media": {"media_entities": [], "possibly_sensitive": False},
+            "semantic_annotation_ids": [], "disallowed_reply_options": None},
+            with_features=True)
+        E.guard(resp, "CreateTweet")
+        nid = resp.get("data", "create_tweet", "tweet_results", "result", "rest_id")
+        if not nid:
+            raise E.XTxnError("CreateTweet 200 with empty tweet_results: bad txn; NOT posted.")
+        resp.tweet_id = nid
+        resp.poll_card = uri
+        if verify and "choice1_label" not in self.get(nid).raw:
+            raise E.XVerifyError(f"Poll card missing on re-read of {nid}.")
+        return resp
+
+    def post_thread(self, texts, verify=True):
+        """Post a thread (first tweet + chained replies). Returns [ids], in order.
+        On mid-thread failure, already-posted ids are attached as err.posted_ids
+        (delete them yourself). Proven live by xapiweb 2026-09-20."""
+        texts = list(texts)
+        if not texts:
+            raise ValueError("post_thread needs >= 1 text")
+        ids = []
+        try:
+            reply_to = None
+            for t in texts:
+                r = self.post(t, reply_to=reply_to, verify=verify)
+                reply_to = r.tweet_id
+                ids.append(reply_to)
+        except E.XError as e:
+            e.posted_ids = ids
+            raise
+        return ids
+
+    def delete(self, tweet_id, verify=True):
+        """Delete own tweet. Proven: test_post_and_delete_tweet.py"""
+        resp = self._s.gql_post("DeleteTweet", {"tweet_id": str(tweet_id)})
+        E.guard(resp, "DeleteTweet")
+        if verify:
+            back = self.get(tweet_id)
+            if '"tweetResult":{}' not in back.raw.replace(" ", ""):
+                raise E.XVerifyError(f"Tweet {tweet_id} still readable after delete.")
+        return resp
+
+    def pin(self, tweet_id):
+        """Pin own tweet. Proven: test_pin_cycle.py"""
+        resp = self._s.gql_post("PinTweet", {"tweet_id": str(tweet_id)})
+        return E.guard(resp, "PinTweet")
+
+    def unpin(self, tweet_id):
+        """Unpin own tweet. Proven: test_pin_cycle.py"""
+        resp = self._s.gql_post("UnpinTweet", {"tweet_id": str(tweet_id)})
+        return E.guard(resp, "UnpinTweet")
+
+    def set_reply_control(self, tweet_id, mode, allowed_country_codes=None, verify=True):
+        """Limit who can reply. Modes: ByInvitation|Verified|Subscribers|Community|
+        MyNetwork(gated)|CountryOfOrigin(+codes). Proven: test_conversation_control_pair.py"""
+        if mode not in REPLY_MODES:
+            raise ValueError(f"mode must be one of {REPLY_MODES}")
+        variables = {"tweet_id": str(tweet_id), "mode": mode}
+        if allowed_country_codes:
+            variables["allowed_country_codes"] = list(allowed_country_codes)
+        resp = self._s.gql_post("ConversationControlChange", variables)
+        E.guard(resp, "ConversationControlChange")
+        if verify:
+            back = self.get(tweet_id)
+            if f'"mode":"{mode}"' not in back.raw.replace(" ", ""):
+                raise E.XVerifyError(f"Reply-control marker {mode} not found on re-read.")
+        return resp
+
+    def remove_reply_control(self, tweet_id):
+        """Revert reply limits (idempotent 'Done'). Proven: test_conversation_control_pair.py"""
+        resp = self._s.gql_post("ConversationControlDelete", {"tweet_id": str(tweet_id)})
+        return E.guard(resp, "ConversationControlDelete")
+
+    def add_ad_disclosure(self, tweet_id, verify=True):
+        """Paid-promotion label. Proven: test_content_disclosure_pair.py"""
+        resp = self._s.gql_post("AddContentDisclosure", {
+            "tweet_id": str(tweet_id), "advertising_disclosure": {"is_paid_promotion": True}})
+        E.guard(resp, "AddContentDisclosure")
+        if verify:
+            self._assert_disclosure(tweet_id, True)
+        return resp
+
+    def add_ai_disclosure(self, tweet_id, verify=True):
+        """AI-generated-media label. Proven: test_content_disclosure_pair.py"""
+        resp = self._s.gql_post("AddContentDisclosure", {
+            "tweet_id": str(tweet_id),
+            "ai_generated_disclosure": {"has_ai_generated_media": True}})
+        E.guard(resp, "AddContentDisclosure")
+        if verify:
+            self._assert_disclosure(tweet_id, True)
+        return resp
+
+    def remove_disclosure(self, tweet_id, verify=True):
+        """Remove disclosure label. Proven: test_content_disclosure_pair.py"""
+        resp = self._s.gql_post("DeleteContentDisclosure", {"tweet_id": str(tweet_id)})
+        E.guard(resp, "DeleteContentDisclosure")
+        if verify:
+            import time
+            self._assert_disclosure(tweet_id, False)
+        return resp
+
+    def _assert_disclosure(self, tweet_id, present):
+        import time
+        d = self.detail(tweet_id)
+        has = "disclosure" in d.raw.lower()
+        if present and not has:
+            raise E.XVerifyError("Disclosure marker missing on re-read.")
+        if not present and has:
+            time.sleep(3)
+            d = self.detail(tweet_id)
+            if "disclosure" in d.raw.lower():
+                raise E.XVerifyError("Disclosure marker still present after remove.")
+
+    # ---------------- gated (documented, not usable on this account type) ----------------
+    def create_note(self, text):
+        """Long-form note. GATED: needs Premium (code 37 without). Proven: test_note_tweet_guard.py"""
+        return self._s.gql_post("CreateNoteTweet", {"tweet_text": text})
+
+    def create_highlight(self, tweet_id):
+        """GATED: needs unknown eligibility. Proven: test_create_highlight_shape.py"""
+        return self._s.gql_post("CreateHighlight", {"tweet_id": str(tweet_id)})
+
+    def delete_highlight(self, tweet_id):
+        """GATED: mirrors create. Proven: test_delete_highlight_shape.py"""
+        return self._s.gql_post("DeleteHighlight", {"tweet_id": str(tweet_id)})

xapiweb/resources/users.py

@@ -0,0 +1,85 @@
+"""Users: profiles, batches, recommendations, credentials."""
+from ._base import BaseResource
+
+
+class Users(BaseResource):
+    def by_screen_name(self, screen_name, grok_bio=True):
+        """Proven: test_user_by_screen_name.py"""
+        return self._s.gql_get("UserByScreenName",
+                               {"screen_name": screen_name, "withGrokTranslatedBio": grok_bio})
+
+    def by_id(self, user_id, grok_bio=True):
+        """Proven: test_user_by_rest_id.py"""
+        return self._s.gql_get("UserByRestId",
+                               {"userId": str(user_id), "withGrokTranslatedBio": grok_bio})
+
+    def batch_by_ids(self, user_ids):
+        """POST-only (GET 404s). Proven: test_users_by_rest_ids.py"""
+        return self._s.gql_post("UsersByRestIds", {"userIds": [str(i) for i in user_ids]})
+
+    def batch_by_names(self, screen_names):
+        """snake_case var! Proven: test_users_by_screen_names.py"""
+        return self._s.gql_get("UsersByScreenNames", {"screen_names": list(screen_names)})
+
+    def viewer(self):
+        """Viewer/me object. Proven: test_viewer.py"""
+        return self._s.gql_get("Viewer", {})
+
+    def username_availability(self, username, suggestions=True):
+        """Proven: test_username_availability.py"""
+        return self._s.gql_post("GetUsernameAvailabilityAndSuggestions", {
+            "username": username, "include_suggestions": suggestions, "session_token": ""})
+
+    def show(self, user_id):
+        """REST, txn-gated (404 without). Proven: test_user_show.py"""
+        return self._s.rest_get("users/show.json", {"user_id": str(user_id), "skip_status": 1})
+
+    def lookup(self, user_ids):
+        """REST batch, txn-gated. Proven: test_users_lookup.py"""
+        if isinstance(user_ids, (list, tuple)):
+            user_ids = ",".join(str(i) for i in user_ids)
+        return self._s.rest_get("users/lookup.json", {"user_id": user_ids})
+
+    def verify_credentials(self):
+        """REST, txn-gated. Proven: test_verify_credentials.py"""
+        return self._s.rest_get("account/verify_credentials.json", {"skip_status": 1})
+
+    def recommendations(self, limit=3, user_id=None):
+        """Proven: test_user_recommendations.py"""
+        return self._s.rest_get("users/recommendations.json", {
+            "limit": limit, "user_id": str(user_id or self._me()),
+            "display_location": "profile-cluster-follow", "skip_status": 1})
+
+    def verified_avatars(self, user_ids):
+        """Proven: test_users_verified_avatars.py"""
+        return self._s.gql_get("UsersVerifiedAvatars",
+                               {"userIds": [str(i) for i in user_ids]}, with_toggles=False)
+
+    def spotlights(self, screen_name):
+        """Proven: test_profile_spotlights.py"""
+        return self._s.gql_get("ProfileSpotlightsQuery", {"screen_name": screen_name},
+                               with_features=False, with_toggles=False)
+
+    def claims(self):
+        """Proven: test_user_claims.py"""
+        return self._s.gql_get("GetUserClaims", {})
+
+    def preferences(self):
+        """Proven: test_user_preferences.py"""
+        return self._s.gql_get("UserPreferences", {})
+
+    def sessions(self):
+        """Active sessions list. Proven: test_user_sessions.py"""
+        return self._s.gql_get("UserSessionsList", {})
+
+    def upsells(self):
+        """Proven: test_upsells.py"""
+        return self._s.gql_get("Upsells", {})
+
+    def me(self):
+        """Cached {id, screen_name, ...} of the session owner (via verify_credentials)."""
+        if self._client._me_cache is None:
+            r = self.verify_credentials()
+            self._client._me_cache = {"id": r.get("id_str"), "screen_name": r.get("screen_name"),
+                                      "name": r.get("name"), "raw": r}
+        return self._client._me_cache

xapiweb/response.py

@@ -0,0 +1,39 @@
+"""Response: one parsed wrapper for every xapiweb call."""
+import json
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Response:
+    url: str
+    status: int
+    headers: dict
+    raw: str
+    _data: object = field(default=None, repr=False, compare=False)
+
+    @property
+    def data(self):
+        if self._data is None:
+            try:
+                self._data = json.loads(self.raw)
+            except Exception:
+                self._data = {}
+        return self._data
+
+    @property
+    def ok(self):
+        return 200 <= self.status < 300
+
+    def get(self, *keys, default=None):
+        """Safe nested walk over parsed JSON (dict keys or list indices)."""
+        cur = self.data
+        try:
+            for k in keys:
+                cur = cur[k]
+            return cur
+        except Exception:
+            return default
+
+    def summary(self, limit=600):
+        body = self.raw if isinstance(self.raw, str) else json.dumps(self.raw)
+        return body[:limit] + ("…(truncated)" if len(body) > limit else "")

xapiweb/session.py

@@ -0,0 +1,213 @@
+"""Session: auth, txn-id, pacing, and low-level HTTP for X web APIs.
+
+Engine ported from the proven x_api_pack (common.py, live 2026-09-19),
+repackaged as a class so secrets are never module-global.
+Stdlib only.
+"""
+import json
+import os
+import tempfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from ._txn import ClientTransaction
+from .qids import QIDS
+from .response import Response
+from . import errors as E
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DATA_DIR = os.path.join(HERE, "data")
+DEFAULT_BEARER = ("AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D"
+                  "1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA")
+DEFAULT_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:154.0) "
+              "Gecko/20100101 Firefox/154.0")
+TXN_TTL = 600  # one homepage load serves many calls, like a browser tab
+
+
+class Session:
+    def __init__(self, cookie, csrf_token, bearer=None, user_agent=None,
+                 txn_cache=None, min_interval=1.0, timeout=25):
+        if not cookie or not csrf_token:
+            raise E.XError("cookie and csrf_token are required")
+        self.cookie = cookie
+        self.csrf_token = csrf_token
+        self.bearer = bearer or DEFAULT_BEARER
+        self.user_agent = user_agent or DEFAULT_UA
+        self.txn_cache = txn_cache or os.path.join(tempfile.gettempdir(), "xapiweb_txn_cache.json")
+        self.min_interval = min_interval
+        self.timeout = timeout
+        with open(os.path.join(DATA_DIR, "features.json")) as f:
+            self.features = json.load(f)
+        with open(os.path.join(DATA_DIR, "fieldtoggles.json")) as f:
+            self.field_toggles = json.load(f)
+        self._txn = None
+        self._last_call = 0.0
+        self.refs = {}      # reference_ids from session file (self_id, ...)
+        self.account = None
+
+    @classmethod
+    def from_session_file(cls, path, **kw):
+        """Load a my_data.json-style session file (cookie + csrf_token + ...)."""
+        with open(path) as f:
+            d = json.load(f)
+        s = cls(
+            d["cookie"], d.get("csrf_token") or d.get("ct0"),
+            bearer=d.get("bearer"), user_agent=d.get("user_agent"),
+            txn_cache=kw.pop("txn_cache", os.path.join(
+                os.path.dirname(os.path.abspath(path)), ".txn_cache.json")),
+            **kw)
+        s.refs = d.get("reference_ids", {}) or {}
+        s.account = d.get("account")
+        return s
+
+    # ---------------- transaction id ----------------
+    def _key_works(self, html):
+        """True if txn-ids minted from this homepage HTML are accepted (cheap probe)."""
+        try:
+            t = ClientTransaction()
+            t.init_from_html(html)
+            tid = t.generate_transaction_id(method="GET", path="/1.1/account/settings.json")
+        except Exception:
+            return False
+        hh = {"Authorization": f"Bearer {self.bearer}", "x-twitter-auth-type": "OAuth2Session",
+              "x-csrf-token": self.csrf_token, "x-twitter-client-language": "en",
+              "x-twitter-active-user": "yes", "x-client-transaction-id": tid,
+              "User-Agent": self.user_agent, "Accept": "*/*", "Referer": "https://x.com/home",
+              "Cookie": self.cookie}
+        try:
+            req = urllib.request.Request("https://api.x.com/1.1/account/settings.json",
+                                         headers=hh, method="GET")
+            with urllib.request.urlopen(req, timeout=20) as r:
+                return r.status == 200
+        except Exception:
+            return False
+
+    def _txn_html(self):
+        """Logged-in homepage HTML with a WORKING key, cached on disk."""
+        try:
+            d = json.load(open(self.txn_cache))
+            html = d.get("html", "")
+            if time.time() - d.get("saved_at", 0) < TXN_TTL and self._key_works(html):
+                return html
+        except Exception:
+            pass
+        for _ in range(3):
+            req = urllib.request.Request("https://x.com/home",
+                                         headers={"User-Agent": self.user_agent,
+                                                  "Cookie": self.cookie, "Accept": "text/html"})
+            html = urllib.request.urlopen(req, timeout=25).read().decode("utf-8", "replace")
+            if "loading-x-anim" in html and "twitter-site-verification" in html \
+                    and self._key_works(html):
+                try:
+                    json.dump({"saved_at": time.time(), "html": html}, open(self.txn_cache, "w"))
+                except Exception:
+                    pass
+                return html
+            time.sleep(2)
+        raise RuntimeError("3 homepage loads yielded no working transaction key")
+
+    def txn_id(self, method: str, path: str) -> str:
+        """Valid x-client-transaction-id for one (method, path)."""
+        if self._txn is None:
+            self._txn = ClientTransaction()
+            self._txn.init_from_html(self._txn_html())
+        return self._txn.generate_transaction_id(method=method, path=path)
+
+    def headers(self, method: str, path: str, referer="https://x.com/home"):
+        return {
+            "Authorization": f"Bearer {self.bearer}",
+            "x-twitter-auth-type": "OAuth2Session",
+            "x-csrf-token": self.csrf_token,
+            "x-twitter-client-language": "en",
+            "x-twitter-active-user": "yes",
+            "x-client-transaction-id": self.txn_id(method, path),
+            "User-Agent": self.user_agent, "Accept": "*/*",
+            "Referer": referer, "Cookie": self.cookie,
+        }
+
+    # ---------------- HTTP ----------------
+    def _pace(self):
+        wait = self.min_interval - (time.monotonic() - self._last_call)
+        if wait > 0:
+            time.sleep(wait)
+
+    def call(self, method, url, payload=None, content_type="application/json",
+             referer="https://x.com/home", timeout=None) -> Response:
+        """One HTTP call with pacing + one retry on 403/429. Raises structured errors."""
+        self._pace()
+        path = urllib.parse.urlparse(url).path
+        hh = self.headers(method, path, referer)
+        data = None
+        if payload is not None:
+            data = payload.encode() if isinstance(payload, str) else payload
+            hh["Content-Type"] = content_type
+            hh["Origin"] = "https://x.com"
+            hh["Content-Length"] = str(len(data))
+        req = urllib.request.Request(url, data=data, headers=hh, method=method)
+        to = timeout or self.timeout
+        try:
+            for attempt in (0, 1):
+                try:
+                    with urllib.request.urlopen(req, timeout=to) as resp:
+                        self._last_call = time.monotonic()
+                        return Response(url=url, status=resp.status,
+                                        headers=dict(resp.headers),
+                                        raw=resp.read().decode("utf-8", "replace"))
+                except urllib.error.HTTPError as e:
+                    if e.code in (403, 429) and attempt == 0:
+                        time.sleep(5)
+                        continue
+                    raise
+        except urllib.error.HTTPError as e:
+            self._last_call = time.monotonic()
+            body = ""
+            try:
+                body = e.read().decode("utf-8", "replace")
+            except Exception:
+                pass
+            raise E.http_error(url, e.code, body)
+
+    # ---------------- GraphQL / REST helpers ----------------
+    def gql_get(self, op, variables, with_features=True, with_toggles=True) -> Response:
+        qid = QIDS[op]
+        qs = {"variables": json.dumps(variables, separators=(",", ":"))}
+        if with_features:
+            qs["features"] = json.dumps(self.features, separators=(",", ":"))
+        if with_toggles:
+            qs["fieldToggles"] = json.dumps(self.field_toggles, separators=(",", ":"))
+        url = f"https://x.com/i/api/graphql/{qid}/{op}?" + urllib.parse.urlencode(qs)
+        return self.call("GET", url)
+
+    def gql_post(self, op, variables, with_features=False) -> Response:
+        qid = QIDS[op]
+        url = f"https://x.com/i/api/graphql/{qid}/{op}"
+        payload = {"variables": variables, "queryId": qid}
+        if with_features:
+            payload["features"] = self.features
+        return self.call("POST", url, json.dumps(payload))
+
+    def rest_get(self, path, params=None, host="https://x.com", prefix="/i/api/1.1/") -> Response:
+        url = host + prefix + path.lstrip("/") + ("?" + urllib.parse.urlencode(params) if params else "")
+        return self.call("GET", url)
+
+    def rest_post_form(self, path, form, host="https://x.com", prefix="/i/api/1.1/") -> Response:
+        url = host + prefix + path.lstrip("/")
+        return self.call("POST", url, urllib.parse.urlencode(form),
+                         "application/x-www-form-urlencoded; charset=UTF-8")
+
+    @staticmethod
+    def jget(body, *keys, default=None):
+        try:
+            cur = json.loads(body) if isinstance(body, str) else body
+            for k in keys:
+                cur = cur[k]
+            return cur
+        except Exception:
+            return default
+
+    @staticmethod
+    def summarize(body, limit=600):
+        body = body if isinstance(body, str) else json.dumps(body)
+        return body[:limit] + ("…(truncated)" if len(body) > limit else "")