Библиотека TypeScript API для Scorecard

Эта библиотека предоставляет удобный доступ к REST API Scorecard из серверного TypeScript или JavaScript.

Документация по REST API доступна на docs.scorecard.io. Полный API этой библиотеки можно найти в api.md.

Она сгенерирована с помощью Stainless.

MCP-сервер

Используйте MCP-сервер Scorecard, чтобы позволить ИИ-ассистентам взаимодействовать с этим API, давая им возможность исследовать конечные точки, отправлять тестовые запросы и использовать документацию для интеграции этого SDK в ваше приложение.

Примечание: Возможно, вам потребуется установить переменные окружения в вашем MCP-клиенте.

Related MCP server: @roarkanalytics/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');

Документация для каждого метода, параметра запроса и поля ответа доступна в docstrings и будет отображаться при наведении курсора в большинстве современных редакторов.

Обработка ошибок

Когда библиотека не может подключиться к 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;
  }
});

Коды ошибок следующие:

Повторные попытки

Некоторые ошибки будут автоматически повторяться 2 раза по умолчанию с короткой экспоненциальной задержкой. Ошибки соединения (например, из-за проблемы с сетевым подключением), 408 Request Timeout, 409 Conflict, 429 Rate Limit и внутренние ошибки >=500 будут повторяться по умолчанию.

Вы можете использовать опцию 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.

Обратите внимание, что запросы, время которых истекло, будут повторены дважды по умолчанию.

Автопагинация

Методы списков в API Scorecard разбиты на страницы. Вы можете использовать синтаксис 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 (например, заголовкам)

«Сырой» Response, возвращаемый fetch(), можно получить через метод .asResponse() на типе APIPromise, который возвращают все методы. Этот метод возвращается сразу после получения заголовков успешного ответа и не потребляет тело ответа, поэтому вы можете свободно писать собственную логику разбора или потоковой передачи.

Вы также можете использовать метод .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, вы можете либо полифиллить глобальную:

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 [docs]

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 [docs]

import Scorecard from 'scorecard-ai';

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

Deno [docs]

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. Изменения внутренних компонентов библиотеки, которые технически являются публичными, но не предназначены или не документированы для внешнего использования. (Пожалуйста, откройте issue на GitHub, чтобы сообщить нам, если вы полагаетесь на такие внутренние компоненты.)

3. Изменения, которые, как мы ожидаем, не повлияют на подавляющее большинство пользователей на практике.

Мы серьезно относимся к обратной совместимости и прилагаем усилия, чтобы вы могли рассчитывать на плавное обновление.

Мы заинтересованы в ваших отзывах; пожалуйста, откройте issue с вопросами, ошибками или предложениями.

Требования

Поддерживается TypeScript >= 4.9.

Поддерживаются следующие среды выполнения:

• Веб-браузеры (актуальные Chrome, Firefox, Safari, Edge и другие)

• Node.js 20 LTS или более поздние (non-EOL) версии.

• Deno v1.28.0 или выше.

• Bun 1.0 или более поздние версии.

• Cloudflare Workers.

• Vercel Edge Runtime.

• Jest 28 или выше с окружением "node" ("jsdom" в настоящее время не поддерживается).

• Nitro v2.6 или выше.

Обратите внимание, что React Native в настоящее время не поддерживается.

Если вас интересуют другие среды выполнения, пожалуйста, откройте или проголосуйте за issue на GitHub.

Внесение вклада

См. документацию по внесению вклада.