Biblioteca de API TypeScript de Scorecard

Esta biblioteca proporciona un acceso conveniente a la API REST de Scorecard desde TypeScript o JavaScript del lado del servidor.

La documentación de la API REST se puede encontrar en docs.scorecard.io. La API completa de esta biblioteca se puede encontrar en api.md.

Está generada con Stainless.

MCP Server

Utilice el servidor MCP de Scorecard para permitir que los asistentes de IA interactúen con esta API, permitiéndoles explorar endpoints, realizar solicitudes de prueba y usar la documentación para ayudar a integrar este SDK en su aplicación.

Nota: Es posible que necesite configurar variables de entorno en su cliente MCP.

Related MCP server: @roarkanalytics/sdk-mcp

Instalación

npm install scorecard-ai

Uso

La API completa de esta biblioteca se puede encontrar en 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);

Tipos de solicitud y respuesta

Esta biblioteca incluye definiciones de TypeScript para todos los parámetros de solicitud y campos de respuesta. Puede importarlos y usarlos de la siguiente manera:

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

La documentación para cada método, parámetro de solicitud y campo de respuesta está disponible en docstrings y aparecerá al pasar el cursor en la mayoría de los editores modernos.

Manejo de errores

Cuando la biblioteca no puede conectarse a la API, o si la API devuelve un código de estado no exitoso (es decir, respuesta 4xx o 5xx), se lanzará una subclase de 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;
  }
});

Los códigos de error son los siguientes:

Reintentos

Ciertos errores se reintentarán automáticamente 2 veces por defecto, con un breve retroceso exponencial. Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, 429 Rate Limit y errores internos >=500 se reintentarán por defecto.

Puede usar la opción maxRetries para configurar o deshabilitar esto:

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

Tiempos de espera

Las solicitudes expiran después de 1 minuto por defecto. Puede configurar esto con una opción 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,
});

Al expirar, se lanza un APIConnectionTimeoutError.

Tenga en cuenta que las solicitudes que expiran se reintentarán dos veces por defecto.

Paginación automática

Los métodos de lista en la API de Scorecard están paginados. Puede usar la sintaxis for await … of para iterar a través de los elementos de todas las páginas:

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

Alternativamente, puede solicitar una sola página a la vez:

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();
  // ...
}

Uso avanzado

Acceso a datos de respuesta sin procesar (por ejemplo, encabezados)

La Response "cruda" devuelta por fetch() se puede acceder a través del método .asResponse() en el tipo APIPromise que devuelven todos los métodos. Este método devuelve tan pronto como se reciben los encabezados de una respuesta exitosa y no consume el cuerpo de la respuesta, por lo que puede escribir lógica de análisis o transmisión personalizada.

También puede usar el método .withResponse() para obtener la Response cruda junto con los datos analizados. A diferencia de .asResponse(), este método consume el cuerpo, devolviendo una vez que se analiza.

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

Registro

[!IMPORTANT] Todos los mensajes de registro están destinados solo para depuración. El formato y el contenido de los mensajes de registro pueden cambiar entre versiones.

Niveles de registro

El nivel de registro se puede configurar de dos maneras:

1. A través de la variable de entorno SCORECARD_LOG

2. Usando la opción de cliente logLevel (anula la variable de entorno si está configurada)

import Scorecard from 'scorecard-ai';

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

Niveles de registro disponibles, de más a menos detallado:

• 'debug' - Mostrar mensajes de depuración, información, advertencias y errores

• 'info' - Mostrar mensajes de información, advertencias y errores

• 'warn' - Mostrar advertencias y errores (predeterminado)

• 'error' - Mostrar solo errores

• 'off' - Deshabilitar todo el registro

En el nivel 'debug', se registran todas las solicitudes y respuestas HTTP, incluidos encabezados y cuerpos. Algunos encabezados relacionados con la autenticación se redactan, pero los datos confidenciales en los cuerpos de solicitud y respuesta pueden seguir siendo visibles.

Registrador personalizado

Por defecto, esta biblioteca registra en globalThis.console. También puede proporcionar un registrador personalizado. Se admiten la mayoría de las bibliotecas de registro, incluidas pino, winston, bunyan, consola, signale y @std/log. Si su registrador no funciona, abra un problema.

