xapiweb 1.5.0__py3-none-any.whl

xapiweb/resources/moderation.py

@@ -0,0 +1,84 @@
+"""Mutes & blocks (REST + GraphQL)."""
+from .. import errors as E
+from ._base import BaseResource
+
+
+class Moderation(BaseResource):
+    # ---- mutes ----
+    def mute(self, user_id, verify=True):
+        """Proven: test_mute_pair.py"""
+        resp = self._s.rest_post_form("mutes/users/create.json",
+                                      {"user_id": str(user_id), "skip_status": 1})
+        if verify and str(user_id) not in [str(i) for i in (self.mutes_ids().get("ids") or [])]:
+            raise E.XVerifyError(f"Mute of {user_id} not confirmed in ids.")
+        return resp
+
+    def unmute(self, user_id, verify=True):
+        """Proven: test_mute_pair.py"""
+        resp = self._s.rest_post_form("mutes/users/destroy.json", {"user_id": str(user_id)})
+        if verify and str(user_id) in [str(i) for i in (self.mutes_ids().get("ids") or [])]:
+            raise E.XVerifyError(f"Unmute of {user_id} not confirmed in ids.")
+        return resp
+
+    def mutes_ids(self):
+        """Proven: test_mutes_ids.py"""
+        return self._s.rest_get("mutes/users/ids.json", {"cursor": -1})
+
+    def mutes_list(self):
+        """Proven: test_mutes_list.py"""
+        return self._s.rest_get("mutes/users/list.json", {"cursor": -1})
+
+    def muted_accounts_gql(self):
+        """Proven: test_muted_accounts_gql.py"""
+        return self._s.gql_get("MutedAccounts", {})
+
+    def advanced_filters(self):
+        """May 404 (dead-ish). Proven: test_mutes_advanced_filters.py"""
+        return self._s.rest_get("mutes/advanced_filters.json", {})
+
+    # ---- blocks ----
+    def block(self, user_id, verify=True):
+        """Proven: test_block_pair.py"""
+        resp = self._s.rest_post_form("blocks/create.json",
+                                      {"user_id": str(user_id), "skip_status": 1})
+        if verify and str(user_id) not in [str(i) for i in (self.blocks_ids().get("ids") or [])]:
+            raise E.XVerifyError(f"Block of {user_id} not confirmed in ids.")
+        return resp
+
+    def unblock(self, user_id, verify=True):
+        """Proven: test_block_pair.py"""
+        resp = self._s.rest_post_form("blocks/destroy.json", {"user_id": str(user_id)})
+        if verify and str(user_id) in [str(i) for i in (self.blocks_ids().get("ids") or [])]:
+            raise E.XVerifyError(f"Unblock of {user_id} not confirmed in ids.")
+        return resp
+
+    def blocks_ids(self):
+        """Proven: test_blocks_ids.py"""
+        return self._s.rest_get("blocks/ids.json", {"cursor": -1})
+
+    def blocks_list(self):
+        """Proven: test_blocks_list.py"""
+        return self._s.rest_get("blocks/list.json", {"cursor": -1, "skip_status": 1})
+
+    def blocked_accounts_gql(self, count=5):
+        """Proven: test_blocked_accounts_gql.py"""
+        return self._s.gql_get("BlockedAccountsAll", {"count": count})
+
+    def blocked_imported_gql(self):
+        """Proven: test_blocked_imported_gql.py"""
+        return self._s.gql_get("BlockedAccountsImported", {})
+
+    # ---- DM-specific ----
+    def dm_block(self, user_id, verify=True):
+        """Lowercase-dm op; ids differ from REST. Proven: test_dm_block_pair.py"""
+        resp = self._s.gql_post("dmBlockUser", {"target_user_id": str(user_id)})
+        if verify and "Blocked" not in resp.raw:
+            raise E.XVerifyError("dmBlock ack missing 'Blocked'.")
+        return resp
+
+    def dm_unblock(self, user_id, verify=True):
+        """Proven: test_dm_block_pair.py"""
+        resp = self._s.gql_post("dmUnblockUser", {"target_user_id": str(user_id)})
+        if verify and "Unblocked" not in resp.raw:
+            raise E.XVerifyError("dmUnblock ack missing 'Unblocked'.")
+        return resp

