feat: add integration smoke tests

CLI-level smoke tests using --yaml output against real Twitter API.
Default skipped via @pytest.mark.smoke marker + pyproject.toml addopts.
Run locally with: uv run pytest -m smoke -v

twitter_cli/auth.py

@@ -15,7 +15,7 @@ import logging
 import os
 import subprocess
 import sys
-from typing import Dict, Optional
+from typing import Any, Dict, Optional, Tuple
 
 from .constants import BEARER_TOKEN, get_user_agent
 
@@ -25,8 +25,7 @@ logger = logging.getLogger(__name__)
 _TWITTER_DOMAINS = {"x.com", "twitter.com", ".x.com", ".twitter.com"}
 
 
-def _is_twitter_domain(domain):
-    # type: (str) -> bool
+def _is_twitter_domain(domain: str) -> bool:
     return domain in _TWITTER_DOMAINS or domain.endswith(".x.com") or domain.endswith(".twitter.com")
 
 
@@ -45,8 +44,7 @@ def load_from_env() -> Optional[Dict[str, str]]:
     return None
 
 
-def verify_cookies(auth_token, ct0, cookie_string=None):
-    # type: (str, str, Optional[str]) -> Dict[str, Any]
+def verify_cookies(auth_token: str, ct0: str, cookie_string: Optional[str] = None) -> Dict[str, Any]:
     """Verify cookies by calling a Twitter API endpoint.
 
     Uses curl_cffi for proper TLS fingerprint.
@@ -112,11 +110,10 @@ def verify_cookies(auth_token, ct0, cookie_string=None):
     return {}
 
 
-def _extract_cookies_from_jar(jar, source="unknown"):
-    # type: (Any, str) -> Optional[Dict[str, str]]
+def _extract_cookies_from_jar(jar: Any, source: str = "unknown") -> Optional[Dict[str, str]]:
     """Extract Twitter cookies from a cookie jar."""
-    result = {}  # type: Dict[str, str]
-    all_cookies = {}  # type: Dict[str, str]
+    result: Dict[str, str] = {}
+    all_cookies: Dict[str, str] = {}
     twitter_cookie_count = 0
     for cookie in jar:
         domain = cookie.domain or ""
@@ -144,8 +141,7 @@ def _extract_cookies_from_jar(jar, source="unknown"):
     return None
 
 
-def _extract_in_process():
-    # type: () -> Optional[Dict[str, str]]
+def _extract_in_process() -> Optional[Dict[str, str]]:
     """Extract cookies in the main process (required on macOS for Keychain access).
 
     On macOS, Chrome encrypts cookies using a key stored in the system Keychain.
@@ -184,8 +180,7 @@ def _extract_in_process():
     return None
 
 
-def _extract_via_subprocess():
-    # type: () -> Optional[Dict[str, str]]
+def _extract_via_subprocess() -> Optional[Dict[str, str]]:
     """Extract cookies via subprocess (fallback if in-process fails, e.g. SQLite lock)."""
     extract_script = '''
 import json, sys
@@ -237,8 +232,11 @@ print(json.dumps({
 sys.exit(1)
 '''
 
