Zavudev TypeScript API库

npm bundle size

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

REST API文档可以在 docs.zavu.dev。此库的每个方法和类型都在其资源的模块中 src/resources/.

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

MCP服务器

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

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

安装

npm install @zavudev/sdk

使用

每个方法和类型都在其资源的模块中 src/resources/.

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定义。您可以像这样导入和使用它们：

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 在同一个客户端 client.v2。v2路径中的每个id都是一个位置参数，按路径顺序，和 V2的类型来自 @zavudev/sdk/v2：

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 将被抛出：

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 选项配置或禁用此功能：

// 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 选择:

// 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 抛出。

请注意，请求将超时默认情况下重试两次.

Auto-pagination

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

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;
}

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

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() 此方法使用主体，并在解析后返回。

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);

日志记录

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

日志级别

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

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

import Zavudev from '@zavudev/sdk';

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

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

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

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

自定义日志记录器

默认情况下，此库记录为 globalThis.console。您还可以提供自定义记录器。支持大多数日志库，包括皮诺，温斯顿，班扬， consola， signale, @std /日志。如果您的记录器不工作，请打开一个问题。

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

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动词。在发出这些请求时，将尊重客户机上的选项，例如重试。

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

未记录的请求参数

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

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

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

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

未记录的响应属性

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

自定义获取客户端

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

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

import fetch from 'my-fetch';

globalThis.fetch = fetch;

或者将其传递给客户端：

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

const client = new Zavudev({ fetch });

获取选择

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

import Zavudev from '@zavudev/sdk';

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

配置代理

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

节点 ^［文档］

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,
  },
});

包子 ^［文档］

import Zavudev from '@zavudev/sdk';

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

Deno ^［文档］

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

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

常见问题

语义版本控制

这个包通常如下 SemVer 约定，虽然某些向后不兼容的更改可能作为小版本发布：

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

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

我们渴望得到您的反馈；请打开一个问题提出问题、bug或建议。

要求

支持TypeScript >= 4.9。

支持以下运行时：

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

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

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

贡献

看到贡献文档.

版本	发布日期	距今
`0.60.2`latest	2026/11/03	今天
`0.60.1`	2026/10/31	3 天前
`0.60.0`	2026/10/28	6 天前
`0.59.1`	2026/10/24	10 天前
`0.59.0`	2026/10/22	12 天前
`0.58.1`	2026/10/22	12 天前

@zavudev/sdk