xapiweb/resources/notifications.py

@@ -0,0 +1,84 @@
+"""Notifications: full list + badge-count polling + realtime SSE."""
+import http.client
+import re
+
+from ._base import BaseResource
+
+
+def extract_notifications(resp_or_data, limit=50):
+    """Pull [{id, type, icon, text, users, time, url, tweet_id}] out of a
+    NotificationsTimeline response. type = element like 'users_liked_your_tweet',
+    'users_followed_you', 'mention'. users = [{screen_name, name, id}].
+    Page with xapiweb.resources.timelines.cursors(resp)['bottom']. xapiweb helper."""
+    data = resp_or_data.data if hasattr(resp_or_data, "data") else resp_or_data
+    out = []
+
+    def walk(o):
+        if len(out) >= limit:
+            return
+        if isinstance(o, dict):
+            it = o.get("itemContent")
+            if isinstance(it, dict) and it.get("__typename") == "TimelineNotification":
+                rm = it.get("rich_message") or {}
+                users = []
+                for ent in rm.get("entities") or []:
+                    ur = (((ent.get("ref") or {}).get("user_results") or {}).get("result") or {})
+                    core = ur.get("core") or {}
+                    leg = ur.get("legacy") or {}
+                    sn = core.get("screen_name") or leg.get("screen_name")
+                    if sn:
+                        users.append({"screen_name": sn,
+                                      "name": core.get("name") or leg.get("name"),
+                                      "id": core.get("rest_id") or ur.get("rest_id")})
+                url = (it.get("notification_url") or {}).get("url") or ""
+                m = re.search(r"/status/(\d+)", url)
+                out.append({"id": it.get("id"),
+                            "type": (o.get("clientEventInfo") or {}).get("element"),
+                            "icon": it.get("notification_icon"),
+                            "text": rm.get("text") or "",
+                            "users": users,
+                            "time": it.get("timestamp_ms"),
+                            "url": url,
+                            "tweet_id": m.group(1) if m else None})
+            for v in o.values():
+                walk(v)
+        elif isinstance(o, list):
+            for v in o:
+                walk(v)
+
+    walk(data)
+    return out
+
+
+class Notifications(BaseResource):
+    def list(self, timeline_type="All", count=20, cursor=None):
+        """Full notifications list. timeline_type: 'All'|'Verified'|'Mentions'
+        (all 200-proven). Parse with extract_notifications(resp); page with
+        timelines.cursors(resp)['bottom'] -> cursor=. Proven live 2026-09-20
+        (user-captured qid)."""
+        v = {"timeline_type": timeline_type, "count": count}
+        if cursor:
+            v["cursor"] = cursor
+        return self._s.gql_get("NotificationsTimeline", v, with_toggles=False)
+
+    def badge_counts(self):
+        """{dm_unread_count, ntab_unread_count, total_unread_count, ...} — the polling
+        endpoint. Proven: test_viewer_badge_counts.py"""
+        return self._s.gql_get("ViewerBadgeCounts", {},
+                               with_features=False, with_toggles=False)
+
+    def live_events(self, seconds=6, topic=None):
+        """Hold the SSE stream ~`seconds` and return {'status':, 'sample':}.
+        Full notifications timeline (AuthTimeline) is UNTESTED. Proven: test_live_pipeline.py"""
+        topic = topic or f"/live_content/{self._me()}"
+        conn = http.client.HTTPSConnection("api.x.com", timeout=seconds + 6)
+        conn.request("GET", f"/live_pipeline/events?topic={topic}",
+                     headers=self._s.headers("GET", "/live_pipeline/events"))
+        resp = conn.getresponse()
+        try:
+            conn.sock.settimeout(seconds)
+            sample = resp.read(300).decode("utf-8", "replace")
+        except Exception:
+            sample = "(connected, quiet window)"
+        conn.close()
+        return {"status": resp.status, "topic": topic, "sample": sample[:300]}

xapiweb/resources/settings.py