-    def _run_extract_command(cmd, timeout, label):
-        # type: (list[str], int, str) -> tuple[Optional[dict], bool]
+    def _run_extract_command(
+        cmd: list[str],
+        timeout: int,
+        label: str,
+    ) -> Tuple[Optional[Dict[str, Any]], bool]:
         try:
             result = subprocess.run(
                 cmd,
@@ -294,7 +292,7 @@ sys.exit(1)
         logger.info("Found cookies in %s (subprocess)", data.get("browser", "unknown"))
 
         # Build full cookie string from all extracted cookies
-        cookies = {"auth_token": data["auth_token"], "ct0": data["ct0"]}
+        cookies: Dict[str, str] = {"auth_token": data["auth_token"], "ct0": data["ct0"]}
         all_cookies = data.get("all_cookies", {})
         if all_cookies:
             cookie_str = "; ".join("%s=%s" % (k, v) for k, v in all_cookies.items())
@@ -331,7 +329,7 @@ def get_cookies() -> Dict[str, str]:
 
     Raises RuntimeError if no cookies found.
     """
-    cookies = None  # type: Optional[Dict[str, str]]
+    cookies: Optional[Dict[str, str]] = None
 
     # 1. Try environment variables
     cookies = load_from_env()

twitter_cli/cli.py

@@ -33,6 +33,7 @@ import sys
 import time
 import urllib.parse
 from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
 
 import click
 from rich.console import Console
@@ -49,7 +50,7 @@ from .formatter import (
     print_user_profile,
     print_user_table,
 )
-from .models import UserProfile
+from .models import Tweet, UserProfile
 from .output import (
     default_structured_format,
     emit_error,
@@ -68,6 +69,13 @@ from .serialization import (
     users_to_data,
 )
 
+ConfigDict = Dict[str, Any]
+TweetList = List[Tweet]
+FetchTweets = Callable[[int], TweetList]
+OptionalPath = Optional[str]
+StructuredMode = Optional[str]
+WritePayload = Dict[str, Any]
+WriteOperation = Callable[[TwitterClient], WritePayload]
 
 console = Console(stderr=True)
 FEED_TYPES = ["for-you", "following"]
@@ -145,7 +153,7 @@ def _get_client_for_output(config=None, quiet=False):
 
 def _exit_with_error(exc):
     # type: (RuntimeError) -> None
-    if emit_error("api_error", str(exc)):
+    if emit_error(_error_code_for_message(str(exc)), str(exc)):
         sys.exit(1)
     console.print("[red]❌ %s[/red]" % exc)
     sys.exit(1)
@@ -159,6 +167,20 @@ def _run_guarded(action):
         _exit_with_error(exc)
 
 
+def _error_code_for_message(message):
+    # type: (str) -> str
+    lowered = message.lower()
+    if "cookie expired" in lowered or "no twitter cookies found" in lowered or "invalid cookie" in lowered:
+        return "not_authenticated"
+    if "rate limited" in lowered or "http 429" in lowered:
+        return "rate_limited"
+    if "invalid tweet" in lowered or "required" in lowered or "--max must" in lowered:
+        return "invalid_input"
+    if "not found" in lowered:
+        return "not_found"
+    return "api_error"
+
+
 def _resolve_fetch_count(max_count, configured):
     # type: (Optional[int], int) -> int
     """Resolve fetch count with bounds checks."""
@@ -212,6 +234,63 @@ def _apply_filter(tweets, do_filter, config, rich_output=True):
     return filtered
 
 
+def _structured_mode(as_json: bool, as_yaml: bool) -> StructuredMode:
+    return default_structured_format(as_json=as_json, as_yaml=as_yaml)
+
+
+def _emit_mode_payload(payload: object, mode: StructuredMode) -> bool:
+    if not mode:
+        return False
+    emit_structured(payload, as_json=(mode == "json"), as_yaml=(mode == "yaml"))
+    return True
+
+
+def _print_lines(lines: List[str], mode: StructuredMode) -> None:
+    if mode:
+        return
+    for line in lines:
+        console.print(line)
+
+
+def _handle_structured_runtime_error(
+    exc: RuntimeError,
+    *,
+    mode: StructuredMode,
+    details: Optional[Dict[str, Any]] = None,
+) -> None:
+    if _emit_mode_payload(
+        error_payload(_error_code_for_message(str(exc)), str(exc), details=details),
+        mode,
+    ):
+        raise SystemExit(1) from None
+    _exit_with_error(exc)
+
+
+def _run_write_command(
+    *,
+    as_json: bool,
+    as_yaml: bool,
+    operation: WriteOperation,
+    progress_lines: Optional[List[str]] = None,
+    success_lines: Optional[List[str]] = None,
+    error_details: Optional[Dict[str, Any]] = None,
+) -> Optional[WritePayload]:
+    mode = _structured_mode(as_json=as_json, as_yaml=as_yaml)
+    try:
+        client = _get_client(load_config())
+        _print_lines(progress_lines or [], mode)
+        payload = operation(client)
+    except RuntimeError as exc:
+        _handle_structured_runtime_error(exc, mode=mode, details=error_details)
+        return None
+
+    if _emit_mode_payload(payload, mode):
+        return payload
+
+    _print_lines(success_lines or ["[green]✅ Done.[/green]"], mode)
+    return payload
+
+
 @click.group()
 @click.option("--verbose", "-v", is_flag=True, help="Enable debug logging.")
 @click.option("--compact", "-c", is_flag=True, help="Compact output (minimal fields, LLM-friendly).")
@@ -606,103 +685,111 @@ def following(screen_name, max_count, as_json, as_yaml):
 
 # ── Write commands ──────────────────────────────────────────────────────
 
-def _write_action(emoji, action_desc, client_method, tweet_id):
-    # type: (str, str, str, str) -> None
+def _write_action(emoji, action_desc, client_method, tweet_id, as_json=False, as_yaml=False):
+    # type: (str, str, str, str, bool, bool) -> None
     """Generic write action helper to reduce CLI command boilerplate.
 
     Emits structured JSON/YAML when piped or when OUTPUT env is set.
     """
-    try:
-        config = load_config()
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            console.print("%s %s %s..." % (emoji, action_desc, tweet_id))
+    action_name = action_desc.lower().replace(" ", "_")
+
+    def operation(client: TwitterClient) -> WritePayload:
         getattr(client, client_method)(tweet_id)
-        result = {"success": True, "action": action_desc.lower().replace(" ", "_"), "id": tweet_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Done.[/green]")
-    except RuntimeError as exc:
-        result = {"success": False, "action": action_desc.lower().replace(" ", "_"), "id": tweet_id, "error": str(exc)}
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-            sys.exit(1)
-        _exit_with_error(exc)
+        return {"success": True, "action": action_name, "id": tweet_id}
+
+    _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["%s %s %s..." % (emoji, action_desc, tweet_id)],
+        success_lines=["[green]✅ Done.[/green]"],
+        error_details={"action": action_name, "id": tweet_id},
+    )
 
 
 @cli.command()
 @click.argument("text")
 @click.option("--reply-to", "-r", default=None, help="Reply to this tweet ID.")
-def post(text, reply_to):
-    # type: (str, Optional[str]) -> None
+@structured_output_options
+def post(text, reply_to, as_json, as_yaml):
+    # type: (str, Optional[str], bool, bool) -> None
     """Post a new tweet. TEXT is the tweet content."""
-    config = load_config()
-    try:
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            action = "Replying to %s" % reply_to if reply_to else "Posting tweet"
-            console.print("✏️  %s..." % action)
+    action = "Replying to %s" % reply_to if reply_to else "Posting tweet"
+
+    def operation(client: TwitterClient) -> WritePayload:
         tweet_id = client.create_tweet(text, reply_to_id=reply_to)
-        result = {"success": True, "action": "post", "id": tweet_id, "url": "https://x.com/i/status/%s" % tweet_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Tweet posted![/green]")
-            console.print("🔗 https://x.com/i/status/%s" % tweet_id)
-    except RuntimeError as exc:
-        _exit_with_error(exc)
+        return {"success": True, "action": "post", "id": tweet_id, "url": "https://x.com/i/status/%s" % tweet_id}
+
+    payload = _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["✏️  %s..." % action],
+        success_lines=["[green]✅ Tweet posted![/green]"],
+        error_details={"action": "post", "replyTo": reply_to},
+    )
+    if payload and not _structured_mode(as_json=as_json, as_yaml=as_yaml):
+        console.print("🔗 %s" % payload["url"])
 
 
 @cli.command(name="reply")
 @click.argument("tweet_id")
 @click.argument("text")
-def reply_tweet(tweet_id, text):
-    # type: (str, str) -> None
+@structured_output_options
+def reply_tweet(tweet_id, text, as_json, as_yaml):
+    # type: (str, str, bool, bool) -> None
     """Reply to a tweet. TWEET_ID is the tweet to reply to, TEXT is the reply content."""
     tweet_id = _normalize_tweet_id(tweet_id)
-    config = load_config()
-    try:
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            console.print("💬 Replying to %s..." % tweet_id)
+    def operation(client: TwitterClient) -> WritePayload:
         new_id = client.create_tweet(text, reply_to_id=tweet_id)
-        result = {"success": True, "action": "reply", "id": new_id, "replyTo": tweet_id, "url": "https://x.com/i/status/%s" % new_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Reply posted![/green]")
-            console.print("🔗 https://x.com/i/status/%s" % new_id)
-    except RuntimeError as exc:
-        _exit_with_error(exc)
+        return {
+            "success": True,
+            "action": "reply",
+            "id": new_id,
+            "replyTo": tweet_id,
+            "url": "https://x.com/i/status/%s" % new_id,
+        }
+
+    payload = _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["💬 Replying to %s..." % tweet_id],
+        success_lines=["[green]✅ Reply posted![/green]"],
+        error_details={"action": "reply", "replyTo": tweet_id},
+    )
+    if payload and not _structured_mode(as_json=as_json, as_yaml=as_yaml):
+        console.print("🔗 %s" % payload["url"])
 
 
 @cli.command(name="quote")
 @click.argument("tweet_id")
 @click.argument("text")
-def quote_tweet(tweet_id, text):
-    # type: (str, str) -> None
+@structured_output_options
+def quote_tweet(tweet_id, text, as_json, as_yaml):
+    # type: (str, str, bool, bool) -> None
     """Quote-tweet a tweet. TWEET_ID is the tweet to quote, TEXT is the commentary."""
     tweet_id = _normalize_tweet_id(tweet_id)
-    config = load_config()
-    try:
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            console.print("🔄 Quoting tweet %s..." % tweet_id)
+    def operation(client: TwitterClient) -> WritePayload:
         new_id = client.quote_tweet(tweet_id, text)
-        result = {"success": True, "action": "quote", "id": new_id, "quotedId": tweet_id, "url": "https://x.com/i/status/%s" % new_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Quote tweet posted![/green]")
-            console.print("🔗 https://x.com/i/status/%s" % new_id)
-    except RuntimeError as exc:
-        _exit_with_error(exc)
+        return {
+            "success": True,
+            "action": "quote",
+            "id": new_id,
+            "quotedId": tweet_id,
+            "url": "https://x.com/i/status/%s" % new_id,
+        }
+
+    payload = _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["🔄 Quoting tweet %s..." % tweet_id],
+        success_lines=["[green]✅ Quote tweet posted![/green]"],
+        error_details={"action": "quote", "quotedId": tweet_id},
+    )
+    if payload and not _structured_mode(as_json=as_json, as_yaml=as_yaml):
+        console.print("🔗 %s" % payload["url"])
 
 
 @cli.command(name="status")
@@ -754,125 +841,130 @@ def whoami(as_json, as_yaml):
 
 @cli.command(name="follow")
 @click.argument("screen_name")
-def follow_user(screen_name):
-    # type: (str,) -> None
+@structured_output_options
+def follow_user(screen_name, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Follow a user. SCREEN_NAME is the @handle (without @)."""
     screen_name = screen_name.lstrip("@")
-    config = load_config()
-    try:
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            console.print("👤 Looking up @%s..." % screen_name)
+
+    def operation(client: TwitterClient) -> WritePayload:
         user_id = client.resolve_user_id(screen_name)
-        if not structured:
-            console.print("➕ Following @%s..." % screen_name)
         client.follow_user(user_id)
-        result = {"success": True, "action": "follow", "screenName": screen_name, "userId": user_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Now following @%s[/green]" % screen_name)
-    except RuntimeError as exc:
-        _exit_with_error(exc)
+        return {"success": True, "action": "follow", "screenName": screen_name, "userId": user_id}
+
+    _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["👤 Looking up @%s..." % screen_name, "➕ Following @%s..." % screen_name],
+        success_lines=["[green]✅ Now following @%s[/green]" % screen_name],
+        error_details={"action": "follow", "screenName": screen_name},
+    )
 
 
 @cli.command(name="unfollow")
 @click.argument("screen_name")
-def unfollow_user(screen_name):
-    # type: (str,) -> None
+@structured_output_options
+def unfollow_user(screen_name, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Unfollow a user. SCREEN_NAME is the @handle (without @)."""
     screen_name = screen_name.lstrip("@")
-    config = load_config()
-    try:
-        client = _get_client(config)
-        structured = default_structured_format(as_json=False, as_yaml=False)
-        if not structured:
-            console.print("👤 Looking up @%s..." % screen_name)
+
+    def operation(client: TwitterClient) -> WritePayload:
         user_id = client.resolve_user_id(screen_name)
-        if not structured:
-            console.print("➖ Unfollowing @%s..." % screen_name)
         client.unfollow_user(user_id)
-        result = {"success": True, "action": "unfollow", "screenName": screen_name, "userId": user_id}
-        if structured:
-            emit_structured(result, as_json=(structured == "json"), as_yaml=(structured == "yaml"))
-        else:
-            console.print("[green]✅ Unfollowed @%s[/green]" % screen_name)
-    except RuntimeError as exc:
-        _exit_with_error(exc)
+        return {"success": True, "action": "unfollow", "screenName": screen_name, "userId": user_id}
+
+    _run_write_command(
+        as_json=as_json,
+        as_yaml=as_yaml,
+        operation=operation,
+        progress_lines=["👤 Looking up @%s..." % screen_name, "➖ Unfollowing @%s..." % screen_name],
+        success_lines=["[green]✅ Unfollowed @%s[/green]" % screen_name],
+        error_details={"action": "unfollow", "screenName": screen_name},
+    )
 
 
 @cli.command(name="delete")
 @click.argument("tweet_id")
 @click.confirmation_option(prompt="Are you sure you want to delete this tweet?")
-def delete_tweet(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def delete_tweet(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Delete a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("🗑️", "Deleting tweet", "delete_tweet", tweet_id)
+    _write_action("🗑️", "Deleting tweet", "delete_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def like(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def like(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Like a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("❤️", "Liking tweet", "like_tweet", tweet_id)
+    _write_action("❤️", "Liking tweet", "like_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def unlike(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def unlike(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Unlike a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("💔", "Unliking tweet", "unlike_tweet", tweet_id)
+    _write_action("💔", "Unliking tweet", "unlike_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def retweet(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def retweet(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Retweet a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("🔄", "Retweeting", "retweet", tweet_id)
+    _write_action("🔄", "Retweeting", "retweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def unretweet(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def unretweet(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Undo a retweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("🔄", "Undoing retweet", "unretweet", tweet_id)
+    _write_action("🔄", "Undoing retweet", "unretweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def favorite(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def favorite(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Bookmark (favorite) a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("🔖", "Bookmarking tweet", "bookmark_tweet", tweet_id)
+    _write_action("🔖", "Bookmarking tweet", "bookmark_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def bookmark(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def bookmark(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Bookmark a tweet. TWEET_ID is the numeric tweet ID."""
-    _write_action("🔖", "Bookmarking tweet", "bookmark_tweet", tweet_id)
+    _write_action("🔖", "Bookmarking tweet", "bookmark_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def unfavorite(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def unfavorite(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Remove a tweet from bookmarks (unfavorite). TWEET_ID is the numeric tweet ID."""
-    _write_action("🔖", "Removing bookmark", "unbookmark_tweet", tweet_id)
+    _write_action("🔖", "Removing bookmark", "unbookmark_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 @cli.command()
 @click.argument("tweet_id")
-def unbookmark(tweet_id):
-    # type: (str,) -> None
+@structured_output_options
+def unbookmark(tweet_id, as_json, as_yaml):
+    # type: (str, bool, bool) -> None
     """Remove a tweet from bookmarks. TWEET_ID is the numeric tweet ID."""
-    _write_action("🔖", "Removing bookmark", "unbookmark_tweet", tweet_id)
+    _write_action("🔖", "Removing bookmark", "unbookmark_tweet", tweet_id, as_json=as_json, as_yaml=as_yaml)
 
 
 if __name__ == "__main__":

twitter_cli/client.py

@@ -10,6 +10,7 @@ import random
 import re
 import time
 import urllib.parse
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple, cast
 
 import bs4
 from curl_cffi import requests as _cffi_requests
@@ -34,10 +35,14 @@ from .constants import (
 )
 from .models import Author, Metrics, Tweet, TweetMedia, UserProfile
 
+TimelineInstructionGetter = Callable[[Any], Any]
+TimelineParseResult = Tuple[List[Tweet], Optional[str]]
+SeenIdSet = Set[str]
+
 logger = logging.getLogger(__name__)
 
 # Shared curl_cffi session — impersonates Chrome 133 TLS/JA3/HTTP2 fingerprint
-_cffi_session = None  # type: Optional[Any]  # lazy init
+_cffi_session: Optional[Any] = None
 
 
 FALLBACK_QUERY_IDS = {
@@ -94,7 +99,7 @@ _DEFAULT_FEATURES = {
 FEATURES = dict(_DEFAULT_FEATURES)
 
 # Module-level caches (not thread-safe — CLI is single-threaded)
-_cached_query_ids = {}  # type: Dict[str, str]
+_cached_query_ids: Dict[str, str] = {}
 _bundles_scanned = False
 
 
@@ -142,7 +147,7 @@ def _get_cffi_session():
         target = _best_chrome_target()
         sync_chrome_version(target)  # align UA/sec-ch-ua with impersonate target
         _cffi_session = _cffi_requests.Session(
-            impersonate=target,
+            impersonate=cast(Any, target),
             proxies={"https": proxy, "http": proxy} if proxy else None,
         )
         logger.info("curl_cffi impersonating %s", target)
@@ -686,15 +691,16 @@ class TwitterClient:
 
         while len(tweets) < count and attempts < max_attempts:
             attempts += 1
+            variables: Dict[str, Any]
             if override_base_variables:
-                variables = {"count": min(count - len(tweets) + 5, 40)}  # type: Dict[str, Any]
+                variables = {"count": min(count - len(tweets) + 5, 40)}
             else:
                 variables = {
                     "count": min(count - len(tweets) + 5, 40),
                     "includePromotedContent": False,
                     "latestControlAvailable": True,
                     "requestContext": "launch",
-                }  # type: Dict[str, Any]
+                }
             if extra_variables:
                 variables.update(extra_variables)
             if cursor:

twitter_cli/config.py

@@ -5,13 +5,14 @@ from __future__ import annotations
 import copy
 import logging
 from pathlib import Path
+from typing import Any, Dict, Mapping, Optional
 
 import yaml
 
 logger = logging.getLogger(__name__)
 
 
-DEFAULT_CONFIG = {
+DEFAULT_CONFIG: Dict[str, Dict[str, Any]] = {
     "fetch": {
         "count": 50,
     },
@@ -35,11 +36,10 @@ DEFAULT_CONFIG = {
         "retryBaseDelay": 5.0,
         "maxCount": 200,
     },
-}  # type: Dict[str, Any]
+}
 
 
-def load_config(config_path=None):
-    # type: (Optional[str]) -> Dict[str, Any]
+def load_config(config_path: Optional[str] = None) -> Dict[str, Any]:
     """Load and normalize config from YAML, merged with defaults."""
     config = copy.deepcopy(DEFAULT_CONFIG)
     path = _resolve_config_path(config_path)
@@ -66,8 +66,7 @@ def load_config(config_path=None):
     return _normalize_config(merged)
 
 
-def _resolve_config_path(config_path):
-    # type: (Optional[str]) -> Optional[Path]
+def _resolve_config_path(config_path: Optional[str]) -> Optional[Path]:
     """Find config path from explicit argument or default locations."""
     if config_path:
         path = Path(config_path)
@@ -83,8 +82,7 @@ def _resolve_config_path(config_path):
     return None
 
 
-def _deep_merge(target, source):
-    # type: (Dict[str, Any], Mapping[str, Any]) -> Dict[str, Any]
+def _deep_merge(target: Dict[str, Any], source: Mapping[str, Any]) -> Dict[str, Any]:
     """Deep merge source into target (source values override target)."""
     result = copy.deepcopy(target)
     for key, value in source.items():
@@ -95,8 +93,7 @@ def _deep_merge(target, source):
     return result
 
 
-def _normalize_config(config):
-    # type: (Dict[str, Any]) -> Dict[str, Any]
+def _normalize_config(config: Dict[str, Any]) -> Dict[str, Any]:
     """Normalize shape and value types."""
     normalized = copy.deepcopy(DEFAULT_CONFIG)
     merged = _deep_merge(normalized, config)
@@ -148,8 +145,7 @@ def _normalize_config(config):
     return merged
 
 
-def _as_int(value, default):
-    # type: (Any, int) -> int
+def _as_int(value: Any, default: int) -> int:
     """Best-effort int conversion."""
     try:
         return int(value)
@@ -157,8 +153,7 @@ def _as_int(value, default):
         return default
 
 
-def _as_float(value, default):
-    # type: (Any, float) -> float
+def _as_float(value: Any, default: float) -> float:
     """Best-effort float conversion."""
     try:
         return float(value)

twitter_cli/filter.py

@@ -8,8 +8,10 @@ from __future__ import annotations
 
 from dataclasses import replace
 import math
+from typing import Any, Dict, List, Mapping, Optional, Sequence
 
 from .config import _as_float, _as_int
+from .models import Tweet
 
 DEFAULT_WEIGHTS = {
     "likes": 1.0,
@@ -20,8 +22,7 @@ DEFAULT_WEIGHTS = {
 }
 
 
-def score_tweet(tweet, weights=None):
-    # type: (Tweet, Optional[Dict[str, float]]) -> float
+def score_tweet(tweet: Tweet, weights: Optional[Dict[str, float]] = None) -> float:
     """Calculate engagement score for a single tweet.
 
     Formula:
@@ -45,8 +46,7 @@ def score_tweet(tweet, weights=None):
     )
 
 
-def filter_tweets(tweets, config):
-    # type: (Sequence[Tweet], Mapping[str, Any]) -> List[Tweet]
+def filter_tweets(tweets: Sequence[Tweet], config: Mapping[str, Any]) -> List[Tweet]:
     """Filter and rank tweets according to config.
 
     Config keys:
@@ -74,7 +74,7 @@ def filter_tweets(tweets, config):
     scored = [replace(tweet, score=round(score_tweet(tweet, weights), 1)) for tweet in filtered]
 
     # 4. Sort by score (descending)
-    scored.sort(key=lambda tweet: tweet.score, reverse=True)
+    scored.sort(key=lambda tweet: tweet.score or 0.0, reverse=True)
 
     # 5. Apply filter mode
     mode = str(config.get("mode", "topN"))
@@ -83,12 +83,11 @@ def filter_tweets(tweets, config):
         return scored[:top_n]
     if mode == "score":
         min_score = _as_float(config.get("minScore"), 50.0)
-        return [tweet for tweet in scored if tweet.score >= min_score]
+        return [tweet for tweet in scored if (tweet.score or 0.0) >= min_score]
     return scored
 
 
-def _build_weights(raw_weights):
-    # type: (Mapping[str, Any]) -> Dict[str, float]
+def _build_weights(raw_weights: Mapping[str, Any]) -> Dict[str, float]:
     """Merge custom weights with defaults and coerce to float."""
     merged = {}
     for key, default_value in DEFAULT_WEIGHTS.items():

twitter_cli/formatter.py

@@ -2,14 +2,16 @@
 
 from __future__ import annotations
 
+from typing import List, Optional
 
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
 
+from .models import Tweet, UserProfile
 
-def format_number(n):
-    # type: (int) -> str
+
+def format_number(n: int) -> str:
     """Format number with K/M suffixes."""
     if n >= 1_000_000:
         return "%.1fM" % (n / 1_000_000)
@@ -18,8 +20,11 @@ def format_number(n):
     return str(n)
 
 
-def print_tweet_table(tweets, console=None, title=None):
-    # type: (List[Tweet], Optional[Console], Optional[str]) -> None
+def print_tweet_table(
+    tweets: List[Tweet],
+    console: Optional[Console] = None,
+    title: Optional[str] = None,
+) -> None:
     """Print tweets as a rich table."""
     if console is None:
         console = Console()
@@ -86,8 +91,7 @@ def print_tweet_table(tweets, console=None, title=None):
     console.print(table)
 
 
-def print_tweet_detail(tweet, console=None):
-    # type: (Tweet, Optional[Console]) -> None
+def print_tweet_detail(tweet: Tweet, console: Optional[Console] = None) -> None:
     """Print a single tweet in detail using a rich panel."""
     if console is None:
         console = Console()
@@ -143,8 +147,11 @@ def print_tweet_detail(tweet, console=None):
     ))
 
 
-def print_filter_stats(original_count, filtered, console=None):
-    # type: (int, List[Tweet], Optional[Console]) -> None
+def print_filter_stats(
+    original_count: int,
+    filtered: List[Tweet],
+    console: Optional[Console] = None,
+) -> None:
     """Print filter statistics."""
     if console is None:
         console = Console()
@@ -153,14 +160,14 @@ def print_filter_stats(original_count, filtered, console=None):
         "📊 Filter: %d → %d tweets" % (original_count, len(filtered))
     )
     if filtered:
-        top_score = filtered[0].score
-        bottom_score = filtered[-1].score
+        top_score = filtered[0].score or 0.0
+        bottom_score = filtered[-1].score or 0.0
         console.print(
             "   Score range: %.1f ~ %.1f" % (bottom_score, top_score)
         )
 
-def print_user_profile(user, console=None):
-    # type: (UserProfile, Optional[Console]) -> None
+
+def print_user_profile(user: UserProfile, console: Optional[Console] = None) -> None:
     """Print user profile as a rich panel."""
     if console is None:
         console = Console()
@@ -202,8 +209,11 @@ def print_user_profile(user, console=None):
     ))
 
 
-def print_user_table(users, console=None, title=None):
-    # type: (List[UserProfile], Optional[Console], Optional[str]) -> None
+def print_user_table(
+    users: List[UserProfile],
+    console: Optional[Console] = None,
+    title: Optional[str] = None,
+) -> None:
     """Print a list of users as a rich table."""
     if console is None:
         console = Console()