1"""
2Twitter API client — wraps twitterapi.io endpoints.
3 
4Read-only: search tweets, user profiles, followers, replies, thread context,
5quote tweets, article, and trends.
6Auth: X-API-Key header from TWITTER_API_KEY env var.
7"""
8 
9import logging
10import os
11from typing import Any, List
12 
13from core.http_client import proxied_get
14 
15CALLER_ID = "chat:twitter-skill"
16 
17logger = logging.getLogger(__name__)
18 
19TWITTERAPI_BASE_URL = "https://api.twitterapi.io"
20 
21 
22class TwitterApiClient:
23    """
24    Sync twitterapi.io client using proxied_get.
25 
26    All endpoints are public GET requests authenticated via X-API-Key header.
27    """
28 
29    def __init__(self):
30        self.base_url = TWITTERAPI_BASE_URL
31        self.api_key = os.environ.get("TWITTER_API_KEY", "")
32 
33    def _get(self, path: str, params: dict = None) -> Any:
34        """GET a twitterapi.io endpoint."""
35        url = f"{self.base_url}{path}"
36 
37        headers = {"SC-CALLER-ID": CALLER_ID}
38        if self.api_key:
39            headers["X-API-Key"] = self.api_key
40 
41        response = proxied_get(url, headers=headers, params=params, timeout=15)
42        if response.status_code >= 400:
43            raise Exception(f"twitterapi.io {response.status_code}: {response.text}")
44        return response.json()
45 
46    # ── Tweet Endpoints ──────────────────────────────────────────────────
47 
48    def search_tweets(self, query: str, cursor: str = None) -> dict:
49        """Advanced tweet search."""
50        params = {"query": query}
51        if cursor:
52            params["cursor"] = cursor
53        return self._get("/twitter/tweet/advanced_search", params)
54 
55    def get_tweets(self, tweet_ids: List[str]) -> dict:
56        """Get tweets by IDs."""
57        params = {"tweet_ids": ",".join(tweet_ids)}
58        return self._get("/twitter/tweets", params)
59 
60    def get_tweet_replies(self, tweet_id: str, cursor: str = None) -> dict:
61        """Get replies to a tweet."""
62        params = {"tweetId": tweet_id}
63        if cursor:
64            params["cursor"] = cursor
65        return self._get("/twitter/tweet/replies", params)
66 
67    def get_tweet_retweeters(self, tweet_id: str, cursor: str = None) -> dict:
68        """Get users who retweeted a tweet."""
69        params = {"tweetId": tweet_id}
70        if cursor:
71            params["cursor"] = cursor
72        return self._get("/twitter/tweet/retweeters", params)
73 
74    def get_tweet_thread_context(self, tweet_id: str) -> dict:
75        """Get complete thread context for a tweet (parents + direct replies)."""
76        return self._get("/twitter/tweet/thread_context", {"tweetId": tweet_id})
77 
78    def get_tweet_quote(self, tweet_id: str, cursor: str = None) -> dict:
79        """Get quote tweets for a tweet."""
80        params = {"tweetId": tweet_id}
81        if cursor:
82            params["cursor"] = cursor
83        return self._get("/twitter/tweet/quotes", params)
84 
85    def get_article(self, tweet_id: str) -> dict:
86        """Get article content by tweet ID (long-form X article)."""
87        return self._get("/twitter/article", {"tweet_id": tweet_id})
88 
89    def get_trends(self, woeid: str = None, country: str = None, category: str = None, limit: int = None) -> dict:
90        """Get trending topics."""
91        params = {}
92        if woeid:
93            params["woeid"] = woeid
94        if country:
95            params["country"] = country
96        if category:
97            params["category"] = category
98        if limit is not None:
99            params["limit"] = limit
100        return self._get("/twitter/trends", params)
101 
102    # ── User Endpoints ───────────────────────────────────────────────────
103 
104    def get_user_info(self, username: str) -> dict:
105        """Get user profile info."""
106        return self._get("/twitter/user/info", {"userName": username})
107 
108    def get_user_tweets(self, username: str, cursor: str = None) -> dict:
109        """Get user's recent tweets."""
110        params = {"userName": username}
111        if cursor:
112            params["cursor"] = cursor
113        return self._get("/twitter/user/last_tweets", params)
114 
115    def get_user_followers(self, username: str, cursor: str = None) -> dict:
116        """Get user's followers."""
117        params = {"userName": username}
118        if cursor:
119            params["cursor"] = cursor
120        return self._get("/twitter/user/followers", params)
121 
122    def get_user_followings(self, username: str, cursor: str = None) -> dict:
123        """Get accounts the user follows."""
124        params = {"userName": username}
125        if cursor:
126            params["cursor"] = cursor
127        return self._get("/twitter/user/followings", params)
128 
129    def search_users(self, query: str, cursor: str = None) -> dict:
130        """Search for users."""
131        params = {"query": query}
132        if cursor:
133            params["cursor"] = cursor
134        return self._get("/twitter/user/search", params)
135