@finch_ren/x-scraper 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Finch R
+
+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

@@ -1,17 +1,129 @@
 # x-scraper
 
-`x-scraper` 是一个面向 X/Twitter 内部 GraphQL 接口的 TypeScript SDK。  
-重点是让常见场景开箱即用，同时保持类型清晰、便于扩展。
+English | [简体中文](./README.zh-CN.md)
 
-## 特性
+`x-scraper` is a TypeScript SDK for X/Twitter internal GraphQL endpoints.
+It focuses on practical, ready-to-run usage while keeping strong OpenAPI-generated types.
 
-- 自动 Guest Token 初始化（无需手动配置 token）
-- 支持 Cookie 登录态客户端
-- 面向常用场景提供开箱即用调用入口（用户、推文、互动等）
+## Features
 
-## 快速开始
+- Automatic guest token initialization
+- Cookie-authenticated client support
+- Practical high-level APIs for common user/tweet/interaction flows
 
-### Guest 模式
+## Installation
+
+<details open>
+<summary><strong>npm</strong></summary>
+
+```bash
+npm install @finch_ren/x-scraper
+```
+
+</details>
+
+<details>
+<summary><strong>pnpm</strong></summary>
+
+```bash
+pnpm add @finch_ren/x-scraper
+```
+
+</details>
+
+<details>
+<summary><strong>yarn</strong></summary>
+
+```bash
+yarn add @finch_ren/x-scraper
+```
+
+</details>
+
+## Simple Call Example
+
+```ts
+import { XScraper } from '@finch_ren/x-scraper';
+
+async function main() {
+  const scraper = new XScraper();
+  const client = await scraper.getClientFromCookies({
+    __cf_bm: '<__cf_bm>',
+    __cuid: '<__cuid>',
+    _ga: '<_ga>',
+    _ga_BLY4P7T5KW: '<_ga_BLY4P7T5KW>',
+    _twitter_sess: '<_twitter_sess>',
+    auth_token: '<auth_token>',
+    ct0: '<ct0>',
+    guest_id: '<guest_id>',
+    guest_id_ads: '<guest_id_ads>',
+    guest_id_marketing: '<guest_id_marketing>',
+    kdt: '<kdt>',
+    lang: '<lang>',
+    personalization_id: '<personalization_id>',
+    twid: '<twid>',
+  });
+
+  const res = await client.getTweetDetail({
+    focalTweetId: '2018440335140024383',
+  });
+}
+
+main().catch(console.error);
+```
+
+<details open>
+<summary><strong>Example Response (JSON) (Display only, actual response may vary)</strong></summary>
+
+```json
+{
+  "raw": {
+    "instruction": [
+      { "type": "TimelineClearCache" },
+      { "type": "TimelineAddEntries", "entries": [/* ... */] },
+      { "type": "TimelineTerminateTimeline" }
+    ]
+  },
+  "cursor": {
+    "bottom": {
+      "typename": "TimelineTimelineCursor",
+      "cursorType": "Bottom",
+      "entryType": "TimelineTimelineCursor",
+      "value": "DAAKCgABHB6qs_W__pULAAIAAAGoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUNVY0F2UXhkOXN4dEJ3Qzl4Y3gyNkJ0SEFNbGdrOFhvU3djQXZHZ0hCZWhBeHdDODE5MVd1SGRIQUwzU3c4Ym9UMGNBdlkrcGhyeDBCd0M4VXJZMXFFZEhBTTJhdnlhTVVBY0F2Z24zSnN3TUJ3Qys2aFJHbEdvSEFOYjhqZmFrVjRjQXZtYzBadkF3UndDOE96NDJsRmtIQUwvWUxVV3NkY2NBeEM2dFJ0d1N4d0MrdFY4R3BFYUhBTDdySXNhMGNzY0F2REthRmR3UHh3REEwNnAydEFxSEFOSDA4eWFZV3NjQXhFN3I5c1JTaHdEQVpFSkc4RXFIQUwwNXpmYTBZd2NBdmJ6SHBxeFJod0M5V1BmVzREWkhBTUJ6b3ZhRVl3Y0F2R3Z0TmN4MGh3QzgzM0Myb0V0SEFMOGNBYmJzUDRjQTdxQm1ScUEyQndDK0Y1SzI4QnJIQUx5OFl5YkVaQWNBdjY5THRyeGJSd0RCQ24wVzBGdUhBTDR6TGJiRVBvY0F2UFZqRnRCVWc9PQgAAwAAAAILAAQAAAAGQm90dG9tAAA"
+    }
+  },
+  "data": [
+    {
+      "raw": { "typename": "Tweet", "restId": "2018440335140024383" },
+      "tweet": {
+        "id": "2018440335140024383",
+        "text": "SpaceX has acquired xAI, forming one of the most ambitious...",
+        "createdAt": "Mon Feb 02 21:44:11 +0000 2026",
+        "favoriteCount": 44183,
+        "retweetCount": 7746,
+        "replyCount": 3354
+      },
+      "user": {
+        "id": "34743251",
+        "name": "SpaceX",
+        "screenName": "SpaceX",
+        "followersCount": 41074731
+      }
+    },
+    {
+      "raw": { /* ... */ },
+      "tweet": { /* ... */ },
+      "user": { /* ... */ }
+    }
+  ]
+}
+```
+
+</details>
+
+## Quick Start
+
+### Guest mode
 
 ```ts
 import { XScraper } from '@finch_ren/x-scraper';
@@ -30,9 +142,9 @@ async function main() {
 main().catch(console.error);
 ```
 
