Skip to main content
Glama

Scorecard TypeScript API ライブラリ

NPM version npm bundle size

このライブラリは、サーバーサイドのTypeScriptまたはJavaScriptからScorecard REST APIへの便利なアクセスを提供します。

REST APIのドキュメントはdocs.scorecard.ioにあります。このライブラリの完全なAPIはapi.mdにあります。

Stainlessで生成されています。

MCPサーバー

Scorecard MCPサーバーを使用すると、AIアシスタントがこのAPIと対話し、エンドポイントの探索、テストリクエストの送信、ドキュメントの活用ができるようになり、このSDKをアプリケーションに統合するのに役立ちます。

Add to Cursor Install in VS Code

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

各メソッド、リクエストパラメータ、レスポンスフィールドのドキュメントは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

なし

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

タイムアウトしたリクエストは、デフォルトで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();
  // ...
}

高度な使用法

生のレスポンスデータ(例: ヘッダー)へのアクセス

すべてのメソッドが返す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);

ロギング

[!IMPORTANT] すべてのログメッセージはデバッグ専用です。ログメッセージの形式と内容はリリース間で変更される場合があります。

ログレベル

ログレベルは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にログを出力します。カスタムロガーを提供することもできます。 pinowinstonbunyanconsolasignale@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.getclient.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動詞のリクエストの場合、追加のパラメータはクエリに含まれ、その他のリクエストでは追加のパラメータがボディで送信されます。

追加の引数を明示的に送信する場合は、querybodyheadersリクエストオプションを使用して送信できます。

非公開レスポンスプロパティ

文書化されていないレスポンスプロパティにアクセスするには、レスポンスオブジェクトに// @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. 技術的には公開されているが、外部での使用を意図または文書化されていないライブラリ内部の変更。(そのような内部に依存している場合は、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を開くか、賛成票を投じてください。

コントリビューション

コントリビューションガイドを参照してください。

A
license - permissive license
Not graded
quality - not tested
A
maintenance

Maintenance

Maintainers
Response time
4wRelease cycle
15Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to interact with the Test2w REST API to explore endpoints, make test requests, and access documentation. It facilitates the integration of the Test2w SDK into applications through natural language interfaces in supported AI clients.
    1
    Apache 2.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to interact with the Roark REST API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
    4,208
    7
    Apache 2.0
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to interact with the Nimble REST API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
    1,775
    Apache 2.0
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to interact with the Thrive MCP REST API for exploring endpoints, making test requests, and integrating with the API.
    8
    Apache 2.0

View all related MCP servers

Related MCP Connectors

  • Provides AI assistants with direct access to Mapbox developer APIs and documentation.

  • Public social-data API and live docs for AI coding agents.

  • Gateway between LLM agents and world data through eight tools and a bundled endpoint catalog.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/scorecard-ai/scorecard-node'

If you have feedback or need assistance with the MCP directory API, please join our Discord server