scorecard

Scorecard TypeScript API ライブラリ

このライブラリを使用すると、サーバーサイドの TypeScript または JavaScript から Scorecard REST API に簡単にアクセスできます。

REST API のドキュメントは docs.scorecard.io でご覧いただけます。このライブラリの API 全体については、api.md をご覧ください。

Stainless を使用して生成されています。

MCP サーバー

Scorecard MCP Server を使用すると、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');

各メソッド、リクエストパラメーター、レスポンスフィールドのドキュメントは docstring で確認でき、ほとんどの最新エディターではホバー時に表示されます。

エラー処理

ライブラリが 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 の内部エラーは、デフォルトですべて再試行されます。

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 がスローされます。

タイムアウトしたリクエストは、デフォルトで2回再試行されることに注意してください。

自動ページネーション

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

または、一度に1ページずつリクエストできます。

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 データ（ヘッダーなど）へのアクセス

fetch() が返す「生の」Response は、すべてのメソッドが返す APIPromise 型の .asResponse() メソッドからアクセスできます。 このメソッドは、成功したレスポンスのヘッダーを受信するとすぐに返り、レスポンスボディを消費しないため、独自の解析やストリーミングのロジックを自由に実装できます。

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

ロギング

重要

すべてのログメッセージは、デバッグのみを目的としています。ログメッセージの形式と内容は、リリースによって変更される場合があります。

ログレベル

ログレベルは、次の2つの方法で設定できます。

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 など、ほとんどのロギングライブラリに対応しています。ロガーが動作しない場合は、イシューを作成してください。

カスタムロガーを指定した場合も、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 ^{[ドキュメント]}

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。
• "node" 環境での Jest 28 以降（現時点では "jsdom" はサポートされていません）。
• Nitro v2.6 以降。

現時点では React Native はサポートされていません。

他のランタイム環境に関心がある場合は、GitHub で issue を作成するか、既存の issue に賛成票を投じてください。

コントリビューション

コントリビューションに関するドキュメントをご覧ください。