xr-cli 0.1.0__py3-none-any.whl

xr/__init__.py

@@ -0,0 +1,2 @@
+"""XR — X (Twitter) Research CLI."""
+__version__ = "0.1.0"

xr/api.py

@@ -0,0 +1,55 @@
+"""HTTP client for X API v2 with rate limit handling."""
+from __future__ import annotations
+import sys
+import time
+from typing import Any
+
+import requests
+
+API_BASE = "https://api.x.com/2"
+MAX_RETRIES = 3
+
+class APIError(Exception):
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+class RateLimitError(APIError):
+    def __init__(self, reset_at: int):
+        self.reset_at = reset_at
+        super().__init__(429, f"Rate limited. Resets at {reset_at}")
+
+class XClient:
+    def __init__(self, bearer_token: str):
+        self.bearer_token = bearer_token
+
+    def _url(self, endpoint: str) -> str:
+        return f"{API_BASE}/{endpoint}"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.bearer_token}",
+            "User-Agent": "xr-cli/0.1.0",
+        }
+
+    def get(self, endpoint: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Make GET request with retry on rate limit."""
+        url = self._url(endpoint)
+        for attempt in range(MAX_RETRIES):
+            resp = requests.get(url, headers=self._headers(), params=params, timeout=15)
+
+            if resp.ok:
+                return resp.json()
+
+            if resp.status_code == 429:
+                reset_at = int(resp.headers.get("x-rate-limit-reset", 0))
+                if attempt < MAX_RETRIES - 1:
+                    wait = max(reset_at - int(time.time()), 1) + 1
+                    print(f"Rate limited. Waiting {wait}s...", file=sys.stderr)
+                    time.sleep(wait)
+                    continue
+                raise RateLimitError(reset_at)
+
+            raise APIError(resp.status_code, resp.text)
+
+        raise APIError(0, "Max retries exceeded")

xr/auth.py

@@ -0,0 +1,77 @@
+"""Credential loading and bearer token generation."""
+from __future__ import annotations
+import base64
+import os
+import tomllib
+from pathlib import Path
+
+import requests
+
+class CredentialError(Exception):
+    pass
+
+def _credentials_path() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+    return Path(xdg) / "xr" / "credentials.toml"
+
+def _legacy_path() -> Path:
+    return Path.home() / "charlie" / ".env.x-api"
+
+def load_credentials(
+    path: Path | None = None,
+    legacy_path: Path | None = None,
+) -> tuple[str, str]:
+    """Load consumer key and secret. Priority: env vars > toml > legacy .env file."""
+    # 1. Environment variables
+    env_key = os.environ.get("XR_CONSUMER_KEY")
+    env_secret = os.environ.get("XR_CONSUMER_SECRET")
+    if env_key and env_secret:
+        return env_key, env_secret
+
+    # 2. TOML credentials file
+    cred_path = path or _credentials_path()
+    if cred_path.exists():
+        with open(cred_path, "rb") as f:
+            data = tomllib.load(f)
+        creds = data.get("credentials", {})
+        key = creds.get("consumer_key")
+        secret = creds.get("consumer_secret")
+        if key and secret:
+            return key, secret
+
+    # 3. Legacy .env.x-api
+    lp = legacy_path or _legacy_path()
+    if lp.exists():
+        kvs = {}
+        with open(lp) as f:
+            for line in f:
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    k, v = line.split("=", 1)
+                    kvs[k.strip()] = v.strip()
+        key = kvs.get("X_API_CONSUMER_KEY")
+        secret = kvs.get("X_API_CONSUMER_SECRET")
+        if key and secret:
+            return key, secret
+
+    raise CredentialError(
+        "No X API credentials found. Run 'xr auth setup' or set "
+        "XR_CONSUMER_KEY and XR_CONSUMER_SECRET environment variables."
+    )
+
+def get_bearer_token(consumer_key: str, consumer_secret: str) -> str:
+    """Generate OAuth 2.0 Bearer Token from consumer credentials."""
+    credentials = f"{consumer_key}:{consumer_secret}"
+    b64 = base64.b64encode(credentials.encode()).decode()
+    resp = requests.post(
+        "https://api.x.com/oauth2/token",
+        headers={
+            "Authorization": f"Basic {b64}",
+            "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        },
+        data="grant_type=client_credentials",
+        timeout=10,
+    )
+    if not resp.ok:
+        raise CredentialError(f"Failed to get bearer token: {resp.status_code} {resp.text}")
+    return resp.json()["access_token"]

xr/cache.py

@@ -0,0 +1,158 @@
+"""SQLite cache for API responses."""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+def _cache_path() -> Path:
+    xdg = os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))
+    return Path(xdg) / "xr" / "cache.db"
+
+class Cache:
+    def __init__(self, path: Path | None = None, enabled: bool = True):
+        self.enabled = enabled
+        self.path = path or _cache_path()
+        if self.enabled:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.conn = sqlite3.connect(str(self.path))
+            self._init_tables()
+        else:
+            self.conn = None
+
+    def _init_tables(self):
+        self.conn.executescript("""
+            CREATE TABLE IF NOT EXISTS tweets (
+                tweet_id TEXT PRIMARY KEY,
+                data TEXT NOT NULL,
+                fetched_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS users (
+                user_id TEXT PRIMARY KEY,
+                username TEXT UNIQUE,
+                data TEXT NOT NULL,
+                fetched_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS searches (
+                query_hash TEXT PRIMARY KEY,
+                query TEXT NOT NULL,
+                result_ids TEXT NOT NULL,
+                fetched_at REAL NOT NULL
+            );
+            CREATE TABLE IF NOT EXISTS counts (
+                query_hash TEXT PRIMARY KEY,
+                query TEXT NOT NULL,
+                granularity TEXT NOT NULL,
+                data TEXT NOT NULL,
+                fetched_at REAL NOT NULL
+            );
+        """)
+
+    def _is_fresh(self, fetched_at: float, ttl: int) -> bool:
+        return (time.time() - fetched_at) < ttl
+
+    def _query_hash(self, query: str) -> str:
+        return hashlib.sha256(query.strip().lower().encode()).hexdigest()
+
+    # --- Tweets ---
+    def get_tweet(self, tweet_id: str, ttl: int) -> dict | None:
+        if not self.enabled or not self.conn:
+            return None
+        row = self.conn.execute(
+            "SELECT data, fetched_at FROM tweets WHERE tweet_id = ?", (tweet_id,)
+        ).fetchone()
+        if row and self._is_fresh(row[1], ttl):
+            return json.loads(row[0])
+        return None
+
+    def put_tweet(self, tweet_id: str, data: dict):
+        if not self.enabled or not self.conn:
+            return
+        self.conn.execute(
+            "INSERT OR REPLACE INTO tweets (tweet_id, data, fetched_at) VALUES (?, ?, ?)",
+            (tweet_id, json.dumps(data), time.time()),
+        )
+        self.conn.commit()
+
+    # --- Users ---
+    def get_user(self, username: str, ttl: int) -> dict | None:
+        if not self.enabled or not self.conn:
+            return None
+        row = self.conn.execute(
+            "SELECT data, fetched_at FROM users WHERE username = ?", (username,)
+        ).fetchone()
+        if row and self._is_fresh(row[1], ttl):
+            return json.loads(row[0])
+        return None
+
+    def put_user(self, user_id: str, username: str, data: dict):
+        if not self.enabled or not self.conn:
+            return
+        self.conn.execute(
+            "INSERT OR REPLACE INTO users (user_id, username, data, fetched_at) VALUES (?, ?, ?, ?)",
+            (user_id, username, json.dumps(data), time.time()),
+        )
+        self.conn.commit()
+
+    # --- Searches ---
+    def get_search(self, query: str, ttl: int) -> list[str] | None:
+        if not self.enabled or not self.conn:
+            return None
+        qh = self._query_hash(query)
+        row = self.conn.execute(
+            "SELECT result_ids, fetched_at FROM searches WHERE query_hash = ?", (qh,)
+        ).fetchone()
+        if row and self._is_fresh(row[1], ttl):
+            return json.loads(row[0])
+        return None
+
+    def put_search(self, query: str, result_ids: list[str]):
+        if not self.enabled or not self.conn:
+            return
+        qh = self._query_hash(query)
+        self.conn.execute(
+            "INSERT OR REPLACE INTO searches (query_hash, query, result_ids, fetched_at) VALUES (?, ?, ?, ?)",
+            (qh, query, json.dumps(result_ids), time.time()),
+        )
+        self.conn.commit()
+
+    # --- Counts ---
+    def get_counts(self, query: str, granularity: str, ttl: int) -> dict | None:
+        if not self.enabled or not self.conn:
+            return None
+        qh = self._query_hash(f"{query}:{granularity}")
+        row = self.conn.execute(
+            "SELECT data, fetched_at FROM counts WHERE query_hash = ?", (qh,)
+        ).fetchone()
+        if row and self._is_fresh(row[1], ttl):
+            return json.loads(row[0])
+        return None
+
+    def put_counts(self, query: str, granularity: str, data: dict):
+        if not self.enabled or not self.conn:
+            return
+        qh = self._query_hash(f"{query}:{granularity}")
+        self.conn.execute(
+            "INSERT OR REPLACE INTO counts (query_hash, query, granularity, data, fetched_at) VALUES (?, ?, ?, ?, ?)",
+            (qh, query, granularity, json.dumps(data), time.time()),
+        )
+        self.conn.commit()
+
+    def cleanup(self, max_size_mb: int = 50):
+        """Remove old entries if cache exceeds max size."""
+        if not self.enabled or not self.conn:
+            return
+        size = self.path.stat().st_size / (1024 * 1024) if self.path.exists() else 0
+        if size > max_size_mb:
+            for table in ("tweets", "searches", "users", "counts"):
+                self.conn.execute(f"""
+                    DELETE FROM {table} WHERE rowid IN (
+                        SELECT rowid FROM {table} ORDER BY fetched_at ASC
+                        LIMIT (SELECT COUNT(*) / 2 FROM {table})
+                    )
+                """)
+            self.conn.commit()
+            self.conn.execute("VACUUM")

xr/cli.py

@@ -0,0 +1,258 @@
+"""CLI entry point for XR."""
+from __future__ import annotations
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from xr import __version__
+from xr.auth import load_credentials, get_bearer_token, CredentialError
+from xr.api import XClient, APIError, RateLimitError
+from xr.cache import Cache
+from xr.config import Config
+from xr.formatters.markdown import (
+    format_tweet, format_user, format_search, format_thread,
+    format_timeline, format_followers, format_counts,
+)
+from xr.formatters.json_fmt import format_json
+
+def _get_client_and_cache(ctx) -> tuple[XClient, Cache]:
+    config = ctx.obj.get("config") or Config.load()
+    ctx.obj["config"] = config
+    try:
+        key, secret = load_credentials()
+    except CredentialError as e:
+        click.echo(str(e), err=True)
+        raise SystemExit(1)
+    token = get_bearer_token(key, secret)
+    client = XClient(token)
+    no_cache = ctx.obj.get("no_cache", False)
+    cache = Cache(enabled=config.cache_enabled and not no_cache)
+    return client, cache
+
+def _output(ctx, content: str, filename: str | None = None):
+    """Print to stdout and optionally save."""
+    click.echo(content)
+    if ctx.obj.get("save") and filename:
+        config = ctx.obj["config"]
+        save_dir = Path(config.save_dir).expanduser()
+        save_dir.mkdir(parents=True, exist_ok=True)
+        path = save_dir / filename
+        path.write_text(content)
+        click.echo(f"Saved: {path}", err=True)
+
+@click.group()
+@click.version_option(__version__, prog_name="xr")
+@click.option("--pretty", is_flag=True, help="Output raw JSON")
+@click.option("--save", is_flag=True, help="Save to configured directory")
+@click.option("--no-cache", is_flag=True, help="Bypass cache")
+@click.pass_context
+def main(ctx, pretty, save, no_cache):
+    """XR — X (Twitter) Research CLI."""
+    ctx.ensure_object(dict)
+    ctx.obj["pretty"] = pretty
+    ctx.obj["save"] = save
+    ctx.obj["no_cache"] = no_cache
+
+@main.command()
+@click.argument("input_str")
+@click.pass_context
+def tweet(ctx, input_str):
+    """Fetch a single tweet by ID or URL."""
+    from xr.commands.tweet import fetch_tweet, extract_tweet_id
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    tweet_id = extract_tweet_id(input_str)
+    if ctx.obj["pretty"]:
+        data = client.get(f"tweets/{tweet_id}", {
+            "tweet.fields": "created_at,author_id,text,public_metrics,entities,referenced_tweets,note_tweet,conversation_id",
+            "expansions": "author_id,referenced_tweets.id",
+            "user.fields": "username,name,verified",
+        })
+        _output(ctx, format_json(data), f"tweet-{tweet_id}.json")
+    else:
+        t = fetch_tweet(client, cache, tweet_id, config.cache_ttl_tweets)
+        md = format_tweet(t)
+        _output(ctx, md, f"tweet-{t.username}-{t.id}.md")
+
+@main.command()
+@click.argument("input_str")
+@click.option("--author-only", is_flag=True, help="Only thread author's tweets")
+@click.pass_context
+def thread(ctx, input_str, author_only):
+    """Fetch a conversation thread."""
+    from xr.commands.tweet import extract_tweet_id
+    from xr.commands.thread import fetch_thread
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    tweet_id = extract_tweet_id(input_str)
+    tweets, conv_id = fetch_thread(client, cache, tweet_id, author_only, config.cache_ttl_tweets, config.cache_ttl_searches)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json([{"id": t.id, "text": t.text, "username": t.username} for t in tweets]))
+    else:
+        md = format_thread(tweets, conv_id)
+        suffix = "-author-only" if author_only else ""
+        _output(ctx, md, f"thread-{tweets[0].username if tweets else 'unknown'}-{conv_id}{suffix}.md")
+
+@main.command()
+@click.argument("query")
+@click.option("--lang", default="", help="Filter by language (e.g., es, en)")
+@click.option("--no-rt", is_flag=True, help="Exclude retweets")
+@click.option("--top", is_flag=True, help="Sort by relevancy instead of recency")
+@click.option("--max", "max_results", default=20, help="Max results (default: 20)")
+@click.pass_context
+def search(ctx, query, lang, no_rt, top, max_results):
+    """Search recent tweets (7-day window)."""
+    from xr.commands.search import fetch_search
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+
+    # Build query with operators
+    q = query
+    if lang:
+        q += f" lang:{lang}"
+    if no_rt:
+        q += " -is:retweet"
+
+    sort = "relevancy" if top else "recency"
+    result = fetch_search(client, cache, q, max_results, sort, config.cache_ttl_searches, config.cache_ttl_tweets)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json({"query": q, "total": result.total, "tweets": [{"id": t.id, "text": t.text, "username": t.username, "likes": t.likes} for t in result.tweets]}))
+    else:
+        md = format_search(result, sort)
+        _output(ctx, md, f"search-{query[:50].replace(' ', '-')}.md")
+
+@main.command()
+@click.argument("username")
+@click.pass_context
+def user(ctx, username):
+    """Fetch user profile."""
+    from xr.commands.user import fetch_user
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    username = username.lstrip("@")
+    u = fetch_user(client, cache, username, config.cache_ttl_users)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json({"id": u.id, "username": u.username, "name": u.name, "followers": u.followers, "following": u.following, "tweets": u.tweet_count}))
+    else:
+        md = format_user(u)
+        _output(ctx, md, f"user-{u.username}.md")
+
+@main.command()
+@click.argument("username")
+@click.option("--top", is_flag=True, help="Sort by likes")
+@click.option("--no-rt", is_flag=True, help="Exclude retweets")
+@click.option("--no-replies", is_flag=True, help="Exclude replies")
+@click.option("--max", "max_results", default=20, help="Max results")
+@click.pass_context
+def timeline(ctx, username, top, no_rt, no_replies, max_results):
+    """Fetch user's recent tweets."""
+    from xr.commands.timeline import fetch_timeline
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    username = username.lstrip("@")
+    tweets, u = fetch_timeline(client, cache, username, max_results, no_rt, no_replies, top, config.cache_ttl_users, config.cache_ttl_tweets)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json([{"id": t.id, "text": t.text, "likes": t.likes} for t in tweets]))
+    else:
+        md = format_timeline(tweets, u.username)
+        _output(ctx, md, f"timeline-{u.username}.md")
+
+@main.command()
+@click.argument("username")
+@click.option("--max", "max_results", default=20, help="Max results")
+@click.pass_context
+def mentions(ctx, username, max_results):
+    """Fetch user's recent mentions."""
+    from xr.commands.mentions import fetch_mentions
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    username = username.lstrip("@")
+    tweets, u = fetch_mentions(client, cache, username, max_results, config.cache_ttl_users, config.cache_ttl_tweets)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json([{"id": t.id, "text": t.text, "username": t.username} for t in tweets]))
+    else:
+        md = format_timeline(tweets, f"{u.username} (mentions)")
+        _output(ctx, md, f"mentions-{u.username}.md")
+
+@main.command()
+@click.argument("username")
+@click.option("--max", "max_results", default=100, help="Max results")
+@click.pass_context
+def followers(ctx, username, max_results):
+    """Fetch user's followers."""
+    from xr.commands.followers import fetch_followers
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    username = username.lstrip("@")
+    users, target = fetch_followers(client, cache, username, max_results, config.cache_ttl_users)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json([{"username": u.username, "followers": u.followers} for u in users]))
+    else:
+        md = format_followers(users, target.username, "followers")
+        _output(ctx, md, f"followers-{target.username}.md")
+
+@main.command()
+@click.argument("username")
+@click.option("--max", "max_results", default=100, help="Max results")
+@click.pass_context
+def following(ctx, username, max_results):
+    """Fetch who a user follows."""
+    from xr.commands.followers import fetch_following
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    username = username.lstrip("@")
+    users, target = fetch_following(client, cache, username, max_results, config.cache_ttl_users)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json([{"username": u.username, "followers": u.followers} for u in users]))
+    else:
+        md = format_followers(users, target.username, "following")
+        _output(ctx, md, f"following-{target.username}.md")
+
+@main.command()
+@click.argument("query")
+@click.option("--granularity", type=click.Choice(["day", "hour"]), default="day", help="Bucket size")
+@click.pass_context
+def counts(ctx, query, granularity):
+    """Show tweet volume over time."""
+    from xr.commands.counts import fetch_counts
+    client, cache = _get_client_and_cache(ctx)
+    config = ctx.obj["config"]
+    result = fetch_counts(client, cache, query, granularity, config.cache_ttl_counts)
+    if ctx.obj["pretty"]:
+        _output(ctx, format_json({"query": query, "total": result.total, "buckets": [{"date": b.start, "count": b.count} for b in result.buckets]}))
+    else:
+        md = format_counts(result)
+        _output(ctx, md, f"counts-{query[:50].replace(' ', '-')}.md")
+
+@main.group()
+def auth():
+    """Manage API credentials."""
+    pass
+
+@auth.command("setup")
+def auth_setup():
+    """Interactive credential setup."""
+    click.echo("XR — X API Credential Setup")
+    click.echo("Get your credentials at: https://developer.x.com/en/portal/dashboard\n")
+    key = click.prompt("Consumer Key (API Key)")
+    secret = click.prompt("Consumer Secret (API Secret)", hide_input=True)
+
+    import os
+    from pathlib import Path
+    xdg = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+    config_dir = Path(xdg) / "xr"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    cred_path = config_dir / "credentials.toml"
+    cred_path.write_text(f'[credentials]\nconsumer_key = "{key}"\nconsumer_secret = "{secret}"\n')
+    cred_path.chmod(0o600)
+    click.echo(f"\nCredentials saved to {cred_path} (mode 600)")
+
+    # Test connection
+    try:
+        from xr.auth import get_bearer_token
+        get_bearer_token(key, secret)
+        click.echo("Connection test: OK")
+    except Exception as e:
+        click.echo(f"Connection test failed: {e}", err=True)