-### Cookie 模式
+### Cookie mode
 
-方式 A：浏览器导出的 Cookie 数组
+A) Browser-exported cookie array
 
 ```ts
 import { XScraper } from '@finch_ren/x-scraper';
@@ -41,17 +153,8 @@ async function main() {
   const scraper = new XScraper();
 
   const client = await scraper.getClientFromCookies([
-    {
-      domain: '.x.com',
-      name: 'ct0',
-      value: '<csrf_token>',
-    },
-    {
-      domain: '.x.com',
-      name: 'auth_token',
-      value: '<auth_token>',
-    },
-    ...
+    { domain: '.x.com', name: 'ct0', value: '<csrf_token>' },
+    { domain: '.x.com', name: 'auth_token', value: '<auth_token>' },
   ]);
 
   const profile = await client.getUserByScreenName({ screenName: 'jack' });
@@ -61,7 +164,7 @@ async function main() {
 main().catch(console.error);
 ```
 
-方式 B：对象映射（`name -> value`）
+B) Cookie map (`name -> value`)
 
 ```ts
 import { XScraper } from '@finch_ren/x-scraper';
@@ -70,9 +173,20 @@ async function main() {
   const scraper = new XScraper();
 
   const client = await scraper.getClientFromCookies({
-    ct0: '<csrf_token>',
+    __cf_bm: '<__cf_bm>',
+    __cuid: '<__cuid>',
+    _ga: '<_ga>',
+    _ga_BLY4P7T5KW: '<_ga_BLY4P7T5KW>',
+    _twitter_sess: '<_twitter_sess>',
     auth_token: '<auth_token>',
-    ....
+    ct0: '<ct0>',
+    guest_id: '<guest_id>',
+    guest_id_ads: '<guest_id_ads>',
+    guest_id_marketing: '<guest_id_marketing>',
+    kdt: '<kdt>',
+    lang: '<lang>',
+    personalization_id: '<personalization_id>',
+    twid: '<twid>',
   });
 
   const profile = await client.getUserByScreenName({ screenName: 'jack' });
@@ -82,67 +196,35 @@ async function main() {
 main().catch(console.error);
 ```
 
-## 常用 API 入口
-
-同一能力通常有两种调用方式：
+## API Entry Styles
 
-- 顶层快捷方法：`client.getUserByScreenName(...)`
-- 分组方法：`client.user.getUserByScreenName(...)`
+Most APIs support both styles:
 
-### 两种写法对照（等价）
+- Flat shortcut: `client.getUserByScreenName(...)`
+- Grouped API: `client.user.getUserByScreenName(...)`
 
 ```ts
-// User
 const userA = await client.getUserByScreenName({ screenName: 'elonmusk' });
 const userB = await client.user.getUserByScreenName({ screenName: 'elonmusk' });
 
-// Tweet timeline
 const tweetsA = await client.getUserTweets({ userId: '44196397' });
 const tweetsB = await client.tweet.getUserTweets({ userId: '44196397' });
 
-// Post actions
 await client.createTweet({ tweetText: 'hello' });
 await client.post.postCreateTweet({ tweetText: 'hello' });
 ```
 
-### 顶层快捷方法（高频） 
+## Auth and Runtime Notes
 
-- `client.getUserByScreenName(...)`
-- `client.getUserTweets(...)`
-- `client.getTweetDetail(...)`
-- `client.createTweet(...)`
-- `client.deleteTweet(...)`
-- `client.likeTweet(...)`
-- `client.unlikeTweet(...)`
-- `client.retweet(...)`
-....
+### Cookie notes
 
-### 分组 API（完整入口）
+- You can use the `Cookie-Editor` browser extension to export cookies as JSON and pass it to `getClientFromCookies([...])`
+- Do not commit cookies to git
+- Use local files or environment variables for secret injection
 
