Scorecard TypeScript API-Bibliothek

Diese Bibliothek bietet bequemen Zugriff auf die Scorecard-REST-API aus serverseitigem TypeScript oder JavaScript.

Die REST-API-Dokumentation finden Sie unter docs.scorecard.io. Die vollständige API dieser Bibliothek finden Sie in api.md.

Sie wird mit Stainless generiert.

MCP Server

Nutzen Sie den Scorecard MCP Server, um KI-Assistenten die Interaktion mit dieser API zu ermöglichen. So können sie Endpunkte erkunden, Testanfragen stellen und die Dokumentation verwenden, um dieses SDK in Ihre Anwendung zu integrieren.

Hinweis: Möglicherweise müssen Sie Umgebungsvariablen in Ihrem MCP-Client festlegen.

Related MCP server: @roarkanalytics/sdk-mcp

Installation

npm install scorecard-ai

Verwendung

Die vollständige API dieser Bibliothek finden Sie in 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);

Typen für Request und Response

Diese Bibliothek enthält TypeScript-Definitionen für alle Request-Parameter und Response-Felder. Sie können sie beispielsweise so importieren und verwenden:

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

Die Dokumentation zu jeder Methode, jedem Request-Parameter und jedem Response-Feld ist in DocstringsZugriff auf die vollständige ApiPromise-Signatur verfügbar und wird in den meisten modernen Editoren beim Überfahren mit der Maus angezeigt.

Fehlerbehandlung

Wenn keine Verbindung zur API hergestellt werden kann oder die API einen [] Erfolg zurückgibt (also keinen 4xx- oder 5xx-Response), wird eine Unterklasse von APIError ausgelöst:

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

Die Fehlercodes lauten wie folgt:

Wiederholungsversuche

Bestimmte Fehler werden standardmäßig automatisch 2-mal mit einem kurzen exponentiellen Backoff wiederholt. Verbindungsfehler (z. B. aufgrund eines Netzwerkproblems), 408 Request Timeout, 409 Conflict, 429 Rate Limit und >=500 Internal Server Errors werden standardmäßig wiederholt.

Sie können die Option maxRetries verwenden, um dieses Verhalten zu konfigurieren oder zu deaktivieren:

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

Zeitüberschreitungen

Requests laufen standardmäßig nach 1 Minute ab. Sie können dies mit der Option timeout konfigurieren:

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

Bei Zeitüberschreitung wird ein APIConnectionTimeoutError ausgelöst.

Beachten Sie, dass Requests, die eine Zeitüberschreitung verursachen, standardmäßig zweimal wiederholt werden.

Automatische Paginierung

Alle Listenmethoden in der Scorecard-API sind paginiert. Sie können die for await … of-Syntax verwenden, um Elemente über alle Seiten hinweg zu durchlaufen:

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

Alternativ können Sie auch jeweils eine einzelne Seite anfordern:

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

Erweiterte Nutzung

Zugriff auf rohe Response-Daten (z. B. Header)

Die "rohe" Response, die von fetch() zurückgegeben wird, kann über die .asresponse()-Methode auf dem APIPromise-Typ abgerufen werden, den alle Methoden zurückgeben. Diese Methode gibt das Ergebnis sofort zurück, sobald die Header für eine erfolgreiche Antwort empfangen werden, und konsumiert den Response-Body nicht. Sie können also eigene Parsing- oder Streaming-Logik implementieren.

Sie können auch die .withResponse()-Methode verwenden, um die rohe Response zusammen mit den analysierten Daten zu erhalten. Im Gegensatz zu .asResponse() konsumiert diese Methode den Body und gibt Sie nach dem Parsen zurück.

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

Protokollierung

Hinweis: Alle Protokollmeldungen sind nur für Debugging.zhwecke gedacht. Format und Inhalt der Protokollmeldungen können sich zwischen den Releases ändern.

Protokolllevel

