Scorecard TypeScript API 라이브러리

이 라이브러리는 서버 측 TypeScript 또는 JavaScript에서 Scorecard REST API에 편리하게 접근할 수 있는 기능을 제공합니다.

REST API 문서는 docs.scorecard.io에서 확인할 수 있습니다. 이 라이브러리의 전체 API는 api.md에서 확인할 수 있습니다.

이 라이브러리는 Stainless로 생성되었습니다.

MCP 서버

Scorecard MCP 서버를 사용하여 AI 어시스턴트가 이 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');

각 메서드, 요청 매개변수, 응답 필드에 대한 문서는 docstring에 포함되어 있으며 대부분의 최신 편집기에서 마우스를 올리면 표시됩니다.

오류 처리

라이브러리가 API에 연결할 수 없거나, API가 성공 상태 코드가 아닌 응답(즉, 4xx 또는 5xx 응답)을 반환하는 경우, APIError의 하위 클래스가 throw됩니다:

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가 throw됩니다.

타임아웃된 요청은 기본적으로 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;
}

또는 한 번에 한 페이지씩 요청할 수 있습니다:

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 데이터 접근 (예: 헤더)

모든 메서드가 반환하는 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] 모든 로그 메시지는 디버깅 전용입니다. 로그 메시지의 형식과 내용은 릴리스 간에 변경될 수 있습니다.

로그 레벨

로그 레벨은 두 가지 방법으로 구성할 수 있습니다:

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 [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 이슈를 열어 알려주세요.)

3. 실제로 대다수의 사용자에게 영향을 미치지 않을 것으로 예상되는 변경 사항.

우리는 하위 호환성을 중요하게 생각하며 원활한 업그레이드 경험을 보장하기 위해 노력하고 있습니다.

피드백을 환영합니다. 질문, 버그 또는 제안 사항이 있으면 이슈를 열어 주세요.

요구 사항

TypeScript >= 4.9가 지원됩니다.

다음 런타임이 지원됩니다:

• 웹 브라우저 (최신 Chrome, Firefox, Safari, Edge 등)

• Node.js 20 LTS 이상 (비-EOL) 버전.

• Deno v1.28.0 이상.

• Bun 1.0 이상.

• Cloudflare Workers.

• Vercel Edge Runtime.

• "node" 환경의 Jest 28 이상 ("jsdom"은 현재 지원되지 않습니다).

• Nitro v2.6 이상.

React Native는 현재 지원되지 않습니다.

다른 런타임 환경에 관심이 있다면 GitHub에서 이슈를 열거나 투표해 주세요.

기여

기여 문서를 참조하세요.