@@ -0,0 +1,102 @@
+"""Settings & preferences (reads + safe writes; blind writes need confirm=True)."""
+from .. import errors as E
+from ._base import BaseResource
+
+
+class Settings(BaseResource):
+    def account(self):
+        """Txn-gated, alt host. Proven: test_account_settings.py"""
+        return self._s.rest_get("account/settings.json", {"include_mention_filter": "true"},
+                                host="https://api.x.com", prefix="/1.1/")
+
+    def help_config(self):
+        """Proven: test_help_settings.py"""
+        return self._s.rest_get("help/settings.json", {})
+
+    def email_phone_info(self):
+        """PRIVATE account emails/phones — handle with care. Proven: test_email_phone_info.py"""
+        return self._s.rest_get("users/email_phone_info.json", {})
+
+    def saved_searches(self):
+        """Txn-gated, alive. Proven: test_saved_searches.py"""
+        return self._s.rest_get("saved_searches/list.json", {})
+
+    def alt_text_get(self):
+        """Proven: test_alt_text_preference.py"""
+        return self._s.gql_get("getAltTextPromptPreference", {},
+                               with_features=False, with_toggles=False)
+
+    def alt_text_set(self, prompt_type="None", verify=True):
+        """'None' = app default (default-equivalent). Proven: test_alt_text_pair.py"""
+        resp = self._s.gql_post("updateAltTextPromptPreference", {"promptType": prompt_type})
+        E.guard(resp, "updateAltTextPromptPreference")
+        if verify:
+            back = self._s.gql_post("getAltTextPromptPreference", {})
+            if f'"{prompt_type}"' not in back.raw:
+                raise E.XVerifyError("Alt-text read-back mismatch.")
+        return resp
+
+    def creator_subscriptions(self, user_id=None):
+        """Proven: test_creator_subscriptions.py"""
+        return self._s.gql_get("UserCreatorSubscriptions",
+                               {"userId": str(user_id or self._me()),
+                                "includePromotedContent": False})
+
+    def creator_subscribers(self, user_id=None):
+        """Proven: test_creator_subscribers.py"""
+        return self._s.gql_get("UserCreatorSubscribers",
+                               {"userId": str(user_id or self._me()),
+                                "includePromotedContent": False})
+
+    def phone_state(self):
+        """Proven: test_profile_phone_state.py"""
+        return self._s.gql_get("ProfileUserPhoneState", {})
+
+    def multi_accounts(self):
+        """Proven: test_multi_accounts.py"""
+        return self._s.rest_get("account/multi/list.json", {})
+
+    def oauth_apps(self):
+        """Authorized apps. Proven: test_oauth_apps.py"""
+        return self._s.rest_get("oauth/list.json", {})
+
+    def rate_limits(self):
+        """Proven: test_rate_limits.py"""
+        return self._s.rest_get("application/rate_limit_status.json", {})
+
+    def client_education_flag(self, flag="NewUserPromptEducation"):
+        """Proven: test_client_education_flag.py"""
+        resp = self._s.gql_post("PutClientEducationFlag", {"flag": flag})
+        return E.guard(resp, "PutClientEducationFlag")
+
+    def phone_label_enable(self):
+        """Code 37 'Cannot find user phone' when no phone. Proven: test_verified_phone_pair.py"""
+        return self._s.gql_post("EnableVerifiedPhoneLabel", {})
+
+    def phone_label_disable(self):
+        """Proven: test_verified_phone_pair.py"""
+        return self._s.gql_post("DisableVerifiedPhoneLabel", {})
+
+    def data_saver_mode(self, device_id="Windows/Firefox"):
+        """Proven: test_data_saver_mode.py"""
+        return self._s.gql_get("DataSaverMode", {"device_id": device_id},
+                               with_features=False, with_toggles=False)
+
+    def write_data_saver(self, data_saver_enabled, device_id=None, video_autoplay=None, confirm=False):
+        """NEVER auto-fire: current videoAutoplay is unreadable. Shape: test_write_datasaver_shape.py."""
+        if not confirm:
+            raise E.XError("write_data_saver() needs confirm=True (current value unreadable).")
+        v = {"dataSaverEnabled": bool(data_saver_enabled)}
+        if device_id is not None:
+            v["deviceId"] = device_id
+        if video_autoplay is not None:
+            v["videoAutoplay"] = video_autoplay
+        return self._s.gql_post("WriteDataSaverPreferences", v)
+
+    def write_audiospaces_sharing(self, user_id=None, sharing=None, confirm=False):
+        """NEVER auto-fire: no read API. Shape: test_sharing_audiospaces_shape.py."""
+        if not confirm:
+            raise E.XError("write_audiospaces_sharing() needs confirm=True (no read API to restore).")
+        return self._s.gql_post("SharingAudiospacesListeningDataWithFollowersUpdate", {
+            "userId": str(user_id or self._me()),
+            "sharingAudiospacesListeningDataWithFollowers": sharing})

