@marswave/listenhub-sdk

JavaScript SDK for the ListenHub API.

Install

npm i @marswave/listenhub-sdk

Quick start

Clone the repo and run the OAuth login example — it opens a browser, handles the callback, and prints your tokens:

git clone https://github.com/marswaveai/listenhub-sdk.git
cd listenhub-sdk
pnpm i
npx tsx examples/oauth-login.ts

Client options

const client = new ListenHubClient({
	accessToken: 'token', // static string or () => string | undefined
	baseURL: 'https://api.listenhub.ai/api',
	timeout: 30_000, // request timeout in ms
	maxRetries: 2, // max retries on 429 (default: 2)
});

Examples

File	Description
examples/basic.ts	Static token, API calls, error handling
examples/oauth-login.ts	Browser-based OAuth login flow
examples/create-podcast.ts	Create a duo podcast and poll for result
examples/create-tts.ts	Text-to-speech from plain text
examples/create-explainer-video.ts	Explainer video from a URL
examples/create-slides.ts	Slide deck presentation
examples/create-ai-image.ts	AI image generation from a prompt
examples/music.ts	Music generation and cover from audio

Documentation

Document	Description
Architecture	Module dependency diagram and responsibilities
Client Behavior	Request/response flow, hooks, retry and refresh logic
Testing	Test layers, running tests, mock server setup

API

Auth

Method	Description
connectInit({callbackPort})	Start OAuth flow, returns authUrl and sessionId
connectToken({sessionId, code})	Exchange authorization code for tokens
refresh({refreshToken})	Refresh an expired access token
revoke({refreshToken})	Revoke a refresh token

Checkin

Method	Description
checkinSubmit()	Submit daily check-in
checkinStatus()	Get check-in streak and status

Settings

Method	Description
getApiKey()	Get current API key
regenerateApiKey()	Regenerate API key (triggers onApiKeyChanged)
getSettings()	Get episode template settings per product type

Content creation

Method	Description
createPodcast(params)	Create a podcast (solo/duo)
createTTS(params)	Create a text-to-speech audio
createExplainerVideo(params)	Create an explainer video
createSlides(params)	Create a slides presentation
createAIImage(params)	Generate an AI image from a prompt

Music

Method	Description
createMusicGenerate(params)	Generate music from a text prompt
createMusicCover(params)	Create a cover from a reference audio URL
getMusicTask(taskId)	Get music task status and details
listMusicTasks(params?)	List music tasks with optional filtering

List by product

Method	Description
listPodcasts(params?)	List podcast episodes
listTTS(params?)	List TTS episodes
listExplainerVideos(params?)	List explainer videos
listSlides(params?)	List slides
listAIImages(params?)	List AI-generated items
getCreation(episodeId)	Get full creation detail
deleteCreations({ids})	Batch delete creations

Users

Method	Description
getCurrentUser()	Get current user profile
getSubscription()	Get subscription and credit usage info

Speakers

Method	Description
listSpeakers(params?)	List available speakers by language

Custom requests

client.api exposes the underlying ky instance for endpoints not yet covered by the SDK:

const user = await client.api.get('v1/users/me').json();

Rate limiting

On 429 Too Many Requests, the SDK reads the Retry-After header and retries automatically, up to maxRetries times (default: 2).

License

MIT