Spotify Web API TypeScript SDK

https://github.com/spotify/spotify-web-api-ts-sdk
Admin
A TypeScript SDK for the Spotify Web API with support for multiple authentication flows and...
Tokens:3,461
Snippets:50
Trust Score:9.7
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start the Project

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/CONTRIBUTING.md

Execute this command to run the project after installation. This is typically used for development or running the example app.

```bash
npm run start
```

--------------------------------

### Configure environment variables for example app

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Create a .env file in the example directory and add your Spotify client ID and redirect URL for testing purposes.

```env
VITE_SPOTIFY_CLIENT_ID=your_spotify_client_id_for_tests
VITE_REDIRECT_TARGET=http://localhost:3000
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/CONTRIBUTING.md

Run this command to install all necessary dependencies for the project. Ensure you are in the project's root directory.

```bash
npm install
```

--------------------------------

### Install SDK using npm

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Install the SDK package using npm. This command should be run in your project directory.

```bash
npm install @spotify/web-api-ts-sdk
```

--------------------------------

### Configure Example App Environment Variables

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/CONTRIBUTING.md

These environment variables are required for the embedded example app to function correctly. Place them in a .env file within the ./example directory.

```bash
VITE_SPOTIFY_CLIENT_ID=the same value as set in INTEGRATION_TESTS_SPOTIFY_CLIENT_ID
VITE_REDIRECT_TARGET=http://localhost:3000
```

--------------------------------

### Making an API Request

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Shows an example of how to use the authenticated SDK instance to perform a search query and process the results.

```APIDOC
## Making an API Request

Once you have an authenticated `SpotifyApi` instance, you can make requests to the Spotify Web API.

### Example: Searching for an Artist

This example demonstrates how to search for artists and display their names, follower counts, and popularity.

```js
// Assuming 'sdk' is an authenticated SpotifyApi instance
const items = await sdk.search("The Beatles", ["artist"]);

console.table(items.artists.items.map((item) => ({
    name: item.name,
    followers: item.followers.total,
    popularity: item.popularity,
})));
```

This operation leverages the SDK's type safety and autocompletion features.
```

--------------------------------

### Search for artists and display results

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Perform a search for a specific artist and log formatted results to the console. This example assumes an authenticated SDK instance is available.

```javascript
const items = await sdk.search("The Beatles", ["artist"]);

console.table(items.artists.items.map((item) => ({
    name: item.name,
    followers: item.followers.total,
    popularity: item.popularity,
})));
```

--------------------------------

### Get current user profile

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Fetch the current authenticated user's profile information. This requires an SDK instance created with user authorization.

```javascript
const sdk = SpotifyApi.withUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"]);
const user = await sdk.currentUser.profile()
```

--------------------------------

### Define Caching Strategy Interface

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Defines the `ICachingStrategy` interface for custom caching implementations. It includes methods for getting, setting, and removing cached items.

```typescript
interface ICachingStrategy {
    getOrCreate<T>(cacheKey: string, createFunction: () => Promise<T & ICachable & object>): Promise<T & ICachable>;
    get<T>(cacheKey: string): T & ICachable | null;
    setCacheItem<T>(cacheKey: string, item: T & ICachable): void;
    remove(cacheKey: string): void;
}
```

--------------------------------

### Creating a Client Instance

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Demonstrates how to create an instance of the SpotifyApi client using different authentication methods like User Authorization and Client Credentials.

```APIDOC
## Creating a Client Instance

This section shows how to initialize the `SpotifyApi` client for making requests.

### With User Authorization (Authorization Code Flow)

Use this method for browser-based applications where user consent is required.

```js
import { SpotifyApi } from '@spotify/web-api-ts-sdk';

const sdk = SpotifyApi.withUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"]);
```

### With Client Credentials

Use this method for server-side applications when you have your Client ID and Client Secret.

```js
import { SpotifyApi } from '@spotify/web-api-ts-sdk';

const sdk = SpotifyApi.withClientCredentials("client-id", "secret", ["scope1", "scope2"]);
```

Both methods return a `SpotifyApi` instance that can be used to interact with the Spotify Web API.
```

--------------------------------

### Initialize SDK with Custom Fetch Option

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Demonstrates how to initialize the Spotify SDK with a custom fetch implementation, allowing for custom request handling.

```javascript
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);
```

--------------------------------

### Run Project Tests

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/CONTRIBUTING.md

Use this command to execute the project's test suite. Ensure all required environment variables are set up.

```bash
npm run test
```

--------------------------------

### Server-Side Token Acceptance and SDK Initialization

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Sets up an Express.js server to accept user tokens via a POST request and initializes the Spotify SDK with the received access token.

```javascript
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;
    sdk = SpotifyApi.withAccessToken("client-id", data); // SDK now authenticated as client-side user
}); 
 
