JavaScript SDK
ListenHub API 向けの型付き JavaScript/TypeScript クライアント。API キー認証と OAuth 認証に対応した 2 つのクライアントを提供します。
@marswave/listenhub-sdk は ListenHub API の公式 JavaScript/TypeScript クライアントです。フラットなクライアントで——すべてのエンドポイントがクライアントオブジェクト上のメソッドとして並びます——ky ベースの HTTP レイヤーの上に構築されており、標準の { code, message, data } エンベロープを自動で展開し、429 レスポンスも代わりにリトライします。
- ESM のみ対応、TypeScript の型を同梱——
@typesパッケージは不要です。 - Node.js >= 20。 OAuth のユーザートークンで認証すれば、ブラウザでも動作します。
- 依存は 1 つだけ（
ky）なので、バンドルサイズは小さいままです。
インストール
npm i @marswave/listenhub-sdk2 つのクライアント
SDK は 2 つのクライアントをエクスポートします。レスポンスの扱い方とリトライの挙動は共通で、違うのは認証方法と対象となる API 範囲です。コードが動く場所に応じて選んでください。
OpenAPIClient | ListenHubClient | |
|---|---|---|
| 認証 | API キー（Authorization: Bearer） | OAuth ユーザー access token |
| 実行環境 | サーバー、スクリプト、CI | ユーザー向けアプリ、ログイン済みユーザーの代理 |
| Base URL | https://api.marswave.ai/openapi | https://api.listenhub.ai/api |
| 実行主体 | あなたのアカウント / キーの所有者 | ログイン中のユーザー |
サーバーサイドや自動化の用途には OpenAPIClient を使います。 これは公開 OpenAPI 製品に対応するクライアントで、listenhub.ai/settings/api-keys で作成した API キーを渡すか、環境変数 LISTENHUB_API_KEY を設定したうえで引数なしで構築します。
リクエストごとに個々のユーザーのアカウントで実行する必要がある場合は ListenHubClient を使います——ユーザーが OAuth でサインインするインタラクティブなアプリなどです。accessToken は静的な文字列のほか、ゲッター関数 () => string | undefined も受け付けます。この関数はリクエストのたびに呼ばれるため、時間とともに更新されるトークンを渡せます。
API キーはシークレットとして扱ってください。サーバーサイドに保管し、ブラウザやモバイルのクライアントコードに API キーを含めて配布してはいけません。ユーザー向けアプリでは OAuth で認証し、各リクエストがユーザー自身のアカウントで実行されるようにします。
Hello world
クライアントを構築し、スピーカーを一覧して、flow speech（テキスト読み上げ）エピソードを開始します。以下は OpenAPIClient を使い、キーを LISTENHUB_API_KEY から読み取る例です。
import { OpenAPIClient } from '@marswave/listenhub-sdk';
const client = new OpenAPIClient(); // reads LISTENHUB_API_KEY
const { items: speakers } = await client.listSpeakers({ language: 'en' });
const { episodeId } = await client.createFlowSpeech({
sources: [{ type: 'text', content: 'Hello world' }],
speakers: [{ speakerId: speakers[0].speakerId }],
});生成は非同期です。createFlowSpeech はすぐに episodeId を返します。音声 URL を得るには、processStatus が pending から変わるまで getFlowSpeech(episodeId) をポーリングしてください。「作成してポーリングする」完全なループは クイックスタート を参照してください。
レスポンスの扱い方
ListenHub のレスポンスはすべて { "code": 0, "message": "", "data": { … } } でラップされており、code が 0 以外ならエラーを表します。どちらのクライアントもこれを代わりに処理します：
codeが0のとき、メソッドはdataに直接解決されます——エンベロープが表に出ることはありません。codeが 0 以外の場合や HTTP エラーが起きた場合、メソッドはstatus、code、requestIdを持つListenHubErrorを投げます。429 Too Many Requestsのとき、クライアントはRetry-Afterヘッダーを読み取り、maxRetries（デフォルトは2）まで自動でリトライします。
SDK がまだラップしていないものについては、ListenHubClient が内部の ky インスタンスを client.api として公開しています——同じ認証、base URL、リトライの挙動をそのまま再利用できるエスケープハッチです（OpenAPIClient はこれを公開していません）：
import { ListenHubClient } from '@marswave/listenhub-sdk';
const userClient = new ListenHubClient({ accessToken });
const me = await userClient.api.get('v1/users/me').json();