用于比珀客户端 API API 库的 TypeScript SDK

这个库提供了从服务器侧的TypeScript或JavaScript方便地访问Beeper桌面 REST API.

REST API 文档可见于 开发者. beeper.com。此库的全部 API 可以在 日记。 。 。 .

安装

npm install @beeper/desktop-api

使用量

此库的全部 API 可在 日记。 。 。 .

import BeeperDesktop from '@beeper/desktop-api';

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

const page = await client.chats.search({
  accountIDs: ['matrix', 'discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc'],
  includeMuted: true,
  limit: 3,
  type: 'single',
});
const chat = page.items[0];

console.log(chat.id);

请求响应类型( A)

这个库包括所有请求参数和响应字段的TypeScript定义. 你可以这样导入和使用它们:

import BeeperDesktop from '@beeper/desktop-api';

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

const accounts: BeeperDesktop.AccountListResponse = await client.accounts.list();

每种方法的文件、请求参数和响应字段都以道克字符串形式提供,并将出现在大多数现代编辑中.

文件上传

请求对应文件上传的参数可以以许多不同的形式传递:

• File (或结构相同的物体)
• (单位:千美元) fetch Response (或结构相同的物体)
• a 一个 fs.ReadStream
• 我们的回归价值 toFile 帮助者

import fs from 'fs';
import BeeperDesktop, { toFile } from '@beeper/desktop-api';

const client = new BeeperDesktop();

// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
await client.assets.upload({ file: fs.createReadStream('/path/to/file') });

// Or if you have the web `File` API you can pass a `File` instance:
await client.assets.upload({ file: new File(['my bytes'], 'file') });

// You can also pass a `fetch` `Response`:
await client.assets.upload({ file: await fetch('https://somesite/file') });

// Finally, if none of the above are convenient, you can use our `toFile` helper:
await client.assets.upload({ file: await toFile(Buffer.from('my bytes'), 'file') });
await client.assets.upload({ file: await toFile(new Uint8Array([0, 1, 2]), 'file') });

处理错误

当库无法连接到API时, 或者如果API返回一个非成功状态代码(即4xx或5xx回复), 子类 APIError 将扔出 :

const accounts = await client.accounts.list().catch(async (err) => {
  if (err instanceof BeeperDesktop.APIError) {
    console.log(err.status); // 400
    console.log(err.name); // BadRequestError
    console.log(err.headers); // {server: 'nginx', ...}
  } else {
    throw err;
  }
});

出错代码如下:

检索

某些出错默认会自动重试2次,并有短暂的指数后退. 连接出错(例如由于网络连接问题) 408 请求超时, 409 相冲突, 429 限制费率,和 QQ500 内部出错都会默认重审.

你可以用这个 maxRetries 选项以配置或禁用此选项:

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

// Or, configure per-request:
await client.accounts.list({
  maxRetries: 5,
});

超时

默认30秒后请求暂停 。 您可以用一个 timeout 选项 :

// Configure the default for all requests:
const client = new BeeperDesktop({
  timeout: 20 * 1000, // 20 seconds (default is 30 seconds)
});

// Override per-request:
await client.accounts.list({
  timeout: 5 * 1000,
});

超时,一个 APIConnectionTimeoutError 被抛出.

请注意,哪些时间是 默认重审两次。 。 。 .

自动涂鸦

BeeperDesktop API中的列表方法被平分. 你可以用这个 for await … of 在所有页面中通过项目排列的语法 :

async function fetchAllMessages(params) {
  const allMessages = [];
  // Automatically fetches more pages as needed.
  for await (const message of client.messages.search({
    accountIDs: ['discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc'],
    limit: 10,
    query: 'oauth',
  })) {
    allMessages.push(message);
  }
  return allMessages;
}

或者,您可以一次请求一页:

let page = await client.messages.search({
  accountIDs: ['discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc'],
  limit: 10,
  query: 'oauth',
});
for (const message of page.items) {
  console.log(message);
}

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

高级使用

树摇

这个库支持树摇晃来减小捆绑大小. 不导入完整的客户端, 您只能创建客户端, 包括您需要的 API 资源 :

import { createClient } from '@beeper/desktop-api/tree-shakable';
import { Accounts } from '@beeper/desktop-api/resources/accounts/accounts';
import { BaseChats } from '@beeper/desktop-api/resources/chats/chats';

const client = createClient({
  // Specify the resources you'd like to use ...
  resources: [Accounts, BaseChats],
});

// ... then make API calls as usual.
const account = await client.accounts.retrieve('accountID');
const chat = await client.chats.create({
  accountID: 'accountID',
  participantIDs: ['string'],
  type: 'single',
});