xr/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules."""

xr/commands/counts.py

@@ -0,0 +1,33 @@
+"""Fetch tweet volume counts."""
+from __future__ import annotations
+
+from xr.api import XClient
+from xr.cache import Cache
+from xr.models import CountBucket, CountResult
+
+def fetch_counts(
+    client: XClient, cache: Cache, query: str,
+    granularity: str = "day", ttl: int = 3600,
+) -> CountResult:
+    cached = cache.get_counts(query, granularity, ttl)
+    if cached:
+        buckets = [CountBucket(**b) for b in cached.get("buckets", [])]
+        return CountResult(query=query, granularity=granularity, buckets=buckets, total=cached.get("total", 0))
+
+    data = client.get("tweets/counts/recent", {
+        "query": query,
+        "granularity": granularity,
+    })
+
+    buckets = [
+        CountBucket(start=b["start"], end=b["end"], count=b["tweet_count"])
+        for b in data.get("data", [])
+    ]
+    total = data.get("meta", {}).get("total_tweet_count", sum(b.count for b in buckets))
+
+    cache.put_counts(query, granularity, {
+        "buckets": [{"start": b.start, "end": b.end, "count": b.count} for b in buckets],
+        "total": total,
+    })
+
+    return CountResult(query=query, granularity=granularity, buckets=buckets, total=total)

xr/commands/followers.py

@@ -0,0 +1,38 @@
+"""Fetch followers and following lists."""
+from __future__ import annotations
+
+from xr.api import XClient
+from xr.cache import Cache
+from xr.models import User
+from xr.commands.user import fetch_user, USER_FIELDS
+
+def fetch_followers(
+    client: XClient, cache: Cache, username: str,
+    max_results: int = 100, ttl_user: int = 86400,
+) -> tuple[list[User], User]:
+    target = fetch_user(client, cache, username, ttl_user)
+
+    data = client.get(f"users/{target.id}/followers", {
+        "user.fields": USER_FIELDS,
+        "max_results": min(max_results, 1000),
+    })
+
+    users = [User.from_api(u) for u in data.get("data", [])]
+    for u in users:
+        cache.put_user(u.id, u.username, {"data": data})
+
+    return users, target
+
+def fetch_following(
+    client: XClient, cache: Cache, username: str,
+    max_results: int = 100, ttl_user: int = 86400,
+) -> tuple[list[User], User]:
+    target = fetch_user(client, cache, username, ttl_user)
+
+    data = client.get(f"users/{target.id}/following", {
+        "user.fields": USER_FIELDS,
+        "max_results": min(max_results, 1000),
+    })
+
+    users = [User.from_api(u) for u in data.get("data", [])]
+    return users, target

xr/commands/mentions.py

@@ -0,0 +1,30 @@
+"""Fetch user's mentions."""
+from __future__ import annotations
+
+from xr.api import XClient
+from xr.cache import Cache
+from xr.models import Tweet, User
+from xr.commands.user import fetch_user
+from xr.commands.tweet import TWEET_FIELDS, USER_FIELDS as TWEET_USER_FIELDS
+
+def fetch_mentions(
+    client: XClient, cache: Cache, username: str,
+    max_results: int = 20, ttl_user: int = 86400, ttl_tweet: int = 604800,
+) -> tuple[list[Tweet], User]:
+    user = fetch_user(client, cache, username, ttl_user)
+
+    data = client.get(f"users/{user.id}/mentions", {
+        "tweet.fields": TWEET_FIELDS,
+        "expansions": "author_id",
+        "user.fields": TWEET_USER_FIELDS,
+        "max_results": min(max_results, 100),
+    })
+    includes = data.get("includes", {})
+
+    tweets = []
+    for t in data.get("data", []):
+        tweet = Tweet.from_api(t, includes)
+        tweets.append(tweet)
+        cache.put_tweet(tweet.id, {"data": t, "includes": includes})
+
+    return tweets, user