-- `client.tweet`
-- `client.user`
-- `client.users`
-- `client.userList`
-- `client.post`
-- `client.space`
-- `client.v11Get`
-- `client.v11Post`
-- `client.v20Get`
-- `client.default`
-- `client.initialState`
-....
+### Header/platform mismatch
 
-## 认证与环境说明
-
-### 1) 关于 Cookie
-
-- 推荐从已登录浏览器导出 `ct0` / `auth_token`（可选 `gt`）。
-- `getClientFromCookies` 支持两种格式：对象映射或浏览器 cookie 数组。
-- 不要把 Cookie 写入仓库，建议走本地文件或环境变量注入。
-
-### 2) 平台 Header 一致性
-
-某些账号 Cookie 与 `sec-ch-ua-platform` 不一致时可能失败，可手动覆盖：
+If cookie origin and `sec-ch-ua-platform` mismatch, override header manually:
 
 ```ts
 import { XScraper } from '@finch_ren/x-scraper';
@@ -153,13 +235,13 @@ scraper.setAdditionalApiHeaders({
 });
 ```
 
-### 3) 风险与限制
+### Risk notice
 
-- 该库依赖 X 私有接口，接口字段和行为可能随时变化。
-- 登录态调用存在账号风控风险，请自行评估并使用低风险账号。
-- 可能触发动态限流，建议在业务侧做重试与退避（backoff）。
+- This SDK depends on private endpoints that may change without notice
+- Authenticated calls may trigger account risk controls
+- Add retry + backoff in production
 
-## 本地开发
+## Local Development
 
 ```bash
 pnpm install
@@ -167,48 +249,44 @@ pnpm build
 pnpm test
 ```
 
-## 重新生成 OpenAPI 代码
+## Regenerate OpenAPI Code
 
 ```bash
 pnpm generate
 ```
 
-## openapi/placeholder.json 说明
+## `openapi/placeholder.json`
 
-`openapi/placeholder.json` 是运行时使用的 GraphQL 操作模板表，不是普通示例文件。  
-SDK 会在请求时读取这里的配置来组装参数与请求上下文。
+`openapi/placeholder.json` is a runtime GraphQL operation template registry.
+It is used by the SDK to build request variables/features/fieldToggles and endpoint metadata.
 
-每个条目通常包含：
+Typical fields:
 
-- `@path`：接口路径（用于 transaction id 生成等）
-- `@method`：HTTP 方法（用于 transaction id 生成等）
-- `queryId`：GraphQL queryId
-- `variables`：默认变量模板（可被调用参数覆盖）
-- `features` / `fieldToggles`：默认开关参数
+- `@path`: endpoint path (used in transaction id generation)
+- `@method`: HTTP method (used in transaction id generation)
+- `queryId`: GraphQL query id
+- `variables`: default variable template
+- `features` / `fieldToggles`: default toggles
 
-代码关联关系：
+Code linkage:
 
-- `src/api.ts` 会加载该文件作为 `flagData`
-- `src/utils/api.ts#getKwargs` 会把 `variables/features/fieldToggles` 转成请求参数
-- 各 API utils（如 `client.tweet.*`、`client.user.*`、`client.space.*`）通过 `this.flag[...]` 取对应模板
+- `src/api.ts` loads it as `flagData`
+- `src/utils/api.ts#getKwargs` builds request params from templates
+- API groups (`client.tweet.*`, `client.user.*`, `client.space.*`) read templates via `this.flag[...]`
 
-注意：
+Notes:
 
-- `client.space.getAudioSpaceById` 与 `client.space.getBroadcastQuery` 依赖该文件条目
-- `client.getLiveVideoStreamStatus`（v1.1 接口）不依赖 `placeholder.json`
+- `client.space.getAudioSpaceById` and `client.space.getBroadcastQuery` depend on this file
+- `client.getLiveVideoStreamStatus` (v1.1 endpoint) does not depend on this file
 
-## 鸣谢
+## Acknowledgements
 
-本项目核心代码来源于：
+Core source is based on:
 
 - [fa0311/twitter-openapi-typescript](https://github.com/fa0311/twitter-openapi-typescript)
 
-在上游基础上，本项目做了工程整合与二次封装，包括：
-
-- 整合 `twitter-openapi` 相关生成内容到当前 SDK 结构
-- 提供更直接的调用入口与项目化组织方式
-
-另外补充了 Space 相关接口能力（`client.space`）：
+This project adds integration and higher-level SDK ergonomics on top of upstream,
+including additional Space APIs:
 
 - `getAudioSpaceById`
 - `getLiveVideoStreamStatus`