JavaScript SDK
ListenHub API를 위한 타입이 지정된 JavaScript/TypeScript 클라이언트. API 키 인증과 OAuth 인증에 대응하는 두 개의 클라이언트를 제공합니다.
@marswave/listenhub-sdk는 ListenHub API의 공식 JavaScript/TypeScript 클라이언트입니다. 플랫한 클라이언트로 — 모든 엔드포인트가 클라이언트 객체에 바로 붙은 메서드입니다 — ky 기반 HTTP 레이어 위에 만들어졌으며, 표준 { code, message, data } 래퍼를 대신 벗겨 주고 429 응답은 자동으로 재시도합니다.
- ESM 전용, TypeScript 타입을 함께 제공합니다 —
@types패키지가 필요 없습니다. - Node.js >= 20. OAuth 사용자 토큰으로 인증하면 브라우저에서도 동작합니다.
- 의존성은 하나뿐(
ky)이라 번들에서 크기가 작게 유지됩니다.
설치
npm i @marswave/listenhub-sdk두 개의 클라이언트
SDK는 두 개의 클라이언트를 내보냅니다. 응답 처리와 재시도 동작은 공통이고, 인증 방식과 대상 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은 정적 문자열이나 getter 함수 () => string | undefined를 받으며, 이 함수는 매 요청 전에 호출되므로 시간이 지나며 갱신되는 토큰을 넘길 수 있습니다.
API 키는 비밀 정보로 다루세요. 반드시 서버 측에만 두고 — 브라우저나 모바일 클라이언트 코드에 API 키를 포함해 배포하지 마세요. 사용자 대상 앱에서는 OAuth로 인증해, 각 요청이 사용자 본인의 계정으로 실행되도록 하세요.
Hello world
클라이언트를 생성하고, 스피커(speaker)를 조회하고, 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)를 폴링(polling)하세요. 생성 후 폴링하는 전체 루프는 빠른 시작을 참고하세요.
응답이 처리되는 방식
모든 ListenHub 응답은 { "code": 0, "message": "", "data": { … } } 형태로 감싸여 있으며, code가 0이 아니면 에러를 뜻합니다. 두 클라이언트 모두 이를 대신 처리합니다:
code 0일 때 메서드는data로 바로 resolve됩니다 — 래퍼가 겉으로 드러나는 일은 없습니다.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();