birdapi 0.0.1__tar.gz → 0.0.3__tar.gz

{birdapi-0.0.1 → birdapi-0.0.3}/CLAUDE.md

@@ -79,6 +79,7 @@ client.get_home_timeline(count)             # → list[Tweet]
 client.get_home_latest_timeline(count)      # → list[Tweet]
 client.get_current_user()                   # → User | None
 client.get_user_id_by_username(handle)      # → User | None
+client.get_user_profile(handle)             # → UserProfile | None (full profile via UserByScreenName)
 client.get_following(user_id, count)        # → (list[User], next_cursor)
 client.get_followers(user_id, count)        # → (list[User], next_cursor)
 client.like/unlike/retweet/unretweet/bookmark/unbookmark(tweet_id)  # → bool

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: birdapi
-Version: 0.0.1
+Version: 0.0.3
 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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "birdapi"
-version = "0.0.1"
+version = "0.0.3"
 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.3}/src/bird/__init__.py

@@ -1,12 +1,23 @@
 """bird — X/Twitter GraphQL client library."""
 
 from .client import TwitterClient
-from ._models import AboutProfile, ArticleMetadata, Author, MediaItem, NewsItem, Tweet, TwitterList, User
+from ._models import (
+    AboutProfile,
+    ArticleMetadata,
+    Author,
+    MediaItem,
+    NewsItem,
+    Tweet,
+    TwitterList,
+    User,
+    UserProfile,
+)
 
 __all__ = [
     "TwitterClient",
     "Tweet",
     "User",
+    "UserProfile",
     "Author",
     "MediaItem",
     "ArticleMetadata",

{birdapi-0.0.1 → birdapi-0.0.3}/src/bird/_constants.py

@@ -41,6 +41,7 @@ FALLBACK_QUERY_IDS: dict[str, str] = {
     "GenericTimelineById": "uGSr7alSjR9v6QJAIaqSKQ",
     "TrendHistory": "Sj4T-jSB9pr0Mxtsc1UKZQ",
     "AboutAccountQuery": "zs_jFPFT78rBpXv9Z3U2YQ",
+    "UserByScreenName": "681MIj51w00Aj6dY0GXnHw",
 }
 
 SETTINGS_SCREEN_NAME_RE = re.compile(r'"screen_name":"([^"]+)"')

{birdapi-0.0.1 → birdapi-0.0.3}/src/bird/_models.py

@@ -8,6 +8,7 @@ from typing import Any, Optional
 class Author:
     username: str
     name: str
+    profile_image_url: Optional[str] = None
 
 
 @dataclass
@@ -36,6 +37,7 @@ class Tweet:
     reply_count: Optional[int] = None
     retweet_count: Optional[int] = None
     like_count: Optional[int] = None
+    view_count: Optional[int] = None
     conversation_id: Optional[str] = None
     in_reply_to_status_id: Optional[str] = None
     author_id: Optional[str] = None
@@ -58,6 +60,38 @@ class User:
     created_at: Optional[str] = None
 
 
+@dataclass
+class UserProfile:
+    """Full profile information from the UserByScreenName endpoint."""
+
+    id: str
+    username: str
+    name: str
+    description: Optional[str] = None
+    location: Optional[str] = None
+    website: Optional[str] = None
+    created_at: Optional[str] = None
+    followers_count: Optional[int] = None
+    following_count: Optional[int] = None
+    tweet_count: Optional[int] = None
+    media_count: Optional[int] = None
+    listed_count: Optional[int] = None
+    likes_count: Optional[int] = None
+    is_blue_verified: Optional[bool] = None
+    is_verified: Optional[bool] = None
+    verified_type: Optional[str] = None
+    is_identity_verified: Optional[bool] = None
+    verified_since: Optional[str] = None
+    profile_image_url: Optional[str] = None
+    profile_banner_url: Optional[str] = None
+    is_protected: Optional[bool] = None
+    can_dm: Optional[bool] = None
+    pinned_tweet_ids: Optional[list[str]] = None
+    professional_type: Optional[str] = None
+    professional_category: Optional[str] = None
+    _raw: Optional[Any] = field(default=None, repr=False)
+
+
 @dataclass
 class TwitterList:
     id: str

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

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import re
+from datetime import datetime, timezone
 from typing import Any, Optional
 
 from ._models import (
@@ -11,6 +12,7 @@ from ._models import (
     MediaItem,
     Tweet,
     User,
+    UserProfile,
 )
 
 
@@ -20,6 +22,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:
@@ -346,11 +361,33 @@ def _unwrap_tweet_result(result: Optional[dict]) -> Optional[dict]:
     return result.get("tweet") or result
 
 
+def _extract_view_count(result: dict, legacy: dict) -> Optional[int]:
+    """Pull the impression count from views.count (or legacy ext_views)."""
+    raw = (result.get("views") or {}).get("count")
+    if raw is None:
+        raw = (legacy.get("ext_views") or {}).get("count")
+    try:
+        return int(raw) if raw is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _extract_user_avatar(user_result: dict) -> Optional[str]:
+    return (
+        (user_result.get("avatar") or {}).get("image_url")
+        or (user_result.get("legacy") or {}).get("profile_image_url_https")
+    )
+
+
 def map_tweet_result(
     result: Optional[dict],
     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 {}
@@ -379,11 +416,16 @@ def map_tweet_result(
     tweet = Tweet(
         id=result["rest_id"],
         text=text,
-        author=Author(username=username, name=name or username),
+        author=Author(
+            username=username,
+            name=name or username,
+            profile_image_url=_extract_user_avatar(user_result),
+        ),
         created_at=legacy.get("created_at"),
         reply_count=legacy.get("reply_count"),
         retweet_count=legacy.get("retweet_count"),
         like_count=legacy.get("favorite_count"),
+        view_count=_extract_view_count(result, legacy),
         conversation_id=legacy.get("conversation_id_str"),
         in_reply_to_status_id=legacy.get("in_reply_to_status_id_str") or None,
         author_id=user_id,
@@ -401,6 +443,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,11 +496,95 @@ 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
 
 
+def map_user_profile_result(
+    result: Optional[dict],
+    include_raw: bool = False,
+) -> Optional[UserProfile]:
+    """Map a UserByScreenName ``user.result`` payload to a UserProfile.
+
+    Handles both the new schema (core/avatar/privacy/location/profile_bio)
+    and the legacy field layout.
+    """
+    if not result:
+        return None
+    if result.get("__typename") == "UserWithVisibilityResults" and result.get("user"):
+        result = result["user"]
+    legacy = result.get("legacy") or {}
+    core = result.get("core") or {}
+    username = core.get("screen_name") or legacy.get("screen_name")
+    if not result.get("rest_id") or not username:
+        return None
+
+    website: Optional[str] = None
+    for u in ((legacy.get("entities") or {}).get("url") or {}).get("urls") or []:
+        if u.get("expanded_url"):
+            website = u["expanded_url"]
+            break
+    if not website:
+        website = legacy.get("url")
+
+    verification = result.get("verification") or {}
+    verification_info = result.get("verification_info") or {}
+    verified_since: Optional[str] = None
+    msec = (verification_info.get("reason") or {}).get("verified_since_msec")
+    try:
+        if msec is not None:
+            verified_since = datetime.fromtimestamp(
+                int(msec) / 1000, tz=timezone.utc
+            ).isoformat()
+    except (TypeError, ValueError, OSError, OverflowError):
+        verified_since = None
+
+    privacy = result.get("privacy") or {}
+    is_protected = privacy.get("protected")
+    if is_protected is None:
+        is_protected = legacy.get("protected")
+
+    professional = result.get("professional") or {}
+    categories = professional.get("category") or []
+    professional_category = next(
+        (c.get("name") for c in categories if c.get("name")), None
+    )
+
+    profile = UserProfile(
+        id=result["rest_id"],
+        username=username,
+        name=core.get("name") or legacy.get("name") or username,
+        description=(result.get("profile_bio") or {}).get("description")
+        or legacy.get("description"),
+        location=(result.get("location") or {}).get("location") or legacy.get("location"),
+        website=website,
+        created_at=core.get("created_at") or legacy.get("created_at"),
+        followers_count=legacy.get("followers_count"),
+        following_count=legacy.get("friends_count"),
+        tweet_count=legacy.get("statuses_count"),
+        media_count=legacy.get("media_count"),
+        listed_count=legacy.get("listed_count"),
+        likes_count=legacy.get("favourites_count"),
+        is_blue_verified=result.get("is_blue_verified"),
+        is_verified=verification.get("verified"),
+        verified_type=verification.get("verified_type"),
+        is_identity_verified=verification_info.get("is_identity_verified"),
+        verified_since=verified_since,
+        profile_image_url=_extract_user_avatar(result),
+        profile_banner_url=legacy.get("profile_banner_url"),
+        is_protected=is_protected,
+        can_dm=(result.get("dm_permissions") or {}).get("can_dm"),
+        pinned_tweet_ids=legacy.get("pinned_tweet_ids_str") or None,
+        professional_type=professional.get("professional_type"),
+        professional_category=professional_category,
+    )
+    if include_raw:
+        profile._raw = result
+    return profile
+
+
 def parse_users_from_instructions(instructions: Optional[list]) -> list[User]:
     users: list[User] = []
     for instruction in instructions or []: