Node 客户端

同一批 HTTP 接口之上的一层轻薄、带类型的封装。它做的事用 fetch 都能做；它只是省下你重写错误类、重试和格式协商的功夫。

安装

npm install @xcrapcc/sdk

或者，用你实际在用的：

pnpm add @xcrapcc/sdk
yarn add @xcrapcc/sdk
bun add @xcrapcc/sdk

环境要求 · Node 18 或更高版本。无运行时依赖——使用内置的 fetch。

永远不需要密钥

没有要注册的东西，没有要塞进环境变量的东西，也没有谁不小心提交上去之后要轮换的东西。
一路都有类型

每个方法、每种响应形状都有完整声明，字段名写错是一条红波浪线，而不是运行时的意外。
内建 markdown

一个选项就能把任何响应变成可直接用于提示词的 markdown，并附上它会占用多少上下文的估算。

两行代码拿到一条帖子

没有密钥要传，也没有客户端要配置。构造出来直接调用。

import { Xcrap } from '@xcrapcc/sdk';

const xcrap = new Xcrap();

const tweet = await xcrap.tweet('https://x.com/jack/status/20');
console.log(tweet.text);               // just setting up my twttr
console.log(tweet.metrics.likes);      // 308067

Markdown，附带 token 成本

每个读取方法都接受一个 markdown 选项。响应会以可直接放进提示词的字符串返回，客户端同时记录这段字符串大概要花多少 token，好让你在花掉之前先核对预算。

// Markdown, ready to drop into a prompt.
const md = await xcrap.tweet('https://x.com/jack/status/20', { markdown: true });

// How many tokens that will cost, before you spend them.
console.log(xcrap.lastMeta.markdownTokens);

长贴与时间线

长贴会展开并按顺序返回，从第一条而不是最后一条开始。时间线通过游标自动翻页，你不必自己保存它们。

const thread = await xcrap.thread(
  'https://x.com/naval/status/1002103360646823936',
);

console.log(thread.count);                      // 31
for (const post of thread.tweets) console.log(post.text);

搜索，支持 X 自己的运算符

按你在 X 里输入的样子传入查询，运算符照写。返回一页结果和下一页的游标。搜索是所有方法中额度最紧的，一个精确的查询胜过五个宽泛的查询。

const page = await xcrap.search('from:nasa mars', {
  feed: 'latest',          // or 'top', 'photos', 'videos'
  since: '2026-01-01',
});

for (const post of page.tweets) console.log(post.author.screen_name, post.text);

// The next page, when there is one.
if (page.next_cursor) await xcrap.search('from:nasa mars', { cursor: page.next_cursor });

错误是类型，不是状态码

每一种失败都是一个可以按名字捕获的类。404 表示帖子被删或不公开，429 带着距离窗口重置还有多少秒，而网络故障和拒绝是可以区分开的。

import { Xcrap, XcrapNotFound, XcrapRateLimited } from '@xcrapcc/sdk';

try {
  await xcrap.tweet('https://x.com/jack/status/1');
} catch (error) {
  if (error instanceof XcrapNotFound) return null;
  if (error instanceof XcrapRateLimited) {
    // The client already knows when the window resets.
    await sleep(error.retryAfter * 1000);
  }
  throw error;
}

全部方法

它们都接受 format 和 markdown 选项，返回的形状也和 HTTP API 完全一致。

tweet(url, opts?): 一条帖子，完整解析：正文、作者、数据、媒体、投票，以及被引用的帖子。
thread(url, opts?): 从长贴中的任意一条出发，按发布顺序展开整个长贴。
search(query, opts?): 匹配查询的帖子——最新、热门、图片或视频——可限定日期范围。
replies(url, opts?): 某条帖子的一页直接回复，按最多点赞或最新排序。
user(handle, opts?): 一份主页：简介、各项计数、注册时间、认证、位置和网站。
userTweets(handle, opts?): 某个账号的一页帖子，附带下一页的游标。
userHistory(handle, opts?): 一次调用获取某账号最多一千条帖子，从新到旧，可限定日期范围。
followers(handle, opts?): 关注某个账号的一页账号。
following(handle, opts?): 某个账号所关注的一页账号。
trends(opts?): 正在流行的内容，X 给出数量时一并带上。
media(url, opts?): 所有附件，涵盖 X 编码出的每一档码率，以直链形式给出。
downloadMedia(url, opts?): 把其中一个文件以字节流返回，而不是给一个链接。
bulk(urls, opts?): 一次请求最多五十条帖子。失效链接只会让它自己那一条失败。

每一个参数，都在 API 参考里另外还有一个 Python 客户端。