# @zavudev/sdk 中文文档

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

版本：0\.60\.2
npm 元数据更新时间：2026-11-02T22:36:40.945Z
中文译文更新时间：2026-11-03T01:13:25.359Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：3.4 MB，1226 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2025-12-02T18:05:35.657Z
- 最新版本发布：2026-11-02T22:36:40.552Z
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

Zavudev API的官方TypeScript库

## 安装

```sh
npm install @zavudev/sdk
```

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

## README

# Zavudev TypeScript API库

[![NPM version](https://img.shields.io/npm/v/@zavudev/sdk.svg?label=npm%20\(stable\))](https://npmjs.org/package/@zavudev/sdk) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zavudev/sdk)

这个库提供了从服务器端TypeScript或JavaScript访问Zavudev REST API的便利。

REST API文档可以在 [docs.zavu.dev](https://docs.zavu.dev/)。此库的每个方法和类型都在其资源的模块中 [`src/resources/`](https://npmcn.com/package/%40zavudev/sdk/src/resources).

它是由Zavu的OpenAPI规范生成的。

## MCP服务器

使用Zavudev MCP服务器使AI助手能够与此API交互，允许他们探索端点，发出测试请求，并使用文档来帮助将此SDK集成到您的应用程序中。

[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40zavudev%2Fsdk-mcp&config=eyJuYW1lIjoiQHphdnVkZXYvc2RrLW1jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJ1cmwiOiJodHRwczovL3phdnVkZXYuc3RsbWNwLmNvbSIsImhlYWRlcnMiOnsieC16YXZ1ZGV2LWFwaS1rZXkiOiJNeSBBUEkgS2V5In19) [![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40zavudev%2Fsdk-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fzavudev.stlmcp.com%22%2C%22headers%22%3A%7B%22x-zavudev-api-key%22%3A%22My%20API%20Key%22%7D%7D)

> 注意：您可能需要在MCP客户端中设置环境变量。

## 安装

```sh
npm install @zavudev/sdk
```

## 使用

每个方法和类型都在其资源的模块中 [`src/resources/`](https://npmcn.com/package/%40zavudev/sdk/src/resources).

```js
import Zavudev from '@zavudev/sdk';

const client = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const messageResponse = await client.messages.send({
  to: '+14155551234',
  text: 'Hello from Zavu!',
});

console.log(messageResponse.message);
```

### 请求和响应类型

这个库包含了所有请求参数和响应字段的TypeScript定义。您可以像这样导入和使用它们：

```ts
import Zavudev from '@zavudev/sdk';

const client = new Zavudev({
  apiKey: process.env['ZAVUDEV_API_KEY'], // This is the default and can be omitted
});

const params: Zavudev.MessageSendParams = { to: '+14155551234', text: 'Hello from Zavu!' };
const messageResponse: Zavudev.MessageResponse = await client.messages.send(params);
```

每个方法、请求参数和响应字段的文档都可以在文档字符串中找到，并且在大多数现代编辑器中会显示在悬停位置。

## API v2

[API v2](https://docs.zavu.dev/api-v2/overview) 在同一个客户端 `client.v2`。v2路径中的每个id都是一个位置参数，按路径顺序，和 V2的类型来自 `@zavudev/sdk/v2`：

```ts
import Zavudev from '@zavudev/sdk';
import type { MessageSendParams } from '@zavudev/sdk/v2';

const client = new Zavudev();

const params: MessageSendParams = { from: '+13125551212', to: '+56912345678', text: 'Hi' };
const { message } = await client.v2.messages.send(params);

await client.v2.channels.activate('+13125551212', 'whatsapp');
```

## 处理错误

当库无法连接到API时， 或者如果API返回非成功状态码（即4xx或5xx响应）， 的子类 `APIError` 将被抛出：

```ts
const messageResponse = await client.messages
  .send({ to: '+14155551234', text: 'Hello from Zavu!' })
  .catch(async (err) => {
    if (err instanceof Zavudev.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
```

错误码如下：

| 状态码 | 错误类型 |
| --- | --- |
| 400 | `BadRequestError` |
| 401 | `AuthenticationError` |
| 403 | `PermissionDeniedError` |
| 404 | `NotFoundError` |
| 422 | `UnprocessableEntityError` |
| 429 | `RateLimitError` |
| \> = 500 | `InternalServerError` |
| N/A | `APIConnectionError` |

### 重试

默认情况下，某些错误将自动重试2次，并有短暂的指数回退。 连接错误（例如，由于网络连接问题），408请求超时，409冲突， 429 Rate Limit和>=500默认情况下，所有内部错误都将重试。

你可以使用 `maxRetries` 选项配置或禁用此功能：

```js
// Configure the default for all requests:
const client = new Zavudev({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.messages.send({ to: '+14155551234', text: 'Hello from Zavu!' }, {
  maxRetries: 5,
});
```

### 超时

请求默认在1分钟后超时。您可以使用a进行配置 `timeout` 选择:

```ts
// Configure the default for all requests:
const client = new Zavudev({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.messages.send({ to: '+14155551234', text: 'Hello from Zavu!' }, {
  timeout: 5 * 1000,
});
```

超时时， `APIConnectionTimeoutError` 抛出。

请注意，请求将超时 [默认情况下重试两次](https://npmcn.com/package/%40zavudev/sdk/#readme-retries).

## Auto-pagination

Zavudev API中的列表方法是分页的。 你可以使用 `for await … of` 遍历所有页面项的语法：

```ts
async function fetchAllMessages(params) {
  const allMessages = [];
  // Automatically fetches more pages as needed.
  for await (const message of client.messages.list()) {
    allMessages.push(message);
  }
  return allMessages;
}
```

或者，您可以一次请求一个页面：

```ts
let page = await client.messages.list();
for (const message of page.items) {
  console.log(message);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}
```

## 高级用法

### 访问原始响应数据（例如，报头）

“生” `Response` 返回的 `fetch()` 可以通过 `.asResponse()` 方法上的 `APIPromise` 键入所有方法返回的类型。 此方法在接收到成功响应的标头后立即返回，并且不使用响应体，因此您可以自由编写自定义解析或流逻辑。

你也可以用 `.withResponse()` 获取原料的方法 `Response` 与已解析的数据一起。 不像 `.asResponse()` 此方法使用主体，并在解析后返回。

```ts
const client = new Zavudev();

const response = await client.messages
  .send({ to: '+14155551234', text: 'Hello from Zavu!' })
  .asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: messageResponse, response: raw } = await client.messages
  .send({ to: '+14155551234', text: 'Hello from Zavu!' })
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(messageResponse.message);
```

### 日志记录

> \[!重要的) 所有日志消息仅用于调试。日志消息的格式和内容 在不同版本之间可能会改变。

#### 日志级别

日志级别有两种配置方式：

1.  通过 `ZAVUDEV_LOG` 环境变量
2.  使用 `logLevel` 客户端选项（如果设置了，将覆盖环境变量）

```ts
import Zavudev from '@zavudev/sdk';

const client = new Zavudev({
  logLevel: 'debug', // Show all log messages
});
```

可用的日志级别，从最详细到最不详细：

-   `'debug'` —显示调试消息、信息、警告和错误
-   `'info'` —显示提示消息、警告和错误
-   `'warn'` -显示警告和错误（默认）
-   `'error'` -只显示错误
-   `'off'` -禁用所有日志记录

在 `'debug'` 在级别上，所有HTTP请求和响应都被记录下来，包括标头和正文。 一些与身份验证相关的标头被编校，但请求和响应体中的敏感数据被编校 可能仍然可见。

#### 自定义日志记录器

默认情况下，此库记录为 `globalThis.console`。您还可以提供自定义记录器。 支持大多数日志库，包括 [皮诺](https://www.npmjs.com/package/pino)， [温斯顿](https://www.npmjs.com/package/winston)， [班扬](https://www.npmjs.com/package/bunyan)， [consola](https://www.npmjs.com/package/consola)， [signale](https://www.npmjs.com/package/signale), [@std /日志](https://jsr.io/@std/log)。如果您的记录器不工作，请打开一个问题。

在提供自定义记录器时， `logLevel` 选项仍然控制发出哪些消息，消息 低于配置的级别将不会发送到您的记录器。

```ts
import Zavudev from '@zavudev/sdk';
import pino from 'pino';

const logger = pino();

const client = new Zavudev({
  logger: logger.child({ name: 'Zavudev' }),
  logLevel: 'debug', // Send all messages to pino, allowing it to filter
});
```

### 提出自定义/未记录的请求

这个库的类型是为了方便地访问文档化的API。如果您需要访问无证文件 端点、参数或响应属性，仍然可以使用库。

#### 非法的端点

要向未归档的端点发出请求，可以使用 `client.get`， `client.post`，以及其他HTTP动词。 在发出这些请求时，将尊重客户机上的选项，例如重试。

```ts
await client.post('/some/path', {
  body: { some_prop: 'foo' },
  query: { some_query_arg: 'bar' },
});
```

#### 未记录的请求参数

要使用未记录的参数发出请求，您可以使用 `// @ts-expect-error` 关于无证文件 参数。此库在运行时不会验证请求是否与类型匹配，因此任何额外的值都将被删除 Send将按原样发送。

```ts
client.messages.send({
  // ...
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});
```

如欲查询 `GET` 谓词，任何额外的参数将在查询中，所有其他请求将发送 主体中的额外参数。

如果您想显式地发送一个额外的参数，可以使用 `query`， `body`, `headers` 请求 选项。

#### 未记录的响应属性

要访问未记录的响应属性，您可以使用 `// @ts-expect-error` 在 或将响应对象强制转换为必需的类型。与请求参数一样，我们不这样做 验证或从API的响应中删除额外的属性。

### 自定义获取客户端

默认情况下，此库需要一个全局变量 `fetch` 函数定义。

如果你想用不同的 `fetch` 函数，您可以填充全局：

```ts
import fetch from 'my-fetch';

globalThis.fetch = fetch;
```

或者将其传递给客户端：

```ts
import Zavudev from '@zavudev/sdk';
import fetch from 'my-fetch';

const client = new Zavudev({ fetch });
```

### 获取选择

如果你想设置自定义 `fetch` 选项，而不覆盖 `fetch` 函数，您可以提供 `fetchOptions` 对象实例化客户端或发出请求时。（特定于请求的选项覆盖客户端选项。）

```ts
import Zavudev from '@zavudev/sdk';

const client = new Zavudev({
  fetchOptions: {
    // `RequestInit` options
  },
});
```

#### 配置代理

要修改代理行为，可以提供自定义 `fetchOptions` 添加特定于运行时的代理 请求选项：

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg) **节点** ［[文档](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)］

```ts
import Zavudev from '@zavudev/sdk';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new Zavudev({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});
```

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg) **包子** ［[文档](https://bun.sh/guides/http/proxy)］

```ts
import Zavudev from '@zavudev/sdk';

const client = new Zavudev({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});
```

![](https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg) **Deno** ［[文档](https://docs.deno.com/api/deno/~/Deno.createHttpClient)］

```ts
import Zavudev from 'npm:@zavudev/sdk';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new Zavudev({
  fetchOptions: {
    client: httpClient,
  },
});
```

## 常见问题

## 语义版本控制

这个包通常如下 [SemVer](https://semver.org/spec/v2.0.0.html) 约定，虽然某些向后不兼容的更改可能作为小版本发布：

1.  仅影响静态类型而不破坏运行时行为的更改。
2.  对库内部的更改，这些更改在技术上是公开的，但不打算或记录供外部使用。 _（请打开GitHub问题，让我们知道你是否依赖于这样的内部。）_
3.  我们不希望在实践中影响绝大多数用户的更改。

我们认真对待向后兼容性，并努力确保您可以依靠平滑的升级体验。

我们渴望得到您的反馈；请打开一个 [问题](https://www.github.com/zavudev/sdk-typescript/issues) 提出问题、bug或建议。

## 要求

支持TypeScript >= 4.9。

支持以下运行时：

-   网络浏览器（最新的Chrome， Firefox, Safari， Edge等）
-   Node.js 20 LTS或更高版本([non-EOL](https://endoflife.date/nodejs))版本。
-   Deno v1.28.0或更高版本。
-   Bun 1.0或更高版本。
-   Cloudflare的工人。
-   Vercel边缘运行时。
-   开玩笑28或更大 `"node"` 环境(`"jsdom"` 目前不支持)。
-   Nitro v2.6或更高版本。

请注意，目前还不支持React Native。

如果您对其他运行时环境感兴趣，请在GitHub上打开或投票。

## 贡献

看到 [贡献文档](https://npmcn.com/package/%40zavudev/sdk/CONTRIBUTING.md).

## 常见问题

### @zavudev/sdk 是什么？

Zavudev API的官方TypeScript库

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

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

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

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

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

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

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

@zavudev/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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