birdapi 0.0.1__tar.gz → 0.0.2__tar.gz

{birdapi-0.0.1 → birdapi-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: birdapi
-Version: 0.0.1
+Version: 0.0.2
 Summary: CLI and library for X/Twitter GraphQL API (cookie auth, no API key required)
 Project-URL: Homepage, https://github.com/dvermaas/birdapi
 Project-URL: Repository, https://github.com/dvermaas/birdapi

{birdapi-0.0.1 → birdapi-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "birdapi"
-version = "0.0.1"
+version = "0.0.2"
 description = "CLI and library for X/Twitter GraphQL API (cookie auth, no API key required)"
 readme = "README.md"
 license = { text = "MIT" }

{birdapi-0.0.1 → birdapi-0.0.2}/src/bird/_utils.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+from datetime import datetime
 from typing import Any, Optional
 
 from ._models import (
@@ -20,6 +21,19 @@ from ._models import (
 
 _HANDLE_RE = re.compile(r"^[A-Za-z0-9_]{1,15}$")
 
+# X timestamp format, e.g. "Sun Jun 07 23:11:05 +0000 2026"
+_TWEET_TIME_FMT = "%a %b %d %H:%M:%S %z %Y"
+
+
+def parse_tweet_datetime(created_at: Optional[str]) -> Optional[datetime]:
+    """Parse a tweet ``created_at`` string into an aware datetime, or None."""
+    if not created_at:
+        return None
+    try:
+        return datetime.strptime(created_at, _TWEET_TIME_FMT)
+    except (ValueError, TypeError):
+        return None
+
 
 def normalize_handle(raw: Optional[str]) -> Optional[str]:
     if not raw:
@@ -351,6 +365,10 @@ def map_tweet_result(
     quote_depth: int = 1,
     include_raw: bool = False,
 ) -> Optional[Tweet]:
+    if not result:
+        return None
+    # Unwrap TweetWithVisibilityResults for callers that pass the raw result directly.
+    result = _unwrap_tweet_result(result)
     if not result:
         return None
     user_result = (result.get("core") or {}).get("user_results", {}).get("result") or {}
@@ -401,6 +419,9 @@ def _collect_tweet_results_from_entry(entry: dict) -> list[dict]:
     content = entry.get("content") or {}
 
     def push(r: Optional[dict]) -> None:
+        # Visibility-gated tweets arrive wrapped as TweetWithVisibilityResults,
+        # with rest_id nested under .tweet — unwrap before the rest_id check.
+        r = _unwrap_tweet_result(r)
         if r and r.get("rest_id"):
             results.append(r)
 
@@ -451,6 +472,7 @@ def find_tweet_in_instructions(
             result = (entry.get("content") or {}).get("itemContent", {}).get(
                 "tweet_results", {}
             ).get("result")
+            result = _unwrap_tweet_result(result)
             if result and result.get("rest_id") == tweet_id:
                 return result
     return None

{birdapi-0.0.1 → birdapi-0.0.2}/src/bird/cli.py

@@ -6,6 +6,7 @@ import io
 import json
 import os
 import sys
+from datetime import datetime, timezone
 from typing import Optional
 
 import click
@@ -27,6 +28,7 @@ def _make_client(
     auth_token: Optional[str],
     ct0: Optional[str],
     timeout: Optional[float],
+    min_request_interval: float = 0.0,
 ) -> TwitterClient:
     tok, csrf = resolve_credentials(auth_token, ct0)
     if not tok or not csrf:
@@ -36,34 +38,78 @@ def _make_client(
             err=True,
         )
         sys.exit(1)
-    return TwitterClient(tok, csrf, timeout=timeout)
+    return TwitterClient(tok, csrf, timeout=timeout, min_request_interval=min_request_interval)
+
+
+# ---------------------------------------------------------------------------
+# Shorthand group: bird <tweet-id-or-url> → bird read <tweet-id-or-url>
+# ---------------------------------------------------------------------------
+
+class BirdGroup(click.Group):
+    def resolve_command(self, ctx, args):
+        cmd_name = args[0] if args else None
+        if cmd_name and cmd_name not in self.commands and not cmd_name.startswith("-"):
+            if cmd_name.isdigit() or "/status/" in cmd_name or "x.com" in cmd_name or "twitter.com" in cmd_name:
+                args.insert(0, "read")
+        return super().resolve_command(ctx, args)
 
 
 # ---------------------------------------------------------------------------
 # Global options
 # ---------------------------------------------------------------------------
 
-@click.group()
+@click.group(cls=BirdGroup)
 @click.pass_context
 @click.option("--auth-token", envvar=["AUTH_TOKEN", "TWITTER_AUTH_TOKEN"], hidden=True)
 @click.option("--ct0", envvar=["CT0", "TWITTER_CT0"], hidden=True)
 @click.option("--timeout", type=float, default=None, envvar="BIRD_TIMEOUT_MS",
               help="Request timeout in milliseconds.")
+@click.option("--rate-limit", "rate_limit", type=float, default=0.0, envvar="BIRD_RATE_LIMIT",
+              help="Minimum seconds between calls to x.com (0 = off). e.g. --rate-limit 5")
 @click.option("--json", "as_json", is_flag=True)
 @click.option("--quote-depth", type=int, default=1, envvar="BIRD_QUOTE_DEPTH")
-def main(ctx: click.Context, auth_token, ct0, timeout, as_json, quote_depth):
+@click.option("--plain", is_flag=True, default=False,
+              help="Plain output: no emoji, no color (stable for scripting).")
+@click.option("--no-emoji", "no_emoji", is_flag=True, default=False,
+              help="Disable emoji in output.")
+@click.option("--no-color", "no_color", is_flag=True, default=False,
+              help="Disable ANSI colors (or set NO_COLOR env var).")
+def main(ctx: click.Context, auth_token, ct0, timeout, rate_limit, as_json, quote_depth, plain, no_emoji, no_color):
     """bird — fast X/Twitter CLI (cookie auth, no browser extraction)."""
     ctx.ensure_object(dict)
     ctx.obj["auth_token"] = auth_token
     ctx.obj["ct0"] = ct0
     ctx.obj["timeout"] = timeout / 1000 if timeout else None
+    ctx.obj["rate_limit"] = max(0.0, rate_limit or 0.0)
     ctx.obj["as_json"] = as_json
     ctx.obj["quote_depth"] = quote_depth
+    # plain implies both no_emoji and no_color
+    ctx.obj["plain"] = plain or no_emoji or no_color
+    # Respect NO_COLOR env var
+    if os.environ.get("NO_COLOR"):
+        ctx.obj["plain"] = True
 
 
 def _client(ctx) -> TwitterClient:
     o = ctx.obj
-    return _make_client(o["auth_token"], o["ct0"], o["timeout"])
+    return _make_client(o["auth_token"], o["ct0"], o["timeout"], o.get("rate_limit", 0.0))
+
+
+def _parse_since(value: str) -> datetime:
+    """Parse --since (YYYY-MM-DD or ISO 8601) into an aware UTC datetime."""
+    s = value.strip()
+    try:
+        if len(s) == 10 and s.count("-") == 2:
+            dt = datetime.strptime(s, "%Y-%m-%d")
+        else:
+            dt = datetime.fromisoformat(s.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise click.BadParameter(
+            f"Invalid date {value!r}. Use YYYY-MM-DD or ISO 8601."
+        ) from exc
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
 
 
 # ---------------------------------------------------------------------------
@@ -79,7 +125,7 @@ def _unescape(text: str) -> str:
     return _html.unescape(text)
 
 
-def _format_tweet(tweet) -> str:
+def _format_tweet(tweet, plain: bool = False, show_stats: bool = False) -> str:
     lines: list[str] = []
 
     # Header: @username (Full Name):
@@ -96,41 +142,70 @@ def _format_tweet(tweet) -> str:
             lines.append(f"\u2502 {body_line}")
         if qt.media:
             for m in qt.media:
-                icon = "\U0001f3ac" if m.type in ("video", "animated_gif") else "\U0001f5bc\ufe0f"
-                lines.append(f"\u2502 {icon} {m.url}")
+                if plain:
+                    tag = "[video]" if m.type in ("video", "animated_gif") else "[image]"
+                    lines.append(f"\u2502 {tag} {m.url}")
+                else:
+                    icon = "\U0001f3ac" if m.type in ("video", "animated_gif") else "\U0001f5bc\ufe0f"
+                    lines.append(f"\u2502 {icon} {m.url}")
         lines.append(f"\u2514\u2500 https://x.com/{qt.author.username}/status/{qt.id}")
 
     # Media on the outer tweet
     if tweet.media:
         for m in tweet.media:
-            icon = "\U0001f3ac" if m.type in ("video", "animated_gif") else "\U0001f5bc\ufe0f"
-            lines.append(f"{icon} {m.url}")
+            if plain:
+                tag = "[video]" if m.type in ("video", "animated_gif") else "[image]"
+                lines.append(f"{tag} {m.url}")
+            else:
+                icon = "\U0001f3ac" if m.type in ("video", "animated_gif") else "\U0001f5bc\ufe0f"
+                lines.append(f"{icon} {m.url}")
 
     # Metadata
     if tweet.created_at:
-        lines.append(f"\U0001f4c5 {tweet.created_at}")
-    lines.append(f"\U0001f517 https://x.com/{tweet.author.username}/status/{tweet.id}")
-    lines.append(_SEPARATOR)
+        if plain:
+            lines.append(f"date: {tweet.created_at}")
+        else:
+            lines.append(f"\U0001f4c5 {tweet.created_at}")
+    url = f"https://x.com/{tweet.author.username}/status/{tweet.id}"
+    if plain:
+        lines.append(f"url: {url}")
+    else:
+        lines.append(f"\U0001f517 {url}")
+
+    # Engagement stats (shown for single-tweet read, not list views)
+    if show_stats and not plain:
+        parts = []
+        if tweet.like_count is not None:
+            parts.append(f"\u2764\ufe0f {tweet.like_count}")
+        if tweet.retweet_count is not None:
+            parts.append(f"\U0001f501 {tweet.retweet_count}")
+        if tweet.reply_count is not None:
+            parts.append(f"\U0001f4ac {tweet.reply_count}")
+        if parts:
+            lines.append("  ".join(parts))
+    else:
+        lines.append(_SEPARATOR)
 
     return "\n".join(lines)
 
 
-def _dump_tweet(tweet, as_json: bool) -> None:
+def _dump_tweet(tweet, as_json: bool, plain: bool = False, include_raw: bool = False,
+                show_stats: bool = False) -> None:
     if as_json:
-        click.echo(json.dumps(_tweet_to_dict(tweet), ensure_ascii=False, indent=2))
+        click.echo(json.dumps(_tweet_to_dict(tweet, include_raw=include_raw), ensure_ascii=False, indent=2))
     else:
-        click.echo(_format_tweet(tweet))
+        click.echo(_format_tweet(tweet, plain=plain, show_stats=show_stats))
 
 
-def _dump_tweets(tweets, as_json: bool) -> None:
+def _dump_tweets(tweets, as_json: bool, plain: bool = False, include_raw: bool = False) -> None:
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=include_raw) for t in tweets], ensure_ascii=False))
     else:
         for t in tweets:
-            click.echo(_format_tweet(t))
+            click.echo(_format_tweet(t, plain=plain))
 
 
-def _tweet_to_dict(tweet) -> dict:
+def _tweet_to_dict(tweet, include_raw: bool = False) -> dict:
     d: dict = {
         "id": tweet.id,
         "text": _unescape(tweet.text),
@@ -145,9 +220,11 @@ def _tweet_to_dict(tweet) -> dict:
     d["author"] = {"username": tweet.author.username, "name": tweet.author.name}
     d["authorId"] = tweet.author_id
     if tweet.quoted_tweet:
-        d["quotedTweet"] = _tweet_to_dict(tweet.quoted_tweet)
+        d["quotedTweet"] = _tweet_to_dict(tweet.quoted_tweet, include_raw=include_raw)
     if tweet.media:
         d["media"] = [_media_to_dict(m) for m in tweet.media]
+    if include_raw and tweet._raw is not None:
+        d["_raw"] = tweet._raw
     return d
 
 
@@ -183,20 +260,23 @@ def _user_to_dict(user) -> dict:
 @main.command()
 @click.argument("tweet_id_or_url")
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def read(ctx, tweet_id_or_url, as_json):
+def read(ctx, tweet_id_or_url, as_json, json_full):
     """Fetch and display a tweet by ID or URL."""
     tweet_id = extract_tweet_id(tweet_id_or_url)
     if not tweet_id:
         click.echo(f"Error: cannot parse tweet ID from {tweet_id_or_url!r}", err=True)
         sys.exit(1)
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweet = client.get_tweet(tweet_id)
+        tweet = client.get_tweet(tweet_id, include_raw=json_full)
     if not tweet:
         click.echo("Tweet not found.", err=True)
         sys.exit(1)
-    _dump_tweet(tweet, as_json)
+    _dump_tweet(tweet, as_json, plain=plain, include_raw=json_full, show_stats=True)
 
 
 # ---------------------------------------------------------------------------
@@ -206,34 +286,40 @@ def read(ctx, tweet_id_or_url, as_json):
 @main.command()
 @click.argument("tweet_id_or_url")
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def thread(ctx, tweet_id_or_url, as_json):
+def thread(ctx, tweet_id_or_url, as_json, json_full):
     """Show the full conversation thread for a tweet."""
     tweet_id = extract_tweet_id(tweet_id_or_url)
     if not tweet_id:
         click.echo(f"Error: cannot parse tweet ID from {tweet_id_or_url!r}", err=True)
         sys.exit(1)
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets = client.get_thread(tweet_id)
-    _dump_tweets(tweets, as_json)
+        tweets = client.get_thread(tweet_id, include_raw=json_full)
+    _dump_tweets(tweets, as_json, plain=plain, include_raw=json_full)
 
 
 @main.command()
 @click.argument("tweet_id_or_url")
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def replies(ctx, tweet_id_or_url, count, as_json):
+def replies(ctx, tweet_id_or_url, count, as_json, json_full):
     """List replies to a tweet."""
     tweet_id = extract_tweet_id(tweet_id_or_url)
     if not tweet_id:
         click.echo(f"Error: cannot parse tweet ID from {tweet_id_or_url!r}", err=True)
         sys.exit(1)
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets = client.get_replies(tweet_id)
-    _dump_tweets(tweets[:count], as_json)
+        tweets = client.get_replies(tweet_id, include_raw=json_full)
+    _dump_tweets(tweets[:count], as_json, plain=plain, include_raw=json_full)
 
 
 # ---------------------------------------------------------------------------
@@ -245,13 +331,18 @@ def replies(ctx, tweet_id_or_url, count, as_json):
 @click.pass_context
 def post_tweet(ctx, text):
     """Post a new tweet."""
-    with _client(ctx) as client:
-        tweet_id = client.tweet(text)
-    if tweet_id:
-        click.echo(f"Posted: https://x.com/i/status/{tweet_id}")
-    else:
-        click.echo("Failed to post tweet.", err=True)
+    plain = ctx.obj.get("plain", False)
+    try:
+        with _client(ctx) as client:
+            tweet_id = client.tweet(text)
+    except RuntimeError as exc:
+        click.echo(f"Failed to post tweet: {exc}", err=True)
         sys.exit(1)
+    url = f"https://x.com/i/status/{tweet_id}"
+    if plain:
+        click.echo(f"Tweet posted successfully!\n{url}")
+    else:
+        click.echo(f"\u2705 Tweet posted successfully!\n\U0001f517 {url}")
 
 
 @main.command(name="reply")
@@ -260,17 +351,22 @@ def post_tweet(ctx, text):
 @click.pass_context
 def post_reply(ctx, tweet_id_or_url, text):
     """Reply to a tweet."""
+    plain = ctx.obj.get("plain", False)
     tweet_id = extract_tweet_id(tweet_id_or_url)
     if not tweet_id:
         click.echo(f"Error: cannot parse tweet ID from {tweet_id_or_url!r}", err=True)
         sys.exit(1)
-    with _client(ctx) as client:
-        new_id = client.reply(text, tweet_id)
-    if new_id:
-        click.echo(f"Replied: https://x.com/i/status/{new_id}")
-    else:
-        click.echo("Failed to post reply.", err=True)
+    try:
+        with _client(ctx) as client:
+            new_id = client.reply(text, tweet_id)
+    except RuntimeError as exc:
+        click.echo(f"Failed to post reply: {exc}", err=True)
         sys.exit(1)
+    url = f"https://x.com/i/status/{new_id}"
+    if plain:
+        click.echo(f"Reply posted successfully!\n{url}")
+    else:
+        click.echo(f"\u2705 Reply posted successfully!\n\U0001f517 {url}")
 
 
 # ---------------------------------------------------------------------------
@@ -281,31 +377,39 @@ def post_reply(ctx, tweet_id_or_url, text):
 @click.argument("query")
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.option("--cursor", default=None)
 @click.option("--max-pages", type=int, default=None)
 @click.pass_context
-def search(ctx, query, count, as_json, cursor, max_pages):
+def search(ctx, query, count, as_json, json_full, cursor, max_pages):
     """Search for tweets matching a query."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets, next_cursor = client.search(query, count, cursor=cursor, max_pages=max_pages)
+        tweets, next_cursor = client.search(query, count, cursor=cursor, max_pages=max_pages,
+                                             include_raw=json_full)
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False, indent=2))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=json_full) for t in tweets],
+                               ensure_ascii=False, indent=2))
     else:
-        _dump_tweets(tweets, False)
+        _dump_tweets(tweets, False, plain=plain)
 
 
 @main.command()
-@click.option("--user", default=None, help="@handle to search mentions for")
+@click.option("-u", "--user", default=None, help="@handle to search mentions for")
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def mentions(ctx, user, count, as_json):
+def mentions(ctx, user, count, as_json, json_full):
     """Find tweets mentioning a user (defaults to authenticated user)."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets, _ = client.get_mentions(user, count)
-    _dump_tweets(tweets, as_json)
+        tweets, _ = client.get_mentions(user, count, include_raw=json_full)
+    _dump_tweets(tweets, as_json, plain=plain, include_raw=json_full)
 
 
 # ---------------------------------------------------------------------------
@@ -316,25 +420,42 @@ def mentions(ctx, user, count, as_json):
 @click.argument("handle")
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.option("--cursor", default=None)
+@click.option("--max-pages", type=int, default=None)
+@click.option("--since", "since", default=None,
+              help="Fetch tweets back to this date (YYYY-MM-DD or ISO 8601) instead "
+                   "of a fixed count. -n caps the result; --max-pages bounds requests.")
+@click.option("--delay", "delay_ms", type=int, default=1000, show_default=True,
+              help="Delay in ms between page fetches when paginating.")
 @click.pass_context
-def user_tweets(ctx, handle, count, as_json, cursor):
+def user_tweets(ctx, handle, count, as_json, json_full, cursor, max_pages, since, delay_ms):
     """Get tweets from a user's profile timeline."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     norm = normalize_handle(handle)
     if not norm:
         click.echo(f"Invalid handle: {handle!r}", err=True)
         sys.exit(1)
+    since_dt = _parse_since(since) if since else None
+    # In since-mode, a default (unset) -n shouldn't cap results; an explicit -n does.
+    if since_dt is not None and ctx.get_parameter_source("count") != click.core.ParameterSource.COMMANDLINE:
+        count = None
     with _client(ctx) as client:
         user = client.get_user_id_by_username(norm)
         if not user:
             click.echo(f"User @{norm} not found.", err=True)
             sys.exit(1)
-        tweets, next_cursor = client.get_user_tweets(user.id, count, cursor=cursor)
+        tweets, next_cursor = client.get_user_tweets(
+            user.id, count, cursor=cursor, max_pages=max_pages,
+            include_raw=json_full, page_delay=delay_ms / 1000, since=since_dt,
+        )
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False, indent=2))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=json_full) for t in tweets],
+                               ensure_ascii=False, indent=2))
     else:
-        _dump_tweets(tweets, False)
+        _dump_tweets(tweets, False, plain=plain)
 
 
 # ---------------------------------------------------------------------------
@@ -348,19 +469,24 @@ def user_tweets(ctx, handle, count, as_json, cursor):
 @click.option("--max-pages", type=int, default=None)
 @click.option("--cursor", default=None)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def bookmarks(ctx, count, folder_id, fetch_all, max_pages, cursor, as_json):
+def bookmarks(ctx, count, folder_id, fetch_all, max_pages, cursor, as_json, json_full):
     """List bookmarked tweets."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     limit = -1 if fetch_all else count
     with _client(ctx) as client:
         tweets, next_cursor = client.get_bookmarks(
-            limit, folder_id=folder_id, cursor=cursor, max_pages=max_pages
+            limit, folder_id=folder_id, cursor=cursor, max_pages=max_pages,
+            include_raw=json_full,
         )
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False, indent=2))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=json_full) for t in tweets],
+                               ensure_ascii=False, indent=2))
     else:
-        _dump_tweets(tweets, False)
+        _dump_tweets(tweets, False, plain=plain)
 
 
 @main.command()
@@ -386,17 +512,21 @@ def unbookmark(ctx, tweet_ids_or_urls):
 @main.command()
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.option("--cursor", default=None)
 @click.pass_context
-def likes(ctx, count, as_json, cursor):
+def likes(ctx, count, as_json, json_full, cursor):
     """List liked tweets."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets, next_cursor = client.get_likes(count, cursor=cursor)
+        tweets, next_cursor = client.get_likes(count, cursor=cursor, include_raw=json_full)
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False, indent=2))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=json_full) for t in tweets],
+                               ensure_ascii=False, indent=2))
     else:
-        _dump_tweets(tweets, False)
+        _dump_tweets(tweets, False, plain=plain)
 
 
 # ---------------------------------------------------------------------------
@@ -407,16 +537,19 @@ def likes(ctx, count, as_json, cursor):
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--following", is_flag=True, help="Show Following (chronological) feed")
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.pass_context
-def home(ctx, count, following, as_json):
+def home(ctx, count, following, as_json, json_full):
     """Fetch home timeline (For You or Following feed)."""
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
         if following:
             tweets = client.get_home_latest_timeline(count)
         else:
             tweets = client.get_home_timeline(count)
-    _dump_tweets(tweets, as_json)
+    _dump_tweets(tweets, as_json, plain=plain, include_raw=json_full)
 
 
 # ---------------------------------------------------------------------------
@@ -475,6 +608,58 @@ def followers(ctx, user, count, as_json, cursor):
             click.echo(f"@{u.username} — {u.name}")
 
 
+# ---------------------------------------------------------------------------
+# follow / unfollow
+# ---------------------------------------------------------------------------
+
+def _resolve_user_id(client, username_or_id: str) -> Optional[str]:
+    """Return a numeric user ID from a bare ID or @handle / handle."""
+    val = username_or_id.lstrip("@").strip()
+    if val.isdigit():
+        return val
+    norm = normalize_handle(val)
+    if not norm:
+        return None
+    user = client.get_user_id_by_username(norm)
+    return user.id if user else None
+
+
+@main.command(name="follow")
+@click.argument("username_or_id")
+@click.pass_context
+def follow_user(ctx, username_or_id):
+    """Follow a user (username with or without @, or numeric user ID)."""
+    with _client(ctx) as client:
+        uid = _resolve_user_id(client, username_or_id)
+        if not uid:
+            click.echo(f"User not found: {username_or_id!r}", err=True)
+            sys.exit(1)
+        ok = client.follow(uid)
+    if ok:
+        click.echo(f"Followed: {username_or_id}")
+    else:
+        click.echo(f"Failed to follow: {username_or_id}", err=True)
+        sys.exit(1)
+
+
+@main.command(name="unfollow")
+@click.argument("username_or_id")
+@click.pass_context
+def unfollow_user(ctx, username_or_id):
+    """Unfollow a user (username with or without @, or numeric user ID)."""
+    with _client(ctx) as client:
+        uid = _resolve_user_id(client, username_or_id)
+        if not uid:
+            click.echo(f"User not found: {username_or_id!r}", err=True)
+            sys.exit(1)
+        ok = client.unfollow(uid)
+    if ok:
+        click.echo(f"Unfollowed: {username_or_id}")
+    else:
+        click.echo(f"Failed to unfollow: {username_or_id}", err=True)
+        sys.exit(1)
+
+
 # ---------------------------------------------------------------------------
 # lists / list-timeline
 # ---------------------------------------------------------------------------
@@ -507,22 +692,27 @@ def list_lists(ctx, member_of, count, as_json):
 @click.argument("list_id_or_url")
 @click.option("-n", "--count", default=20, show_default=True)
 @click.option("--json", "as_json", is_flag=True)
+@click.option("--json-full", "json_full", is_flag=True,
+              help="Include raw API response in _raw field.")
 @click.option("--cursor", default=None)
 @click.option("--max-pages", type=int, default=None)
 @click.pass_context
-def list_timeline(ctx, list_id_or_url, count, as_json, cursor, max_pages):
+def list_timeline(ctx, list_id_or_url, count, as_json, json_full, cursor, max_pages):
     """Get tweets from a list timeline."""
     list_id = extract_list_id(list_id_or_url)
     if not list_id:
         click.echo(f"Cannot parse list ID from {list_id_or_url!r}", err=True)
         sys.exit(1)
-    as_json = as_json or ctx.obj.get("as_json")
+    as_json = as_json or json_full or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     with _client(ctx) as client:
-        tweets, next_cursor = client.get_list_timeline(list_id, count, cursor=cursor, max_pages=max_pages)
+        tweets, next_cursor = client.get_list_timeline(list_id, count, cursor=cursor,
+                                                        max_pages=max_pages, include_raw=json_full)
     if as_json:
-        click.echo(json.dumps([_tweet_to_dict(t) for t in tweets], ensure_ascii=False, indent=2))
+        click.echo(json.dumps([_tweet_to_dict(t, include_raw=json_full) for t in tweets],
+                               ensure_ascii=False, indent=2))
     else:
-        _dump_tweets(tweets, False)
+        _dump_tweets(tweets, False, plain=plain)
 
 
 # ---------------------------------------------------------------------------
@@ -545,6 +735,7 @@ def news(ctx, count, ai_only, with_tweets, tweets_per_item,
          tab_for_you, tab_news, tab_sports, tab_entertainment, tab_trending, as_json):
     """Fetch news and trending topics from X's Explore tabs."""
     as_json = as_json or ctx.obj.get("as_json")
+    plain = ctx.obj.get("plain", False)
     tabs: list[str] = []
     if tab_for_you:
         tabs.append("forYou")
@@ -633,8 +824,8 @@ def about(ctx, handle, as_json):
             click.echo(f"Based in: {profile.account_based_in}")
         if profile.source:
             click.echo(f"Source: {profile.source}")
-        if profile.created_country_accurate:
-            click.echo(f"Created in: {profile.created_country_accurate}")
+        if profile.learn_more_url:
+            click.echo(f"Info: {profile.learn_more_url}")
 
 
 @main.command()

{birdapi-0.0.1 → birdapi-0.0.2}/src/bird/client.py

@@ -15,6 +15,7 @@ import os
 import re
 import time
 import uuid
+from datetime import datetime
 from typing import Any, Optional
 
 import httpx
@@ -56,6 +57,7 @@ from ._utils import (
     find_tweet_in_instructions,
     map_tweet_result,
     normalize_handle,
+    parse_tweet_datetime,
     parse_tweets_from_instructions,
     parse_users_from_instructions,
 )
@@ -66,6 +68,9 @@ _DEFAULT_UA = (
     "Chrome/131.0.0.0 Safari/537.36"
 )
 _PAGE_SIZE = 20
+# --since pagination safety bounds: default page budget and hard ceiling.
+_SINCE_DEFAULT_PAGES = 25
+_SINCE_MAX_PAGES = 50
 
 # Regex to detect query-ID mismatch errors in 400/422 responses
 _RAW_QUERY_MISSING_RE = re.compile(r"must be defined", re.IGNORECASE)
