SDK · JavaScript / TypeScript
Spotify API Node SDK — @checkleaked/spotify-api
The official TypeScript client for this API: zero runtime dependencies, built on native fetch, runs on Node 18+, Deno, Bun, edge runtimes and the browser. 110 typed methods across 25 namespaces, and no OAuth anywhere.
Install and first call
| npm install @checkleaked/spotify-api |
Methods return the API's unwrapped data payload. The key can also come from SPOTIFY_API_KEY or RAPIDAPI_KEY in the environment.
What the package does for you
Zero dependencies, every runtime
Built on native fetch; ships ESM and CJS with complete .d.ts types. Node 18+, Deno, Bun, edge runtimes and browsers.
Ids, URIs and URLs interchangeably
Anywhere an id is expected, pass a bare Spotify id, a spotify: URI or an open.spotify.com URL; multi-id endpoints also take arrays. normalizeId and normalizeIds are exported.
Retries, timeouts, hooks
429 and 5xx are retried with exponential backoff honouring Retry-After; per-request timeouts; onRequest, onResponse and onRetry lifecycle hooks; a debug logger.
Pagination helpers
paginate() iterates any offset/limit endpoint page by page; collect() gathers everything up to maxItems or maxPages.
One error type
Any non-2xx response, or a body with success: false, throws SpotifyApiError with status, code, url, body and isRateLimit / isServerError / isTimeout flags.
RapidAPI-compatible
Defaults to the spotify81 RapidAPI host; provider: "proxy" switches to the direct portal with the same methods and paths.
Providers
One option switches between the two keyed channels; the methods and paths are identical.
| provider | Base URL | Key |
|---|---|---|
| rapidapi (default) | https://spotify81.p.rapidapi.com | Your RapidAPI key; the client adds x-rapidapi-host |
| proxy | https://spotify-proxy.checkleaked.cc/spotify-data | A key from the direct portal |
Errors, timeouts, cancellation
| import { SpotifyApiError, createClient } from "@checkleaked/spotify-api"; |
| const spotify = createClient({ apiKey: process.env.RAPIDAPI_KEY, timeoutMs: 30_000, retries: 2 }); |
| try { |
| await spotify.artists.overview({ id: "bad-id" }); |
| } catch (err) { |
| if (err instanceof SpotifyApiError) { |
| console.log(err.status, err.code, err.url); // e.g. 404, upstream code or TIMEOUT / NETWORK / ABORTED |
| console.log(err.isRateLimit, err.isServerError, err.isTimeout); |
| } |
| } |
| // Cancel a request |
| const controller = new AbortController(); |
| setTimeout(() => controller.abort(), 1000); |
| await spotify.search.search({ q: "muse" }, { signal: controller.signal }); |
Requests time out after 30 s by default; 429 and 5xx responses are retried twice with exponential backoff and jitter, honouring Retry-After. Any request takes an AbortSignal.
Namespaces
The client mirrors the reference: one namespace per endpoint group. Each links to the group's page, which lists every operation with its parameters and a runnable example.
- spotify.ai24
- spotify.artists10
- spotify.tracking9
- spotify.health8
- spotify.charts6
- spotify.partner6
- spotify.webhooks6
- spotify.batch5
- spotify.browse5
- spotify.concerts5
- spotify.search5
- spotify.tracks4
- spotify.albums3
- spotify.analysis3
- spotify.audiobooks3
- spotify.playlists3
- spotify.shows3
- spotify.cache2
- spotify.credentials2
- spotify.downloads2
- spotify.episodes2
- spotify.lookups2
- spotify.snapshots2
- spotify.users2
- spotify.markets1
FAQ
Does it need OAuth or a Spotify developer app?
No. The client sends one API key header. There is no client id, no token exchange and no refresh loop — the same reason the rest of this API needs none.
Which Node version?
Node 18 or newer, which is where native fetch arrived. Deno, Bun, Cloudflare Workers and browsers work with the same build.
Where do the method names come from?
The package documents 110 methods in 25 namespaces that mirror the endpoint groups on this site. Any endpoint without a dedicated method is reachable through spotify.request({ method, path, query }), which also returns the raw success envelope with its metadata.
Can I read the raw response envelope?
Yes. Methods return the unwrapped data field; spotify.request() returns the whole { success, data, metadata } envelope for pagination cursors and timings.
Is it open source?
MIT-licensed, published on npm as @checkleaked/spotify-api, version 1.0.0.
Get a key, then npm install
Free tier on RapidAPI; direct keys from $9 a month.