1"""
2Twitter/X skill exports — script-mode wrapper around twitterapi.io.
3 
4Usage from a bash block:
5    python3 - <<'EOF'
6    import sys
7    sys.path.insert(0, "/data/workspace/skills/twitter")
8    from exports import twitter_user_info, twitter_search_tweets
9    print(twitter_user_info(username="elonmusk"))
10    EOF
11 
12All 13 functions are flat, sync wrappers around TwitterApiClient methods.
13HTTP traffic goes through sc-proxy via core.http_client — credentials
14injected server-side, no TWITTER_API_KEY needed locally.
15"""
16from __future__ import annotations
17 
18import os
19import sys
20from typing import List, Optional
21 
22# Make local client.py importable regardless of caller cwd.
23_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
24if _THIS_DIR not in sys.path:
25    sys.path.insert(0, _THIS_DIR)
26 
27from client import TwitterApiClient  # noqa: E402
28 
29_client_singleton: Optional[TwitterApiClient] = None
30 
31 
32def _client() -> TwitterApiClient:
33    global _client_singleton
34    if _client_singleton is None:
35        _client_singleton = TwitterApiClient()
36    return _client_singleton
37 
38 
39# ── Tweet endpoints ──────────────────────────────────────────────────────────
40 
41 
42def twitter_search_tweets(query: str, cursor: Optional[str] = None) -> dict:
43    """Search Twitter/X tweets using advanced query syntax.
44 
45    Operators: from:user, to:user, #hashtag, $cashtag, lang:en, has:media,
46    has:links, is:reply, min_faves:100, since:YYYY-MM-DD, until:YYYY-MM-DD.
47 
48    Returns dict with `tweets` array and `next_cursor` for pagination.
49    """
50    return _client().search_tweets(query, cursor=cursor)
51 
52 
53def twitter_get_tweets(tweet_ids: List[str]) -> dict:
54    """Get one or more tweets by their tweet IDs.
55 
56    `tweet_ids` is a list of stringified tweet IDs.
57    Returns dict with `tweets` array containing full tweet data.
58    """
59    if isinstance(tweet_ids, str):
60        # Be forgiving — accept comma string too.
61        tweet_ids = [t.strip() for t in tweet_ids.split(",") if t.strip()]
62    return _client().get_tweets(tweet_ids)
63 
64 
65def twitter_tweet_replies(tweet_id: str, cursor: Optional[str] = None) -> dict:
66    """Get replies to a specific tweet (by tweet ID)."""
67    return _client().get_tweet_replies(tweet_id, cursor=cursor)
68 
69 
70def twitter_tweet_retweeters(tweet_id: str, cursor: Optional[str] = None) -> dict:
71    """Get users who retweeted a specific tweet."""
72    return _client().get_tweet_retweeters(tweet_id, cursor=cursor)
73 
74 
75def twitter_tweet_thread_context(tweet_id: str) -> dict:
76    """Get full thread context for a tweet (parent chain + direct replies)."""
77    return _client().get_tweet_thread_context(tweet_id)
78 
79 
80def twitter_tweet_quote(tweet_id: str, cursor: Optional[str] = None) -> dict:
81    """Get quote tweets that quote a specific tweet."""
82    return _client().get_tweet_quote(tweet_id, cursor=cursor)
83 
84 
85def twitter_get_article(tweet_id: str) -> dict:
86    """Get long-form X article content by the article's tweet ID."""
87    return _client().get_article(tweet_id)
88 
89 
90def twitter_get_trends(
91    woeid: Optional[str] = None,
92    country: Optional[str] = None,
93    category: Optional[str] = None,
94    limit: Optional[int] = None,
95) -> dict:
96    """Get Twitter/X trending topics.
97 
98    All filters optional. `woeid` = Where On Earth ID (numeric region code).
99    """
100    return _client().get_trends(woeid=woeid, country=country, category=category, limit=limit)
101 
102 
103# ── User endpoints ───────────────────────────────────────────────────────────
104 
105 
106def twitter_user_info(username: str) -> dict:
107    """Get a user's profile: bio, follower/following count, tweet count, verified."""
108    return _client().get_user_info(username)
109 
110 
111def twitter_user_tweets(username: str, cursor: Optional[str] = None) -> dict:
112    """Get a user's recent tweets (paginated)."""
113    return _client().get_user_tweets(username, cursor=cursor)
114 
115 
116def twitter_user_followers(username: str, cursor: Optional[str] = None) -> dict:
117    """Get a user's followers (paginated)."""
118    return _client().get_user_followers(username, cursor=cursor)
119 
120 
121def twitter_user_followings(username: str, cursor: Optional[str] = None) -> dict:
122    """Get accounts a user follows (paginated)."""
123    return _client().get_user_followings(username, cursor=cursor)
124 
125 
126def twitter_search_users(query: str, cursor: Optional[str] = None) -> dict:
127    """Search for users by name or keyword."""
128    return _client().search_users(query, cursor=cursor)
129 
130 
131__all__ = [
132    "twitter_search_tweets",
133    "twitter_get_tweets",
134    "twitter_tweet_replies",
135    "twitter_tweet_retweeters",
136    "twitter_tweet_thread_context",
137    "twitter_tweet_quote",
138    "twitter_get_article",
139    "twitter_get_trends",
140    "twitter_user_info",
141    "twitter_user_tweets",
142    "twitter_user_followers",
143    "twitter_user_followings",
144    "twitter_search_users",
145]
146