Spotify Web API TypeScript SDK

Use this pattern if you want your Node.js server to interact with Spotify 'as a specific user' by performing a client-side Authorization Code Flow with PKCE and passing the resulting token to your server.

1. Client Side: Trigger Authorization

Use performUserAuthorization to trigger the redirect and handle the token exchange. You can provide a callback for custom post-back logic.

// Redirect to a specific backend endpoint
SpotifyApi.performUserAuthorization("client-id", "https://localhost:3000", ["scope1"], "https://your-backend-server.com/accept-user-token");

// OR use a custom callback
SpotifyApi.performUserAuthorization("client-id", "https://localhost:3000", ["scope1"], (accessToken) => {
    /* perform custom postback here */
});

2. Server Side: Accept Token

Create an endpoint on your server to receive the token and initialize the SDK instance.

const { SpotifyApi } = require("@spotify/web-api-ts-sdk");
const express = require('express');
const bodyParser = require('body-parser'); 
const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: false }));

let sdk;

app.post('/accept-user-token', (req, res) => {
    let data = req.body;
    // Initialize SDK as the specific user
    sdk = SpotifyApi.withAccessToken("client-id", data);
}); 

app.listen(3000);

// Client Side
SpotifyApi.performUserAuthorization("client-id", "https://localhost:3000", ["scope1"], "https://your-backend-server.com/accept-user-token");

// Server Side
app.post('/accept-user-token', (req, res) => {
    let data = req.body;
    sdk = SpotifyApi.withAccessToken("client-id", data);
});

All constructors and static initialization methods accept an optional SdkConfiguration object to override default behaviors.

Default Configuration Schema

const defaultConfig: SdkConfiguration = {
    fetch: (req: RequestInfo | URL, init: RequestInit | undefined) => fetch(req, init),
    beforeRequest: (_: string, __: RequestInit) => { },
    afterRequest: (_: string, __: RequestInit, ___: Response) => { },
    deserializer: new DefaultResponseDeserializer(),
    responseValidator: new DefaultResponseValidator(),
    errorHandler: new NoOpErrorHandler(),
    redirectionStrategy: new DocumentLocationRedirectionStrategy(),
    cachingStrategy: isBrowser
        ? new LocalStorageCachingStrategy()
        : new InMemoryCachingStrategy()
};

Customizing the SDK

Pass your custom options object as the last argument to any factory method:

const opts = {
    fetch: (req, init) => {
        console.log("Called via my custom fetch!");
        return fetch(req, init);
    }
};

const sdk = SpotifyApi.withUserAuthorization("client-id", "https://callback", ["scope1"], opts);

The ICachingStrategy interface allows you to define how the SDK stores and retrieves cached API responses. This is useful for reducing network calls and improving performance.

To implement it, you must provide:

• getOrCreate<T>: A method to retrieve an item from cache or create it using a provided function if it doesn't exist.
• get<T>: Retrieve an existing item by its cacheKey.
• setCacheItem<T>: Manually add an item to the cache.
• remove: Remove an item from the cache.

Items stored in the cache should implement ICachable, which allows specifying an expires timestamp or an expiresOnAccess flag.

export interface ICachingStrategy {
    getOrCreate<T>(
        cacheKey: string,
        createFunction: () => Promise<T & ICachable & object>,
        updateFunction?: (item: T) => Promise<T & ICachable & object>
    ): Promise<T & ICachable>;

    get<T>(cacheKey: string): Promise<T & ICachable | null>;
    setCacheItem<T>(cacheKey: string, item: T & ICachable): void;
    remove(cacheKey: string): void;
}

export interface ICachable {
    expires?: number;
    expiresOnAccess?: boolean;
}