What makes this library special?

• Multiplatform: You can use it with Node.js, Deno on the server, or with client-side JavaScript.
• Comprehensive Spotify Auth support: It can handle all Spotify Auth flows and automatically refreshes access tokens.
• Modern: It leverages modern web APIs like native fetch, crypto, URLSearchParams and doesn't require any external dependencies.
• Lightweight and treeshakable: It's designed to be as small as possible (exact size TBD).
• TypeScript first: It's built with TypeScript and provides great support for it out of the box.
• Great docs: The library comes with extensive documentation and lots of examples to help you get started.

Installation

NPM npm.js/soundify-web-api

npm i soundify-web-api

Unfortunately, the soundify package on the NPM was already taken ;(

// For nodejs (server-side)
import { ... } from "soundify-web-api"

// For client-side javascript
import { ... } from "soundify-web-api/web"

Deno deno.land/x/soundify

// Import from denoland (recomended)
import { ... } from "https://deno.land/x/soundify/mod.ts"

// Import from github repo main branch 
import { ... } from "https://raw.githubusercontent.com/MellKam/soundify/main/mod.ts";

Gettings started

Let's write "Hello world!" with soundify.

import { getCurrentUserProfile, SpotifyClient } from "soundify-web-api";

const client = new SpotifyClient("YOUR_ACCESS_TOKEN");

const user = await getCurrentUserProfile(client);
console.log(user);

If your Access Token is valid it will output something like this

{
  "id": "31xofk5q7l22rvsbff7yiechyx6i",
  "display_name": "Soundify",
  "type": "user",
  "uri": "spotify:user:31xofk5q7l22rvsbff7yiechyx6i",
  // etc...
}

But how to get your Access Token?

If you just want to get a token quickly you can go to the Spotify Console. Then navigate to any endpoint and click on "GET TOKEN". You will be prompted to select scopes and then redirected to authentification. You will then have your token in the "OAuth Token" field.

Or you can try running one of our examples with a simple http server that will give you your token. With node examples/node-express-auth or with deno examples/deno-oak-auth

Authorization

If you have no experience with Spotify Auth you can read more about it in the Spotify Authorization Guide.

Auth Flows

Authorization flows are organized into separate namespaces, with each namespace containing all the necessary functions and classes to implement a specific authorization flow. This allows for easy importing of a specific flow.

For instance, the following code imports all authorization flow namespaces:

import { 
  // Authorization Code flow
  AuthCode, 
  // Authorization Code flow with PKCE
  PKCEAuthCode, 
  // Client Credentials flow
  ClientCredentials,
  // Implicit Grant flow 
  ImplicitGrant
} from "soundify-web-api"

You can take a look at the examples to see how to use each authorization flow.

• Authorization Code flow - examples/node-express-auth, examples/next-ssr, examples/deno-oak-auth
• Authorization Code flow with PKCE - examples/react-pkce-auth
• Client Credentials flow - TBD
• Implicit Grant flow - examples/react-implicit-grant

Auth provider and automatic tokens refreshing

As you saw earlier, you can simply pass the Access Token to SpotifyClient. But after some time (1 hour to be exact), it will expire and you'll need to deal with it yourself. Somehow get a new Access Token and set it on the client.

import { SpotifyClient } from "soundify-web-api"

const client = new SpotifyClient("ACCESS_TOKEN")
// ...
// Oops, token expires :(
client.setAuthProvider("NEW_ACCESS_TOKEN")

But if you don't want to deal with all that, you can just create an AuthProvider and pass it instead of the Access Token.

import { AuthCode, SpotifyClient } from "soundify-web-api";

const authProvider = new AuthCode.AuthProvider({
  client_id: "YOUR_SPOTIFY_CLIENT_ID",
  client_secret: "YOUR_SPOTIFY_CLIENT_SECRET",
  refresh_token: "YOUR_REFRESH_TOKEN",
});

const client = new SpotifyClient(authProvider);

You can create an AuthProvider from AuthCode, PKCEAuthCode, ClientCredentials flows. Implicit grant does not allow you to implement such a thing.

Auth Scopes

Scopes are usually used when creating authorization url. Pay attention to them, because many fields and endpoints may not be available if the correct scopes are not specified. Read the Spotify guide to learn more.

In Soundify scopes can be used as strings or with const object SCOPES.

import { SCOPES, AuthCode } from "soundify-web-api";

AuthCode.getAuthURL({
  scopes: ["user-read-email"],
  // or like this
  scopes: [SCOPES.USER_READ_EMAIL]
  // or use all scopes
  scopes: Object.values(SCOPES),
})

All contributions are very welcome ❤️