xapiweb/resources/timelines.py

@@ -0,0 +1,228 @@
+"""Timelines: home, user timelines, search, followers, pins + URT parsing helpers."""
+from ._base import BaseResource
+
+
+def extract_tweets(resp_or_data, limit=50):
+    """Pull [{rest_id, author, text, views, retweeted, favorited, counts}] out of any
+    timeline response (walks URT instructions). xapiweb helper."""
+    data = resp_or_data.data if hasattr(resp_or_data, "data") else resp_or_data
+    tweets, seen = [], set()
+
+    def walk(obj):
+        if len(tweets) >= limit:
+            return
+        if isinstance(obj, dict):
+            tr = obj.get("tweet_results")
+            if isinstance(tr, dict):
+                r = tr.get("result", {})
+                rid = r.get("rest_id") if isinstance(r, dict) else None
+                if rid and rid not in seen:
+                    seen.add(rid)
+                    leg = r.get("legacy", {}) or {}
+                    author = "?"
+                    try:
+                        author = r["core"]["user_results"]["result"]["legacy"]["screen_name"]
+                    except Exception:
+                        try:
+                            author = r["core"]["user_results"]["result"]["core"]["screen_name"]
+                        except Exception:
+                            pass
+                    tweets.append({"rest_id": rid, "author": author,
+                                   "text": leg.get("full_text") or "",
+                                   "views": _views(r),
+                                   "retweeted": leg.get("retweeted"),
+                                   "favorited": leg.get("favorited"),
+                                   "retweet_count": leg.get("retweet_count"),
+                                   "favorite_count": leg.get("favorite_count")})
+            for v in obj.values():
+                walk(v)
+        elif isinstance(obj, list):
+            for v in obj:
+                walk(v)
+
+    walk(data.get("data", data) if isinstance(data, dict) else data)
+    return tweets
+
+
+def _views(result):
+    """result.views.count -> int (or None). Lives at result level, not legacy."""
+    try:
+        return int((result.get("views") or {}).get("count"))
+    except (TypeError, ValueError):
+        return None
+
+
+def cursors(resp_or_data):
+    """Return {'top': ..., 'bottom': ...} pagination cursors (may be None). xapiweb helper."""
+    data = resp_or_data.data if hasattr(resp_or_data, "data") else resp_or_data
+    out = {"top": None, "bottom": None}
+
+    def walk(obj):
+        if isinstance(obj, dict):
+            if obj.get("cursorType") in ("Top", "Bottom") and obj.get("value"):
+                out[obj["cursorType"].lower()] = obj["value"]
+            for v in obj.values():
+                walk(v)
+        elif isinstance(obj, list):
+            for v in obj:
+                walk(v)
+
+    walk(data)
+    return out
+
+
+class Timelines(BaseResource):
+    def home(self, count=5, seen_ids=None):
+        """Home/For-you (POST). Proven: test_home_timeline.py"""
+        return self._s.gql_post("HomeTimeline", {
+            "count": count, "includePromotedContent": True,
+            "requestContext": "launch", "withCommunity": True,
+            "seenTweetIds": seen_ids or []}, with_features=True)
+
+    # ---- user timelines (GET) ----
+    def _user_tl(self, op, user_id, count, extra=None):
+        v = {"userId": str(user_id or self._me()), "count": count,
+             "includePromotedContent": False, "withVoice": True}
+        if extra:
+            v.update(extra)
+        return self._s.gql_get(op, v)
+
+    def user_tweets(self, user_id=None, count=5):
+        """Proven: test_user_tweets.py"""
+        return self._user_tl("UserTweets", user_id, count,
+                             {"includePromotedContent": True})
+
+    def user_replies(self, user_id=None, count=5):
+        """Proven: test_user_replies.py"""
+        return self._s.gql_get("UserRepliesTimeline",
+                               {"userId": str(user_id or self._me()), "count": count,
+                                "includePromotedContent": False, "withVoice": True})
+
+    def user_media(self, user_id=None, count=5):
+        """Proven: test_user_media.py"""
+        return self._user_tl("UserMedia", user_id, count, {"withClientEventToken": False})
+
+    def user_likes(self, user_id=None, count=5):
+        """Proven: test_user_likes.py"""
+        return self._user_tl("Likes", user_id, count, {"withClientEventToken": False})
+
+    def user_reposts(self, user_id=None, count=5):
+        """Proven: test_user_reposts.py"""
+        return self._user_tl("UserRepostsTimeline", user_id, count)
+
+    def user_video(self, user_id=None, count=5):
+        """Proven: test_user_video_timeline.py"""
+        return self._user_tl("UserVideoTimeline", user_id, count, {"withClientEventToken": False})
+
+    def user_highlights(self, user_id=None, count=5):
+        """Proven: test_user_highlights.py"""
+        return self._user_tl("UserHighlightsTweets", user_id, count)
+
+    def user_articles(self, user_id=None, count=5):
+        """Proven: test_user_articles.py"""
+        return self._user_tl("UserArticlesTweets", user_id, count)
+
+    def user_photo(self, user_id=None, count=5):
+        """Proven: test_user_photo_timeline.py"""
+        return self._user_tl("UserPhotoTimeline", user_id, count)
+
+    def user_originals(self, user_id=None, count=5):
+        """Proven: test_user_originals_timeline.py"""
+        return self._s.gql_get("UserOriginalsTimeline",
+                               {"userId": str(user_id or self._me()), "count": count,
+                                "includePromotedContent": True,
+                                "withQuickPromoteEligibilityTweetFields": True, "withVoice": True})
+
+    def user_tweets_and_replies(self, user_id=None, count=5):
+        """POST-only. Proven: test_user_tweets_and_replies.py"""
+        return self._s.gql_post("UserTweetsAndReplies", {
+            "userId": str(user_id or self._me()), "count": count,
+            "includePromotedContent": False, "withVoice": True}, with_features=True)
+
+    def user_super_follow(self, user_id=None, count=5):
+        """Proven: test_user_super_follow_tweets.py"""
+        return self._user_tl("UserSuperFollowTweets", user_id, count)
+
+    def user_promoted(self, user_id=None, count=5):
+        """Proven: test_user_promoted_tweets.py"""
+        return self._s.gql_get("UserPromotedTweets",
+                               {"userId": str(user_id or self._me()), "count": count})
+
+    def user_promotable(self, user_id=None, count=5):
+        """Proven: test_user_promotable_tweets.py"""
+        return self._s.gql_get("UserPromotableTweets",
+                               {"userId": str(user_id or self._me()), "count": count})
+
+    # ---- follow graphs (GraphQL) ----
+    def followers(self, user_id=None, count=5):
+        """POST-only (GET 404s). Proven: test_followers_gql.py"""
+        return self._s.gql_post("Followers", {
+            "userId": str(user_id or self._me()), "count": count,
+            "includePromotedContent": False}, with_features=True)
+
+    def following(self, user_id=None, count=5):
+        """Proven: test_following_gql.py"""
+        return self._s.gql_get("Following", {
+            "userId": str(user_id or self._me()), "count": count,
+            "includePromotedContent": False}, with_toggles=False)
+
+    def blue_verified_followers(self, user_id=None, count=5):
+        """Proven: test_blue_verified_followers.py"""
+        return self._s.gql_get("BlueVerifiedFollowers", {
+            "userId": str(user_id or self._me()), "count": count,
+            "includePromotedContent": False}, with_toggles=False)
+
+    def followers_you_know(self, user_id=None, count=5):
+        """Proven: test_followers_you_know.py"""
+        return self._s.gql_get("FollowersYouKnow", {
+            "userId": str(user_id or self._me()), "count": count,
+            "includePromotedContent": False})
+
+    # ---- search ----
+    def search(self, raw_query, count=5, product="Top"):
+        """POST-only. Proven: test_search_timeline.py"""
+        return self._s.gql_post("SearchTimeline", {
+            "rawQuery": raw_query, "count": count,
+            "querySource": "typed_query", "product": product}, with_features=True)
+
+    def list_search(self, list_id, raw_query, count=5):
+        """Proven: test_list_search.py"""
+        return self._s.gql_get("ListSearchTimeline",
+                               {"listId": str(list_id), "rawQuery": raw_query, "count": count})
+
+    def communities_post_search(self, raw_query, count=5):
+        """Proven: test_communities_post_search.py"""
+        return self._s.gql_get("GlobalCommunitiesPostSearchTimeline",
+                               {"rawQuery": raw_query, "count": count})
+
+    def communities_latest_search(self, raw_query, count=5):
+        """Proven: test_communities_latest_search.py"""
+        return self._s.gql_get("GlobalCommunitiesLatestPostSearchTimeline",
+                               {"rawQuery": raw_query, "count": count})
+
+    # ---- misc timelines ----
+    def generic_by_id(self, timeline_id):
+        """Ids are opaque server handles; bogus id => routed 200 error. Proven: test_generic_timeline.py"""
+        return self._s.gql_get("GenericTimelineById", {"timelineId": str(timeline_id)},
+                               with_features=False, with_toggles=False)
+
+    def moderated(self, root_tweet_id, count=5):
+        """Community moderation queue view. Proven: test_moderated_timeline.py"""
+        return self._s.gql_get("ModeratedTimeline", {
+            "rootTweetId": str(root_tweet_id), "count": count, "includePromotedContent": False})
+
+    def pinned(self, user_id=None):
+        """Profile pinned timelines. Proven: test_pinned_timelines.py"""
+        return self._s.gql_get("PinnedTimelines", {"userId": str(user_id or self._me())},
+                               with_toggles=False)
+
+    def pinnable(self):
+        """Proven: test_pinnable_timelines.py"""
+        return self._s.gql_get("PinnableTimelines", {})
+
+    def profile_filter(self, user_id=None, bucket="posts"):
+        """BROKEN server-side (timeline.bucket 500s for every user, 2026-09-19).
+        Other buckets => 422. Proven: test_profile_filter.py"""
+        return self._s.gql_post("ProfileFilter", {
+            "userId": str(user_id or self._me()), "includePromotedContent": False,
+            "withVoice": True, "bucket": bucket})

