# @vxil/sdk 中文文档

规范地址：https://npmcn.com/package/%40vxil/sdk/

版本：0\.35\.2
npm 元数据更新时间：2026-11-02T20:13:26.420Z
中文译文更新时间：2026-11-02T20:57:27.728Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40vxil/sdk
原文对照：https://npmcn.com/package/%40vxil/sdk/?lang=original
项目主页：https://vxil.com/

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

- 包体积（解压后）：663 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- 首次发布：2026-07-10T00:21:09.636Z
- 最新版本发布：2026-11-02T20:13:26.222Z
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

vvxil REST API的类型客户端（通知、授权、工作、文件、cms、评论、webhook、实时、组织、速率限制）。

## 安装

```sh
npm install @vxil/sdk
```

也可以使用：`pnpm add @vxil/sdk`、`yarn add @vxil/sdk`、`bun add @vxil/sdk`

## README

# @vxil / sdk

的类型化JavaScript/TypeScript客户端 [Vxil](https://vxil.com/) REST API -后端构建块（auth, cms，文件，支付集成，通知，作业，实时，矢量搜索，AI等）在一行中启用。

```bash
npm install @vxil/sdk
```

```ts
import { Vxil } from '@vxil/sdk';

const vx = new Vxil({ apiKey: process.env.VXIL_API_KEY! });

await vx.users.upsert({ id: 'u_1', email: 'ada@example.com' });
await vx.notifications.send({ user_id: 'u_1', template: 'welcome', data: { app_name: 'MyApp' } });
const { items } = await vx.from('tasks').query({ filter: { status: 'open' } });
```

-   零依赖关系。运行在任何地方 `fetch` 存在：节点≥22，浏览器，边缘运行时间，和 **React Native / Expo** （Hermes） - SDK不使用任何WHATWG `URL` / `URLSearchParams` surface React Native只提供了部分功能。
-   默认为 `https://api.vxil.com`;通过 `baseUrl` 瞄准另一个环境。
-   租户启用的每个特性都可以作为类型化命名空间使用；生成与项目精确相关的客户端 `npx @vxil/cli gen`.
-   每个非2xx响应都会抛出一个 `VxilError` 携带结构化错误信封(`status`， `code`， `message`， `hint`， `fixUrl`， `requestId`, `retryAfter` 服务器发送时的秒数 `Retry-After`）。

## 服务器模式和最终用户模式

一、 **服务器密钥** 是一个秘密：把它放在服务器路由处理程序中，永远不要把它放在浏览器或应用包中。要从浏览器或电话中直接调用Vxil，请使用 **瘦客户机关键** ( `end_user_required` 类-它拒绝任何没有有效的终端用户会话的请求)以及登录用户的会话令牌：

```ts
const vx = new Vxil({
  apiKey: PUBLIC_VXIL_KEY,        // thin-client key: reads + owner-scoped writes only
  endUserToken: session.token,    // from vx.auth.signIn / your sign-in flow
});
// reads and writes on owner-scoped resources are confined to this user
const { items } = await vx.from('meals').query({ limit: 20 });
```

`vx.asEndUser(token)` 返回另一个会话的客户端，并继承其他所有内容；SDK中没有任何东西缓存令牌。

## 重试、超时和请求挂钩

这三个都是 **默认关闭** -如果没有设置，客户端是单一的 `fetch` 每个电话，和以前一样。

```ts
const vx = new Vxil({
  apiKey,
  timeoutMs: 10_000,                 // per attempt; aborts the request AND its body read
  retry: { attempts: 2 },            // up to 3 requests in total
  hooks: {
    beforeRequest: (req) => ({ 'x-request-id': crypto.randomUUID() }),
    afterResponse: ({ request, response, durationMs }) => log(request.method, request.url, response.status, durationMs),
    onRetry: ({ request, delayMs, status, error }) => log('retry', request.url, delayMs, status ?? error),
  },
});
```

| 选项 | 默认的 | 意义 |
| --- | --- | --- |
| `retry.attempts` | `0` (关闭) | 第一次尝试后重试。 |
| `retry.retryOn` | `[429, 502, 503, 504]` | 触发重试的响应状态。 |
| `retry.backoffMs` | `250` | 首先延迟;每次重试双倍，有抖动 `[½, 1]` 计算出的延迟。 |
| `retry.maxBackoffMs` | `10_000` | 两次尝试之间的最长等待时间。一个 `Retry-After` 超过它结束循环，而不是等待。 |
| `retry.respectRetryAfter` | `true` | 使用响应的 `Retry-After` （秒或HTTP-date）作为存在时的延迟。 |
| `retry.retryOnNetworkError` | `true` | 在以下情况下重试 `fetch` 本身失败(DNS，重置，a `timeoutMs` 超时)。 |
| `timeoutMs` | 无 | 每次尝试超时 `AbortController`； 抛出 `VxilError` `{ status: 0, code: 'request_timeout' }`. |
| `hooks.beforeRequest` | \- - - - - - | 在每一次尝试之前奔跑；可能为该尝试返回要添加的标头。 |
| `hooks.afterResponse` | \- - - - - - | 在每个响应（重试或最终）之后运行，包含响应及其持续时间。 |
| `hooks.onRetry` | \- - - - - - | 在客户端休眠以进行重试之前运行。 |

确保重试安全的规则：

-   **只有幂等请求才会被重试**： `GET`， `HEAD`， `PUT`， `DELETE`，和 `POST` 只有当调用带有 `Idempotency-Key` ( `{ idempotencyKey }` 选择金钱路线- `payments.credits.consume`， `notifications.send`,……)。一个光秃秃的 `POST` 或者一个 `PATCH` 永远不会重试 `retry` 说。
-   钩子接收 **冻** 请求描述符(`method`， `url`， `headers`， `attempt`)，它从不包含凭证头，并且它们也不能设置它们；用 `vx.asEndUser(token)`.
-   抛出钩子中止调用。钩子看到的响应体已经被读取；检查 `status` 和 `headers`.

## 错误

```ts
import { VxilError } from '@vxil/sdk';

try {
  await vx.payments.credits.consume({ user_id, credit_type: 'tokens', amount: 5 }, { idempotencyKey });
} catch (e) {
  if (e instanceof VxilError && e.status === 429) {
    showToast(`Try again in ${Math.ceil(e.retryAfter ?? 30)}s`);
  }
}
```

## 更新日志

### 0.4.1 - 2026-09-13

-   仅支持文档：JSDoc不再引用内部存储库路径；转而指向公共导游。没有运行时更改。

### 0.4.0 - 2026-09-11

-   React-Native-clean：每个查询字符串构建时都没有 `URLSearchParams` (React Native的polyfill启动 `.set` 之前0.81);连线字节不变。
-   `VxilError.retryAfter` （秒）解析自 `Retry-After`.
-   可选 `retry`， `timeoutMs` 和 `hooks` 客户端的选项（见上文）。没有行为改变，除非设置。

### 0.3.0

-   代理内环波：结构化输出，使用， `@vxil/react` 同伴。

文档: [vxil.com/docs/guide](https://vxil.com/docs/guide) ·仪表板: [vxil.com/dashboard](https://vxil.com/dashboard) ·条件: [vxil.com/terms](https://vxil.com/terms)

MIT©techmaker.io

## 常见问题

### @vxil/sdk 是什么？

vvxil REST API的类型客户端（通知、授权、工作、文件、cms、评论、webhook、实时、组织、速率限制）。

### 如何安装 @vxil/sdk？

在项目目录运行 npm install @vxil/sdk，或使用 pnpm add / yarn add / bun add。

### @vxil/sdk 支持 TypeScript 吗？

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

### @vxil/sdk 支持 ESM 还是 CommonJS？

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

### @vxil/sdk 需要什么版本的 Node\.js？

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

### @vxil/sdk 可以商用吗？

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

### @vxil/sdk 还在维护吗？

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