x-reader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,206 @@
+# x-reader
+
+[![npm version](https://img.shields.io/npm/v/x-reader)](https://www.npmjs.com/package/x-reader)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+
+**Read-only Twitter/X CLI** for searching tweets, reading timelines, bookmarks, and replies from the terminal. Inspired by [Bird CLI](https://github.com/steipete/bird).
+
+> Uses your own X/Twitter cookies. One user, one account. No API keys required.
+
+## Features
+
+- **Search** tweets by keyword or advanced query (`from:`, `to:`, `filter:`, etc.)
+- **Read** a user's timeline
+- **Read** a single tweet by ID or URL
+- **Read** replies to any tweet
+- **Read** your bookmarks (with `--all` for full export)
+- **Look up** user profiles by handle
+- **JSON output** for piping into other tools (`jq`, scripts, etc.)
+- **Auto-discovers** X's rotating GraphQL query IDs (no manual updates needed)
+- **Zero config** beyond two browser cookies
+
+## Why x-reader?
+
+- No Twitter API keys or developer account needed
+- Read-only by design (no accidental tweets, likes, or follows)
+- Works with X's current GraphQL endpoints
+- Lightweight: single dependency (Commander)
+- Scriptable: JSON output for automation and data pipelines
+
+## Install
+
+### From npm (recommended)
+
+```bash
+npm install -g x-reader
+```
+
+### From source
+
+```bash
+git clone https://github.com/DjinnFoundry/x-reader.git
+cd x-reader
+npm install
+npm run build
+npm link
+```
+
+## Quick start
+
+```bash
+# 1. Set up authentication (interactive)
+x-reader setup
+
+# 2. Search tweets
+x-reader search "machine learning"
+
+# 3. Read a user's timeline
+x-reader user-tweets @naval -n 10
+
+# 4. Export your bookmarks as JSON
+x-reader bookmarks --all --format json > bookmarks.json
+```
+
+## Authentication
+
+You need two cookies from x.com: `auth_token` and `ct0`.
+
+### Option 1: Interactive setup
+```bash
+x-reader setup
+```
+
+### Option 2: Environment variables
+```bash
+export AUTH_TOKEN="your_auth_token"
+export CT0="your_ct0"
+```
+
+### Option 3: CLI flags
+```bash
+x-reader search "query" --auth-token xxx --ct0 yyy
+```
+
+### Where to find your cookies
+1. Go to [x.com](https://x.com) and log in
+2. Open DevTools (F12) -> Application -> Cookies -> x.com
+3. Copy `auth_token` and `ct0` values
+
+Config is saved to `~/.config/x-reader/config.json`.
+
+## Usage
+
+### Search tweets
+```bash
+x-reader search "machine learning"
+x-reader search "from:elonmusk" -n 5
+x-reader search "AI safety" --format json
+```
+
+### Read a user's timeline
+```bash
+x-reader user-tweets @steipete
+x-reader user-tweets elonmusk -n 10
+x-reader user-tweets @naval --format json
+```
+
+### Read a single tweet
+```bash
+x-reader read 1234567890
+x-reader read https://x.com/user/status/1234567890
+x-reader read https://x.com/user/status/1234567890 --format json
+```
+
+### Read replies
+```bash
+x-reader replies 1234567890
+x-reader replies https://x.com/user/status/1234567890 --format json
+```
+
+### Export bookmarks
+```bash
+x-reader bookmarks
+x-reader bookmarks -n 50
+x-reader bookmarks --all --format json
+```
+
+### User lookup
+```bash
+x-reader user-lookup @steipete
+x-reader user-lookup naval --format json
+```
+
+### Query ID management
+```bash
+# Show cached query IDs
+x-reader query-ids
+
+# Force refresh from x.com (when IDs rotate)
+x-reader query-ids --refresh
+```
+
+## Output formats
+
+- **text** (default) - human-readable
+- **json** - machine-readable, pipe to `jq` or save to file
+
+```bash
+# Pipe to jq
+x-reader search "typescript" --format json | jq '.tweets[].text'
+
+# Save to file
+x-reader bookmarks --all --format json > my-bookmarks.json
+```
+
+## Programmatic use
+
+```typescript
+import { XReaderClient } from 'x-reader';
+
+const client = new XReaderClient({
+  cookies: { authToken: '...', ct0: '...' },
+});
+
+const result = await client.search('hello world', 10);
+console.log(result.tweets);
+```
+
+## How it works
+
+X uses GraphQL endpoints with rotating query IDs embedded in their client-side JavaScript bundles. x-reader auto-discovers these IDs by scraping the JS bundles, caching them locally with a 24-hour TTL. No manual ID updates needed.
+
+If you get 404 errors, force a refresh:
+```bash
+x-reader query-ids --refresh
+```
+
+## Architecture
+
+```
+src/
+├── api/
+│   ├── client.ts      # Main API client (read-only operations)
+│   ├── constants.ts   # Bearer token, URLs, default query IDs
+│   ├── features.ts    # GraphQL feature flags per operation
+│   ├── parser.ts      # Response parsing (raw JSON -> Tweet/User)
+│   ├── query-ids.ts   # Auto-discovery of query IDs from x.com JS
+│   └── types.ts       # TypeScript interfaces
+├── cli/
+│   └── index.ts       # CLI entry point (commander)
+├── utils/
+│   ├── auth.ts        # Cookie resolution (env, config, bird compat)
+│   └── format.ts      # Output formatting
+└── index.ts           # Library exports
+```
+
+## Credits
+
+- Inspired by [Bird CLI](https://github.com/steipete/bird) by [@steipete](https://x.com/steipete)
+- Uses the same public bearer token as the X web client
+- Query ID discovery mechanism reverse-engineered from Bird v0.8.0
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * XReader API Client — Read-only Twitter/X GraphQL client.
+ *
+ * Provides: search, user-tweets, tweet-detail, replies, bookmarks, user-lookup.
+ * Does NOT provide any write operations (tweet, like, retweet, follow, etc.)
+ */
+import type { ClientOptions, TweetsResult, TweetResult, UserResult } from './types.js';
+export declare class XReaderClient {
+    private authToken;
+    private ct0;
+    private cookieHeader;
+    private userAgent;
+    private timeoutMs?;
+    private quoteDepth;
+    private clientUuid;
+    constructor(options: ClientOptions);
+    private getHeaders;
+    private fetchWithTimeout;
+    private sleep;
+    private getQueryIds;
+    /**
+     * Try a request with multiple query IDs, auto-refresh on 404.
+     */
+    private tryWithQueryIds;
+    search(query: string, count?: number, options?: {
+        cursor?: string;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    getTweet(tweetId: string, options?: {
+        includeRaw?: boolean;
+    }): Promise<TweetResult>;
+    getReplies(tweetId: string, options?: {
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    getUserTweets(userId: string, count?: number, options?: {
+        cursor?: string;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    getBookmarks(count?: number, options?: {
+        cursor?: string;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    getUserByUsername(username: string): Promise<UserResult>;
+    /**
+     * Search with automatic pagination to collect up to `count` tweets.
+     */
+    searchAll(query: string, count: number, options?: {
+        maxPages?: number;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    /**
+     * Get user tweets with pagination.
+     */
+    getUserTweetsAll(userId: string, count: number, options?: {
+        maxPages?: number;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+    /**
+     * Get all bookmarks with pagination.
+     */
+    getBookmarksAll(count?: number, options?: {
+        maxPages?: number;
+        includeRaw?: boolean;
+    }): Promise<TweetsResult>;
+}