@@ -128,6 +133,7 @@ class TwitterClient:
         user_agent: str = _DEFAULT_UA,
         timeout: Optional[float] = None,
         quote_depth: int = 1,
+        min_request_interval: float = 0.0,
     ) -> None:
         if not auth_token or not ct0:
             raise ValueError("Both auth_token and ct0 are required")
@@ -137,6 +143,9 @@ class TwitterClient:
         self._user_agent = user_agent
         self._timeout = timeout
         self._quote_depth = max(0, int(quote_depth))
+        # Client-side rate limit: minimum seconds between HTTP calls (0 = off).
+        self._min_request_interval = max(0.0, float(min_request_interval))
+        self._last_request_at = 0.0
         self._client_uuid = str(uuid.uuid4())
         self._client_device_id = str(uuid.uuid4())
         self._client_user_id: Optional[str] = None
@@ -202,13 +211,25 @@ class TwitterClient:
         if result and result.id:
             self._client_user_id = result.id
 
+    def _throttle(self) -> None:
+        """Enforce the optional minimum interval between outbound HTTP calls."""
+        if self._min_request_interval <= 0:
+            return
+        wait = self._min_request_interval - (time.monotonic() - self._last_request_at)
+        if wait > 0:
+            time.sleep(wait)
+        self._last_request_at = time.monotonic()
+
     def _get(self, url: str) -> httpx.Response:
+        self._throttle()
         return self._http.get(url, headers=self._json_headers())
 
     def _post(self, url: str, body: str) -> httpx.Response:
+        self._throttle()
         return self._http.post(url, headers=self._json_headers(), content=body.encode())
 
     def _post_form(self, url: str, data: dict, extra_headers: Optional[dict] = None) -> httpx.Response:
+        self._throttle()
         headers = {**self._base_headers(), "content-type": "application/x-www-form-urlencoded"}
         if extra_headers:
             headers.update(extra_headers)
@@ -256,9 +277,16 @@ class TwitterClient:
         limit: int,
         max_pages: Optional[int] = None,
         initial_cursor: Optional[str] = None,
+        page_delay: float = 0.0,
+        since: Optional[datetime] = None,
     ) -> tuple[list[Tweet], Optional[str], Optional[str]]:
         """Generic tweet pagination loop.
 
+        When ``since`` is set, tweets older than the cutoff are dropped and
+        paging stops once a page's oldest tweet predates it. The page's *last*
+        tweet (not any tweet) drives the stop decision so a pinned tweet — which
+        sits at the top regardless of date — doesn't trigger an early stop.
+
         Returns (tweets, next_cursor, error).
         """
         tweets: list[Tweet] = []
@@ -269,7 +297,13 @@ class TwitterClient:
         unlimited = limit == math.inf or limit < 0
 
         while unlimited or len(tweets) < limit:
-            page_count = _PAGE_SIZE if unlimited else min(_PAGE_SIZE, limit - len(tweets))
+            if pages_fetched > 0 and page_delay > 0:
+                time.sleep(page_delay)
+            # Always request a full page. X returns timeline *entries*, many of
+            # which (cursors, who-to-follow, gated dupes) aren't tweets, so a
+            # short request like count=1 wastes a round-trip; we trim to `limit`
+            # via the inner break below.
+            page_count = _PAGE_SIZE
             page_tweets, page_cursor, had_404, error = fetch_page(cursor, page_count)
 
             if error and not page_tweets:
@@ -287,12 +321,23 @@ class TwitterClient:
             for t in page_tweets:
                 if t.id in seen:
                     continue
+                if since is not None:
+                    dt = parse_tweet_datetime(t.created_at)
+                    if dt is not None and dt < since:
+                        continue  # older than cutoff — drop (handles pinned dupes too)
                 seen.add(t.id)
                 tweets.append(t)
                 added += 1
                 if not unlimited and len(tweets) >= limit:
                     break
 
+            # Stop once the page's oldest (last, chronological) tweet predates the cutoff.
+            if since is not None and page_tweets:
+                last_dt = parse_tweet_datetime(page_tweets[-1].created_at)
+                if last_dt is not None and last_dt < since:
+                    next_cursor = None
+                    break
+
             if not page_cursor or page_cursor == cursor or not page_tweets or added == 0:
                 next_cursor = None
                 break
@@ -511,7 +556,7 @@ class TwitterClient:
                     pass
         return None
 
-    def get_tweet(self, tweet_id: str) -> Optional[Tweet]:
+    def get_tweet(self, tweet_id: str, include_raw: bool = False) -> Optional[Tweet]:
         """Fetch a single tweet by ID."""
         data = self._fetch_tweet_detail(tweet_id)
         if not data:
@@ -523,7 +568,7 @@ class TwitterClient:
                 tweet_id,
             )
         )
-        mapped = map_tweet_result(result, self._quote_depth)
+        mapped = map_tweet_result(result, self._quote_depth, include_raw)
         if mapped and result and result.get("article"):
             title = _first_text(
                 (result["article"].get("article_results") or {}).get("result", {}).get("title"),
@@ -539,7 +584,7 @@ class TwitterClient:
                         mapped.text = f"{fallback['title']}\n\n{pt}" if fallback.get("title") else pt
         return mapped
 
-    def get_replies(self, tweet_id: str) -> list[Tweet]:
+    def get_replies(self, tweet_id: str, include_raw: bool = False) -> list[Tweet]:
         """Fetch the first page of replies to a tweet."""
         data = self._fetch_tweet_detail(tweet_id)
         if not data:
@@ -547,10 +592,10 @@ class TwitterClient:
         instructions = (
             (data.get("threaded_conversation_with_injections_v2") or {}).get("instructions")
         )
-        tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+        tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
         return [t for t in tweets if t.in_reply_to_status_id == tweet_id]
 
-    def get_thread(self, tweet_id: str) -> list[Tweet]:
+    def get_thread(self, tweet_id: str, include_raw: bool = False) -> list[Tweet]:
         """Fetch the full conversation thread for a tweet."""
         data = self._fetch_tweet_detail(tweet_id)
         if not data:
@@ -558,7 +603,7 @@ class TwitterClient:
         instructions = (
             (data.get("threaded_conversation_with_injections_v2") or {}).get("instructions")
         )
-        tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+        tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
         target = next((t for t in tweets if t.id == tweet_id), None)
         root_id = (target.conversation_id if target else None) or tweet_id
         thread = [t for t in tweets if t.conversation_id == root_id]
@@ -620,6 +665,7 @@ class TwitterClient:
         *,
         cursor: Optional[str] = None,
         max_pages: Optional[int] = None,
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         """Search for tweets.  Returns ``(tweets, next_cursor)``."""
         features = search_features()
@@ -659,7 +705,7 @@ class TwitterClient:
                         .get("timeline", {})
                         .get("instructions")
                     )
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:
@@ -675,6 +721,7 @@ class TwitterClient:
         self,
         username: Optional[str] = None,
         count: int = 20,
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         """Search for mentions of *username* (defaults to authenticated user)."""
         if username:
@@ -687,7 +734,7 @@ class TwitterClient:
             if not user:
                 return [], None
             q = f"@{user.username}"
-        return self.search(q, count)
+        return self.search(q, count, include_raw=include_raw)
 
     # ------------------------------------------------------------------
     # Posting
@@ -739,23 +786,35 @@ class TwitterClient:
                         TWITTER_API_BASE, headers=headers, content=build_body(qid).encode()
                     )
             if not r.is_success:
-                return None
+                raise RuntimeError(f"HTTP {r.status_code}: {r.text[:200]}")
             data = r.json()
             errors = data.get("errors") or []
             if errors:
+                msgs = ", ".join(
+                    (e or {}).get("message") or f"Error {(e or {}).get('code', '?')}"
+                    for e in errors
+                )
                 # Fallback to legacy REST on error code 226 (bot detection)
                 if any((e or {}).get("code") == 226 for e in errors):