Al proporcionar un registrador personalizado, la opción logLevel aún controla qué mensajes se emiten; los mensajes por debajo del nivel configurado no se enviarán a su registrador.

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

Realizar solicitudes personalizadas/no documentadas

Esta biblioteca está tipada para un acceso conveniente a la API documentada. Si necesita acceder a endpoints, parámetros o propiedades de respuesta no documentados, la biblioteca aún se puede usar.

Endpoints no documentados

Para realizar solicitudes a endpoints no documentados, puede usar client.get, client.post y otros verbos HTTP. Las opciones del cliente, como los reintentos, se respetarán al realizar estas solicitudes.

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

Parámetros de solicitud no documentados

Para realizar solicitudes con parámetros no documentados, puede usar // @ts-expect-error en el parámetro no documentado. Esta biblioteca no valida en tiempo de ejecución que la solicitud coincida con el tipo, por lo que cualquier valor adicional que envíe se enviará tal cual.

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

Para solicitudes con el verbo GET, cualquier parámetro adicional estará en la consulta; todas las demás solicitudes enviarán el parámetro adicional en el cuerpo.

Si desea enviar explícitamente un argumento adicional, puede hacerlo con las opciones de solicitud query, body y headers.

Propiedades de respuesta no documentadas

Para acceder a propiedades de respuesta no documentadas, puede acceder al objeto de respuesta con // @ts-expect-error en el objeto de respuesta, o convertir el objeto de respuesta al tipo requerido. Al igual que con los parámetros de solicitud, no validamos ni eliminamos propiedades adicionales de la respuesta de la API.

Personalización del cliente fetch

Por defecto, esta biblioteca espera que se defina una función fetch global.

Si desea usar una función fetch diferente, puede rellenar (polyfill) la global:

import fetch from 'my-fetch';

globalThis.fetch = fetch;

O pasarla al cliente:

import Scorecard from 'scorecard-ai';
import fetch from 'my-fetch';

const client = new Scorecard({ fetch });

Opciones de fetch

Si desea establecer opciones fetch personalizadas sin anular la función fetch, puede proporcionar un objeto fetchOptions al instanciar el cliente o al realizar una solicitud. (Las opciones específicas de la solicitud anulan las opciones del cliente).

import Scorecard from 'scorecard-ai';

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

Configuración de proxies

Para modificar el comportamiento del proxy, puede proporcionar fetchOptions personalizados que agreguen opciones de proxy específicas del tiempo de ejecución a las solicitudes:

Node [documentación]

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 [documentación]

import Scorecard from 'scorecard-ai';

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

Deno [documentación]

import Scorecard from 'npm:scorecard-ai';

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

Preguntas frecuentes

Versionado semántico

Este paquete generalmente sigue las convenciones de SemVer, aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores:

1. Cambios que solo afectan a tipos estáticos, sin romper el comportamiento en tiempo de ejecución.

2. Cambios en los internos de la biblioteca que son técnicamente públicos pero no están destinados ni documentados para uso externo. (Abra un issue en GitHub para informarnos si depende de dichos internos.)

3. Cambios que no esperamos que afecten a la gran mayoría de los usuarios en la práctica.

Nos tomamos en serio la compatibilidad con versiones anteriores y trabajamos duro para garantizar que pueda confiar en una experiencia de actualización fluida.

Estamos interesados en sus comentarios; abra un issue con preguntas, errores o sugerencias.

Requisitos

Se admite TypeScript >= 4.9.

Se admiten los siguientes tiempos de ejecución:

• Navegadores web (Chrome, Firefox, Safari, Edge actualizados y más)

• Node.js 20 LTS o versiones posteriores (no EOL).

• Deno v1.28.0 o superior.

• Bun 1.0 o posterior.

• Cloudflare Workers.

• Vercel Edge Runtime.

• Jest 28 o superior con el entorno "node" ("jsdom" no se admite en este momento).

• Nitro v2.6 o superior.

Tenga en cuenta que React Native no se admite en este momento.

Si está interesado en otros entornos de tiempo de ejecución, abra o vote por un issue en GitHub.

Contribución

Consulte la documentación de contribución.