每个API资源有两个版本,全资源(如, Accounts),包括所有分资源,以及基础资源(例如, BaseAccounts没有.

树形客户端已完全输入, 因此 TypeScript 将提供准确的自动完成, 并阻止访问未包含在您的配置中的资源 . 这个 createClient 函数自动推断出正确的类型,但也可以使用 PartialBeeperDesktop 明确类型 :

import BeeperDesktop from '@beeper/desktop-api';
import { createClient, type PartialBeeperDesktop } from '@beeper/desktop-api/tree-shakable';
import { BaseAccounts } from '@beeper/desktop-api/resources/accounts/accounts';

// Explicit variable type
const client: PartialBeeperDesktop<{ accounts: BaseAccounts }> = createClient({
  resources: [BaseAccounts],
  /* ... */
});

// Function parameter type
async function main(client: PartialBeeperDesktop<{ accounts: BaseAccounts }>) {
  const account = await client.accounts.retrieve('accountID');
}

// Works with any client that has the accounts resource
const treeShakableClient = createClient({
  resources: [BaseAccounts],
  /* ... */
});
const fullClient = new BeeperDesktop(/* ... */);

main(treeShakableClient); // Works
main(fullClient); // Also works

获取原始响应数据(例如信头)

那个"行" Response 返回时间 fetch() 可通过 .asResponse() 方法 APIPromise 键入所有方法返回. 此方法一旦收到成功的响应信头即返回,而不消耗响应正文,所以您可以自由写入自定义解析或流出逻辑.

你也可以使用这个 .withResponse() 获取原始数据的方法 Response 与解析数据一起. 与 .asResponse() 这种方法消耗了身体,一旦解析就返回.

const client = new BeeperDesktop();

const response = await client.accounts.list().asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: accounts, response: raw } = await client.accounts.list().withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(accounts);

日志

[大 所有日志消息仅用于调试 。 日志信息的格式和内容 释放之间可能会有变化.

日志级别

日志级别可以配置两种方式:

1. 通过 BEEPER_LOG 环境变量
2. 使用 logLevel 客户端选项( 如果设置, 覆盖环境变量)

import BeeperDesktop from '@beeper/desktop-api';

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

可用的日志水平, 从大多数到最小动词 :

• 'debug' - 显示调试消息、信息、警告和错误
• 'info' - 显示信息信息、警告和错误
• 'warn' - 显示警告和错误(默认)
• 'error' - 只显示出错
• 'off' - 禁用所有记录

在那个 'debug' 级别、所有HTTP请求和答复都登录,包括信头和正文. 一些与认证相关的头被编辑,但在请求和响应机构中有敏感数据 可能仍然可见.

自定义日志

默认情况下,此库日志将 globalThis.console。也可以提供自定义日志. 大多数伐木库都得到支持,包括: 皮诺, (中文(简体) ), 温通, (中文(简体) ), 包扬, (中文(简体) ), 康索拉语name, (中文(简体) ), 信号,以及 @ std/ log (帮助)如果您的日志不工作,请打开一个问题.

当提供自定义日志时 logLevel 选项仍然控制哪些消息被发送,消息 在配置的关卡以下将不会发送到您的日志 .

import BeeperDesktop from '@beeper/desktop-api';
import pino from 'pino';

const logger = pino();

const client = new BeeperDesktop({
  logger: logger.child({ name: 'BeeperDesktop' }),
  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 关于无证件者 参数。 此库不会在运行时验证请求是否与类型相匹配, 所以任何额外的值 发送将按.

client.chats.search({
  // ...
  // @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 BeeperDesktop from '@beeper/desktop-api';
import fetch from 'my-fetch';

const client = new BeeperDesktop({ fetch });

获取选项

如果你想设置自定义 fetch 选项,而不压倒 fetch 函数,您可以提供 fetchOptions 当即决客户端或提出请求时对象。 (请求特定选项压倒客户选项. )

import BeeperDesktop from '@beeper/desktop-api';

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

配置代理人

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

节点 ^{[文档[ . ]}

import BeeperDesktop from '@beeper/desktop-api';
import * as undici from 'undici';

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

阿宝 ^{[文档[ . ]}

import BeeperDesktop from '@beeper/desktop-api';

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

德诺 ^{[文档[ . ]}

import BeeperDesktop from 'npm:@beeper/desktop-api';

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

经常被问到的问题

语义版本

这套套件一般沿用 交换器 虽然某些向后兼容的修改可以作为小版本发布:

1. 仅影响静态类型的变化,而不突破运行时的行为.
2. 图书馆内部的改动,技术上是公开的,但并非打算或记录外部使用的. (请打开一个 GitHub 问题让我们知道, 如果你依赖这样的内部。 )
3. 我们预计不会在实践中影响到绝大多数用户的变化.

我们认真对待倒向相容性,并努力地确保你能够依靠平稳的升级经验.

我们很期待你的反馈,请打开 问题 包括问题、错误或建议.

所需资源

TypeScript QQ 4.9 得到支持.

支持以下运行时间:

• 网页浏览器(最新Chrome、Firefox、Safari、Edge等)
• 节点.js 20 LTS 或以后(非欧洲)版本.
• 德诺v1.28.0以上.
• 1.0号或以后.
• 云浮活计.
• Vercel Edge 运行时段.
• 28岁以上 "node" 环境"jsdom" 目前不支持).
• Nitro v 2.6 或 更强.

注意React Industrial此时不支持.

如果您对其它运行时间环境感兴趣, 请在 GitHub 上打开或投票 .

捐款

见 提供的文件。 。 。 .