# @fetcher-sh/api 中文文档

规范地址：https://npmcn.com/package/%40fetcher-sh/api/

版本：1\.0\.1
npm 元数据更新时间：2026-08-14T13:36:41.774Z
中文译文更新时间：2026-11-14T15:08:16.829Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40fetcher-sh/api
原文对照：https://npmcn.com/package/%40fetcher-sh/api/?lang=original
项目主页：https://fetcher.sh/
源码仓库：https://github.com/fetcher-sh/npm-fetcher-sh

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：497 kB，49 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-08-14T13:36:40.970Z
- 最新版本发布：2026-08-14T13:36:41.343Z
- 近 30 天下载量：7945（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

Fearer.sh的开发者友好客户端——111个付费的网络数据端点横跨Twitter/X,YouTube,TikTok,Instagram,Reddit,Google,App Store,和Yelp. 用作国家防范机制图书馆或CLI.

## 安装

```sh
npm install @fetcher-sh/api
```

也可以使用：`pnpm add @fetcher-sh/api`、`yarn add @fetcher-sh/api`、`bun add @fetcher-sh/api`

## README

# @ fetcher-sh/ api (英语)

开发者友好客户端 [**获取器.sh**](https://fetcher.sh/) —— 说 **111个网上数据终端点** 横跨Twitter/X,YouTube,TikTok,Instagram,Reddit,Google搜索,Google地图,Google新闻,Google Play,App Store,和Yelp. 将其作为国家预防机制 **图书馆** 或一个 **国 际**。 。 。 .

每个终点都是平地 `GET` 返回一个稳定 `{ status, message, data }` 信封上写着 以美元支付 [x402 (韩语)](https://fetcher.sh/),或将所有11项服务中的单项预付余额——相同 `bby_live_` 关键在任何地方都有作用.

## 先决条件

-   **节点.js 18+** (使用内置) `fetch`) (中文(简体) ).
-   **其中一个:**
    -   预付 **API 密钥** (单位:千美元)`bby_live_...`)——得到一个在 [获取器.sh/上架](https://fetcher.sh/topup),或
    -   A 类 **钱包** 在Base、Polygon、Arbitrum、Monad或Solana上持有几分USDC,以支付每笔拨打的x402(不需要钥匙).

## 安装

```bash
npm install @fetcher-sh/api
```

## 快速启动( 图书馆)

```ts
// ESM
import { Fetcher } from "@fetcher-sh/api";

// CommonJS
const { Fetcher } = require("@fetcher-sh/api");

const fetcher = new Fetcher({ apiKey: process.env.FETCHER_API_KEY });

// Search tweets
const tweets = await fetcher.twitter.search({ query: "x402" });

// Look up an Instagram profile by handle
const profile = await fetcher.instagram.userByHandle("nasa");

// Clean Google web-search results
const serp = await fetcher.google.search({ query: "climate change" });

console.log(tweets, profile, serp);
```

默认情况下,每种方法只返回 `data` 字段。 过 `{ fullResponse: true }` 来得到整个 `{ status, message, data }` 信封上写着.

```ts
const env = await fetcher.reddit.searchPosts(
  { query: "bitcoin" },
  { fullResponse: true },
);
console.log(env.status, env.message, env.data);
```

如果 `apiKey` 被省略,它会回到 `FETCHER_API_KEY` 环境变量.

## 服务和方法

一个余额,11个服务。 每个命名空间地图1:1到 [实时目录](https://fetcher.sh/llms.txt)。 。 。 .

| 命名空间 | 通过 | 要点 |
| --- | --- | --- |
| 推特/ X 页面存档备份,存于互联网档案馆 | `fetcher.twitter` 编号 : `fetcher.x` | `search`, (中文(简体) ), `handle`, (中文(简体) ), `user`, (中文(简体) ), `userTweets`, (中文(简体) ), `userFollowers`, (中文(简体) ), `tweet`, (中文(简体) ), `tweetReplies`, (中文(简体) ), `trends`, (中文(简体) ), `listTweets` |
| YouTube (英语) | `fetcher.youtube` | `searchVideo`, (中文(简体) ), `video`, (中文(简体) ), `videoComments`, (中文(简体) ), `channel`, (中文(简体) ), `channelVideos`, (中文(简体) ), `trending`, (中文(简体) ), `playlistVideos` |
| 叮当 | `fetcher.tiktok` | `searchPosts`, (中文(简体) ), `postByUrl`, (中文(简体) ), `userByHandle`, (中文(简体) ), `userPosts`, (中文(简体) ), `hashtagPosts`, (中文(简体) ), `musicPosts` |
| 内存 | `fetcher.instagram` | `userByHandle`, (中文(简体) ), `user`, (中文(简体) ), `userPosts`, (中文(简体) ), `userReels`, (中文(简体) ), `userStories`, (中文(简体) ), `hashtagPosts`, (中文(简体) ), `postByCode` |
| 编辑 | `fetcher.reddit` | `searchPosts`, (中文(简体) ), `subredditPosts`, (中文(简体) ), `post`, (中文(简体) ), `postComments`, (中文(简体) ), `postsHot`, (中文(简体) ), `user`, (中文(简体) ), `userComments` |
| 谷歌搜索 | `fetcher.google` | `search` |
| 谷歌地图 | `fetcher.googleMaps` | `searchPlaces`, (中文(简体) ), `place`, (中文(简体) ), `placeReviews`, (中文(简体) ), `review` |
| 谷歌新闻 | `fetcher.googleNews` | `search`, (中文(简体) ), `latest`, (中文(简体) ), `world`, (中文(简体) ), `business`, (中文(简体) ), `technology`, (中文(简体) ), `topic`, (中文(简体) ), `decodeArticleUrl` |
| 谷歌播放 | `fetcher.googlePlay` | `searchApps`, (中文(简体) ), `app`, (中文(简体) ), `appReviews`, (中文(简体) ), `appPermissions`, (中文(简体) ), `appDataSafety`, (中文(简体) ), `developer` |
| 应用程序存储 | `fetcher.appStore` | `searchApps`, (中文(简体) ), `app`, (中文(简体) ), `appReviews`, (中文(简体) ), `appSimilar`, (中文(简体) ), `bundle`, (中文(简体) ), `developer` |
| 耶尔普 | `fetcher.yelp` | `search`, (中文(简体) ), `place`, (中文(简体) ), `placeByHandle`, (中文(简体) ), `placeReviews` |

### 普通出逃舱门

任何终点——即使没有指定助手的终点——都可以达到 `get`数字 :

```ts
await fetcher.get("/api/twitter/search", { params: { query: "x402" } });
await fetcher.get("/api/reddit/subreddit/programming/posts");
```

### 倾斜

贴出端点返回不透明 `cursor`。将它传回获取下一页:

```ts
let cursor: string | undefined;
do {
  const page = await fetcher.twitter.userFollowers("44196397", {
    fullResponse: true,
    params: { cursor },
  });
  // ...process page.data...
  cursor = (page.data as any)?.cursor;
} while (cursor);
```

## 用x402(无密钥)支付每个呼叫

跳过 API 密钥, 并通过一个 付款包 `fetch` 换句话说 客户端保持无依赖性——你带钱包:

```ts
import { Fetcher } from "@fetcher-sh/api";
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: ["eip155:8453", "eip155:137", "eip155:42161", "eip155:143"].map(
    (network) => ({ network, client: new ExactEvmScheme(account) }),
  ),
});

const fetcher = new Fetcher({ fetch: fetchWithPayment });
const tweets = await fetcher.twitter.search({ query: "x402" }); // 402 → sign → retry, automatically
```

气体是赞助的,因此钱包不需要本地的代币——只要USDC在任何被支持的链上.

## 贷项

```ts
// Read the shared balance (needs an API key)
const balance = await fetcher.credits.balance();
console.log(balance.balance_usd);

// Top up (x402-paid; requires a payment-wrapped fetch). The first top-up
// returns the bby_live_ key EXACTLY ONCE — store it, it cannot be recovered.
const result = await fetcher.credits.topup(5);
console.log(result.key);
```

## 处理错误

每个非-2xx响应都会发出一个 `FetcherError` 带有状态、解析后的信封和助手:

```ts
import { FetcherError } from "@fetcher-sh/api";

try {
  await fetcher.twitter.search({ query: "x402" });
} catch (err) {
  if (err instanceof FetcherError) {
    if (err.isTopupRequired) console.error("Out of credits — top up.");
    else if (err.isUnauthorized) console.error("Bad or rotated API key.");
    else if (err.isPaymentRequired) console.error("x402 payment required.");
    else console.error(err.status, err.message);
  }
}
```

## 国 际

从命令行安装到全球使用 :

```bash
npm install -g @fetcher-sh/api
```

### 设置

```bash
# Store your API key (saved to ~/.fetcher-sh/config.json)
fetcher init --token bby_live_xxx

# Or set it as an environment variable
export FETCHER_API_KEY=bby_live_xxx

# Or pass it per command
fetcher balance --token bby_live_xxx
```

### 图标

```bash
# Shortcuts for each service's hero endpoint
fetcher twitter-search "x402"
fetcher youtube-search "lofi hip hop"
fetcher tiktok-search "cats"
fetcher instagram-user nasa
fetcher reddit-search "bitcoin"
fetcher google-search "climate change"
fetcher google-maps-search "coffee near me"
fetcher google-news-search "artificial intelligence"
fetcher googleplay-apps "notes"
fetcher appstore-apps "notes"
fetcher yelp-search "coffee" --location "San Francisco"

# Call ANY endpoint by path; extra --flags become query params
fetcher get /api/twitter/user/44196397/tweets --cursor abc123
fetcher get /api/reddit/subreddit/programming/posts

# Credits
fetcher balance
fetcher topup --amount 5          # needs an x402 wallet — see notes

# Explore the catalog
fetcher services
fetcher endpoints twitter
```

### 输出选项

```bash
fetcher twitter-search "x402"              # pretty JSON (default)
fetcher twitter-search "x402" --json       # compact JSON
fetcher twitter-search "x402" --jsonl      # one object per line (arrays)
fetcher twitter-search "x402" --output out.json
fetcher get /api/x/y --debug               # show raw error bodies
```

### 全球旗帜

| 旗帜 | 说明 |
| --- | --- |
| `--token <key>` | API 密钥( E)`bby_live_...`; 覆盖 env 配置( c) |
| `--base-url <url>` | 覆盖 API 基础 URL |
| `--json` | 压缩 JSON 输出 |
| `--jsonl` | 每行1个JSON对象(仅限阵列) |
| `--output <file>` | 将输出写入文件 |
| `--<key> <value>` | 任何额外的查询参数(例如. `--cursor`, (中文(简体) ), `--location`(中文(简体) ) |

## API 参考

### `new Fetcher(options?)`

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | `FETCHER_API_KEY` 环境 | 预付信贷钥匙`bby_live_...`(中文(简体) ) |
| `baseUrl` | `string` | `https://fetcher.sh` | API 基础 URL |
| `fetch` | `FetchLike` | 全球 `fetch` | 自定义抓取( 如 x402 付款被包) |
| `timeout` | `number` | `30000` | 默认请求超时( ms) |
| `headers` | `object` | `{}` | 在每个请求中增加标题 |

### 请求选项( 每一次呼叫)

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `fullResponse` | `boolean` | 返回时 `{ status, message, data }` 而不是仅仅 `data` |
| `params` | `object` | 额外查询参数 |
| `timeout` | `number` | 请求超时( 以毫秒计) |
| `signal` | `AbortSignal` | 取消请求 |

### 静态

-   `Fetcher.endpoints()` ——111个出价终点的完整目录.
-   `Fetcher.services()` ——每个服务元数据(主机,计数,汇总).
-   `Fetcher.priceOf(path)` ——路径(支持的路径)的美元价格.

## 页:1

-   **设计时只读.** 每个终点都是 `GET` ——没有写作,后面写作,也没有文章.
-   **无利率限制.** 您的平衡( 或钱包) 是自然回压 .
-   **上游故障时不退.** 在交货前解决.
-   这个 **非正式** fearer.sh的客户端,它本身是一个独立的代理,与X,TikTok,Meta,Google,Yelp或Apple没有隶属关系.

## 许可证

麻省理工学院

## 常见问题

### @fetcher-sh/api 是什么？

Fearer\.sh的开发者友好客户端——111个付费的网络数据端点横跨Twitter/X,YouTube,TikTok,Instagram,Reddit,Google,App Store,和Yelp\. 用作国家防范机制图书馆或CLI\.

### 如何安装 @fetcher-sh/api？

在项目目录运行 npm install @fetcher-sh/api，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 fetcher，可以用 npx fetcher 直接运行。

### @fetcher-sh/api 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @fetcher-sh/api 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @fetcher-sh/api 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fetcher-sh/api 可以商用吗？

@fetcher-sh/api 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @fetcher-sh/api 的下载量有多少？

根据 npm 官方下载统计，@fetcher-sh/api 在 2026/10/15 – 2026/11/13 这 30 天内被下载 7,945 次，日均约 265 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @fetcher-sh/api 还在维护吗？

最新版本 1\.0\.1 发布于 2026/08/14（3 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/08/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。