Die Protokolllevel-Stufe kann auf zwei Arten konfiguriert werden:

1. Über die Umgebungsvariable SCORECARD_LOG

2. Über die Client-Option logLevel (überschreibt die Umgebungsvariable, falls gesetzt)

import Scorecard from 'scorecard-ai';

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

Verfügbare Protokolllevel, vom ausführlichsten zum geringsten:

• 'debug' – Debug-Meldungen, Infos, Warnungen und Fehler anzeigen

• 'info' – Info-Meldungen, Warnungen und Fehler anzeigen

• 'warn' – Warnungen und Fehler anzeigen (Standard)

• 'error' – nur Fehler anzeigen

• 'off' – die Protokollierung deaktivieren

Auf dem 'debug'-Level werden alle HTTP-Requests und -Responses protokolliert, einschließlich Header und Body. Einige Authentifizierungs-Header werden maskiert, aber sensible Daten in Request- und Response-Bodies können weiterhin sichtbar sein.

Eigener Logger

Standardmäßig protokolliert diese Bibliothek an globalThis.console. Sie können auch einen eigenen Logger bereitstellen, der in cron? “. Die meisten Logging-Bibliotheken werden unterstützt, einschließlich pino, winston, bunyan, consola, signale und @std/log. Falls Ihr Logger nicht funktioniert, öffnen Sie bitte ein Issue.

Wenn Sie einen benutzerdefinierten Logger bereitstellen, steuert die logLevel-Option weiterhin, welche Meldungen ausgegeben werden. Meldungen unterhalb des konfigurierten Levels werden nicht für Ihren Logger gesendet.

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

Eigene bzw. nicht dokumentierte Anfragen

Diese Bibliothek ist für den bequemen Zugriff auf die dokumentierte API typisiert. Wenn Sie Endpunkte, Parameter oder Antworteigenschaften verwenden, die nicht dokumentiert sind, kann die Bibliothek weiterhin verwendet werden.

Nicht dokumentierte Endpunkte

Für Anfragen an nicht dokumentierte Endpunkte können Sie client.get, client.post und andere HTTP-Methoden verwenden. Optionen ampere:

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

Nicht dokumentierte Request-Parameter

Verwenden Sie für Anfragen mit nicht dokumentierten Parametern // @ts-expect-er, um den undokumentierten Parameter zu kennzeichnen. Diese Bibliothek validiert zur Laufzeit nicht, ob die Anfrage zum Typ passt. Zusätzliche Werte werden also unverändert gesendet.

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

Bei Requests mit der GET-Methode werden zusätzliche Parameter in der Query abgelegt, bei allen anderen Requests werden die zusätzlichen Parameter im Body gesendet.

Wenn Sie ein zusätzliches Argument explizit senden möchten, können Sie das mit den Request-Optionen query, body und headers tun.

Nicht dokumentierte Response-Eigenschaften

Zugriff auf nicht dokumentierte Response-Eigenschaften erhalten Sie, indem Sie // @ts-expect-error vor dem Response-Objekt verwenden oder das Response-Objekt in den gewünschten Typen wandeln. Wie bei den Request-Parametern validieren wir zusätzliche Eigenschaften in der API-Antwort nicht und entfernen sie auch nicht.

Anpassen des Fetch-Clients

Standardmäßig erwartet diese Bibliothek eine globale fetch-Funktion.

Wenn du eine andere fetch-Funktion verwenden möchtest, kannst du entweder die globale Funktion polyfillen:

import fetch from 'my-fetch';

globalThis.fetch = fetch;

Oder du gibst sie an den Client weiter:

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

const client = new Scorecard({ fetch });

Fetch-Optionen

Wenn Sie benutzerdefinierte fetch-Optionen setzen möchten, ohne die fetch-Funktion zu überschreiben, können Sie beim Instanziieren des Clients oder bei einem neuen Request ein fetchOptions-Objekt angeben. (Requestspezifische Optionen überschreiben Client-Optionen.)