Finbud Data TypeScript API Library

Finbud Data TypeScript API 库

此库可在服务端 TypeScript 或 JavaScript 中便捷地访问 Finbud Data REST API。

此库的完整 API 文档请参阅 api.md。

此库使用 Stainless 生成。

安装

npm install finbud-data

用法

此库的完整 API 文档请参阅 api.md。

import FinbudData from 'finbud-data';

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

async function main() {
  const response = await client.analysts.retrieveEstimates('REPLACE_ME');
}

main();

请求和响应类型

此库包含所有请求参数和响应字段的 TypeScript 定义。你可以按如下方式导入和使用：

import FinbudData from 'finbud-data';

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

async function main() {
  const response: FinbudData.AnalystRetrieveEstimatesResponse = await client.analysts.retrieveEstimates(
    'REPLACE_ME',
  );
}

main();

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

错误处理

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

async function main() {
  const response = await client.analysts.retrieveEstimates('REPLACE_ME').catch(async (err) => {
    if (err instanceof FinbudData.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
}

main();

错误代码如下：

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

重试

某些错误默认会自动重试 2 次，并采用较短的指数退避。 默认会重试连接错误（例如由网络连接问题导致的错误）、408 Request Timeout、409 Conflict、 429 Rate Limit 以及 >=500 的内部错误。

你可以使用 maxRetries 选项进行配置或禁用重试：

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

// Or, configure per-request:
await client.analysts.retrieveEstimates('REPLACE_ME', {
  maxRetries: 5,
});

超时

请求默认在 1 分钟后超时。你可以通过 timeout 选项进行配置：

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

// Override per-request:
await client.analysts.retrieveEstimates('REPLACE_ME', {
  timeout: 5 * 1000,
});

超时时会抛出 APIConnectionTimeoutError。

请注意，超时的请求默认会重试两次。

高级用法

访问原始 Response 数据（例如，标头）

可以通过所有方法返回的 APIPromise 类型上的 .asResponse() 方法，访问 fetch() 返回的“原始” Response。 此方法会在收到成功响应的标头后立即返回，且不会读取响应正文，因此你可以自由编写自定义解析或流处理逻辑。

你也可以使用 .withResponse() 方法，在获取解析后数据的同时获取原始 Response。 与 .asResponse() 不同，此方法会读取正文，并在解析完成后返回。

const client = new FinbudData();

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

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

日志

重要

所有日志消息仅用于调试。日志消息的格式和内容 可能会在不同版本之间发生变化。

日志级别

可以通过以下两种方式配置日志级别：

1. 通过 FINBUD_DATA_LOG 环境变量
2. 使用 logLevel 客户端选项（设置后会覆盖环境变量）

import FinbudData from 'finbud-data';

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

可用的日志级别，按详细程度从高到低排列：

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

在 'debug' 级别下，会记录所有 HTTP 请求和响应，包括标头和正文。 部分与身份验证相关的标头会被隐藏，但请求和响应正文中的敏感数据 仍可能会显示。

自定义日志记录器

默认情况下，此库会将日志记录到 globalThis.console。你也可以提供自定义日志记录器。 支持大多数日志记录库，包括 pino、winston、bunyan、consola、signale 和 @std/log。如果你的日志记录器无法正常工作，请提交一个 issue。

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

import FinbudData from 'finbud-data';
import pino from 'pino';

const logger = pino();

const client = new FinbudData({
  logger: logger.child({ name: 'FinbudData' }),
  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.foo.create({
  foo: 'my_param',
  bar: 12,
  // @ts-expect-error baz is not yet public
  baz: 'undocumented option',
});

对于使用 GET 方法的请求，所有额外参数都会放在查询字符串中；其他请求则会将额外参数放在请求正文中。

如果要显式发送额外参数，可以使用 query、body 和 headers 请求选项。

未记录的响应属性

若要访问未记录的响应属性，可以在响应对象上使用 // @ts-expect-error，也可以将响应对象转换为所需类型。与请求参数一样，我们不会验证或移除 API 响应中的额外属性。

自定义 fetch 客户端

默认情况下，此库要求定义全局 fetch 函数。

如果要使用其他 fetch 函数，可以为全局函数添加 polyfill：

import fetch from 'my-fetch';

globalThis.fetch = fetch;

也可以将其传递给客户端：

import FinbudData from 'finbud-data';
import fetch from 'my-fetch';

const client = new FinbudData({ fetch });

Fetch 选项

如果要设置自定义 fetch 选项而不覆盖 fetch 函数，可以在实例化客户端或发起请求时提供 fetchOptions 对象。（请求专用选项会覆盖客户端选项。）

import FinbudData from 'finbud-data';

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

配置代理

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

Node ^[文档]

import FinbudData from 'finbud-data';
import * as undici from 'undici';

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

Bun ^[文档]

import FinbudData from 'finbud-data';

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

Deno ^[文档]

import FinbudData from 'npm:finbud-data';

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

常见问题

语义化版本

此软件包通常遵循 SemVer 约定，但某些不向后兼容的更改可能会作为次要版本发布：

1. 仅影响静态类型、不破坏运行时行为的更改。
2. 对库内部实现的更改，这些实现虽然在技术上是公开的，但并非面向外部使用或有相关文档。（如果你依赖此类内部实现，请提交 GitHub issue 告知我们。）
3. 我们预计实际上不会影响绝大多数用户的更改。

我们非常重视向后兼容性，并会努力确保升级体验顺畅。

我们很期待收到你的反馈；如有问题、错误报告或建议，请提交 issue。

要求

支持 TypeScript >= 4.9。

支持以下运行时：

• Web 浏览器（最新版本的 Chrome、Firefox、Safari、Edge 等）
• Node.js 18 LTS 或更高版本（尚未停止生命周期）。
• Deno v1.28.0 或更高版本。
• Bun 1.0 或更高版本。
• Cloudflare Workers。
• Vercel Edge Runtime。
• Jest 28 或更高版本，且使用 "node" 环境（目前不支持 "jsdom"）。
• Nitro v2.6 或更高版本。

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

如果你对其他运行时环境感兴趣，请在 GitHub 上提交 issue 或为相关 issue 投票。

贡献

请参阅贡献文档。