# @belvador/api 中文文档

规范地址：https://npmcn.com/package/%40belvador/api/

版本：0\.8\.7
npm 元数据更新时间：2026-10-30T10:08:47.452Z
中文译文更新时间：2026-11-07T21:45:22.394Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40belvador/api
原文对照：https://npmcn.com/package/%40belvador/api/?lang=original
项目主页：https://belvador.dev/docs/reference/api

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

- 包体积（解压后）：280 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.10
- 运行依赖：0 个
- 首次发布：2026-10-26T19:48:27.721Z
- 最新版本发布：2026-10-30T10:08:47.214Z
- 近 30 天下载量：3644（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

为Belvador API(api.belvador.dev,OpenAPI 3.1)打出客户端: 每一次操作通过操作Id, problem+json出错,重试,节点直接从边缘读取有短寿命票.

## 安装

```sh
npm install @belvador/api
```

也可以使用：`pnpm add @belvador/api`、`yarn add @belvador/api`、`bun add @belvador/api`

## README

# @belvador/ api (英语)

输入客户端 [贝尔瓦多](https://belvador.dev/docs/reference/api) (单位:千美元)`https://api.belvador.dev`, OpenAPI 3.1 (中文(简体) ). 每个操作都被它的 OpenAPI 调用 `operationId` 包含 API 线名中的参数( snake case); 操作表和参数类型来自与 OpenAPI 文档相同的登记册.

```sh
npm install @belvador/api
```

```ts
import { BelvadorApiError, createClient } from "@belvador/api";

const belvador = createClient({ token: process.env.BELVADOR_TOKEN! });

const { data } = await belvador.call("issues.list", { status: "unresolved", period: "24h", limit: 20 });

for await (const rows of belvador.pages("monitors.list", { limit: 100 })) console.log(rows.length);

try {
  await belvador.call(
    "monitors.create",
    {
      project_id: 1,
      slug: "nightly-backup",
      name: "Nightly backup",
      kind: "crontab",
      schedule: { type: "crontab", value: "0 2 * * *" },
      timezone: "UTC",
      checkin_margin_min: 5,
      max_runtime_min: 30,
      failure_threshold: 1,
      recovery_threshold: 1,
      expected_environments: ["production"],
    },
    { idempotencyKey: crypto.randomUUID() },
  );
} catch (e) {
  if (e instanceof BelvadorApiError && e.code === "API_SCOPE_INSUFFICIENT") console.log("needs", e.scope);
}
```

-   **键**: 个人纪念物(`blv_pat_`),服务代号(`blv_svc_`)或 OAuth 访问符 (`blv_oat_`) (中文(简体) ). 在设置 ~ API 令牌中创建一个 。 客户端从不将符号放入出错消息中.
-   **错误** 是 RFC 9457 问题+json,表面为 `BelvadorApiError` 拥有稳定 `code`, (中文(简体) ), `status`, (中文(简体) ), `scope` (计: `API_SCOPE_INSUFFICIENT`, (中文(简体) ), `retryAfter` 财务报告和审定财务报表 `requestId`。 。 。 .
-   **核准**: 敏感操作(钥匙、成员、信使、提醒目的地、节点更改) `APPROVAL_REQUIRED` 与 `e.approval` =: `{ id, url, expiresAt, state }`。一个人打开 `url` 打开 belvador.dev 并用其验证码批准; 以相同的密码再次呼叫 `idempotencyKey` (或 `call("approvals.get", { approval_id })`)读出结果. 仅限 https `/approve/<id>` 链接被保留.
-   **检索**:读取,写出 `idempotencyKey`,在429 / 502–504和网络上重审 错误 (`retries`,默认值 2), 荣誉 `Retry-After` 最高为10 s. `NODE_OFFLINE` 未重审.
-   **范围**数字 : `await belvador.scopes()` 返回符号的有效范围( `Belvador-Scopes` 头曰.
-   **节点数据** (问题,事件,跨度,痕迹,日志) 活在工作空间自己的节点上. 与 `nodeReads: "edge"` 客户端询问 `POST /v1/tickets` 一张短命的读票和读票 `edge.belvador.dev` 直接, 因此数据不会通过 API 网关; 它会掉回网关 当信使不能持有票时.

## 命令行

`belvador-api privacy pull` 写一个项目的隐私政策, 如 JSON Belvador SDKs 所接受 (单位:千美元)`privacyPolicy()`, SDK 0.6.0+),所以一个建筑可以运送相同的规则 你的节点适用:

```sh
BELVADOR_TOKEN=blv_svc_… npx -p @belvador/api belvador-api privacy pull --project 42 --out belvador-privacy.json
```

`--project` 是工程的编号(它的 DSN 结束) 。 代币需要 `projects:read`; 读取 仅来自 `BELVADOR_TOKEN` 从不印刷。 退出代码: 0 写入, 1 被 API 拒绝(代码为 打印),2个用法错误.

节点20.10 Bun、Deno和现代浏览器(任何运行时间) `fetch` 财务报告和审定财务报表 `AbortSignal.any`麻省理工学院有执照.

## 常见问题

### @belvador/api 是什么？

为Belvador API\(api\.belvador\.dev,OpenAPI 3\.1\)打出客户端: 每一次操作通过操作Id, problem\+json出错,重试,节点直接从边缘读取有短寿命票\.

### 如何安装 @belvador/api？

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

### @belvador/api 支持 TypeScript 吗？

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

### @belvador/api 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

### @belvador/api 可以商用吗？

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

### @belvador/api 的下载量有多少？

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

### @belvador/api 还在维护吗？

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