Finbud Data TypeScript API Library

Finbud Data TypeScript API ライブラリ

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

このライブラリの完全な API については、api.md をご覧ください。

このライブラリは Stainless を使用して生成されています。

インストール

npm install finbud-data

使い方

このライブラリの完全な API については、api.md をご覧ください。

import FinbudData from 'finbud-data';

const client = new FinbudData({
  apiKey: process.env['FINBUD_DATA_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const response = await client.analysts.retrieveEstimates('REPLACE_ME');
}

main();

リクエストとレスポンスの型

このライブラリには、すべてのリクエストパラメーターとレスポンスフィールドの TypeScript 定義が含まれています。次のようにインポートして使用できます。

import FinbudData from 'finbud-data';

const client = new FinbudData({
  apiKey: process.env['FINBUD_DATA_API_KEY'], // This is the default and can be omitted
});

async function main() {
  const response: FinbudData.AnalystRetrieveEstimatesResponse = await client.analysts.retrieveEstimates(
    'REPLACE_ME',
  );
}

main();

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

エラーの処理

ライブラリが API に接続できない場合、 または API が成功以外のステータスコード（4xx または 5xx のレスポンス）を返した場合は、 APIError のサブクラスがスローされます。

async function main() {
  const response = await client.analysts.retrieveEstimates('REPLACE_ME').catch(async (err) => {
    if (err instanceof FinbudData.APIError) {
      console.log(err.status); // 400
      console.log(err.name); // BadRequestError
      console.log(err.headers); // {server: 'nginx', ...}
    } else {
      throw err;
    }
  });
}

main();

エラーコードは次のとおりです。

ステータスコード	エラーの種類
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 FinbudData({
  maxRetries: 0, // default is 2
});

// Or, configure per-request:
await client.analysts.retrieveEstimates('REPLACE_ME', {
  maxRetries: 5,
});

タイムアウト

リクエストはデフォルトで 1 分後にタイムアウトします。timeout オプションを使用して設定できます。

// Configure the default for all requests:
const client = new FinbudData({
  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
});

// Override per-request:
await client.analysts.retrieveEstimates('REPLACE_ME', {
  timeout: 5 * 1000,
});

タイムアウトすると、APIConnectionTimeoutError がスローされます。

タイムアウトしたリクエストはデフォルトで 2 回再試行されます。

高度な使い方

生の Response データ（ヘッダーなど）へのアクセス

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

.withResponse() メソッドを使うと、解析済みデータとともに生の Response を取得することもできます。 .asResponse() とは異なり、このメソッドは本文を消費し、解析が完了してから返ります。

const client = new FinbudData();

const response = await client.analysts.retrieveEstimates('REPLACE_ME').asResponse();
console.log(response.headers.get('X-My-Header'));
console.log(response.statusText); // access the underlying Response object

const { data: response, response: raw } = await client.analysts
  .retrieveEstimates('REPLACE_ME')
  .withResponse();
console.log(raw.headers.get('X-My-Header'));
console.log(response);

ログ記録

重要

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

ログレベル

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

1. FINBUD_DATA_LOG 環境変数を使用する
2. クライアントオプションの logLevel を使用する（設定されている場合は環境変数より優先されます）

import FinbudData from 'finbud-data';

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

利用可能なログレベルを、詳細度の高い順に示します。

• 'debug' - デバッグメッセージ、情報、警告、エラーを表示します
• 'info' - 情報、警告、エラーを表示します
• 'warn' - 警告とエラーを表示します（デフォルト）
• 'error' - エラーのみを表示します
• 'off' - すべてのログ記録を無効にします

'debug' レベルでは、ヘッダーや本文を含むすべての HTTP リクエストとレスポンスが記録されます。 認証関連のヘッダーの一部はマスクされますが、リクエスト本文やレスポンス本文に含まれる機密データは 表示される場合があります。

カスタムロガー

デフォルトでは、このライブラリは globalThis.console にログを出力します。カスタムロガーを指定することもできます。 pino、winston、bunyan、consola、signale、@std/log など、ほとんどのロギングライブラリに対応しています。お使いのロガーが動作しない場合は、issue を作成してください。

カスタムロガーを指定した場合も、logLevel オプションによって出力されるメッセージが制御されます。設定したレベルより低いメッセージは、ロガーに送信されません。

import FinbudData from 'finbud-data';
import pino from 'pino';

const logger = pino();

const client = new FinbudData({
  logger: logger.child({ name: 'FinbudData' }),
  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.foo.create({
  foo: 'my_param',
  bar: 12,
  // @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 FinbudData from 'finbud-data';
import fetch from 'my-fetch';

const client = new FinbudData({ fetch });

fetch オプション

fetch 関数を上書きせずにカスタムの fetch オプションを設定する場合は、クライアントのインスタンス化時またはリクエスト時に fetchOptions オブジェクトを指定できます。（リクエスト固有のオプションは、クライアントのオプションより優先されます。）

import FinbudData from 'finbud-data';

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

プロキシの設定

プロキシの動作を変更するには、ランタイム固有のプロキシオプションをリクエストに追加するカスタムの fetchOptions を指定できます。

Node ^{[ドキュメント]}

import FinbudData from 'finbud-data';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new FinbudData({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

Bun ^{[ドキュメント]}

import FinbudData from 'finbud-data';

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

Deno ^{[ドキュメント]}

import FinbudData from 'npm:finbud-data';

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

よくある質問

セマンティックバージョニング

このパッケージは基本的にSemVerの規約に従いますが、以下のような後方互換性のない変更がマイナーバージョンとしてリリースされる場合があります。

1. 実行時の動作に影響せず、静的型のみに影響する変更。
2. 技術的には公開されているものの、外部からの利用を意図または文書化していない、ライブラリ内部の変更。 (このような内部機能に依存している場合は、GitHub の issue を作成してお知らせください。)
3. 実際には大多数のユーザーに影響しないと見込まれる変更。

後方互換性を重視しており、スムーズにアップグレードできるよう努めています。

皆さまからのフィードバックをお待ちしています。ご質問、バグ、提案がありましたら、issueを作成してください。

要件

TypeScript >= 4.9 をサポートしています。

以下のランタイムをサポートしています。

• Web ブラウザー（最新の Chrome、Firefox、Safari、Edge など）
• Node.js 18 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 に賛成票を投じてください。

コントリビュート

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