An easy-to-use zero-dependencies node.js wrapper for the Spotify API.

All versions are written in node.js v18.17.0 and have no dependencies.

Some of the most notable capabilities:

• Fetching a Spotify Token in each one of the four ways specified in the Spotify API documentation;
• Simple & documented methods to request anything from the api;
• Access token auto-refreshing

Note free accounts can only be used for browsing and current playback status. Only premium accounts can be controlled (pause, play, next, etc.).

const SpotifyAPI = require("spoteasy");

To fetch the Spotify API, you must first create a token. The purpose of this library is to make that as easy as possible. There are four ways to create one, as described in the Spotify API documentation, and each one has its advantages and disadvantages.

Note that each method requires a Spotify Client ID (and sometimes a Spotify Client Secret). You can get both of them by creating an app in the Spotify Dashboard and accessing the app credentials.

I've made two examples that use the Client Credentials Flow and the Authorization Code PKCE Flow

let spoteasy = new SpotifyAPI()
spoteasy.clientCredentialsFlow("<Client ID>", "<Client Secret>")

Adds a "token" property to the "spoteasy" object. The "token" property contains an object with various useful properties, beyond the actual access token.

For security reasons, do not hardcode the client ID and Secret in your code. Consider using environment variables or configuration files.

Now let's try to fetch an album from the Spotify API.

// Same as spoteasy.getAlbum("6PFPjumGRpZnBzqnDci6qJ")
// Also, if you are in an async function, you can, of course, "await" the Promise.
spoteasy.getAlbum("https://open.spotify.com/album/6PFPjumGRpZnBzqnDci6qJ")
  .then(res => {
    let tracklist = res.tracks.items
    console.log(tracklist.map(track => track.name))
  })

/*
  [
    'Papercut',
    'One Step Closer',
    'With You',
    'Points of Authority',
    'Crawling',
    'Runaway',
    'By Myself',
    'In the End',
    'A Place for My Head',
    'Forgotten',
    'Cure for the Itch',
    'Pushing Me Away'
  ]
*/

Now let's create a playlist in a logged user's account. To do this, we have to make the user log in into his spotify account. The next example will use the express.js library to do that. (Note: it's a very barebones implementation, useful only for explanation purposes.)

As you can see (and can also be seen from the JSDOC documentation), it's stated that to do that we need two authorization scopes: "playlist-modify-public" and "playlist-modify-private". These tell spotify what we are about to do with the user's account. We can pass them as arguments in the authorization code PKCE method.

const SpotifyAPI = require("spoteasy")
let spoteasy = new SpotifyAPI()

app.get("/auth", async (req, res) => {
  // If the URL query is empty (thus user hasn't logged in yet).
  if (Object.keys(req.query).length === 0) {
    // Create the Spotify authentication URL, using the authorization code PKCE flow.
    let url = spoteasy.authorizationCodePKCEFlow(
      // Your Spotify Client ID.
      "<Client ID>",
      // Redirect back to this URL after the user logs in.
      // WARNING! you must whitelist this URL in the redirect URI section of the spotify app settings.
      "https://whatever.webpage.com/auth",
      {
        // The scopes that the user will be asked to authorize.
        scope: ["playlist-modify-public", "playlist-modify-private"]
      }
    )

    // Redirect the user to the Spotify authentication page.
    res.status(100).redirect(url)
  }
  // If the auth code is in the URL query (thus user was redirected back from the spotify auth page).
  // & if the token is waiting to be resolved.
  else if ("code" in req.query && "resolve" in spoteasy.token) {
    // Resolve the authentication code in the URL query to finally create the access token.
    await spoteasy.resolveToken(req.query)

    // We are now logged in. Let's create a playlist.
    // The ID of the current user can be obtained via the Get Current User's Profile endpoint
    let currentUser = await spoteasy.getCurrentUserProfile()

    // Create a playlist in the user's account.
    let response = await spoteasy.createPlaylist(currentUser.id, {
      name: "Hello World",
      public_playlist: false,
      description: "Your coolest playlist"
    })

    // Print out the url of the just created playlist
    console.log( response.external_urls.spotify )

    // Do whatever after the user logs in.
    res.status(202).redirect("https://whatever.webpage.com/")
  }
  // If user rejected the authentication request.
  else {
    // Do whatever after the user rejects the authentication request.
    res.status(401).redirect("https://whatever.webpage.com/")
  }
})

*Note that the methods and parameters are fully documented in the JSDOC methods comments

These are the properties that the token object might have during or after its creation with one of the 4 methods

Watch out for this section if you wish to migrate to a different version.

• v1.1.0:
  - Added "searchTrack" method
  - Added declaration file.
  - Removed minified version.

• v1.2.0:
  - Added "tracksParser" parser, and placed it as the default parser of the "request" method.

• v1.3.0:
  - Added "precautionSeconds" option on constructor.
  - Added "refresh_timeout", "expires_now_in" and "auto_refresh" token properties.

  • v1.3.1:
    - Fixed bug where the "searchTrack" method wouldn't parse its track.
  
  

• v1.4.0
  - Added "isValidURL" method.
  - Fixed trackParser bug regarding episodes.

• v1.5.0:
  - Added a shorthand for every SpotifyAPI endpoint as of this version upload date.
  - Added a "defaultMarket" option on constructor.
  - Fixed a bug where an empty response would throw an Exception.

• v1.6.0:
  - Added URL "id", "ids" and "uris" parsing for every SpotifyAPI endpoint shorthand.

  • v1.6.1:
    - Fixed bug where the "public_playlist" property won't work.
  • v1.6.2:
    - Updated spoteasy declaration file.
  
  

• v1.7.0:
  - Added "getMagic" method.
  - Added "responseParser" option on constructor.
  - Added "promise" token property.
  - Fixed declaration file link in package.json.

  • v1.7.1:
    - Fixed wrong JSDOC parameter types.
    - Fixed "startOrResumePlayback" method that won't parse URIs.
  
  

• v1.8.0:
  - Added "awaitToken" option on constructor.
  - Fixed broken JSDOC optional parameters types, caused by patch v1.7.1

• v2.0.0:
  - Removed "parser" option from "request" method. You can choose the response parser by setting the "responseParser" property either in the constructor or whenever you need it in the SpotifyAPI class object.
  - Made "scope" property in the token obect an Array of scopes, instead of a string of scopes separated by a space " ".
  - Made "image" parameter an optional one in the method "addCustomPlaylistCover".
  - Made "searchTrack" method return the actual response, not only the parsed track (This will also affect the "getMagic" method).
  - Fixed bug where a track object with no external url would crash "trackParser".

• v2.1.0:
  - Updated shorthands so that they use body instead of query when possible to send requests (to avoid exceeding the maximum length of the request URI).
  - Fixed bugs where a lot of Playlists related shorthands used body instead of query to send requests or viceversa, making them unusable.
  - Fixed bugs where some shorthands wouldn't parse given URLs/URIs

• v2.2.0:
  - Added "trackParser" support for getting several albums. This might also generally fix some bugs with the parser, as the previously used method was changed to a more flexible one.

• v3.0.0:
  - Completely migrated to TypeScript.
  - Updated parameters to the ones accepted by current Spotify API.
  - Made "name" parameter in the "createPlaylist" method mandatory, and moved it out of the "options" object.
  - Made "seed_artists", "seed_genres" and "seed_tracks" parameters in the "getRecommendations" method optional, and moved them in the "options" object.
  - Fixed wrong parameter types & a few bugs.

Please open an issue on Github to request a change, report a bug or ask for help about something and i will gladly look into it.

If you like this library, consider giving it a star on Github. It means a lot :)