xapiweb/resources/trends.py

@@ -0,0 +1,49 @@
+"""Trends, explore, search helpers, geo."""
+from ._base import BaseResource
+
+
+class Trends(BaseResource):
+    def available(self):
+        """Trend locations (woeids). Proven: test_trends_available.py"""
+        return self._s.rest_get("trends/available.json", {})
+
+    def place(self, woeid=1):
+        """Proven: test_trends_place.py"""
+        return self._s.rest_get("trends/place.json", {"id": woeid})
+
+    def history(self, trend_id):
+        """Proven: test_trend_history.py"""
+        return self._s.gql_get("TrendHistory", {"trendId": str(trend_id)})
+
+    def relevant_users(self, trend_id):
+        """Proven: test_trend_relevant_users.py"""
+        return self._s.gql_get("TrendRelevantUsers", {"trendId": str(trend_id)})
+
+    def sidebar(self):
+        """Explore sidebar. Proven: test_explore_sidebar.py"""
+        return self._s.gql_get("ExploreSidebar", {}, with_toggles=False)
+
+    def explore_page(self, candidate="news", tab="news"):
+        """Proven: test_explore_page.py"""
+        return self._s.gql_get("ExplorePage", {"candidateId": candidate, "tabId": tab})
+
+    def connect_tab(self, count=5):
+        """Proven: test_connect_tab.py"""
+        return self._s.gql_get("ConnectTabTimeline", {"count": count})
+
+    def creator_studio_tab(self):
+        """Proven: test_creator_studio_tab.py"""
+        return self._s.gql_get("CreatorStudioTabBarItemQuery", {},
+                               with_features=False, with_toggles=False)
+
+    def finance_tags(self, query):
+        """Proven: test_finance_tags.py"""
+        return self._s.gql_get("FinanceSearchTags", {"query": query})
+
+    def geo_search(self, query):
+        """E.g. 'Colombo'. Proven: test_geo_search.py"""
+        return self._s.rest_get("geo/search.json", {"query": query})
+
+    def typeahead(self, q):
+        """Search typeahead. Proven: test_search_typeahead.py"""
+        return self._s.rest_get("search/typeahead.json", {"q": q, "src": "search_box"})