-                    return self._post_status_update(variables)
-                return None
-            return (
+                    fallback = self._post_status_update(variables)
+                    if fallback:
+                        return fallback
+                    raise RuntimeError(msgs)
+                raise RuntimeError(msgs)
+            tweet_id = (
                 (data.get("data") or {})
                 .get("create_tweet", {})
                 .get("tweet_results", {})
                 .get("result", {})
                 .get("rest_id")
             )
-        except Exception:
-            return None
+            if not tweet_id:
+                raise RuntimeError("Tweet created but no ID returned")
+            return tweet_id
+        except RuntimeError:
+            raise
+        except Exception as exc:
+            raise RuntimeError(str(exc)) from exc
 
     def _post_status_update(self, variables: dict) -> Optional[str]:
         """Legacy statuses/update.json fallback for tweet creation."""
@@ -930,17 +989,19 @@ class TwitterClient:
         folder_id: Optional[str] = None,
         cursor: Optional[str] = None,
         max_pages: Optional[int] = None,
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         """Fetch bookmarked tweets.  Returns ``(tweets, next_cursor)``."""
         if folder_id:
-            return self._bookmarks_folder(folder_id, count, cursor, max_pages)
-        return self._bookmarks_main(count, cursor, max_pages)
+            return self._bookmarks_folder(folder_id, count, cursor, max_pages, include_raw)
+        return self._bookmarks_main(count, cursor, max_pages, include_raw)
 
     def _bookmarks_main(
         self,
         limit: int,
         initial_cursor: Optional[str],
         max_pages: Optional[int],
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         features = bookmarks_features()
         qids = list(dict.fromkeys([
@@ -978,7 +1039,7 @@ class TwitterClient:
                         .get("timeline", {})
                         .get("instructions")
                     )
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:
@@ -994,6 +1055,7 @@ class TwitterClient:
         limit: int,
         initial_cursor: Optional[str],
         max_pages: Optional[int],
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         features = bookmarks_features()
         qids = list(dict.fromkeys([
@@ -1028,7 +1090,7 @@ class TwitterClient:
                         .get("timeline", {})
                         .get("instructions")
                     )
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:
@@ -1048,6 +1110,7 @@ class TwitterClient:
         *,
         cursor: Optional[str] = None,
         max_pages: Optional[int] = None,
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         """Fetch liked tweets for the current user.  Returns ``(tweets, next_cursor)``."""
         user = self.get_current_user()
@@ -1088,7 +1151,7 @@ class TwitterClient:
                         .get("timeline", {})
                         .get("instructions")
                     )
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:
@@ -1105,17 +1168,37 @@ class TwitterClient:
     def get_user_tweets(
         self,
         user_id: str,
-        count: int = 20,
+        count: Optional[int] = 20,
         *,
         cursor: Optional[str] = None,
         max_pages: Optional[int] = None,
+        include_raw: bool = False,
+        page_delay: float = 0.0,
+        since: Optional[datetime] = None,
     ) -> tuple[list[Tweet], Optional[str]]:
-        """Fetch tweets from a user's profile timeline.  Returns ``(tweets, next_cursor)``."""
+        """Fetch tweets from a user's profile timeline.  Returns ``(tweets, next_cursor)``.
+
+        ``since`` (aware datetime) fetches everything back to that cutoff instead
+        of a fixed ``count``: paging continues until tweets predate it, bounded
+        by ``max_pages`` (default ``_SINCE_DEFAULT_PAGES``). When ``since`` is set
+        ``count`` becomes an optional upper cap (``None`` = no tweet cap).
+        """
         features = user_tweets_features()
         qids = list(dict.fromkeys([self._get_query_id("UserTweets"), "Wms1GvIiHXAPBaCr9KblaA"]))
-        hard_max = 10
-        computed_max = max(1, math.ceil(count / _PAGE_SIZE))
-        effective_max = min(hard_max, max_pages or computed_max)
+        if since is not None:
+            # since-mode: date is the goal; max_pages is the safety bound and
+            # count is an optional upper cap on returned tweets.
+            limit = count if count is not None else math.inf
+            effective_max = min(_SINCE_MAX_PAGES, max_pages or _SINCE_DEFAULT_PAGES)
+        else:
+            limit = count if count is not None else _PAGE_SIZE
+            hard_max = 10
+            # +1 page of headroom: a profile page of N entries nets fewer than N
+            # tweets (cursors, who-to-follow, pinned dupes, gated tweets), so allow
+            # one extra page to top up to `count`. The _paginate loop stops as soon
+            # as `count` is reached, so the common case is still 1 request.
+            computed_max = math.ceil(limit / _PAGE_SIZE) + 1
+            effective_max = min(hard_max, max_pages or computed_max)
 
         def fetch_page(page_cursor, page_count):
             variables: dict[str, Any] = {
@@ -1154,14 +1237,16 @@ class TwitterClient:
                         msgs = ", ".join(e.get("message", "") for e in errors)
                         if not instructions:
                             return [], None, False, msgs
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:
                     return [], None, False, str(exc)
             return [], None, False, "No query IDs available"
 
-        tweets, next_cursor, _ = self._paginate(fetch_page, count, effective_max, cursor)
+        tweets, next_cursor, _ = self._paginate(
+            fetch_page, limit, effective_max, cursor, page_delay=page_delay, since=since,
+        )
         return tweets, next_cursor
 
     # ------------------------------------------------------------------
@@ -1188,7 +1273,9 @@ class TwitterClient:
         cursor: Optional[str] = None
 
         while len(tweets) < count:
-            page_count = min(_PAGE_SIZE, count - len(tweets))
+            # Request full pages; non-tweet entries get filtered, so a partial
+            # request under-delivers. Trimmed to `count` after the dedup loop.
+            page_count = _PAGE_SIZE
             had_404 = False
             success = False
             for qid in qids:
@@ -1230,6 +1317,8 @@ class TwitterClient:
                             seen.add(t.id)
                             tweets.append(t)
                             added += 1
+                            if len(tweets) >= count:
+                                break
                     if not new_cursor or new_cursor == cursor or not page_tweets or added == 0:
                         return tweets
                     cursor = new_cursor
@@ -1456,6 +1545,7 @@ class TwitterClient:
         *,
         cursor: Optional[str] = None,
         max_pages: Optional[int] = None,
+        include_raw: bool = False,
     ) -> tuple[list[Tweet], Optional[str]]:
         """Fetch tweets from a list timeline.  Returns ``(tweets, next_cursor)``."""
         features = lists_features()
@@ -1487,7 +1577,7 @@ class TwitterClient:
                         .get("timeline", {})
                         .get("instructions")
                     )
-                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth)
+                    page_tweets = parse_tweets_from_instructions(instructions, self._quote_depth, include_raw)
                     next_cur = extract_cursor_from_instructions(instructions)
                     return page_tweets, next_cur, False, None
                 except Exception as exc:

birdapi-0.0.2/tests/test_client.py

@@ -0,0 +1,109 @@
+"""Unit tests for TwitterClient pagination/throttle internals — no network."""
+
+from datetime import datetime, timedelta, timezone
+
+from bird._models import Author, Tweet
+from bird.client import TwitterClient
+
+
+def _client():
+    return TwitterClient(auth_token="x", ct0="y")
+
+
+def _tweet(tid: str, dt: datetime, pinned_label: str = "") -> Tweet:
+    return Tweet(
+        id=tid,
+        text=f"tweet {tid}{pinned_label}",
+        author=Author(username="alice", name="Alice"),
+        created_at=dt.strftime("%a %b %d %H:%M:%S %z %Y"),
+    )
+
+
+# ---------------------------------------------------------------------------
+# _paginate: since-mode date filtering
+# ---------------------------------------------------------------------------
+
+def _make_fetcher(pages):
+    """Return a fetch_page(cursor, count) that yields successive pages.
+
+    `pages` is a list of (tweets, next_cursor).
+    """
+    state = {"i": 0}
+
+    def fetch_page(cursor, count):
+        i = state["i"]
+        if i >= len(pages):
+            return [], None, False, None
+        tweets, cur = pages[i]
+        state["i"] = i + 1
+        return tweets, cur, False, None
+
+    return fetch_page
+
+
+def test_paginate_since_stops_and_filters():
+    now = datetime(2026, 6, 7, tzinfo=timezone.utc)
+    cutoff = now - timedelta(days=2)
+    # Page 1: all newer than cutoff. Page 2: straddles cutoff (last is older).
+    p1 = [_tweet("1", now), _tweet("2", now - timedelta(days=1))]
+    p2 = [
+        _tweet("3", now - timedelta(days=1, hours=12)),
+        _tweet("4", now - timedelta(days=3)),
+    ]
+    p3 = [_tweet("5", now - timedelta(days=5))]  # should never be fetched
+    fetch = _make_fetcher([(p1, "c1"), (p2, "c2"), (p3, "c3")])
+
+    tweets, _, _ = _client()._paginate(fetch, limit=float("inf"), since=cutoff)
+    ids = [t.id for t in tweets]
+    assert ids == ["1", "2", "3"]  # "4" dropped (older), page 3 never fetched
+
+
+def test_paginate_since_pinned_old_does_not_stop_early():
+    now = datetime(2026, 6, 7, tzinfo=timezone.utc)
+    cutoff = now - timedelta(days=2)
+    # Pinned tweet (old) sits FIRST but the rest of the page is recent.
+    pinned = _tweet("pin", now - timedelta(days=400), " [pinned]")
+    p1 = [pinned, _tweet("1", now), _tweet("2", now - timedelta(days=1))]
+    p2 = [_tweet("3", now - timedelta(days=3))]  # crosses cutoff -> stop after this
+    fetch = _make_fetcher([(p1, "c1"), (p2, "c2")])
+
+    tweets, _, _ = _client()._paginate(fetch, limit=float("inf"), since=cutoff)
+    ids = [t.id for t in tweets]
+    # Pinned dropped (older than cutoff), but page 2 WAS still fetched.
+    assert "pin" not in ids
+    assert ids == ["1", "2"]
+
+
+def test_paginate_since_count_caps_result():
+    now = datetime(2026, 6, 7, tzinfo=timezone.utc)
+    cutoff = now - timedelta(days=30)
+    p1 = [_tweet(str(i), now - timedelta(hours=i)) for i in range(20)]
+    fetch = _make_fetcher([(p1, "c1"), (p1, "c2")])
+    tweets, _, _ = _client()._paginate(fetch, limit=5, since=cutoff)
+    assert len(tweets) == 5
+
+
+# ---------------------------------------------------------------------------
+# rate-limit throttle
+# ---------------------------------------------------------------------------
+
+def test_throttle_disabled_by_default(monkeypatch):
+    slept = []
+    monkeypatch.setattr("bird.client.time.sleep", lambda s: slept.append(s))
+    c = _client()
+    c._throttle()
+    c._throttle()
+    assert slept == []
+
+
+def test_throttle_spaces_calls(monkeypatch):
+    slept = []
+    clock = {"t": 100.0}
+    monkeypatch.setattr("bird.client.time.monotonic", lambda: clock["t"])
+    monkeypatch.setattr("bird.client.time.sleep", lambda s: slept.append(s))
+    c = TwitterClient(auth_token="x", ct0="y", min_request_interval=5.0)
+    c._throttle()  # first call: last_request_at was 0, so elapsed huge -> no sleep
+    assert slept == []
+    # Second call immediately after: must wait the full interval.
+    c._throttle()
+    assert slept and abs(slept[0] - 5.0) < 1e-6

{birdapi-0.0.1 → birdapi-0.0.2}/tests/test_utils.py

@@ -1,5 +1,7 @@
 """Unit tests for _utils.py — no network required."""
 
+from datetime import timezone
+
 import pytest
 from bird._utils import (
     extract_bookmark_folder_id,
@@ -8,6 +10,7 @@ from bird._utils import (
     extract_tweet_id,
     map_tweet_result,
     normalize_handle,
+    parse_tweet_datetime,
     parse_tweets_from_instructions,
     render_content_state,
 )
@@ -203,6 +206,48 @@ def test_parse_tweets_deduplication():
     assert len(tweets) == 1
 
 
+def test_map_tweet_result_visibility_wrapper():
+    # Visibility-gated tweets nest the real tweet under .tweet with no top rest_id.
+    inner = _make_raw_tweet()
+    wrapped = {"__typename": "TweetWithVisibilityResults", "tweet": inner}
+    tweet = map_tweet_result(wrapped)
+    assert tweet is not None
+    assert tweet.id == "1"
+    assert tweet.text == "Hello"
+
+
+def test_parse_tweet_datetime_valid():
+    dt = parse_tweet_datetime("Sun Jun 07 23:11:05 +0000 2026")
+    assert dt is not None
+    assert (dt.year, dt.month, dt.day, dt.hour) == (2026, 6, 7, 23)
+    assert dt.tzinfo is not None
+    assert dt.utcoffset().total_seconds() == 0
+
+
+def test_parse_tweet_datetime_invalid():
+    assert parse_tweet_datetime(None) is None
+    assert parse_tweet_datetime("") is None
+    assert parse_tweet_datetime("not a date") is None
+
+
+def test_parse_tweet_datetime_is_comparable():
+    older = parse_tweet_datetime("Mon Jan 01 00:00:00 +0000 2024")
+    newer = parse_tweet_datetime("Sun Jun 07 23:11:05 +0000 2026")
+    cutoff = parse_tweet_datetime("Mon Jan 01 00:00:00 +0000 2026")
+    assert older < cutoff < newer
+    assert cutoff.tzinfo == timezone.utc or cutoff.utcoffset().total_seconds() == 0
+
+
+def test_parse_tweets_from_instructions_visibility_wrapper():
+    # Regression: accounts under visibility gating return all tweets wrapped as
+    # TweetWithVisibilityResults; without unwrapping the parser yielded 0 tweets.
+    inner = _make_raw_tweet()
+    wrapped = {"__typename": "TweetWithVisibilityResults", "tweet": inner}
+    tweets = parse_tweets_from_instructions(_instructions_with_tweet(wrapped))
+    assert len(tweets) == 1
+    assert tweets[0].id == "1"
+
+
 # ---------------------------------------------------------------------------
 # extract_cursor_from_instructions
 # ---------------------------------------------------------------------------