Soundify is a lightweight and flexible library for interacting with the Spotify API, designed to work seamlessly with TypeScript and support all available runtimes.

Getting Started | Error handling | Token refreshing | Pagination

Installation

The package doesn't depend on runtime specific apis, so you should be able to use it without any problems everywhere.

pnpm add @soundify/web-api
bun install @soundify/web-api
// deno.json
{
    "imports": {
        "@soundify/web-api": "https://deno.land/x/soundify/mod.ts"
    }
}

Getting Started

Soundify has a very simple structure. It consists of a SpotifyClient capable of making requests to the Spotify API, along with a set of functions (like getCurrentUser) that utilize the client to make requests to specific endpoints.

import { getCurrentUser, search, SpotifyClient } from "@soundify/web-api";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN");

const me = await getCurrentUser(client);
console.log(me);

const result = await search(client, "track", "Never Gonna Give You Up");
console.log(result.tracks.items.at(0));

Compared to the usual OOP way of creating API clients, this approach has several advantages. The main one is that it is tree-shakable. You only ship code you use. This may be not that important for server-side apps, but I'm sure frontend users will thank you for not including an extra 10kb of crappy js into your bundle.

import {
    getAlbumTracks,
    getArtist,
    getArtistAlbums,
    getRecommendations,
    SpotifyClient,
} from "@soundify/web-api";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN");

const radiohead = await getArtist(client, "4Z8W4fKeB5YxbusRsdQVPb");
console.log(`Radiohead popularity - ${radiohead.popularity}`);

const pagingResult = await getArtistAlbums(client, radiohead.id, { limit: 1 });
const album = pagingResult.items.at(0)!;
console.log(`Album - ${album.name}`);

const tracks = await getAlbumTracks(client, album.id, { limit: 5 });
console.table(
    tracks.items.map((track) => ({
        name: track.name,
        duration: track.duration_ms,
    })),
);

const recomendations = await getRecommendations(client, {
    seed_artists: [radiohead.id],
    seed_tracks: tracks.items.map((track) => track.id).slice(0, 4),
    market: "US",
    limit: 5,
});
console.table(
    recomendations.tracks.map((track) => ({
        artist: track.artists.at(0)!.name,
        name: track.name,
    })),
);

Error handling 📛

import { getCurrentUser, SpotifyClient, SpotifyError } from "@soundify/web-api";

const client = new SpotifyClient("INVALID_ACCESS_TOKEN");

try {
    const me = await getCurrentUser(client);
    console.log(me);
} catch (error) {
    if (error instanceof SpotifyError) {
        error.status; // 401

        const message = typeof error.body === "string"
            ? error.body
            : error.body?.error.message;
        console.error(message); // "Invalid access token"

        error.response.headers.get("Date"); // You can access the response here

        console.error(error);
        // SpotifyError: 401 Unauthorized (https://api.spotify.com/v1/me) : Invalid access token
        return;
    }

    // If it's not a SpotifyError, then it's some type of network error that fetch throws
    // Or can be DOMException if you abort the request
    console.error("We're totally f#%ked!");
}

Rate Limiting 🕒

If you're really annoying customer, Spotify may block you for some time. To know what time you need to wait, you can use Retry-After header, which will tell you time in seconds. More about rate limiting↗

To handle this automatically, you can use waitForRateLimit option in SpotifyClient. (it's disabled by default, because it may block your code for unknown time)

const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
    waitForRateLimit: true,
    // wait only if it's less than a minute
    waitForRateLimit: (retryAfter) => retryAfter < 60,
});

Authorization

Soundify doesn't provide any tools for authorization, because that would require to write whole oauth library in here. We have many other battle-tested oauth solutions, like oauth4webapi or oidc-client-ts. I just don't see a point in reinventing the wheel 🫤.

Despite this, we have a huge directory of examples, including those for authorization. OAuth2 Examples↗

Token Refreshing

import { getCurrentUser, SpotifyClient } from "@soundify/web-api";

const refresher = () => {
    // This function should return a new access token
    // You can use any library you want to refresh the token
    // Or even make it yourself, we don't care
    return Promise.resolve("YOUR_NEW_ACCESS_TOKEN");
};

const accessToken = await refresher();
const client = new SpotifyClient(accessToken, { refresher });

const me = await getCurrentUser(client);
console.log(me);

// wait some time to expire the token ...
// 2000 YEARS LATER 🧽

const me = await getCurrentUser(client);
// client will receive 401 and call your refresher to get new token
// you don't have to worry about it as long as your refresher is working
console.log(me);

Pagination

To simplify the process of paginating through the results, we provide a PageIterator class.

import { getPlaylistTracks, SpotifyClient } from "@soundify/web-api";
import { PageIterator } from "@soundify/web-api/pagination";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
    waitForRateLimit: true,
});

const playlistIter = new PageIterator(
    (opts) => getPlaylistTracks(client, "37i9dQZEVXbMDoHDwVN2tF", opts),
);

// iterate over all tracks in the playlist
for await (const track of playlistIter) {
    console.log(track);
}

// or collect all tracks into an array
const allTracks = await playlistIter.collect();
console.log(allTracks.length);

Other customizations

import { SpotifyClient } from "@soundify/web-api";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN", {
    // You can use any fetch implementation you want
    // For example, you can use `node-fetch` in node.js
    fetch: (input, init) => {
        return fetch(input, init);
    },
    // You can change the base url of the client
    // by default it's "https://api.spotify.com/"
    beseUrl: "https://example.com/",
    middlewares: [(next) => (url, opts) => {
        // You can add your own middleware
        // For example, you can add some headers to every request
        return next(url, opts);
    }],
});

Contributors ✨

All contributions are very welcome ❤️ (emoji key)

Artem Melnyk
Artem Melnyk
🚧		 danluki
danluki
💻