scorecard

Scorecard TypeScript API 库

此库可让你通过服务器端 TypeScript 或 JavaScript 便捷地访问 Scorecard REST API。

REST API 文档请参阅 docs.scorecard.io。此库的完整 API 请参阅 api.md。

此库由 Stainless 生成。

MCP 服务

使用 Scorecard MCP 服务可让 AI 助手与此 API 交互，探索端点、发送测试请求，并利用文档帮助你将此 SDK 集成到应用程序中。

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

安装

npm install scorecard-ai

用法

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

import Scorecard from 'scorecard-ai';

const client = new Scorecard({
  apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted
  environment: 'staging', // or 'production' | 'local'; defaults to 'production'
});

const run = await client.runs.create('314', { metricIds: ['789', '101'], testsetId: '246' });

console.log(run.id);

请求和响应类型

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

import Scorecard from 'scorecard-ai';

const client = new Scorecard({
  apiKey: process.env['SCORECARD_API_KEY'], // This is the default and can be omitted
  environment: 'staging', // or 'production' | 'local'; defaults to 'production'
});

const testset: Scorecard.Testset = await client.testsets.get('246');

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

错误处理

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

const testset = await client.testsets.get('246').catch(async (err) => {
  if (err instanceof Scorecard.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 Request Timeout、409 Conflict、 429 Rate Limit 和 >=500 Internal 错误默认都会重试。

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

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

// Or, configure per-request:
await client.testsets.get('246', {
  maxRetries: 5,
});

超时

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

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

// Override per-request:
await client.testsets.get('246', {
  timeout: 5 * 1000,
});

超时时会抛出 APIConnectionTimeoutError。

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

自动分页

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

async function fetchAllTestcases(params) {
  const allTestcases = [];
  // Automatically fetches more pages as needed.
  for await (const testcase of client.testcases.list('246', { limit: 30 })) {
    allTestcases.push(testcase);
  }
  return allTestcases;
}

或者，你也可以一次请求一页：

let page = await client.testcases.list('246', { limit: 30 });
for (const testcase of page.data) {
  console.log(testcase);
}

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

高级用法

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

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

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

const client = new Scorecard();

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

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

日志记录

重要

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

日志级别

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

1. 通过 SCORECARD_LOG 环境变量
2. 使用客户端选项 logLevel（若已设置，则会覆盖环境变量）

import Scorecard from 'scorecard-ai';

const client = new Scorecard({
  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 Scorecard from 'scorecard-ai';
import pino from 'pino';

const logger = pino();

const client = new Scorecard({
  logger: logger.child({ name: 'Scorecard' }),
  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.runs.create({
  // ...
  // @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 Scorecard from 'scorecard-ai';
import fetch from 'my-fetch';

const client = new Scorecard({ fetch });

Fetch 选项

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

import Scorecard from 'scorecard-ai';

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

配置代理

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

Node ^[文档]

import Scorecard from 'scorecard-ai';
import * as undici from 'undici';

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

Bun ^[文档]

import Scorecard from 'scorecard-ai';

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

Deno ^[文档]

import Scorecard from 'npm:scorecard-ai';

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

常见问题

语义化版本控制

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

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

我们非常重视向后兼容性，并努力确保你能够顺利升级。

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

要求

支持 TypeScript >= 4.9。

支持以下运行时：

• Web 浏览器（最新版 Chrome、Firefox、Safari、Edge 等）
• Node.js 20 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 投票。

贡献

请参阅贡献文档。