app.listen(3000, () => {
  console.log('Example app listening on port 3000!')
});
```

--------------------------------

### Create Spotify API client instances

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Instantiate the Spotify API client using either user authorization or client credentials. Ensure you replace placeholders with your actual client ID, redirect URI, and scopes.

```javascript
const sdk = SpotifyApi.withUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"]);
const sdk = SpotifyApi.withClientCredentials("client-id", "secret", ["scope1", "scope2"]);
```

--------------------------------

### Fetching Current User Profile

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Demonstrates how to fetch the profile information of the currently authenticated user using the SDK.

```APIDOC
## Fetching Current User Profile

This example shows how to retrieve the profile details of the user authenticated via the Authorization Code Flow.

### Method

```js
const user = await sdk.currentUser.profile()
```

### Usage

This method is available on an authenticated `SpotifyApi` instance obtained using `SpotifyApi.withUserAuthorization`.

```js
import { SpotifyApi } from '@spotify/web-api-ts-sdk';

const sdk = SpotifyApi.withUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"]);
const user = await sdk.currentUser.profile();
console.log(user);
```
```

--------------------------------

### Perform User Authorization (Client-Side)

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Initiates client-side Authorization Code Flow with PKCE. Use this to trigger redirects for permission grants and handle token exchange.

```javascript
SpotifyApi.performUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"], "https://your-backend-server.com/accept-user-token");
// Alternatively if you want to perform your own custom post-back
SpotifyApi.performUserAuthorization("client-id", "https://localhost:3000", ["scope1", "scope2"], (accessToken) => { /* do postback here */ });
```

--------------------------------

### Custom Fetch Implementation for SDK

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Provides a custom fetch function to override the default implementation for SDK requests. Useful for logging or modifying requests.

```javascript
const opts = {
    fetch: (req, init) => {
        // Do something with the request
        return fetch(req, init);
    }
}
```

--------------------------------

### Default SDK Configuration Object

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Defines the default configuration for the Spotify Web API TS SDK, including fetch, request callbacks, deserializers, and caching strategies.

```typescript
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()
};
```

--------------------------------

### Custom beforeRequest and afterRequest Callbacks for SDK

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Allows overriding the default beforeRequest and afterRequest callbacks to implement custom instrumentation or logging around SDK requests.

```javascript
const opts = {
    beforeRequest: (req, init) => {
        console.log("Called before the request is made");
    },
    afterRequest: (req, init, res) => {
        console.log("Called after the request is made");
    }
}
```

--------------------------------

### Custom Deserializer Interface for SDK

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Defines the interface for a custom response deserializer in the Spotify SDK. Implement this to customize deserialization logic or add logging.

```typescript
async deserialize<TReturnType>(response: Response): Promise<TReturnType> {
    // Implement your custom deserialization logic here
}
```

--------------------------------

### Implement Custom Error Handler

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Customize error handling by implementing the `IHandleErrors` interface. Returning `true` from `handleErrors` prevents the SDK from throwing an error, while `false` re-throws the original error.

```typescript
export default class MyErrorHandler implements IHandleErrors {
    public async handleErrors(error: any): Promise<boolean> {
        return false;
    }
}
```

--------------------------------

### Implement Custom Redirection Strategy

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Override the default redirection strategy by implementing the `IRedirectionStrategy` interface. This is useful for client-side frameworks where state management or operations are needed before redirecting.

```typescript
export default class DocumentLocationRedirectionStrategy implements IRedirectionStrategy {
    public async redirect(targetUrl: string | URL): Promise<void> {
        document.location = targetUrl.toString();
    }

    public async onReturnFromRedirect(): Promise<void> {
    }
}
```

--------------------------------

### Implement Custom Response Validator

Source: https://github.com/spotify/spotify-web-api-ts-sdk/blob/main/README.md

Override the default response validation by implementing the `IValidateResponses` interface. This allows custom logic for checking response status codes and handling errors.

```typescript
export default class MyResponseValidator implements IValidateResponses {
    public async validateResponse(response: Response): Promise<void> {
        // Something here
    }
}
```
Tokens:
Raw