@antcoder/birdxtwittercli 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+# Changelog
+
+## 0.8.0 — 2026-01-19
+
+### Added
+- `bookmarks` thread expansion controls (`--expand-root-only`, `--author-chain`, `--author-only`, `--full-chain-only`, `--include-ancestor-branches`, `--include-parent`, `--thread-meta`, `--sort-chronological`) for richer context exports (#55) — thanks @kkretschmer2.
+- `--chrome-profile-dir` to point at Chromium profile directories or cookie DB files (Arc/Brave/etc) for cookie extraction (#16) — thanks @tekumara.
+- `about` command to report account origin/location metadata (#51) — thanks @pjtf93.
+- `follow`/`unfollow` commands to manage follows (#54) — thanks @citizenlee.
+- Twitter client now supports like/unlike/retweet/unretweet/bookmark via the engagement mixin (#53) — thanks @the-vampiire.
+
+### Fixed
+- `bookmarks` expanded JSON now preserves pagination `nextCursor`, and full-chain filtering only includes ancestor branches when requested.
+- Follow/unfollow REST fallback now supports cursor pagination for followers/following (#54).
+- About account live coverage now verifies data extraction paths (#51) — thanks @pjtf93.
+
+### Tests
+- Live tests now exercise engagement mutations (opt-in) (#53) — thanks @the-vampiire.
+
+## 0.7.0 — 2026-01-12
+
+### Added
+- `home` command for the "For You" and "Following" home timelines (#31) — thanks @odysseus0.
+- `news`/`trending` command for Explore tabs with AI-curated headlines (#39) — thanks @aavetis.
+- `user-tweets` command to fetch a user's profile timeline (#34) — thanks @crcatala.
+- `replies` and `thread` now support pagination (`--all`, `--max-pages`, `--cursor`, `--delay`) (#35) — thanks @crcatala.
+- `search` now supports pagination (`--all`, `--max-pages`, `--cursor`) (#42) — thanks @pjtf93.
+- `likes` now supports pagination (`--all`, `--max-pages`, `--cursor`) (#44) — thanks @jsholmes.
+- `list-timeline` now supports pagination (`--all`, `--max-pages`, `--cursor`) (#30) — thanks @zheli.
+- Rich text output now shows article previews, quoted tweets, and media links (#32) — thanks @odysseus0.
+- Long-form article tweets now render rich Draft.js content blocks/entities (#36) — thanks @crcatala.
+
+### Changed
+- Library typing: `SearchResult` is now a discriminated union (so `error` only exists when `success: false`).
+
+### Fixed
+- Lists GraphQL feature flags updated to prevent 400s (#27) — thanks @zheli.
+- Lists feature overrides now scope new GraphQL flags correctly (#50) — thanks @ryanh-ai.
+- Tweet detail parsing now tolerates partial GraphQL errors when usable data exists (#48) — thanks @jsholmes.
+- News output now respects `--tweets-per-item`, keeps unique IDs, and parses non-add entry instructions (#39) — thanks @aavetis.
+- Following/followers pagination now guards repeat cursors and standardizes JSON output (#28) — thanks @malpern.
+- Likes pagination now follows cursors and avoids stalling on duplicate pages (#12) — thanks @titouv.
+- macOS cookie extraction now supports Brave keychain storage (#40) — thanks @gakonst.
+- Terminal hyperlinks now sanitize control characters before emitting OSC 8 sequences (#29) — thanks @mafulafunk.
+- `pnpm run build:dist` now succeeds after tightening JSON/pagination option typing in tweet output commands.
+
+### Tests
+- Following: split following/likes tests + cover cursor handling (#33) — thanks @VACInc.
+
+## 0.6.0 — 2026-01-05
+
+### Added
+- Bookmark exports now support pagination (`--all`, `--max-pages`) with retries (#15) — thanks @Nano1337.
+- `lists` + `list-timeline` commands for Twitter Lists (#21) — thanks @harperreed
+- Tweet JSON output now includes media items (photos, videos, GIFs) (#14) — thanks @Hormold
+- Bookmarks can resume pagination from a cursor (#26) — thanks @leonho
+- `unbookmark` command to remove bookmarked tweets (#22) — thanks @mbelinky.
+
+### Changed
+- Feature flags can be overridden at runtime via `features.json` (refreshable via `query-ids`).
+
+### Fixed
+- GraphQL feature flags now include `post_ctas_fetch_enabled` to avoid 400s (#38) — thanks @philipp-spiess.
+
+## 0.5.1 — 2026-01-01
+
+### Changed
+- `bird --help` now includes explicit “Shortcuts” and “JSON Output” sections (documents `bird <tweet-id-or-url>` shorthand + `--json`).
+- Release docs now include explicit npm publish verification steps.
+
+### Fixed
+- `pnpm bird --help` now works (dev script runs the CLI entrypoint, not the library entrypoint).
+- `following`/`followers` now fall back to internal v1.1 REST endpoints when GraphQL returns `404`.
+
+### Tests
+- Add root help output regression test.
+- Add opt-in live CLI test suite (real GraphQL calls; skipped by default; gated via `BIRD_LIVE=1`).
+
+## 0.5.0 — 2026-01-01
+
+### Added
+- `likes` command to list your liked tweets (thanks @swairshah).
+- Quoted tweet data in JSON output + `--quote-depth` (thanks @alexknowshtml).
+- `following`/`followers` commands to list users (thanks @lockmeister).
+
+### Changed
+- Query ID updater now tracks the Likes GraphQL operation.
+- Query ID updater now tracks Following/Followers GraphQL operations.
+- Query ID updater now tracks BookmarkFolderTimeline and keeps bookmark query IDs seeded.
+- `following`/`followers` JSON user fields are now camelCase (`followersCount`, `followingCount`, `isBlueVerified`, `profileImageUrl`, `createdAt`).
+- Cookie extraction timeout is now configurable (default 30s on macOS) via `--cookie-timeout` / `BIRD_COOKIE_TIMEOUT_MS` (thanks @tylerseymour).
+- Search now paginates beyond 20 results when using `-n` (thanks @ryanh-ai).
+- Library exports are now separated from the CLI entrypoint for easier embedding.
+
+## 0.4.1 — 2025-12-31
+
+### Added
+- `bookmarks` command to list your bookmarked tweets.
+- `bookmarks --folder-id` to fetch bookmark folders (thanks @tylerseymour).
+
+### Changed
+- Cookie extraction now uses `@steipete/sweet-cookie` (drops `sqlite3` CLI + custom browser readers in `bird`).
+- Query ID updater now tracks the Bookmarks GraphQL operation.
+- Lint rules stricter (block statements, no-negation-else, useConst/useTemplate, top-level regex, import extension enforcement).
+- `pnpm lint` now runs both Biome and oxlint (type-aware).
+
+### Tests
+- Coverage thresholds raised to 90% statements/lines/functions (80% branches).
+- Added targeted Twitter client coverage suites.
+
+## 0.4.0 — 2025-12-26
+
+### Added
+- Cookie source selection: `--cookie-source safari|chrome|firefox` (repeatable) + `cookieSource` config (string or array).
+
+### Fixed
+- `tweet`/`reply`: fallback to `statuses/update.json` when GraphQL `CreateTweet` returns error 226 (“automated request”).
+
+### Breaking
+- Remove `allowSafari`/`allowChrome`/`allowFirefox` config toggles in favor of `cookieSource` ordering.
+
+## 0.3.0 — 2025-12-26
+
+### Added
+- Safari cookie extraction (`Cookies.binarycookies`) + `allowSafari` config toggle.
+
+### Changed
+- Removed the Sweetistics engine + fallback. `bird` is GraphQL-only.
+- Browser cookie fallback order: Safari → Chrome → Firefox.
+
+### Tests
+- Enforce coverage thresholds (>= 70% statements/branches/functions/lines) + expand unit coverage for version/output/Twitter client branches.
+
+## 0.2.0 — 2025-12-26
+
+### Added
+- Output controls: `--plain`, `--no-emoji`, `--no-color` (respects `NO_COLOR`).
+- `help` command: `bird help <command>`.
+- Runtime GraphQL query ID refresh: `bird query-ids --fresh` (cached on disk; auto-retry on 404; override cache via `BIRD_QUERY_IDS_CACHE`).
+- GraphQL media uploads via `--media` (up to 4 images/GIFs, or 1 video).
+
+### Fixed
+- CLI `--version`: read version from `package.json`/`VERSION` (no hardcoded string) + append git sha when available.
+
+### Changed
+- `mentions`: no hardcoded user; defaults to authenticated user or accepts `--user @handle`.
+- GraphQL query ID updater: correctly pairs `operationName` ↔ `queryId` (CreateTweet/CreateRetweet/etc).
+- `build:dist`: copies `src/lib/query-ids.json` into `dist/lib/query-ids.json` (keeps `dist/` in sync).
+- `--engine graphql`: strict GraphQL-only (disables Sweetistics fallback).
+
+## 0.1.1 — 2025-12-26
+
+### Changed
+- Engine default now `auto` (GraphQL primary; Sweetistics only on fallback when configured).
+
+### Tests
+- Add engine resolution tests for auto/default behavior.
+
+### Fixed
+- GraphQL read: rotate TweetDetail query IDs with fallback to avoid 404s.
+
+## 0.1.0 — 2025-12-20
+
+### Added
+- CLI commands: `tweet`, `reply`, `read`, `replies`, `thread`, `search`, `mentions`, `whoami`, `check`.
+- URL/ID shorthand for `read`, plus `--json` output where supported.
+- GraphQL engine with cookie auth from Firefox/Chrome/env/flags (macOS browsers).
+- Sweetistics engine (API key) with automatic fallback when configured.
+- Media uploads via Sweetistics with per-item alt text (images or single video).
+- Long-form Notes and Articles extraction for full text output.
+- Thread + reply fetching with full conversation parsing.
+- Search + mentions via GraphQL (latest timeline).
+- JSON5 config files (`~/.config/bird/config.json5`, `./.birdrc.json5`) with engine defaults, profiles, allowChrome/allowFirefox, and timeoutMs.
+- Request timeouts (`--timeout`, `timeoutMs`) for GraphQL and Sweetistics calls.
+- Bun-compiled standalone binary via `pnpm run build`.
+- Query ID refresh helper: `pnpm run graphql:update`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# bird 🐦 — fast X CLI for tweeting, replying, and reading
+
+`bird` is a fast X CLI for tweeting, replying, and reading via X/Twitter GraphQL (cookie auth).
+
+## Disclaimer
+
+This project uses X/Twitter’s **undocumented** web GraphQL API (and cookie auth). X can change endpoints, query IDs,
+and anti-bot behavior at any time — **expect this to break without notice**.
+
+**Strong recommendation: Do not use bird to tweet. You will hit blocks very quickly. Use it to read tweets.
+Bots are not welcome on X/Twitter. If you absolutely have to, use browser automation instead, or pay for the Twitter API to create tweets.**
+
+## Install
+
+```bash
+npm install -g @antcoder/birdxtwittercli
+# or
+pnpm add -g @antcoder/birdxtwittercli
+# or
+bun add -g @antcoder/birdxtwittercli
+
+# one-shot (no install)
+bunx @antcoder/birdxtwittercli whoami
+```
+
+Homebrew (macOS, prebuilt Bun binary):
+
+```bash
+# brew install coming soon
+```
+
+## Quickstart
+
+```bash
+# Show the logged-in account
+bird whoami
+
+# Discover command help
+bird help whoami
+
+# Read a tweet (URL or ID)
+bird read https://x.com/user/status/1234567890123456789
+bird 1234567890123456789 --json
+
+# Thread + replies
+bird thread https://x.com/user/status/1234567890123456789
+bird replies 1234567890123456789
+bird replies 1234567890123456789 --max-pages 3 --json
+bird thread 1234567890123456789 --max-pages 3 --json
+
+# Search + mentions
+bird search "from:steipete" -n 5
+bird mentions -n 5
+bird mentions --user @steipete -n 5
+
+# User tweets (profile timeline)
+bird user-tweets @steipete -n 20
+bird user-tweets @steipete -n 50 --json
+
+# Bookmarks
+bird bookmarks -n 5
+bird bookmarks --folder-id 123456789123456789 -n 5 # https://x.com/i/bookmarks/<folder-id>
+bird bookmarks --all --json
+bird bookmarks --all --max-pages 2 --json
+bird bookmarks --include-parent --json
+bird unbookmark 1234567890123456789
+bird unbookmark https://x.com/user/status/1234567890123456789
+
+# Likes
+bird likes -n 5
+
+# News and trending topics (AI-curated from Explore tabs)
+bird news --ai-only -n 10
+bird news --sports -n 5
+
+# Lists
+bird list-timeline 1234567890 -n 20
+bird list-timeline https://x.com/i/lists/1234567890 --all --json
+bird list-timeline 1234567890 --max-pages 3 --json
+
+# Following (who you follow)
+bird following -n 20
+bird following --user 12345678 -n 10  # by user ID
+
+# Followers (who follows you)
+bird followers -n 20
+bird followers --user 12345678 -n 10  # by user ID
+
+# Refresh GraphQL query IDs cache (no rebuild)
+bird query-ids --fresh
+```
+
+## News & Trending
+
+Fetch AI-curated news and trending topics from X's Explore page tabs:
+
+```bash
+# Fetch 10 news items from all tabs (default: For You, News, Sports, Entertainment)
+bird news -n 10
+
+# Fetch only AI-curated news (filters out regular trends)
+bird news --ai-only -n 20
+
+# Fetch from specific tabs
+bird news --news-only --ai-only -n 10
+bird news --sports -n 15
+bird news --entertainment --ai-only -n 5
+
+# Include related tweets for each news item
+bird news --with-tweets --tweets-per-item 3 -n 10
+
+# Combine multiple tab filters
+bird news --sports --entertainment -n 20
+
+# JSON output
+bird news --json -n 5
+bird news --json-full --ai-only -n 10  # includes raw API response
+```
+
+Tab options (can be combined):
+- `--for-you` — Fetch from For You tab only
+- `--news-only` — Fetch from News tab only
+- `--sports` — Fetch from Sports tab only
+- `--entertainment` — Fetch from Entertainment tab only
+- `--trending-only` — Fetch from Trending tab only
+
+By default, the command fetches from For You, News, Sports, and Entertainment tabs (Trending excluded to reduce noise). Headlines are automatically deduplicated across tabs.
+
+## Library
+
+`bird` can be used as a library (same GraphQL client as the CLI):
+
+```ts
+import { TwitterClient, resolveCredentials } from '@antcoder/birdxtwittercli';
+
+const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
+const client = new TwitterClient({ cookies });
+
+// Search for tweets
+const searchResult = await client.search('from:steipete', 50);
+
+// Fetch news and trending topics from all tabs (default: For You, News, Sports, Entertainment)
+const newsResult = await client.getNews(10, { aiOnly: true });
+
+// Fetch from specific tabs with related tweets
+const sportsNews = await client.getNews(10, {
+  aiOnly: true,
+  withTweets: true,
+  tabs: ['sports', 'entertainment']
+});
+```
+
+Account details (About profile):
+
+```ts
+const aboutResult = await client.getUserAboutAccount('antcoder');
+if (aboutResult.success && aboutResult.aboutProfile) {
+  console.log(aboutResult.aboutProfile.accountBasedIn);
+}
+```
+
+Fields:
+- `accountBasedIn`
+- `source`
+- `createdCountryAccurate`
+- `locationAccurate`
+- `learnMoreUrl`
+
+## Commands
+
+- `bird tweet "<text>"` — post a new tweet.
+- `bird reply <tweet-id-or-url> "<text>"` — reply to a tweet using its ID or URL.
+- `bird help [command]` — show help (or help for a subcommand).
+- `bird query-ids [--fresh] [--json]` — inspect or refresh cached GraphQL query IDs.
+- `bird home [-n count] [--following] [--json] [--json-full]` — fetch your home timeline (For You) or Following feed.
+- `bird read <tweet-id-or-url> [--json]` — fetch tweet content as text or JSON.
+- `bird <tweet-id-or-url> [--json]` — shorthand for `read` when only a URL or ID is provided.
+- `bird replies <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]` — list replies to a tweet.
+- `bird thread <tweet-id-or-url> [--all] [--max-pages n] [--cursor string] [--delay ms] [--json]` — show the full conversation thread.
+- `bird search "<query>" [-n count] [--all] [--max-pages n] [--cursor string] [--json]` — search for tweets matching a query; `--max-pages` requires `--all` or `--cursor`.
+- `bird mentions [-n count] [--user @handle] [--json]` — find tweets mentioning a user (defaults to the authenticated user).
+- `bird user-tweets <@handle> [-n count] [--cursor string] [--max-pages n] [--delay ms] [--json]` — get tweets from a user's profile timeline.
+- `bird bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor string] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--json]` — list your bookmarked tweets (or a specific bookmark folder); expansion flags control thread context; `--max-pages` requires `--all` or `--cursor`.
+- `bird unbookmark <tweet-id-or-url...>` — remove one or more bookmarks by tweet ID or URL.
+- `bird likes [-n count] [--all] [--max-pages n] [--cursor string] [--json] [--json-full]` — list your liked tweets; `--max-pages` requires `--all` or `--cursor`.
+- `bird news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json]` — fetch news and trending topics from X's Explore tabs.
+- `bird trending` — alias for `news` command.
+- `bird lists [--member-of] [-n count] [--json]` — list your lists (owned or memberships).
+- `bird list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor string] [--json]` — get tweets from a list timeline; `--max-pages` implies `--all`.
+- `bird following [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]` — list users that you (or another user) follow; `--max-pages` requires `--all`.
+- `bird followers [--user <userId>] [-n count] [--cursor string] [--all] [--max-pages n] [--json]` — list users that follow you (or another user); `--max-pages` requires `--all`.
+- `bird about <@handle> [--json]` — get account origin and location information for a user.
+- `bird whoami` — print which Twitter account your cookies belong to.
+- `bird check` — show which credentials are available and where they were sourced from.
+
+Bookmarks flags:
+- `--expand-root-only`: expand threads only when the bookmark is a root tweet.
+- `--author-chain`: keep only the bookmarked author's connected self-reply chain.
+- `--author-only`: include all tweets from the bookmarked author within the thread.
+- `--full-chain-only`: keep the entire reply chain connected to the bookmarked tweet (all authors).
+- `--include-ancestor-branches`: include sibling branches for ancestors when using `--full-chain-only`.
+- `--include-parent`: include the direct parent tweet for non-root bookmarks.
+- `--thread-meta`: add thread metadata fields to each tweet.
+- `--sort-chronological`: sort output globally oldest to newest (default preserves bookmark order).
+
+Global options:
+- `--auth-token <token>`: set the `auth_token` cookie manually.
+- `--ct0 <token>`: set the `ct0` cookie manually.
+- `--cookie-source <safari|chrome|firefox>`: choose browser cookie source (repeatable; order matters).
+- `--chrome-profile <name>`: Chrome profile name for cookie extraction (e.g., `Default`, `Profile 2`).
+- `--chrome-profile-dir <path>`: Chrome/Chromium profile directory or cookie DB path for cookie extraction.
+- `--firefox-profile <name>`: Firefox profile for cookie extraction.
+- `--cookie-timeout <ms>`: cookie extraction timeout for keychain/OS helpers (milliseconds).
+- `--timeout <ms>`: abort requests after the given timeout (milliseconds).
+- `--quote-depth <n>`: max quoted tweet depth in JSON output (default: 1; 0 disables).
+- `--plain`: stable output (no emoji, no color).
+- `--no-emoji`: disable emoji output.
+- `--no-color`: disable ANSI colors (or set `NO_COLOR=1`).
+- `--media <path>`: attach media file (repeatable, up to 4 images or 1 video).
+- `--alt <text>`: alt text for the corresponding `--media` (repeatable).
+
+## Authentication (GraphQL)
+
+GraphQL mode uses your existing X/Twitter web session (no password prompt). It sends requests to internal
+X endpoints and authenticates via cookies (`auth_token`, `ct0`).
+
+Write operations:
+- `tweet`/`reply` primarily use GraphQL (`CreateTweet`).
+- If GraphQL returns error `226` (“automated request”), `bird` falls back to the legacy `statuses/update.json` endpoint.
+
+`bird` resolves credentials in this order:
+
+1. CLI flags: `--auth-token`, `--ct0`
+2. Environment variables: `AUTH_TOKEN`, `CT0` (fallback: `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`)
+3. Browser cookies via `@steipete/sweet-cookie` (override via `--cookie-source` order)
+
+Browser cookie sources:
+- Safari: `~/Library/Cookies/Cookies.binarycookies` (fallback: `~/Library/Containers/com.apple.Safari/Data/Library/Cookies/Cookies.binarycookies`)
+- Chrome: `~/Library/Application Support/Google/Chrome/<Profile>/Cookies`
+- Firefox: `~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite`
+  - For Chromium variants (Arc/Brave/etc), pass a profile directory or cookie DB via `--chrome-profile-dir`.
+
+## Config (JSON5)
+
+Config precedence: CLI flags > env vars > project config > global config.
+
+- Global: `~/.config/bird/config.json5`
+- Project: `./.birdrc.json5`
+
+Example `~/.config/bird/config.json5`:
+
+```json5
+{
+  // Cookie source order for browser extraction (string or array)
+  cookieSource: ["firefox", "safari"],
+  chromeProfileDir: "/path/to/Chromium/Profile",
+  firefoxProfile: "default-release",
+  cookieTimeoutMs: 30000,
+  timeoutMs: 20000,
+  quoteDepth: 1
+}
+```
+
+Environment shortcuts:
+- `BIRD_TIMEOUT_MS`
+- `BIRD_COOKIE_TIMEOUT_MS`
+- `BIRD_QUOTE_DEPTH`
+
+## Output
+
+- `--json` prints raw tweet objects for read/replies/thread/search/mentions/user-tweets/bookmarks/likes.
+- When using `--json` with pagination (`--all`, `--cursor`, `--max-pages`, or for `user-tweets` when `-n > 20`), output is `{ tweets, nextCursor }`.
+- `read` returns full text for Notes and Articles when present.
+- Use `--plain` for stable, script-friendly output (no emoji, no color).
+
+### JSON Schema
+
+When using `--json`, tweet objects include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Tweet ID |
+| `text` | string | Full tweet text (includes Note/Article content when present) |
+| `author` | object | `{ username, name }` |
+| `authorId` | string? | Author's user ID |
+| `createdAt` | string | Timestamp |
+| `replyCount` | number | Number of replies |
+| `retweetCount` | number | Number of retweets |
+| `likeCount` | number | Number of likes |
+| `conversationId` | string | Thread conversation ID |
+| `inReplyToStatusId` | string? | Parent tweet ID (present if this is a reply) |
+| `quotedTweet` | object? | Embedded quote tweet (same schema; depth controlled by `--quote-depth`) |
+
+When using `--json` with `following`/`followers`, user objects include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | User ID |
+| `username` | string | Username/handle |
+| `name` | string | Display name |
+| `description` | string? | User bio |
+| `followersCount` | number? | Followers count |
+| `followingCount` | number? | Following count |
+| `isBlueVerified` | boolean? | Blue verified flag |
+ | `profileImageUrl` | string? | Profile image URL |
+ | `createdAt` | string? | Account creation timestamp |
+
+When using `--json` with `news`/`trending`, news objects include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier for the news item |
+| `headline` | string | News headline or trend title |
+| `category` | string? | Category (e.g., "AI · Technology", "Trending", "News") |
+| `timeAgo` | string? | Relative time (e.g., "2h ago") |
+| `postCount` | number? | Number of posts |
+| `description` | string? | Item description |
+| `url` | string? | URL to the trend or news article |
+| `tweets` | array? | Related tweets (only when `--with-tweets` is used) |
+| `_raw` | object? | Raw API response (only when `--json-full` is used) |
+
+
+## Query IDs (GraphQL)
+
+X rotates GraphQL “query IDs” frequently. Each GraphQL operation is addressed as:
+
+- `operationName` (e.g. `TweetDetail`, `CreateTweet`)
+- `queryId` (rotating ID baked into X’s web client bundles)
+
+`bird` ships with a baseline mapping in `src/lib/query-ids.json` (copied into `dist/` on build). At runtime,
+it can refresh that mapping by scraping X’s public web client bundles and caching the result on disk.
+
+Runtime cache:
+- Default path: `~/.config/bird/query-ids-cache.json`
+- Override path: `BIRD_QUERY_IDS_CACHE=/path/to/file.json`
+- TTL: 24h (stale cache is still used, but marked “not fresh”)
+
+Auto-recovery:
+- On GraphQL `404` (query ID invalid), `bird` forces a refresh once and retries.
+- For `TweetDetail`/`SearchTimeline`, `bird` also rotates through a small set of known fallback IDs to reduce
+  breakage while refreshing.
+
+Refresh on demand:
+
+```bash
+bird query-ids --fresh
+```
+
+Exit codes:
+- `0`: success
+- `1`: runtime error (network/auth/etc)
+- `2`: invalid usage/validation (e.g. bad `--user` handle)
+
+## Version
+
+`bird --version` prints `package.json` version plus current git sha when available, e.g. `0.3.0 (3df7969b)`.
+
+## Media uploads
+
+- Attach media with `--media` (repeatable) and optional `--alt` per item.
+- Up to 4 images/GIFs, or 1 video (no mixing). Supported: jpg, jpeg, png, webp, gif, mp4, mov.
+- Images/GIFs + 1 video supported (uploads via Twitter legacy upload endpoint + cookies; video may take longer to process).
+
+Example:
+
+```bash
+bird tweet "hi" --media img.png --alt "desc"
+```
+
+## Development
+
+```bash
+cd ~/Projects/bird
+pnpm install
+pnpm run build       # dist/ + bun binary
+pnpm run build:dist  # dist/ only
+pnpm run build:binary
+
+pnpm run dev tweet "Test"
+pnpm run dev -- --plain check
+pnpm test
+pnpm run lint
+```
+
+## Notes
+
+- GraphQL uses internal X endpoints and can be rate limited (429).
+- Query IDs rotate; refresh at runtime with `bird query-ids --fresh` (or update the baked baseline via `pnpm run graphql:update`).

package/dist/cli/pagination.d.ts

@@ -0,0 +1,35 @@
+export type PaginationCmdOpts = {
+    all?: boolean;
+    maxPages?: string;
+    cursor?: string;
+    delay?: string;
+};
+export declare function parsePositiveIntFlag(raw: string | undefined, flagName: string): {
+    ok: true;
+    value: number | undefined;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseNonNegativeIntFlag(raw: string | undefined, flagName: string, defaultValue: number): {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parsePaginationFlags(cmdOpts: PaginationCmdOpts, opts?: {
+    maxPagesImpliesPagination?: boolean;
+    defaultDelayMs?: number;
+    includeDelay?: boolean;
+}): {
+    ok: true;
+    usePagination: boolean;
+    maxPages?: number;
+    cursor?: string;
+    pageDelayMs?: number;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/cli/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/cli/pagination.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,GACf;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CASxE;AAED,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAM5D;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,iBAAiB,EAC1B,IAAI,CAAC,EAAE;IACL,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAEC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA8B/B"}

package/dist/cli/pagination.js

@@ -0,0 +1,43 @@
+export function parsePositiveIntFlag(raw, flagName) {
+    if (raw === undefined) {
+        return { ok: true, value: undefined };
+    }
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        return { ok: false, error: `Invalid ${flagName}. Expected a positive integer.` };
+    }
+    return { ok: true, value };
+}
+export function parseNonNegativeIntFlag(raw, flagName, defaultValue) {
+    const value = Number.parseInt(raw ?? String(defaultValue), 10);
+    if (!Number.isFinite(value) || value < 0) {
+        return { ok: false, error: `Invalid ${flagName}. Expected a non-negative integer.` };
+    }
+    return { ok: true, value };
+}
+export function parsePaginationFlags(cmdOpts, opts) {
+    const maxPagesImpliesPagination = opts?.maxPagesImpliesPagination ?? false;
+    const includeDelay = opts?.includeDelay ?? false;
+    const defaultDelayMs = opts?.defaultDelayMs ?? 1000;
+    const maxPages = parsePositiveIntFlag(cmdOpts.maxPages, '--max-pages');
+    if (!maxPages.ok) {
+        return maxPages;
+    }
+    const usePagination = Boolean(cmdOpts.all || cmdOpts.cursor || (maxPagesImpliesPagination && maxPages.value !== undefined));
+    let pageDelayMs;
+    if (includeDelay) {
+        const delay = parseNonNegativeIntFlag(cmdOpts.delay, '--delay', defaultDelayMs);
+        if (!delay.ok) {
+            return delay;
+        }
+        pageDelayMs = delay.value;
+    }
+    return {
+        ok: true,
+        usePagination,
+        maxPages: maxPages.value,
+        cursor: cmdOpts.cursor,
+        pageDelayMs,
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/cli/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/cli/pagination.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,oBAAoB,CAClC,GAAuB,EACvB,QAAgB;IAEhB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC1C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,QAAQ,gCAAgC,EAAE,CAAC;IACnF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,GAAuB,EACvB,QAAgB,EAChB,YAAoB;IAEpB,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,QAAQ,oCAAoC,EAAE,CAAC;IACvF,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,OAA0B,EAC1B,IAIC;IAUD,MAAM,yBAAyB,GAAG,IAAI,EAAE,yBAAyB,IAAI,KAAK,CAAC;IAC3E,MAAM,YAAY,GAAG,IAAI,EAAE,YAAY,IAAI,KAAK,CAAC;IACjD,MAAM,cAAc,GAAG,IAAI,EAAE,cAAc,IAAI,IAAI,CAAC;IAEpD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACvE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAC3B,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,yBAAyB,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAC7F,CAAC;IAEF,IAAI,WAA+B,CAAC;IACpC,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,uBAAuB,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAChF,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC;QACf,CAAC;QACD,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,aAAa;QACb,QAAQ,EAAE,QAAQ,CAAC,KAAK;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/cli/program.d.ts

@@ -0,0 +1,5 @@
+import { Command } from 'commander';
+import { type CliContext } from './shared.js';
+export declare const KNOWN_COMMANDS: Set<string>;
+export declare function createProgram(ctx: CliContext): Command;
+//# sourceMappingURL=program.d.ts.map