diff --git a/spotify-web-api-node/.travis.yml b/spotify-web-api-node/.travis.yml new file mode 100644 index 0000000..aca4270 --- /dev/null +++ b/spotify-web-api-node/.travis.yml @@ -0,0 +1,5 @@ +language: node_js +node_js: + - 14 +after_success: + - npm run travis diff --git a/spotify-web-api-node/CHANGELOG.md b/spotify-web-api-node/CHANGELOG.md new file mode 100644 index 0000000..0a31100 --- /dev/null +++ b/spotify-web-api-node/CHANGELOG.md @@ -0,0 +1,213 @@ +## Change log + +#### 5.0.2 (Jan 2021) + +* Fix: Make `transferMyPlayback` not require the `options` object, since it should be optional. Thanks for the heads-up [@Simber1](https://github.com/Simber1)! + +#### 5.0.1 (Jan 2021) + +* Fix error handling in the HTTP client. Thanks [@yamadapc](https://github.com/yamadapc)! +* This package can currently not be built on **Node 15 on Linux**, due to a dependency not being available yet. Issue can be followed on the [node-canvas](https://github.com/Automattic/node-canvas/issues/1688) issue tracker. In the mean time, Travis CI will run on earlier versions of Node. + +#### 5.0.0 (Oct 2020) + +* **BREAKING CHANGES**. + * Arguments for some API methods have changed, causing incorrect behaviour using argument order from version 4.x. See the `README.md` for examples of how the methods can be used. + * Create Playlist (`createPlaylist`) method no longer accepts a `userId` string as its first argument. + * Transfer A User's Playback (`transferMyPlayback`) method takes a `deviceIds` array as its first argument. + * Skip to Previous (`skipToPrevious`) method takes an `options` object as its first argument. + * Skip to Next (`skipToNext`) method takes an `options` object as its first argument. + * Set Repeat Mode on the Current User's Playback (`setRepeat`) method takes a `state` string as its first argument. + * Set Shuffle Mode on the Current User's Playback (`setShuffle`) method takes a `state` string as its first argument. + + Cheers [@marinacrachi](https://github.com/marinacrachi) for the createPlaylist update. + * Removed legacy support for not passing an `options` object while providing a callback method. This was only supported on a few of the older endpoints, and could lead to tricky bugs. The affected endpoints are `getTrack`, `getTracks`, `getAlbum`, `getAlbums`, and `createPlaylist`. Again, check the `README.md` for examples on how these methods can be used if needed. + * Removed `options` argument for retrieving an access token using the Client Credentials flow, `clientCredentialsGrant`. + * API errors come in five different flavours. + * WebapiRegularError - For errors returned by most API endpoints. + * WebapiPlayerError - For errors returned by the Player API. These contain a bit more information. + * WebapiAuthenticationError - For errors related to authentication. + * WebapiError - For errors that come from the Web API that didn't fit into one of the above. + * TimeoutError - For network timeout errors. + + More importantly, errors now contain the response body, headers, and status code. One side-effect of this is that rate limited requests can be handled by checking the `Retry-After` header. Thanks for the PRs [@kauffecup](https://github.com/kauffecup), [@lantelyes](https://github.com/lantelyes), [@dkliemsch](https://github.com/dkliemsch), and [@erezny](https://github.com/erezny). + + Much appreciated [@konstantinjdobler](https://github.com/konstantinjdobler) for updates to the Player API errors. +* Added support for [Implicit Grant flow](https://developer.spotify.com/documentation/general/guides/authorization-guide/#implicit-grant-flow) - Thanks [@gaganza](https://github.com/gaganza), [@reblws](https://github.com/reblws) and [@noahp78](https://github.com/noahp78)! +* Starts or Resumes the Current User's Playback (`play`) method now supports the `position_ms` option. Thanks [@alqubo](https://github.com/alqubo), [@koflin](https://github.com/koflin), [@DoctorFishy](https://github.com/DoctorFishy). Thanks [@carmilso](https://github.com/carmilso) for general improvements to the Player API methods. +* Binding for [Add an Item to the User's Playback Queue](https://developer.spotify.com/documentation/web-api/reference/player/add-to-queue/) endpoint added. Thanks [@thattomperson](https://github.com/thattomperson) and [@AriciducaZagaria](https://github.com/AriciducaZagaria)! +* Binding for all [Shows and Episodes endpoints](https://developer.spotify.com/console/shows/). Thanks a _lot_ [@andyruwruw](https://github.com/andyruwruw)! +* Documentation updates to keep up to date with ES6, thanks [@dandv](https://github.com/dandv)! Other documentation improvements by [@terensu-desu](https://github.com/terensu-desu), and examples by [@dersimn](https://github.com/dersimn). Thanks! +* Bumped dependencies to resolve critical security issues. +* Finally, hat off to [@dersimn](https://github.com/dersimn). Thanks for collecting all of the lingering PRs and merging them into a working and up-to-date fork. You really stepped up. + +Likely more changes coming before release to npm, which will happen shortly. + +#### 4.0.0 (14 Sep 2018) + +* Modified functions that operate on playlists to drop the user id parameter. This is a breaking change. [PR](https://github.com/thelinmichael/spotify-web-api-node/pull/243) +* Updated superagent to fix a security warning [PR](https://github.com/thelinmichael/spotify-web-api-node/pull/211) +* Fixed a bug by which an empty user was not handled properly in getUserPlaylists(). [PR](https://github.com/thelinmichael/spotify-web-api-node/pull/244) + +#### 3.1.1 (29 Apr 2018) + +* Modernized stack for a better developer experience. Integrated [prettier](https://github.com/thelinmichael/spotify-web-api-node/pull/205) and [jest](https://github.com/thelinmichael/spotify-web-api-node/pull/206). This simplifies the amount of dev dependencies. +* Improved calls to save and remove saved tracks by adding a key as specified in the Spotify docs (See [PR](https://github.com/thelinmichael/spotify-web-api-node/pull/207)). Thanks to [@yanniz0r](https://github.com/yanniz0r) and [@adcar](https://github.com/adcar) for bringing it up. + +#### 3.1.0 (26 Apr 2018) + +* Added support for seeking and setting volume. Thanks to [@isokar](https://github.com/isokar), [@jamesemwallis](https://github.com/jamesemwallis), [@ashthespy](https://github.com/ashthespy), and [@vanderlin](https://github.com/vanderlin) for your PRs. + +#### 3.0.0 (8 Mar 2018) + +* @DalerAsrorov added support for uploading a custom image to a playlist in [this PR](https://github.com/thelinmichael/spotify-web-api-node/pull/169). +* You can now pass a `device_id` when playing and pausing playback. @pfftdammitchris started [a PR to add device_id to the play() method](https://github.com/thelinmichael/spotify-web-api-node/pull/185). The changes served to another PR where we included the functionality. Thanks! +* Added documentation in the README for `getMyCurrentPlaybackState()`. Thanks @PanMan for [your PR](https://github.com/thelinmichael/spotify-web-api-node/pull/160)! +* @brodin realized we there was a lot of duplicated code and refactored it in a [great PR](https://github.com/thelinmichael/spotify-web-api-node/pull/123). + +#### 2.5.0 (4 Sep 2017) + +* Change README to reflect new authorization. Thanks [@arirawr](https://github.com/arirawr) for the [PR](https://github.com/thelinmichael/spotify-web-api-node/pull/146). +* Add support for 'show_dialog' parameter when creating authorization url. Thanks [@ajhaupt7](https://github.com/ajhaupt7) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/101). +* Add support for playback control (play, pause, prev, next), shuffle and repeat. Thanks [@JoseMCO](https://github.com/JoseMCO) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/150). +* Add support for currently playing. Thanks [@dustinblackman](https://github.com/dustinblackman) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/145). +* Fix to remove unnecessary deviceIds parameter from request to transfer playback. Thanks [@philnash](https://github.com/philnash) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/154). + +#### 2.4.0 (2 May 2017) + +* Change `addTracksToPlaylist` to pass the data in the body, preventing an issue with a long URL when passing many tracks. Thanks [@dolcalmi](https://github.com/dolcalmi) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/117) +* Add support for fetching [recently played tracks](https://developer.spotify.com/web-api/console/get-recently-played/). Thanks [@jeremyboles](https://github.com/jeremyboles) for [the PR](https://github.com/thelinmichael/spotify-web-api-node/pull/111). + +#### 2.3.6 (15 October 2016) + +* Add language bindings for the **[Get Audio Analysis for a Track](https://developer.spotify.com/web-api/get-audio-analysis/)** endpoint. + +#### 2.3.5 (20 July 2016) + +* Use `encodeURIComponent` instead of `encodeURI` to encode the user's id. 'encodeURI' wasn't encoding characters like `/` or `#` that were generating an invalid endpoint url. Thanks [@jgranstrom](https://github.com/jgranstrom) for the PR. + +#### 2.3.4 (18 July 2016) + +* Fixed a bug in `clientCredentialsGrant()`. + +#### 2.3.3 (18 July 2016) + +* Migrated to the `superagent` request library to support Node.JS and browsers. Thanks [@SomeoneWeird](https://github.com/SomeoneWeird) for the PR to add it, and [@erezny](https://github.com/erezny) for reporting bugs. + +#### 2.3.2 (10 July 2016) + +* Add language bindings for **[Get a List of Current User's Playlists](https://developer.spotify.com/web-api/get-a-list-of-current-users-playlists/)**. Thanks [@JMPerez](https://github.com/JMPerez) and [@vinialbano](https://github.com/vinialbano). + +#### 2.3.1 (3 July 2016) + +* Fix for `getRecomendations` method causing client error response from the API when making the request. Thanks [@kyv](https://github.com/kyv) for reporting, and [@Boberober](https://github.com/Boberober) and [@JMPerez](https://github.com/JMPerez) for providing fixes. + +#### 2.3.0 (2 April 2016) + +* Add language bindings for **[Get Recommendations Based on Seeds](https://developer.spotify.com/web-api/get-recommendations/)**, **[Get a User's Top Artists and Tracks](https://developer.spotify.com/web-api/get-users-top-artists-and-tracks/)**, **[Get Audio Features for a Track](https://developer.spotify.com/web-api/get-audio-features/)**, and **[Get Audio Features for Several Tracks](https://developer.spotify.com/web-api/get-several-audio-features/)**. Read more about the endpoints in the links above or in this [blog post](https://developer.spotify.com/news-stories/2016/03/29/api-improvements-update/). +* Add generic search method enabling searches for several types at once, e.g. search for both tracks and albums in a single request, instead of one request for track results and one request for album results. + +#### 2.2.0 (23 November 2015) + +* Add language bindings for **[Get User's Saved Albums](https://developer.spotify.com/web-api/get-users-saved-albums/)** and other endpoints related to the user's saved albums. + +#### 2.1.1 (23 November 2015) + +* Username encoding bugfix. + +#### 2.1.0 (16 July 2015) + +* Add language binding for **[Get Followed Artists](https://developer.spotify.com/web-api/get-followed-artists/)** + +#### 2.0.2 (11 May 2015) + +* Bugfix for retrieving an access token through the Client Credentials flow. (Thanks [Nate Wilkins](https://github.com/Nate-Wilkins)!) +* Add test coverage and Travis CI. + +#### 2.0.1 (2 Mar 2015) + +* Return WebApiError objects if error occurs during authentication. + +#### 2.0.0 (27 Feb 2015) + +* **Breaking change**: Response object changed. Add headers and status code to all responses to enable users to implement caching. + +#### 1.3.13 (26 Feb 2015) + +* Add language binding for **[Reorder tracks in a Playlist](https://developer.spotify.com/web-api/reorder-playlists-tracks/)** + +#### 1.3.12 (22 Feb 2015) + +* Add language binding for **[Remove tracks in a Playlist by Position](https://developer.spotify.com/web-api/remove-tracks-playlist/)** + +#### 1.3.11 + +* Add **[Search for Playlists](https://developer.spotify.com/web-api/search-item/)** endpoint. + +#### 1.3.10 + +* Add market parameter to endpoints supporting **[Track Relinking](https://developer.spotify.com/web-api/track-relinking-guide/)**. +* Improve SEO by adding keywords to the package.json file. ;-) + +#### 1.3.8 + +* Add **[Get a List of Categories](https://developer.spotify.com/web-api/get-list-categories/)**, **[Get a Category](https://developer.spotify.com/web-api/get-category/)**, and **[Get A Category's Playlists](https://developer.spotify.com/web-api/get-categorys-playlists/)** endpoints. + +#### 1.3.7 + +* Add **[Check if Users are Following Playlist](https://developer.spotify.com/web-api/check-user-following-playlist/)** endpoint. + +#### 1.3.5 + +* Add missing options parameter in createPlaylist (issue #19). Thanks for raising this [allinallin](https://github.com/allinallin). + +#### 1.3.4 + +* Add **[Follow Playlist](https://developer.spotify.com/web-api/follow-playlist/)** and **[Unfollow Playlist](https://developer.spotify.com/web-api/unfollow-playlist/)** endpoints. + +#### 1.3.3 + +* [Fix](https://github.com/thelinmichael/spotify-web-api-node/pull/18) error format. Thanks [extrakt](https://github.com/extrakt). + +#### 1.3.2 + +* Add ability to use callback methods instead of promise. + +#### 1.2.2 + +* Bugfix. api.addTracksToPlaylist tracks parameter can be a string or an array. Thanks [ofagbemi](https://github.com/ofagbemi)! + +#### 1.2.1 + +* Add **[Follow endpoints](https://developer.spotify.com/web-api/web-api-follow-endpoints/)**. Great work [JMPerez](https://github.com/JMPerez). + +#### 1.1.0 + +* Add **[Browse endpoints](https://developer.spotify.com/web-api/browse-endpoints/)**. Thanks [fsahin](https://github.com/fsahin). + +#### 1.0.2 + +* Specify module's git repository. Thanks [vincentorback](https://github.com/vincentorback). + +#### 1.0.1 + +* Allow options to be set when retrieving a user's playlists. Thanks [EaterOfCode](https://github.com/EaterOfCode). + +#### 1.0.0 + +* Add **[Replace tracks in a Playlist](https://developer.spotify.com/web-api/replace-playlists-tracks/)** endpoint +* Add **[Remove tracks in a Playlist](https://developer.spotify.com/web-api/remove-tracks-playlist/)** endpoint +* Return errors as Error objects instead of unparsed JSON. Thanks [niftylettuce](https://github.com/niftylettuce). + +#### 0.0.11 + +* Add **[Change Playlist details](https://developer.spotify.com/web-api/change-playlist-details/)** endpoint (change published status and name). Gracias [JMPerez](https://github.com/JMPerez). + +#### 0.0.10 + +* Add Your Music Endpoints (**[Add tracks](https://developer.spotify.com/web-api/save-tracks-user/)**, **[Remove tracks](https://developer.spotify.com/web-api/remove-tracks-user/)**, **[Contains tracks](https://developer.spotify.com/web-api/check-users-saved-tracks/)**, **[Get tracks](https://developer.spotify.com/web-api/get-users-saved-tracks/)**). +* Documentation updates (change scope name of playlist-modify to playlist-modify-public, and a fix to a parameter type). Thanks [JMPerez](https://github.com/JMPerez) and [matiassingers](https://github.com/matiassingers). + +#### 0.0.9 + +* Add **[Related artists](https://developer.spotify.com/web-api/get-related-artists/)** endpoint diff --git a/spotify-web-api-node/LICENSE b/spotify-web-api-node/LICENSE new file mode 100644 index 0000000..8830137 --- /dev/null +++ b/spotify-web-api-node/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2014-2021 Michael Thelin + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/spotify-web-api-node/README.md b/spotify-web-api-node/README.md new file mode 100644 index 0000000..1e7a9cd --- /dev/null +++ b/spotify-web-api-node/README.md @@ -0,0 +1,1245 @@ +# Spotify Web API Node + +[![Tests](https://travis-ci.org/thelinmichael/spotify-web-api-node.svg?branch=master)](https://travis-ci.org/thelinmichael/spotify-web-api-node) +[![Coverage Status](https://coveralls.io/repos/thelinmichael/spotify-web-api-node/badge.svg)](https://coveralls.io/r/thelinmichael/spotify-web-api-node) +[![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/spotify-web-api-node.svg)](https://bundlephobia.com/result?p=spotify-web-api-node) + +This is a universal wrapper/client for the [Spotify Web API](https://developer.spotify.com/web-api/) that runs on Node.JS and the browser, using [browserify](http://browserify.org/)/[webpack](https://webpack.github.io/)/[rollup](http://rollupjs.org/). A list of selected wrappers for different languages and environments is available at the Developer site's [Libraries page](https://developer.spotify.com/documentation/web-api/libraries/). + +Project owners are [thelinmichael](https://github.com/thelinmichael) and [JMPerez](https://github.com/JMPerez), with help from [a lot of awesome contributors](https://github.com/thelinmichael/spotify-web-api-node/network/members). + +## Version 5 + +> :warning: Since the last release (4.0.0, released over year ago) a lot of new functionality has been added by a lot of different contributors. **Thank you.** In order to implement some of the feature requests, some **breaking changes** had to be made. A list of them, along with a list of the new functionality, can be found in the [CHANGELOG](https://github.com/thelinmichael/spotify-web-api-node/blob/master/CHANGELOG.md). + +## Table of contents + +* [Features](#features) +* [Installation](#installation) +* [Usage](#usage) +* [Development](#development) + +## Features + +The library includes helper functions to do the following: + +#### Fetch music metadata + +* Albums, artists, and tracks +* Audio features and analysis for tracks +* Albums for a specific artist +* Top tracks for a specific artist +* Artists similar to a specific artist + +#### Profiles + +* User's emails, product type, display name, birthdate, image + +#### Search + +* Albums, artists, tracks, and playlists + +#### Playlist manipulation + +* Get a user's playlists +* Create playlists +* Change playlist details +* Add tracks to a playlist +* Remove tracks from a playlist +* Replace tracks in a playlist +* Reorder tracks in a playlist + +#### Your Music library + +* Add, remove, and get tracks and albums that are in the signed in user's Your Music library +* Check if a track or album is in the signed in user's Your Music library + +#### Personalization + +* Get a user’s top artists and tracks based on calculated affinity + +#### Browse + +* Get New Releases +* Get Featured Playlists +* Get a List of Categories +* Get a Category +* Get a Category's Playlists +* Get recommendations based on seeds +* Get available genre seeds + +#### Player + +* Get a User's Available Devices +* Get Information About The User's Current Playback State +* Get Current User's Recently Played Tracks +* Get the User's Currently Playing Track +* Pause a User's Playback +* Seek To Position In Currently Playing Track +* Set Repeat Mode On User’s Playback +* Set Volume For User's Playback +* Skip User’s Playback To Next Track +* Skip User’s Playback To Previous Track +* Start/Resume a User's Playback +* Toggle Shuffle For User’s Playback +* Transfer a User's Playback + +#### Follow + +* Follow and unfollow users +* Follow and unfollow artists +* Check if the logged in user follows a user or artist +* Follow a playlist +* Unfollow a playlist +* Get followed artists +* Check if users are following a Playlist + +#### Player + +* Add an Item to the User's Playback Queue +* Get a user's available devices +* Get information about the user's current playback +* Get current user’s recently played tracks +* Transfer a user's playback +* Resume a user's playback +* Skip a user's playback to next track +* Skip a user's playback to previous track +* Set a user's shuffle mode +* Set a user's repeat mode +* Set volume +* Seek playback to a given position + +#### Shows + +* [Get a Show](https://developer.spotify.com/documentation/web-api/reference/shows/get-a-show/) + +### Authentication + +All methods require authentication, which can be done using these flows: + +* [Client credentials flow](http://tools.ietf.org/html/rfc6749#section-4.4) (Application-only authentication) +* [Authorization code grant](http://tools.ietf.org/html/rfc6749#section-4.1) (Signed by user) +* [Implicit Grant Flow](https://tools.ietf.org/html/rfc6749#section-4.2) (Client-side Authentication) + +##### Dependencies + +This project depends on [superagent](https://github.com/visionmedia/superagent) to make HTTP requests. + +## Installation + + $ npm install spotify-web-api-node --save + +## Usage + +First, instantiate the wrapper. + +```javascript +var SpotifyWebApi = require('spotify-web-api-node'); + +// credentials are optional +var spotifyApi = new SpotifyWebApi({ + clientId: 'fcecfc72172e4cd267473117a17cbd4d', + clientSecret: 'a6338157c9bb5ac9c71924cb2940e1a7', + redirectUri: 'http://www.example.com/callback' +}); +``` + +If you've got an access token and want to use it for all calls, simply use the API object's set method. Handling credentials is described in detail in the Authorization section. + +```javascript +spotifyApi.setAccessToken(''); +``` + +Lastly, use the wrapper's helper methods to make the request to Spotify's Web API. The wrapper uses promises, so you need to provide a success callback as well as an error callback. + +```javascript +// Get Elvis' albums +spotifyApi.getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE').then( + function(data) { + console.log('Artist albums', data.body); + }, + function(err) { + console.error(err); + } +); +``` + +If you dont wan't to use promises, you can provide a callback method instead. + +```javascript +// Get Elvis' albums +spotifyApi.getArtistAlbums( + '43ZHCT0cAZBISjO8DG9PnE', + { limit: 10, offset: 20 }, + function(err, data) { + if (err) { + console.error('Something went wrong!'); + } else { + console.log(data.body); + } + } +); +``` + +The functions that fetch data from the API also accept a JSON object with a set of options. For example, `limit` and `offset` can be used in functions that returns paginated results, such as search and retrieving an artist's albums. + +Note that the **options** parameter is **required if you're using a callback method.**, even if it's empty. + +```javascript +// Passing a callback - get Elvis' albums in range [20...29] +spotifyApi + .getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE', { limit: 10, offset: 20 }) + .then( + function(data) { + console.log('Album information', data.body); + }, + function(err) { + console.error(err); + } + ); +``` + +### Responses and errors + +This exposes the response headers, status code and body. + +```json +{ + "body" : { + + }, + "headers" : { + + }, + "statusCode" : +} +``` + +Errors have same fields, as well as a human readable `message`. This is especially useful since +Spotify's Web API returns different types of error objects depending on the endpoint being called. + +#### Example of a response + +Retrieving a track's metadata in `spotify-web-api-node` version 1.4.0 and later: + +```json +{ + "body": { + "name": "Golpe Maestro", + "popularity": 42, + "preview_url": + "https://p.scdn.co/mp3-preview/4ac44a56e3a4b7b354c1273d7550bbad38c51f5d", + "track_number": 1, + "type": "track", + "uri": "spotify:track:3Qm86XLflmIXVm1wcwkgDK" + }, + "headers": { + "date": "Fri, 27 Feb 2015 09:25:48 GMT", + "content-type": "application/json; charset=utf-8", + "cache-control": "public, max-age=7200" + }, + "statusCode": 200 +} +``` + +### More examples + +Below are examples for all helper functions. Longer examples of some requests can be found in the [examples folder](examples/). + +```javascript +var SpotifyWebApi = require('spotify-web-api-node'); + +var spotifyApi = new SpotifyWebApi(); + +/** + * Get metadata of tracks, albums, artists, shows, and episodes + */ + +// Get album +spotifyApi.getAlbum('5U4W9E5WsYb2jUQWePT8Xm') + .then(function(data) { + console.log('Album information', data.body); + }, function(err) { + console.error(err); + }); + +// Get multiple albums +spotifyApi.getAlbums(['5U4W9E5WsYb2jUQWePT8Xm', '3KyVcddATClQKIdtaap4bV']) + .then(function(data) { + console.log('Albums information', data.body); + }, function(err) { + console.error(err); + }); + +// Get an artist +spotifyApi.getArtist('2hazSY4Ef3aB9ATXW7F5w3') + .then(function(data) { + console.log('Artist information', data.body); + }, function(err) { + console.error(err); + }); + +// Get multiple artists +spotifyApi.getArtists(['2hazSY4Ef3aB9ATXW7F5w3', '6J6yx1t3nwIDyPXk5xa7O8']) + .then(function(data) { + console.log('Artists information', data.body); + }, function(err) { + console.error(err); + }); + +// Get albums by a certain artist +spotifyApi.getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE') + .then(function(data) { + console.log('Artist albums', data.body); + }, function(err) { + console.error(err); + }); + +// Search tracks whose name, album or artist contains 'Love' +spotifyApi.searchTracks('Love') + .then(function(data) { + console.log('Search by "Love"', data.body); + }, function(err) { + console.error(err); + }); + +// Search artists whose name contains 'Love' +spotifyApi.searchArtists('Love') + .then(function(data) { + console.log('Search artists by "Love"', data.body); + }, function(err) { + console.error(err); + }); + +// Search tracks whose artist's name contains 'Love' +spotifyApi.searchTracks('artist:Love') + .then(function(data) { + console.log('Search tracks by "Love" in the artist name', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Search tracks whose artist's name contains 'Kendrick Lamar', and track name contains 'Alright' +spotifyApi.searchTracks('track:Alright artist:Kendrick Lamar') + .then(function(data) { + console.log('Search tracks by "Alright" in the track name and "Kendrick Lamar" in the artist name', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + + +// Search playlists whose name or description contains 'workout' +spotifyApi.searchPlaylists('workout') + .then(function(data) { + console.log('Found playlists are', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get tracks in an album +spotifyApi.getAlbumTracks('41MnTivkwTO3UUJ8DrqEJJ', { limit : 5, offset : 1 }) + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get an artist's top tracks +spotifyApi.getArtistTopTracks('0oSGxfWSnnOXhD2fKuz2Gy', 'GB') + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get artists related to an artist +spotifyApi.getArtistRelatedArtists('0qeei9KQnptjwb8MgkqEoy') + .then(function(data) { + console.log(data.body); + }, function(err) { + done(err); + }); + +/* Get Audio Features for a Track */ +spotifyApi.getAudioFeaturesForTrack('3Qm86XLflmIXVm1wcwkgDK') + .then(function(data) { + console.log(data.body); + }, function(err) { + done(err); + }); + +/* Get Audio Analysis for a Track */ +spotifyApi.getAudioAnalysisForTrack('3Qm86XLflmIXVm1wcwkgDK') + .then(function(data) { + console.log(data.body); + }, function(err) { + done(err); + }); + +/* Get Audio Features for several tracks */ +spotifyApi.getAudioFeaturesForTracks(['4iV5W9uYEdYUVa79Axb7Rh', '3Qm86XLflmIXVm1wcwkgDK']) + .then(function(data) { + console.log(data.body); + }, function(err) { + done(err); + }); + + +/* + * User methods + */ + +// Get a user +spotifyApi.getUser('petteralexis') + .then(function(data) { + console.log('Some information about this user', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get the authenticated user +spotifyApi.getMe() + .then(function(data) { + console.log('Some information about the authenticated user', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* + * Playlist methods + */ + +// Get a playlist +spotifyApi.getPlaylist('5ieJqeLJjjI8iJWaxeBLuK') + .then(function(data) { + console.log('Some information about this playlist', data.body); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get a user's playlists +spotifyApi.getUserPlaylists('thelinmichael') + .then(function(data) { + console.log('Retrieved playlists', data.body); + },function(err) { + console.log('Something went wrong!', err); + }); + +// Create a private playlist +spotifyApi.createPlaylist('My playlist', { 'description': 'My description', 'public': true }) + .then(function(data) { + console.log('Created playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Add tracks to a playlist +spotifyApi.addTracksToPlaylist('5ieJqeLJjjI8iJWaxeBLuK', ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"]) + .then(function(data) { + console.log('Added tracks to playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Add tracks to a specific position in a playlist +spotifyApi.addTracksToPlaylist('5ieJqeLJjjI8iJWaxeBLuK', ["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"], + { + position : 5 + }) + .then(function(data) { + console.log('Added tracks to playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Remove tracks from a playlist at a specific position +spotifyApi.removeTracksFromPlaylistByPosition('5ieJqeLJjjI8iJWaxeBLuK', [0, 2, 130], "0wD+DKCUxiSR/WY8lF3fiCTb7Z8X4ifTUtqn8rO82O4Mvi5wsX8BsLj7IbIpLVM9") + .then(function(data) { + console.log('Tracks removed from playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Remove all occurrence of a track +var tracks = [{ uri : "spotify:track:4iV5W9uYEdYUVa79Axb7Rh" }]; +var playlistId = '5ieJqeLJjjI8iJWaxeBLuK'; +var options = { snapshot_id : "0wD+DKCUxiSR/WY8lF3fiCTb7Z8X4ifTUtqn8rO82O4Mvi5wsX8BsLj7IbIpLVM9" }; +spotifyApi.removeTracksFromPlaylist(playlistId, tracks, options) + .then(function(data) { + console.log('Tracks removed from playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Reorder the first two tracks in a playlist to the place before the track at the 10th position +var options = { "range_length" : 2 }; +spotifyApi.reorderTracksInPlaylist('5ieJqeLJjjI8iJWaxeBLuK', 0, 10, options) + .then(function(data) { + console.log('Tracks reordered in playlist!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Change playlist details +spotifyApi.changePlaylistDetails('5ieJqeLJjjI8iJWaxeBLuK', + { + name: 'This is a new name for my Cool Playlist, and will become private', + 'public' : false + }).then(function(data) { + console.log('Playlist is now private!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Upload a custom playlist cover image +spotifyApi.uploadCustomPlaylistCoverImage('5ieJqeLJjjI8iJWaxeBLuK','longbase64uri') + .then(function(data) { + console.log('Playlsit cover image uploaded!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Follow a playlist (privately) +spotifyApi.followPlaylist('5ieJqeLJjjI8iJWaxeBLuK', + { + 'public' : false + }).then(function(data) { + console.log('Playlist successfully followed privately!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Unfollow a playlist +spotifyApi.unfollowPlaylist('5ieJqeLJjjI8iJWaxeBLuK') + .then(function(data) { + console.log('Playlist successfully unfollowed!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Check if Users are following a Playlist +spotifyApi.areFollowingPlaylist('5ieJqeLJjjI8iJWaxeBLuK', ['thelinmichael', 'ella']) + .then(function(data) { + data.body.forEach(function(isFollowing) { + console.log("User is following: " + isFollowing); + }); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* + * Following Users and Artists methods + */ + +/* Get followed artists */ +spotifyApi.getFollowedArtists({ limit : 1 }) + .then(function(data) { + // 'This user is following 1051 artists!' + console.log('This user is following ', data.body.artists.total, ' artists!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Follow a user */ +spotifyApi.followUsers(['thelinmichael']) + .then(function(data) { + console.log(data); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Follow an artist */ +spotifyApi.followArtists(['2hazSY4Ef3aB9ATXW7F5w3', '6J6yx1t3nwIDyPXk5xa7O8']) + .then(function(data) { + console.log(data); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Unfollow a user */ +spotifyApi.unfollowUsers(['thelinmichael']) + .then(function(data) { + console.log(data); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Unfollow an artist */ +spotifyApi.unfollowArtists(['2hazSY4Ef3aB9ATXW7F5w3', '6J6yx1t3nwIDyPXk5xa7O8']) + .then(function(data) { + console.log(data); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Check if a user is following a user */ +let usersId = ['thelinmichael']; + +spotifyApi.isFollowingUsers(usersId) + .then(function(data) { + let isFollowing = data.body; + + for (let index = 0; index < usersId.length; index++) { + console.log(usersId[index] + ':' + isFollowing[index]) + } + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Check if a user is following an artist */ +let artistsId = ['6mfK6Q2tzLMEchAr0e9Uzu', '4DYFVNKZ1uixa6SQTvzQwJ']; + +spotifyApi.isFollowingArtists(artistsId) + .then(function(data) { + let isFollowing = data.body; + + for (let index = 0; index < artistsId.length; index++) { + console.log(artistsId[index] + ':' + isFollowing[index]) + } + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* + * Your Music library methods + */ + +/* Tracks */ + +// Get tracks in the signed in user's Your Music library +spotifyApi.getMySavedTracks({ + limit : 2, + offset: 1 + }) + .then(function(data) { + console.log('Done!'); + }, function(err) { + console.log('Something went wrong!', err); + }); + + +// Check if tracks are in the signed in user's Your Music library +spotifyApi.containsMySavedTracks(["5ybJm6GczjQOgTqmJ0BomP"]) + .then(function(data) { + + // An array is returned, where the first element corresponds to the first track ID in the query + var trackIsInYourMusic = data.body[0]; + + if (trackIsInYourMusic) { + console.log('Track was found in the user\'s Your Music library'); + } else { + console.log('Track was not found.'); + } + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Remove tracks from the signed in user's Your Music library +spotifyApi.removeFromMySavedTracks(["3VNWq8rTnQG6fM1eldSpZ0"]) + .then(function(data) { + console.log('Removed!'); + }, function(err) { + console.log('Something went wrong!', err); + }); +}); + +// Add tracks to the signed in user's Your Music library +spotifyApi.addToMySavedTracks(["3VNWq8rTnQG6fM1eldSpZ0"]) + .then(function(data) { + console.log('Added track!'); + }, function(err) { + console.log('Something went wrong!', err); + }); +}); + +/* Albums */ + +// Get albums in the signed in user's Your Music library +spotifyApi.getMySavedAlbums({ + limit : 1, + offset: 0 + }) + .then(function(data) { + // Output items + console.log(data.body.items); + }, function(err) { + console.log('Something went wrong!', err); + }); + + +// Check if albums are in the signed in user's Your Music library +spotifyApi.containsMySavedAlbums(["1H8AHEB8VSE8irHViGOIrF"]) + .then(function(data) { + + // An array is returned, where the first element corresponds to the first album ID in the query + var albumIsInYourMusic = data.body[0]; + + if (albumIsInYourMusic) { + console.log('Album was found in the user\'s Your Music library'); + } else { + console.log('Album was not found.'); + } + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Remove albums from the signed in user's Your Music library +spotifyApi.removeFromMySavedAlbums(["1H8AHEB8VSE8irHViGOIrF"]) + .then(function(data) { + console.log('Removed!'); + }, function(err) { + console.log('Something went wrong!', err); + }); +}); + +// Add albums to the signed in user's Your Music library +spotifyApi.addToMySavedAlbums(["1H8AHEB8VSE8irHViGOIrF"]) + .then(function(data) { + console.log('Added album!'); + }, function(err) { + console.log('Something went wrong!', err); + }); +}); + + +/* + * Browse methods + */ + + // Retrieve new releases +spotifyApi.getNewReleases({ limit : 5, offset: 0, country: 'SE' }) + .then(function(data) { + console.log(data.body); + done(); + }, function(err) { + console.log("Something went wrong!", err); + }); + }); + +// Retrieve featured playlists +spotifyApi.getFeaturedPlaylists({ limit : 3, offset: 1, country: 'SE', locale: 'sv_SE', timestamp:'2014-10-23T09:00:00' }) + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log("Something went wrong!", err); + }); + +// Get a List of Categories +spotifyApi.getCategories({ + limit : 5, + offset: 0, + country: 'SE', + locale: 'sv_SE' + }) + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log("Something went wrong!", err); + }); + +// Get a Category (in Sweden) +spotifyApi.getCategory('party', { + country: 'SE', + locale: 'sv_SE' + }) + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log("Something went wrong!", err); + }); + +// Get Playlists for a Category (Party in Brazil) +spotifyApi.getPlaylistsForCategory('party', { + country: 'BR', + limit : 2, + offset : 0 + }) + .then(function(data) { + console.log(data.body); + }, function(err) { + console.log("Something went wrong!", err); + }); + +// Get Recommendations Based on Seeds +spotifyApi.getRecommendations({ + min_energy: 0.4, + seed_artists: ['6mfK6Q2tzLMEchAr0e9Uzu', '4DYFVNKZ1uixa6SQTvzQwJ'], + min_popularity: 50 + }) + .then(function(data) { + let recommendations = data.body; + console.log(recommendations); + }, function(err) { + console.log("Something went wrong!", err); + }); + +// Get available genre seeds +spotifyApi.getAvailableGenreSeeds() + .then(function(data) { + let genreSeeds = data.body; + console.log(genreSeeds); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Player */ + +// Add an Item to the User's Playback Queue +// TBD + +// Get a User's Available Devices +spotifyApi.getMyDevices() + .then(function(data) { + let availableDevices = data.body.devices; + console.log(availableDevices); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get Information About The User's Current Playback State +spotifyApi.getMyCurrentPlaybackState() + .then(function(data) { + // Output items + if (data.body && data.body.is_playing) { + console.log("User is currently playing something!"); + } else { + console.log("User is not playing anything, or doing so in private."); + } + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get Current User's Recently Played Tracks +spotifyApi.getMyRecentlyPlayedTracks({ + limit : 20 +}).then(function(data) { + // Output items + console.log("Your 20 most recently played tracks are:"); + data.body.items.forEach(item => console.log(item.track)); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Get the User's Currently Playing Track +spotifyApi.getMyCurrentPlayingTrack() + .then(function(data) { + console.log('Now playing: ' + data.body.item.name); + }, function(err) { + console.log('Something went wrong!', err); + }); + +// Pause a User's Playback +spotifyApi.pause() + .then(function() { + console.log('Playback paused'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Seek To Position In Currently Playing Track +spotifyApi.seek(positionMs) + .then(function() { + console.log('Seek to ' + positionMs); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Set Repeat Mode On User’s Playback +spotifyApi.setRepeat('track') + .then(function () { + console.log('Repeat track.'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Set Volume For User's Playback +spotifyApi.setVolume(50) + .then(function () { + console.log('Setting volume to 50.'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Skip User’s Playback To Next Track +spotifyApi.skipToNext() + .then(function() { + console.log('Skip to next'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Skip User’s Playback To Previous Track +spotifyApi.skipToPrevious() + .then(function() { + console.log('Skip to previous'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Start/Resume a User's Playback +spotifyApi.play() + .then(function() { + console.log('Playback started'); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Toggle Shuffle For User’s Playback +spotifyApi.setShuffle(true) + .then(function() { + console.log('Shuffle is on.'); + }, function (err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + +// Transfer a User's Playback +spotifyApi.transferMyPlayback(deviceIds) + .then(function() { + console.log('Transfering playback to ' + deviceIds); + }, function(err) { + //if the user making the request is non-premium, a 403 FORBIDDEN response code will be returned + console.log('Something went wrong!', err); + }); + + +/** + * Personalization Endpoints + */ + +/* Get a User’s Top Artists*/ +spotifyApi.getMyTopArtists() + .then(function(data) { + let topArtists = data.body.items; + console.log(topArtists); + }, function(err) { + console.log('Something went wrong!', err); + }); + +/* Get a User’s Top Tracks*/ +spotifyApi.getMyTopTracks() + .then(function(data) { + let topTracks = data.body.items; + console.log(topTracks); + }, function(err) { + console.log('Something went wrong!', err); + }); + +``` + +### Chaining calls + +```javascript +// track detail information for album tracks +spotifyApi + .getAlbum('5U4W9E5WsYb2jUQWePT8Xm') + .then(function(data) { + return data.body.tracks.map(function(t) { + return t.id; + }); + }) + .then(function(trackIds) { + return spotifyApi.getTracks(trackIds); + }) + .then(function(data) { + console.log(data.body); + }) + .catch(function(error) { + console.error(error); + }); + +// album detail for the first 10 Elvis' albums +spotifyApi + .getArtistAlbums('43ZHCT0cAZBISjO8DG9PnE', { limit: 10 }) + .then(function(data) { + return data.body.albums.map(function(a) { + return a.id; + }); + }) + .then(function(albums) { + return spotifyApi.getAlbums(albums); + }) + .then(function(data) { + console.log(data.body); + }); +``` + +### Authorization +Supplying an access token is required for all requests to the Spotify API. This wrapper supports three authorization flows - The Authorization Code flow (signed by a user), the Client Credentials flow (application authentication - the user isn't involved), and the Implicit Grant Flow (For completely clientside applications). See Spotify's [Authorization guide](https://developer.spotify.com/spotify-web-api/authorization-guide/) for detailed information on these flows. + +**Important: If you are writing a universal/isomorphic web app using this library, you will not be able to use methods that send a client secret to the Spotify authorization service. Client secrets should be kept server-side and not exposed to client browsers. Never include your client secret in the public JS served to the browser.** + +The first thing you need to do is to [create an application](https://developer.spotify.com/my-applications/). A step-by-step tutorial is offered by Spotify in this [tutorial](https://developer.spotify.com/spotify-web-api/tutorial/). + +#### Authorization code flow + +With the application created and its redirect URI set, the only thing necessary for the application to retrieve an **authorization code** is the user's permission. Which permissions you're able to ask for is documented in Spotify's [Using Scopes section](https://developer.spotify.com/spotify-web-api/using-scopes/). + +In order to get permissions, you need to direct the user to [Spotify's Accounts service](https://accounts.spotify.com). Generate the URL by using the wrapper's authorization URL method. + +```javascript +var scopes = ['user-read-private', 'user-read-email'], + redirectUri = 'https://example.com/callback', + clientId = '5fe01282e44241328a84e7c5cc169165', + state = 'some-state-of-my-choice'; + +// Setting credentials can be done in the wrapper's constructor, or using the API object's setters. +var spotifyApi = new SpotifyWebApi({ + redirectUri: redirectUri, + clientId: clientId +}); + +// Create the authorization URL +var authorizeURL = spotifyApi.createAuthorizeURL(scopes, state); + +// https://accounts.spotify.com:443/authorize?client_id=5fe01282e44241328a84e7c5cc169165&response_type=code&redirect_uri=https://example.com/callback&scope=user-read-private%20user-read-email&state=some-state-of-my-choice +console.log(authorizeURL); +``` + +The example below uses a hardcoded authorization code, retrieved from the Accounts service as described above. + +```javascript +var credentials = { + clientId: 'someClientId', + clientSecret: 'someClientSecret', + redirectUri: 'http://www.michaelthelin.se/test-callback' +}; + +var spotifyApi = new SpotifyWebApi(credentials); + +// The code that's returned as a query parameter to the redirect URI +var code = 'MQCbtKe23z7YzzS44KzZzZgjQa621hgSzHN'; + +// Retrieve an access token and a refresh token +spotifyApi.authorizationCodeGrant(code).then( + function(data) { + console.log('The token expires in ' + data.body['expires_in']); + console.log('The access token is ' + data.body['access_token']); + console.log('The refresh token is ' + data.body['refresh_token']); + + // Set the access token on the API object to use it in later calls + spotifyApi.setAccessToken(data.body['access_token']); + spotifyApi.setRefreshToken(data.body['refresh_token']); + }, + function(err) { + console.log('Something went wrong!', err); + } +); +``` + +Since the access token was set on the API object in the previous success callback, **it's going to be used in future calls**. As it was retrieved using the Authorization Code flow, it can also be refreshed. + +```javascript +// clientId, clientSecret and refreshToken has been set on the api object previous to this call. +spotifyApi.refreshAccessToken().then( + function(data) { + console.log('The access token has been refreshed!'); + + // Save the access token so that it's used in future calls + spotifyApi.setAccessToken(data.body['access_token']); + }, + function(err) { + console.log('Could not refresh access token', err); + } +); +``` + +#### Client Credential flow + +The Client Credential flow doesn't require the user to give permissions, so it's suitable for requests where the application just needs to authenticate itself. This is the case with for example retrieving a playlist. However, note that the access token cannot be refreshed, and that it isn't connected to a specific user. + +```javascript +var clientId = 'someClientId', + clientSecret = 'someClientSecret'; + +// Create the api object with the credentials +var spotifyApi = new SpotifyWebApi({ + clientId: clientId, + clientSecret: clientSecret +}); + +// Retrieve an access token. +spotifyApi.clientCredentialsGrant().then( + function(data) { + console.log('The access token expires in ' + data.body['expires_in']); + console.log('The access token is ' + data.body['access_token']); + + // Save the access token so that it's used in future calls + spotifyApi.setAccessToken(data.body['access_token']); + }, + function(err) { + console.log('Something went wrong when retrieving an access token', err); + } +); +``` + +#### Implicit Grant flow + +The Implicit Grant can be used to allow users to login to your completely client-side application. This method still requires a registered application, but won't expose your client secret. +This method of authentication won't return any refresh tokens, so you will need to fully reauthenticate the user everytime a token expires. + +```javascript +var scopes = ['user-read-private', 'user-read-email'], + redirectUri = 'https://example.com/callback', + clientId = '5fe01282e44241328a84e7c5cc169165', + state = 'some-state-of-my-choice', + showDialog = true, + responseType = 'token'; + +// Setting credentials can be done in the wrapper's constructor, or using the API object's setters. +var spotifyApi = new SpotifyWebApi({ + redirectUri: redirectUri, + clientId: clientId +}); + +// Create the authorization URL +var authorizeURL = spotifyApi.createAuthorizeURL( + scopes, + state, + showDialog, + responseType +); + +// https://accounts.spotify.com/authorize?client_id=5fe01282e44241328a84e7c5cc169165&response_type=token&redirect_uri=https://example.com/callback&scope=user-read-private%20user-read-email&state=some-state-of-my-choice&show_dialog=true +console.log(authorizeURL); +``` + +When the client returns, it will have a token we can directly pass to the library: + +```javascript +// The code that's returned as a hash fragment query string parameter to the redirect URI +var code = 'MQCbtKe23z7YzzS44KzZzZgjQa621hgSzHN'; +var credentials = { + clientId: 'someClientId', + clientSecret: 'someClientSecret', + //Either here + accessToken: code +}; + +var spotifyApi = new SpotifyWebApi(credentials); + +//Or with a method +spotifyApi.setAccessToken(code); +``` + +#### Setting credentials + +Credentials are either set when constructing the API object or set after the object has been created using setters. They can be set all at once or one at a time. + +Using setters, getters and resetters. + +```javascript +// Use setters to set all credentials one by one +var spotifyApi = new SpotifyWebApi(); +spotifyApi.setAccessToken('myAccessToken'); +spotifyApi.setRefreshToken('myRefreshToken'); +spotifyApi.setRedirectURI('http://www.example.com/test-callback'); +spotifyApi.setClientId('myOwnClientId'); +spotifyApi.setClientSecret('someSuperSecretString'); + +// Set all credentials at the same time +spotifyApi.setCredentials({ + accessToken: 'myAccessToken', + refreshToken: 'myRefreshToken', + redirectUri: 'http://www.example.com/test-callback', + 'clientId ': 'myClientId', + clientSecret: 'myClientSecret' +}); + +// Get the credentials one by one +console.log('The access token is ' + spotifyApi.getAccessToken()); +console.log('The refresh token is ' + spotifyApi.getRefreshToken()); +console.log('The redirectURI is ' + spotifyApi.getRedirectURI()); +console.log('The client ID is ' + spotifyApi.getClientId()); +console.log('The client secret is ' + spotifyApi.getClientSecret()); + +// Get all credentials +console.log('The credentials are ' + spotifyApi.getCredentials()); + +// Reset the credentials +spotifyApi.resetAccessToken(); +spotifyApi.resetRefreshToken(); +spotifyApi.resetRedirectURI(); +spotifyApi.resetClientId(); +spotifyApi.resetClientSecret(); +spotifyApi.resetCode(); + +// Reset all credentials at the same time +spotifyApi.resetCredentials(); +``` + +Using the constructor. + +```javascript +// Set necessary parts of the credentials on the constructor +var spotifyApi = new SpotifyWebApi({ + clientId: 'myClientId', + clientSecret: 'myClientSecret' +}); + +// Get an access token and 'save' it using a setter +spotifyApi.clientCredentialsGrant().then( + function(data) { + console.log('The access token is ' + data.body['access_token']); + spotifyApi.setAccessToken(data.body['access_token']); + }, + function(err) { + console.log('Something went wrong!', err); + } +); +``` + +```javascript +// Set the credentials when making the request +var spotifyApi = new SpotifyWebApi({ + accessToken: 'njd9wng4d0ycwnn3g4d1jm30yig4d27iom5lg4d3' +}); + +// Do search using the access token +spotifyApi.searchTracks('artist:Love').then( + function(data) { + console.log(data.body); + }, + function(err) { + console.log('Something went wrong!', err); + } +); +``` + +```javascript +// Set the credentials when making the request +var spotifyApi = new SpotifyWebApi({ + accessToken: 'njd9wng4d0ycwnn3g4d1jm30yig4d27iom5lg4d3' +}); + +// Get tracks in a playlist +api + .getPlaylistTracks('3ktAYNcRHpazJ9qecm3ptn', { + offset: 1, + limit: 5, + fields: 'items' + }) + .then( + function(data) { + console.log('The playlist contains these tracks', data.body); + }, + function(err) { + console.log('Something went wrong!', err); + } + ); +``` + +## Development + +See something you think can be improved? [Open an issue](https://github.com/thelinmichael/spotify-web-api-node/issues/new) or clone the project and send a pull request with your changes. + +### Running tests + +You can run the unit tests executing `npm test` and get a test coverage report running `npm test -- --coverage`. diff --git a/spotify-web-api-node/examples/access-token-refresh.js b/spotify-web-api-node/examples/access-token-refresh.js new file mode 100644 index 0000000..9bbffe0 --- /dev/null +++ b/spotify-web-api-node/examples/access-token-refresh.js @@ -0,0 +1,86 @@ +const SpotifyWebApi = require('../') + +/** + * This example refreshes an access token. Refreshing access tokens is only possible access tokens received using the + * Authorization Code flow, documented here: https://developer.spotify.com/spotify-web-api/authorization-guide/#authorization_code_flow + */ + +/* Retrieve an authorization code as documented here: + * https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + * or in the Authorization section of the README. + * + * Codes are given for a set of scopes. For this example, the scopes are user-read-private and user-read-email. + * Scopes are documented here: + * https://developer.spotify.com/documentation/general/guides/scopes/ + */ +const authorizationCode = + '' + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +// When our access token will expire +let tokenExpirationEpoch + +// First retrieve an access token +spotifyApi.authorizationCodeGrant(authorizationCode).then( + function (data) { + // Set the access token and refresh token + spotifyApi.setAccessToken(data.body.access_token) + spotifyApi.setRefreshToken(data.body.refresh_token) + + // Save the amount of seconds until the access token expired + tokenExpirationEpoch = + new Date().getTime() / 1000 + data.body.expires_in + console.log( + 'Retrieved token. It expires in ' + + Math.floor(tokenExpirationEpoch - new Date().getTime() / 1000) + + ' seconds!' + ) + }, + function (err) { + console.log( + 'Something went wrong when retrieving the access token!', + err.message + ) + } +) + +// Continually print out the time left until the token expires.. +let numberOfTimesUpdated = 0 + +setInterval(function () { + console.log( + 'Time left: ' + + Math.floor(tokenExpirationEpoch - new Date().getTime() / 1000) + + ' seconds left!' + ) + + // OK, we need to refresh the token. Stop printing and refresh. + if (++numberOfTimesUpdated > 5) { + clearInterval(this) + + // Refresh token and print the new time to expiration. + spotifyApi.refreshAccessToken().then( + function (data) { + tokenExpirationEpoch = + new Date().getTime() / 1000 + data.body.expires_in + console.log( + 'Refreshed token. It now expires in ' + + Math.floor(tokenExpirationEpoch - new Date().getTime() / 1000) + + ' seconds!' + ) + }, + function (err) { + console.log('Could not refresh the token!', err.message) + } + ) + } +}, 1000) diff --git a/spotify-web-api-node/examples/access-token-using-client-credentials.js b/spotify-web-api-node/examples/access-token-using-client-credentials.js new file mode 100644 index 0000000..f470e58 --- /dev/null +++ b/spotify-web-api-node/examples/access-token-using-client-credentials.js @@ -0,0 +1,32 @@ +const SpotifyWebApi = require('../') + +/** + * This example retrieves an access token using the Client Credentials Flow, documented at: + * https://developer.spotify.com/documentation/general/guides/authorization-guide/#client-credentials-flow + */ + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '' +}) + +// Retrieve an access token +spotifyApi.clientCredentialsGrant().then( + function (data) { + console.log('The access token expires in ' + data.body.expires_in) + console.log('The access token is ' + data.body.access_token) + + // Save the access token so that it's used in future calls + spotifyApi.setAccessToken(data.body.access_token) + }, + function (err) { + console.log( + 'Something went wrong when retrieving an access token', + err.message + ) + } +) diff --git a/spotify-web-api-node/examples/add-remove-replace-tracks-in-a-playlist.js b/spotify-web-api-node/examples/add-remove-replace-tracks-in-a-playlist.js new file mode 100644 index 0000000..f7d3c5a --- /dev/null +++ b/spotify-web-api-node/examples/add-remove-replace-tracks-in-a-playlist.js @@ -0,0 +1,84 @@ +const SpotifyWebApi = require('../') + +/** + * This example demonstrates adding tracks, removing tracks, and replacing tracks in a playlist. At the time of writing this + * documentation, this is the available playlist track modification feature in the Spotify Web API. + * + * Since authorization is required, this example retrieves an access token using the Authorization Code Grant flow, + * documented here: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + * + * Codes are given for a set of scopes. For this example, the scopes are playlist-modify-public. + * Scopes are documented here: + * https://developer.spotify.com/documentation/general/guides/scopes/ + */ + +/* Obtain the `authorizationCode` below as described in the Authorization section of the README. + */ +const authorizationCode = + '' + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +let playlistId + +// First retrieve an access token +spotifyApi + .authorizationCodeGrant(authorizationCode) + .then(function (data) { + // Save the access token so that it's used in future requests + spotifyApi.setAccessToken(data.access_token) + + // Create a playlist + return spotifyApi.createPlaylist( + 'thelinmichael', + 'My New Awesome Playlist' + ) + }) + .then(function (data) { + console.log('Ok. Playlist created!') + playlistId = data.body.id + + // Add tracks to the playlist + return spotifyApi.addTracksToPlaylist(playlistId, [ + 'spotify:track:4iV5W9uYEdYUVa79Axb7Rh', + 'spotify:track:6tcfwoGcDjxnSc6etAkDRR', + 'spotify:track:4iV5W9uYEdYUVa79Axb7Rh' + ]) + }) + .then(function (data) { + console.log('Ok. Tracks added!') + + // Woops! Made a duplicate. Remove one of the duplicates from the playlist + return spotifyApi.removeTracksFromPlaylist('thelinmichael', playlistId, [ + { + uri: 'spotify:track:4iV5W9uYEdYUVa79Axb7Rh', + positions: [0] + } + ]) + }) + .then(function (data) { + console.log('Ok. Tracks removed!') + + // Actually, lets just replace all tracks in the playlist with something completely different + return spotifyApi.replaceTracksInPlaylist('thelinmichael', playlistId, [ + 'spotify:track:5Wd2bfQ7wc6GgSa32OmQU3', + 'spotify:track:4r8lRYnoOGdEi6YyI5OC1o', + 'spotify:track:4TZZvblv2yzLIBk2JwJ6Un', + 'spotify:track:2IA4WEsWAYpV9eKkwR2UYv', + 'spotify:track:6hDH3YWFdcUNQjubYztIsG' + ]) + }) + .then(function (data) { + console.log('Ok. Tracks replaced!') + }) + .catch(function (err) { + console.log('Something went wrong:', err.message) + }) diff --git a/spotify-web-api-node/examples/add-tracks-to-a-playlist.js b/spotify-web-api-node/examples/add-tracks-to-a-playlist.js new file mode 100644 index 0000000..56442c4 --- /dev/null +++ b/spotify-web-api-node/examples/add-tracks-to-a-playlist.js @@ -0,0 +1,49 @@ +const SpotifyWebApi = require('../') + +/** + * This example demonstrates adding tracks to a specified position in a playlist. + * + * Since authorization is required, this example retrieves an access token using the Authorization Code Grant flow, + * documented here: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + * + * Codes are given for a set of scopes. For this example, the scopes are playlist-modify-public. + * Scopes are documented here: + * https://developer.spotify.com/documentation/general/guides/scopes/ + */ + +/* Obtain the `authorizationCode` below as described in the Authorization section of the README. + */ +const authorizationCode = '' + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +// First retrieve an access token +spotifyApi + .authorizationCodeGrant(authorizationCode) + .then(function (data) { + spotifyApi.setAccessToken(data.body.access_token) + return spotifyApi.addTracksToPlaylist( + '5ieJqeLJjjI8iJWaxeBLuK', + [ + 'spotify:track:4iV5W9uYEdYUVa79Axb7Rh', + 'spotify:track:1301WleyT98MSxVHPZCA6M' + ], + { + position: 10 + } + ) + }) + .then(function (data) { + console.log('Added tracks to the playlist!') + }) + .catch(function (err) { + console.log('Something went wrong:', err.message) + }) diff --git a/spotify-web-api-node/examples/client-credentials.js b/spotify-web-api-node/examples/client-credentials.js new file mode 100644 index 0000000..2d594ea --- /dev/null +++ b/spotify-web-api-node/examples/client-credentials.js @@ -0,0 +1,26 @@ +const { util } = require('prettier') +const SpotifyWebApi = require('../') + +/** + * This example uses the Client Credentials authorization flow. + */ + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '' +}) + +// Retrieve an access token using your credentials +spotifyApi.clientCredentialsGrant() + .then(function (result) { + console.log('It worked! Your access token is: ' + result.body.access_token) + }).catch(function (err) { + console.log('If this is printed, it probably means that you used invalid ' + + 'clientId and clientSecret values. Please check!') + console.log('Hint: ') + console.log(err) + }) diff --git a/spotify-web-api-node/examples/get-info-about-current-user.js b/spotify-web-api-node/examples/get-info-about-current-user.js new file mode 100644 index 0000000..9a3ee99 --- /dev/null +++ b/spotify-web-api-node/examples/get-info-about-current-user.js @@ -0,0 +1,54 @@ +const SpotifyWebApi = require('../') + +/** + * This example retrieves information about the 'current' user. The current user is the user that has + * authorized the application to access its data. + */ + +/* Retrieve a code as documented here: + * https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + * + * Codes are given for a set of scopes. For this example, the scopes are user-read-private and user-read-email. + * Scopes are documented here: + * https://developer.spotify.com/documentation/general/guides/scopes/ + */ +const authorizationCode = + '' + +/* Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +// First retrieve an access token +spotifyApi + .authorizationCodeGrant(authorizationCode) + .then(function (data) { + console.log('Retrieved access token', data.body.access_token) + + // Set the access token + spotifyApi.setAccessToken(data.body.access_token) + + // Use the access token to retrieve information about the user connected to it + return spotifyApi.getMe() + }) + .then(function (data) { + // "Retrieved data for Faruk Sahin" + console.log('Retrieved data for ' + data.body.display_name) + + // "Email is farukemresahin@gmail.com" + console.log('Email is ' + data.body.email) + + // "Image URL is http://media.giphy.com/media/Aab07O5PYOmQ/giphy.gif" + console.log('Image URL is ' + data.body.images[0].url) + + // "This user has a premium account" + console.log('This user has a ' + data.body.product + ' account') + }) + .catch(function (err) { + console.log('Something went wrong:', err.message) + }) diff --git a/spotify-web-api-node/examples/get-related-artists.js b/spotify-web-api-node/examples/get-related-artists.js new file mode 100644 index 0000000..ded715a --- /dev/null +++ b/spotify-web-api-node/examples/get-related-artists.js @@ -0,0 +1,49 @@ +const SpotifyWebApi = require('../') + +/* + * This example shows how to get artists related to another artists. The endpoint is documented here: + * https://developer.spotify.com/web-api/get-related-artists/ + + * Please note that authorization is now required and so this example retrieves an access token using the Authorization Code Flow, + * documented here: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + */ + +const authorizationCode = + 'AQAgjS78s64u1axMCBCRA0cViW_ZDDU0pbgENJ_-WpZr3cEO7V5O-JELcEPU6pGLPp08SfO3dnHmu6XJikKqrU8LX9W6J11NyoaetrXtZFW-Y58UGeV69tuyybcNUS2u6eyup1EgzbTEx4LqrP_eCHsc9xHJ0JUzEhi7xcqzQG70roE4WKM_YrlDZO-e7GDRMqunS9RMoSwF_ov-gOMpvy9OMb7O58nZoc3LSEdEwoZPCLU4N4TTJ-IF6YsQRhQkEOJK' + +/* Set the credentials given on Spotify's My Applications page. + * https://developer.spotify.com/my-applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +const artistId = '0qeei9KQnptjwb8MgkqEoy' + +spotifyApi + .authorizationCodeGrant(authorizationCode) + .then(function (data) { + console.log('Retrieved access token', data.body.access_token) + + // Set the access token + spotifyApi.setAccessToken(data.body.access_token) + + // Use the access token to retrieve information about the user connected to it + return spotifyApi.getArtistRelatedArtists(artistId) + }) + .then(function (data) { + if (data.body.artists.length) { + // Print the number of similar artists + console.log('I got ' + data.body.artists.length + ' similar artists!') + + console.log('The most similar one is ' + data.body.artists[0].name) + } else { + console.log("I didn't find any similar artists.. Sorry.") + } + }, + function (err) { + console.log('Something went wrong:', err.message) + } + ) diff --git a/spotify-web-api-node/examples/get-top-tracks-for-artist.js b/spotify-web-api-node/examples/get-top-tracks-for-artist.js new file mode 100644 index 0000000..e749be4 --- /dev/null +++ b/spotify-web-api-node/examples/get-top-tracks-for-artist.js @@ -0,0 +1,56 @@ +const SpotifyWebApi = require('../') + +/** + * This example retrieves the top tracks for an artist. + * https://developer.spotify.com/documentation/web-api/reference/artists/get-artists-top-tracks/ + */ + +/** + * This endpoint doesn't require an access token, but it's beneficial to use one as it + * gives the application a higher rate limit. + * + * Since it's not necessary to get an access token connected to a specific user, this example + * uses the Client Credentials flow. This flow uses only the client ID and the client secret. + * https://developer.spotify.com/documentation/general/guides/authorization-guide/#client-credentials-flow + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '' +}) + +// Retrieve an access token +spotifyApi + .clientCredentialsGrant() + .then(function (data) { + // Set the access token on the API object so that it's used in all future requests + spotifyApi.setAccessToken(data.body.access_token) + + // Get the most popular tracks by David Bowie in Great Britain + return spotifyApi.getArtistTopTracks('0oSGxfWSnnOXhD2fKuz2Gy', 'GB') + }) + .then(function (data) { + console.log('The most popular tracks for David Bowie is..') + console.log('Drum roll..') + console.log('...') + + /* + * 1. Space Oddity - 2009 Digital Remaster (popularity is 51) + * 2. Heroes - 1999 Digital Remaster (popularity is 33) + * 3. Let's Dance - 1999 Digital Remaster (popularity is 20) + * 4. ... + */ + data.body.tracks.forEach(function (track, index) { + console.log( + index + + 1 + + '. ' + + track.name + + ' (popularity is ' + + track.popularity + + ')' + ) + }) + }) + .catch(function (err) { + console.log('Unfortunately, something has gone wrong.', err.message) + }) diff --git a/spotify-web-api-node/examples/search-for-tracks.js b/spotify-web-api-node/examples/search-for-tracks.js new file mode 100644 index 0000000..f9e8a4a --- /dev/null +++ b/spotify-web-api-node/examples/search-for-tracks.js @@ -0,0 +1,55 @@ +const SpotifyWebApi = require('../') + +/* + * This example shows how to search for a track. The endpoint is documented here: + * https://developer.spotify.com/documentation/web-api/reference/search/ + + * Since authorization is now required, this example retrieves an access token using the Authorization Code Grant flow, + * documented here: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow + * + * Obtain the `authorizationCode` below as described in the Authorization section of the README. + */ + +const authorizationCode = '' + +/** + * Get the credentials from Spotify's Dashboard page. + * https://developer.spotify.com/dashboard/applications + */ +const spotifyApi = new SpotifyWebApi({ + clientId: '', + clientSecret: '', + redirectUri: '' +}) + +spotifyApi + .authorizationCodeGrant(authorizationCode) + .then(function (data) { + console.log('Retrieved access token', data.body.access_token) + + // Set the access token + spotifyApi.setAccessToken(data.body.access_token) + + // Use the access token to retrieve information about the user connected to it + return spotifyApi.searchTracks('Love') + }) + .then(function (data) { + // Print some information about the results + console.log('I got ' + data.body.tracks.total + ' results!') + + // Go through the first page of results + const firstPage = data.body.tracks.items + console.log('The tracks in the first page are (popularity in parentheses):') + + /* + * 0: All of Me (97) + * 1: My Love (91) + * 2: I Love This Life (78) + * ... + */ + firstPage.forEach(function (track, index) { + console.log(index + ': ' + track.name + ' (' + track.popularity + ')') + }) + }).catch(function (err) { + console.log('Something went wrong:', err.message) + }) diff --git a/spotify-web-api-node/examples/tutorial/00-get-access-token.js b/spotify-web-api-node/examples/tutorial/00-get-access-token.js new file mode 100644 index 0000000..368f6b2 --- /dev/null +++ b/spotify-web-api-node/examples/tutorial/00-get-access-token.js @@ -0,0 +1,101 @@ +/** + * This example is using the Authorization Code flow. + * + * In root directory run + * + * npm install express + * + * then run with the followinng command. If you don't have a client_id and client_secret yet, + * create an application on Create an application here: https://developer.spotify.com/my-applications to get them. + * Make sure you whitelist the correct redirectUri in line 26. + * + * node access-token-server.js "" "" + * + * and visit in your Browser. + */ +const SpotifyWebApi = require('../../') +const express = require('../../node_modules/express') + +const scopes = [ + 'ugc-image-upload', + 'user-read-playback-state', + 'user-modify-playback-state', + 'user-read-currently-playing', + 'streaming', + 'app-remote-control', + 'user-read-email', + 'user-read-private', + 'playlist-read-collaborative', + 'playlist-modify-public', + 'playlist-read-private', + 'playlist-modify-private', + 'user-library-modify', + 'user-library-read', + 'user-top-read', + 'user-read-playback-position', + 'user-read-recently-played', + 'user-follow-read', + 'user-follow-modify' +] + +const spotifyApi = new SpotifyWebApi({ + redirectUri: 'http://localhost:8888/callback', + clientId: process.argv.slice(2)[0], + clientSecret: process.argv.slice(2)[1] +}) + +const app = express() + +app.get('/login', (req, res) => { + res.redirect(spotifyApi.createAuthorizeURL(scopes)) +}) + +app.get('/callback', (req, res) => { + const error = req.query.error + const code = req.query.code + const state = req.query.state + + if (error) { + console.error('Callback Error:', error) + res.send(`Callback Error: ${error}`) + return + } + + spotifyApi + .authorizationCodeGrant(code) + .then(data => { + const access_token = data.body.access_token + const refresh_token = data.body.refresh_token + const expires_in = data.body.expires_in + + spotifyApi.setAccessToken(access_token) + spotifyApi.setRefreshToken(refresh_token) + + console.log('access_token:', access_token) + console.log('refresh_token:', refresh_token) + + console.log( + `Sucessfully retreived access token. Expires in ${expires_in} s.` + ) + res.send('Success! You can now close the window.') + + setInterval(async () => { + const data = await spotifyApi.refreshAccessToken() + const access_token = data.body.access_token + + console.log('The access token has been refreshed!') + console.log('access_token:', access_token) + spotifyApi.setAccessToken(access_token) + }, expires_in / 2 * 1000) + }) + .catch(error => { + console.error('Error getting Tokens:', error) + res.send(`Error getting Tokens: ${error}`) + }) +}) + +app.listen(8888, () => + console.log( + 'HTTP Server up. Now go to http://localhost:8888/login in your browser.' + ) +) diff --git a/spotify-web-api-node/examples/tutorial/01-basics/01-get-info-about-current-user.js b/spotify-web-api-node/examples/tutorial/01-basics/01-get-info-about-current-user.js new file mode 100644 index 0000000..48aca86 --- /dev/null +++ b/spotify-web-api-node/examples/tutorial/01-basics/01-get-info-about-current-user.js @@ -0,0 +1,11 @@ +const SpotifyWebApi = require('../../../') + +const spotifyApi = new SpotifyWebApi() +spotifyApi.setAccessToken(process.env.SPOTIFY_ACCESS_TOKEN); + +(async () => { + const me = await spotifyApi.getMe() + console.log(me) +})().catch(e => { + console.error(e) +}) diff --git a/spotify-web-api-node/examples/tutorial/README.md b/spotify-web-api-node/examples/tutorial/README.md new file mode 100644 index 0000000..72f763d --- /dev/null +++ b/spotify-web-api-node/examples/tutorial/README.md @@ -0,0 +1,17 @@ +Execute all commands from the root folder of this repository. + +Start with + + git clone + cd spotify-web-api-node + npm install + npm install express + node examples/tutorial/00-get-access-token.js "" "" + +and visit in your browser to get an `access_token`. +If you don't have a `client_id` and `client_secret` yet, create an application here: to get them. Make sure you whitelist the correct redirectUri when creating your application, which is `http://localhost:8888/callback`. + +After you got the `access_token`, call all other examples with this token in ENV variable `SPOTIFY_ACCESS_TOKEN`. The easiest way is to call: + + export SPOTIFY_ACCESS_TOKEN="" + node examples/tutorial/01-basics/01-get-info-about-current-user.js diff --git a/spotify-web-api-node/package.json b/spotify-web-api-node/package.json new file mode 100644 index 0000000..25c887a --- /dev/null +++ b/spotify-web-api-node/package.json @@ -0,0 +1,69 @@ +{ + "name": "spotify-web-api-node", + "version": "5.0.4", + "homepage": "https://github.com/thelinmichael/spotify-web-api-node", + "description": "A Node.js wrapper for Spotify's Web API", + "main": "./src/server.js", + "author": "Michael Thelin", + "contributors": [ + { + "name": "José M. Perez", + "url": "https://github.com/JMPerez" + }, + { + "name": "Deeplydrumming", + "url": "https://gitlab.com/deeplydrumming" + } + ], + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/thelinmichael/spotify-web-api-node.git" + }, + "scripts": { + "test": "jest", + "travis": "npm test -- --coverage && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js", + "precommit": "lint-staged" + }, + "jest": { + "verbose": true, + "testURL": "http://localhost/" + }, + "lint-staged": { + "*.{js,json,css,md}": [ + "prettier --single-quote --write", + "git add" + ] + }, + "dependencies": { + "superagent": "^6.1.0" + }, + "devDependencies": { + "bufferutil": "^4.0.1", + "canvas": "^2.6.1", + "coveralls": "^3.1.0", + "husky": "^4.3.0", + "ini": ">=1.3.6", + "jest": "^26.6.3", + "jest-resolve": "^26.6.2", + "lint-staged": "^10.4.0", + "minimist": "^1.2.5", + "mixin-deep": ">=1.3.2", + "prettier": "^2.1.2", + "set-value": ">=2.0.1", + "sinon": "^9.0.3", + "utf-8-validate": "^5.0.2" + }, + "keywords": [ + "spotify", + "echonest", + "music", + "api", + "wrapper", + "client", + "web api" + ], + "browser": { + "./src/server.js": "./src/client.js" + } +} \ No newline at end of file diff --git a/spotify-web-api-node/src/authentication-request.js b/spotify-web-api-node/src/authentication-request.js new file mode 100644 index 0000000..6005ce0 --- /dev/null +++ b/spotify-web-api-node/src/authentication-request.js @@ -0,0 +1,14 @@ +'use strict' + +const Request = require('./base-request') + +const DEFAULT_HOST = 'accounts.spotify.com' +const DEFAULT_PORT = 443 +const DEFAULT_SCHEME = 'https' + +module.exports.builder = function () { + return Request.builder() + .withHost(DEFAULT_HOST) + .withPort(DEFAULT_PORT) + .withScheme(DEFAULT_SCHEME) +} diff --git a/spotify-web-api-node/src/base-request.js b/spotify-web-api-node/src/base-request.js new file mode 100644 index 0000000..175156a --- /dev/null +++ b/spotify-web-api-node/src/base-request.js @@ -0,0 +1,165 @@ +'use strict' + +const Request = function (builder) { + if (!builder) { + throw new Error('No builder supplied to constructor') + } + + this.host = builder.host + this.port = builder.port + this.scheme = builder.scheme + this.queryParameters = builder.queryParameters + this.bodyParameters = builder.bodyParameters + this.headers = builder.headers + this.path = builder.path +} + +Request.prototype._getter = function (key) { + return function () { + return this[key] + } +} + +Request.prototype.getHost = Request.prototype._getter('host') + +Request.prototype.getPort = Request.prototype._getter('port') + +Request.prototype.getScheme = Request.prototype._getter('scheme') + +Request.prototype.getPath = Request.prototype._getter('path') + +Request.prototype.getQueryParameters = Request.prototype._getter( + 'queryParameters' +) + +Request.prototype.getBodyParameters = Request.prototype._getter( + 'bodyParameters' +) + +Request.prototype.getHeaders = Request.prototype._getter('headers') + +Request.prototype.getURI = function () { + if (!this.scheme || !this.host || !this.port) { + throw new Error('Missing components necessary to construct URI') + } + let uri = this.scheme + '://' + this.host + if ( + (this.scheme === 'http' && this.port !== 80) || + (this.scheme === 'https' && this.port !== 443) + ) { + uri += ':' + this.port + } + if (this.path) { + uri += this.path + } + return uri +} + +Request.prototype.getURL = function () { + const uri = this.getURI() + if (this.getQueryParameters()) { + return uri + this.getQueryParameterString(this.getQueryParameters()) + } else { + return uri + } +} + +Request.prototype.getQueryParameterString = function () { + const queryParameters = this.getQueryParameters() + if (queryParameters) { + return ( + '?' + + Object.keys(queryParameters) + .filter(function (key) { + return queryParameters[key] !== undefined + }) + .map(function (key) { + return key + '=' + queryParameters[key] + }) + .join('&') + ) + } +} + +Request.prototype.execute = function (method, callback) { + if (callback) { + method(this, callback) + return + } + const _self = this + + return new Promise(function (resolve, reject) { + method(_self, function (error, result) { + if (error) { + reject(error) + } else { + resolve(result) + } + }) + }) +} + +const Builder = function () {} + +Builder.prototype._setter = function (key) { + return function (value) { + this[key] = value + return this + } +} + +Builder.prototype.withHost = Builder.prototype._setter('host') + +Builder.prototype.withPort = Builder.prototype._setter('port') + +Builder.prototype.withScheme = Builder.prototype._setter('scheme') + +Builder.prototype.withPath = Builder.prototype._setter('path') + +Builder.prototype._assigner = function (key) { + return function () { + for (let i = 0; i < arguments.length; i++) { + this[key] = this._assign(this[key], arguments[i]) + } + + return this + } +} + +Builder.prototype.withQueryParameters = Builder.prototype._assigner( + 'queryParameters' +) + +Builder.prototype.withBodyParameters = Builder.prototype._assigner( + 'bodyParameters' +) + +Builder.prototype.withHeaders = Builder.prototype._assigner('headers') + +Builder.prototype.withAuth = function (accessToken) { + if (accessToken) { + this.withHeaders({ Authorization: 'Bearer ' + accessToken }) + } + return this +} + +Builder.prototype._assign = function (src, obj) { + if (obj && Array.isArray(obj)) { + return obj + } + if (obj && typeof obj === 'string') { + return obj + } + if (obj && Object.keys(obj).length > 0) { + return Object.assign(src || {}, obj) + } + return src +} + +Builder.prototype.build = function () { + return new Request(this) +} + +module.exports.builder = function () { + return new Builder() +} diff --git a/spotify-web-api-node/src/client.js b/spotify-web-api-node/src/client.js new file mode 100644 index 0000000..77820d1 --- /dev/null +++ b/spotify-web-api-node/src/client.js @@ -0,0 +1 @@ +module.exports = require('./spotify-web-api') diff --git a/spotify-web-api-node/src/http-manager.js b/spotify-web-api-node/src/http-manager.js new file mode 100644 index 0000000..7feac6c --- /dev/null +++ b/spotify-web-api-node/src/http-manager.js @@ -0,0 +1,134 @@ +'use strict' + +const superagent = require('superagent') +const { + TimeoutError, + WebapiError, + WebapiRegularError, + WebapiAuthenticationError, + WebapiPlayerError +} = require('./response-error') + +const HttpManager = {} + +/* Create superagent options from the base request */ +const _getParametersFromRequest = function (request) { + const options = {} + + if (request.getQueryParameters()) { + options.query = request.getQueryParameters() + } + + if (request.getHeaders() && request.getHeaders()['Content-Type'] === 'application/json') { + options.data = JSON.stringify(request.getBodyParameters()) + } else if (request.getBodyParameters()) { + options.data = request.getBodyParameters() + } + + if (request.getHeaders()) { + options.headers = request.getHeaders() + } + return options +} + +const _toError = function (response) { + if (typeof response.body === 'object' && response.body.error && typeof response.body.error === 'object' && response.body.error.reason) { + return new WebapiPlayerError(response.body, response.headers, response.statusCode) + } + + if (typeof response.body === 'object' && response.body.error && typeof response.body.error === 'object') { + return new WebapiRegularError(response.body, response.headers, response.statusCode) + } + + if (typeof response.body === 'object' && response.body.error && typeof response.body.error === 'string') { + return new WebapiAuthenticationError(response.body, response.headers, response.statusCode) + } + + /* Other type of error, or unhandled Web API error format */ + return new WebapiError(response.body, response.headers, response.statusCode, response.body) +} + +/* Make the request to the Web API */ +HttpManager._makeRequest = function (method, options, uri, callback) { + const req = method.bind(superagent)(uri) + + if (options.query) { + req.query(options.query) + } + + if (options.headers) { + req.set(options.headers) + } + + if (options.data) { + req.send(options.data) + } + + req.end(function (err, response) { + if (err) { + if (err.timeout) { + return callback(new TimeoutError()) + } else if (err.response) { + return callback(_toError(err.response)) + } else { + return callback(err) + } + } + + return callback(null, { + body: response.body, + headers: response.headers, + statusCode: response.statusCode + }) + }) +} + +/** + * Make a HTTP GET request. + * @param {BaseRequest} The request. + * @param {Function} The callback function. + */ +HttpManager.get = function (request, callback) { + const options = _getParametersFromRequest(request) + const method = superagent.get + + HttpManager._makeRequest(method, options, request.getURI(), callback) +} + +/** + * Make a HTTP POST request. + * @param {BaseRequest} The request. + * @param {Function} The callback function. + */ +HttpManager.post = function (request, callback) { + const options = _getParametersFromRequest(request) + const method = superagent.post + + HttpManager._makeRequest(method, options, request.getURI(), callback) +} + +/** + * Make a HTTP DELETE request. + * @param {BaseRequest} The request. + * @param {Function} The callback function. + */ +HttpManager.del = function (request, callback) { + const options = _getParametersFromRequest(request) + const method = superagent.del + + HttpManager._makeRequest(method, options, request.getURI(), callback) +} + +/** + * Make a HTTP PUT request. + * @param {BaseRequest} The request. + * @param {Function} The callback function. + */ +HttpManager.put = function (request, callback) { + const options = _getParametersFromRequest(request) + const method = superagent.put + + HttpManager._makeRequest(method, options, request.getURI(), callback) +} + +module.exports = HttpManager diff --git a/spotify-web-api-node/src/response-error.js b/spotify-web-api-node/src/response-error.js new file mode 100644 index 0000000..030ed3c --- /dev/null +++ b/spotify-web-api-node/src/response-error.js @@ -0,0 +1,64 @@ +/* Timeout */ +class NamedError extends Error { + get name () { + return this.constructor.name + } +} + +class TimeoutError extends NamedError { + constructor () { + const message = 'A timeout occurred while communicating with Spotify\'s Web API.' + super(message) + } +} + +/* Web API Parent and fallback error */ +class WebapiError extends NamedError { + constructor (body, headers, statusCode, message) { + super(message) + this.body = body + this.headers = headers + this.statusCode = statusCode + } +} + +/** + * Regular Error + * { status : , message : } + */ +class WebapiRegularError extends WebapiError { + constructor (body, headers, statusCode) { + const message = 'An error occurred while communicating with Spotify\'s Web API.\n' + + 'Details: ' + body.error.message + '.' + + super(body, headers, statusCode, message) + } +} + +/** + * Authentication Error + * { error : , error_description : } + */ +class WebapiAuthenticationError extends WebapiError { + constructor (body, headers, statusCode) { + const message = 'An authentication error occurred while communicating with Spotify\'s Web API.\n' + + 'Details: ' + body.error + (body.error_description ? ' ' + body.error_description + '.' : '.') + + super(body, headers, statusCode, message) + } +} + +/** + * Player Error + * { status : , message : , reason : } + */ +class WebapiPlayerError extends WebapiError { + constructor (body, headers, statusCode) { + const message = 'An error occurred while communicating with Spotify\'s Web API.\n' + + 'Details: ' + body.error.message + (body.error.reason ? ' ' + body.error.reason + '.' : '.') + + super(body, headers, statusCode, message) + } +} + +module.exports = { WebapiError, TimeoutError, WebapiRegularError, WebapiAuthenticationError, WebapiPlayerError } diff --git a/spotify-web-api-node/src/server-methods.js b/spotify-web-api-node/src/server-methods.js new file mode 100644 index 0000000..d9a4fa6 --- /dev/null +++ b/spotify-web-api-node/src/server-methods.js @@ -0,0 +1,106 @@ +'use strict' + +const AuthenticationRequest = require('./authentication-request') +const HttpManager = require('./http-manager') + +module.exports = { + + /** + * Retrieve a URL where the user can give the application permissions. + * @param {string[]} scopes The scopes corresponding to the permissions the application needs. + * @param {string} state A parameter that you can use to maintain a value between the request and the callback to redirect_uri.It is useful to prevent CSRF exploits. + * @param {boolean} showDialog A parameter that you can use to force the user to approve the app on each login rather than being automatically redirected. + * @param {string} responseType An optional parameter that you can use to specify the code response based on the authentication type - can be set to 'code' or 'token'. Default 'code' to ensure backwards compatability. + * @returns {string} The URL where the user can give application permissions. + */ + createAuthorizeURL: function (scopes, state, showDialog, responseType = 'code') { + return AuthenticationRequest.builder() + .withPath('/authorize') + .withQueryParameters({ + client_id: this.getClientId(), + response_type: responseType, + redirect_uri: this.getRedirectURI(), + scope: scopes.join('%20'), + state, + show_dialog: showDialog && !!showDialog + }) + .build() + .getURL() + }, + + /** + * Request an access token using the Client Credentials flow. + * Requires that client ID and client secret has been set previous to the call. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an object containing the access token, + * token type and time to expiration. If rejected, it contains an error object. Not returned if a callback is given. + */ + clientCredentialsGrant: function (callback) { + return AuthenticationRequest.builder() + .withPath('/api/token') + .withBodyParameters({ + grant_type: 'client_credentials' + }) + .withHeaders({ + Authorization: + 'Basic ' + + Buffer.from( + this.getClientId() + ':' + this.getClientSecret() + ).toString('base64'), + 'Content-Type': 'application/x-www-form-urlencoded' + }) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Request an access token using the Authorization Code flow. + * Requires that client ID, client secret, and redirect URI has been set previous to the call. + * @param {string} code The authorization code returned in the callback in the Authorization Code flow. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an object containing the access token, + * refresh token, token type and time to expiration. If rejected, it contains an error object. + * Not returned if a callback is given. + */ + authorizationCodeGrant: function (code, callback) { + return AuthenticationRequest.builder() + .withPath('/api/token') + .withBodyParameters({ + grant_type: 'authorization_code', + redirect_uri: this.getRedirectURI(), + code, + client_id: this.getClientId(), + client_secret: this.getClientSecret() + }) + .withHeaders({ 'Content-Type': 'application/x-www-form-urlencoded' }) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Refresh the access token given that it hasn't expired. + * Requires that client ID, client secret and refresh token has been set previous to the call. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing the + * access token, time to expiration and token type. If rejected, it contains an error object. + * Not returned if a callback is given. + */ + refreshAccessToken: function (callback) { + return AuthenticationRequest.builder() + .withPath('/api/token') + .withBodyParameters({ + grant_type: 'refresh_token', + refresh_token: this.getRefreshToken() + }) + .withHeaders({ + Authorization: + 'Basic ' + + Buffer.from( + this.getClientId() + ':' + this.getClientSecret() + ).toString('base64'), + 'Content-Type': 'application/x-www-form-urlencoded' + }) + .build() + .execute(HttpManager.post, callback) + } +} diff --git a/spotify-web-api-node/src/server.js b/spotify-web-api-node/src/server.js new file mode 100644 index 0000000..7a63bb8 --- /dev/null +++ b/spotify-web-api-node/src/server.js @@ -0,0 +1,4 @@ +const SpotifyWebApi = require('./spotify-web-api') +const ServerMethods = require('./server-methods') +SpotifyWebApi._addMethods(ServerMethods) +module.exports = SpotifyWebApi diff --git a/spotify-web-api-node/src/spotify-web-api.js b/spotify-web-api-node/src/spotify-web-api.js new file mode 100644 index 0000000..9e1379c --- /dev/null +++ b/spotify-web-api-node/src/spotify-web-api.js @@ -0,0 +1,1661 @@ +'use strict' + +const AuthenticationRequest = require('./authentication-request') +const WebApiRequest = require('./webapi-request') +const HttpManager = require('./http-manager') + +function SpotifyWebApi (credentials) { + this._credentials = credentials || {} +} + +SpotifyWebApi.prototype = { + setCredentials: function (credentials) { + for (const key in credentials) { + if (credentials.hasOwnProperty(key)) { + this._credentials[key] = credentials[key] + } + } + }, + + getCredentials: function () { + return this._credentials + }, + + resetCredentials: function () { + this._credentials = null + }, + + setClientId: function (clientId) { + this._setCredential('clientId', clientId) + }, + + setClientSecret: function (clientSecret) { + this._setCredential('clientSecret', clientSecret) + }, + + setAccessToken: function (accessToken) { + this._setCredential('accessToken', accessToken) + }, + + setRefreshToken: function (refreshToken) { + this._setCredential('refreshToken', refreshToken) + }, + + setRedirectURI: function (redirectUri) { + this._setCredential('redirectUri', redirectUri) + }, + + getRedirectURI: function () { + return this._getCredential('redirectUri') + }, + + getClientId: function () { + return this._getCredential('clientId') + }, + + getClientSecret: function () { + return this._getCredential('clientSecret') + }, + + getAccessToken: function () { + return this._getCredential('accessToken') + }, + + getRefreshToken: function () { + return this._getCredential('refreshToken') + }, + + resetClientId: function () { + this._resetCredential('clientId') + }, + + resetClientSecret: function () { + this._resetCredential('clientSecret') + }, + + resetAccessToken: function () { + this._resetCredential('accessToken') + }, + + resetRefreshToken: function () { + this._resetCredential('refreshToken') + }, + + resetRedirectURI: function () { + this._resetCredential('redirectUri') + }, + + _setCredential: function (credentialKey, value) { + this._credentials = this._credentials || {} + this._credentials[credentialKey] = value + }, + + _getCredential: function (credentialKey) { + if (!this._credentials) { + + } else { + return this._credentials[credentialKey] + } + }, + + _resetCredential: function (credentialKey) { + if (!this._credentials) { + + } else { + this._credentials[credentialKey] = null + } + }, + + /** + * Look up a track. + * @param {string} trackId The track's ID. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getTrack('3Qm86XLflmIXVm1wcwkgDK').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the track. Not returned if a callback is given. + */ + getTrack: function (trackId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/tracks/' + trackId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up several tracks. + * @param {string[]} trackIds The IDs of the artists. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getArtists(['0oSGxfWSnnOXhD2fKuz2Gy', '3dBVyJ7JuOMt4GE9607Qin']).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the artists. Not returned if a callback is given. + */ + getTracks: function (trackIds, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/tracks') + .withQueryParameters( + { + ids: trackIds.join(',') + }, + options + ) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up an album. + * @param {string} albumId The album's ID. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAlbum('0sNOF9WDwhWunNAHPD3Baj').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the album. Not returned if a callback is given. + */ + getAlbum: function (albumId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/albums/' + albumId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up several albums. + * @param {string[]} albumIds The IDs of the albums. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAlbums(['0oSGxfWSnnOXhD2fKuz2Gy', '3dBVyJ7JuOMt4GE9607Qin']).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the albums. Not returned if a callback is given. + */ + getAlbums: function (albumIds, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/albums') + .withQueryParameters( + { + ids: albumIds.join(',') + }, + options + ) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up an artist. + * @param {string} artistId The artist's ID. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example api.getArtist('1u7kkVrr14iBvrpYnZILJR').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the artist. Not returned if a callback is given. + */ + getArtist: function (artistId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/artists/' + artistId) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up several artists. + * @param {string[]} artistIds The IDs of the artists. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getArtists(['0oSGxfWSnnOXhD2fKuz2Gy', '3dBVyJ7JuOMt4GE9607Qin']).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the artists. Not returned if a callback is given. + */ + getArtists: function (artistIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/artists') + .withQueryParameters({ + ids: artistIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Search for music entities of certain types. + * @param {string} query The search query. + * @param {string[]} types An array of item types to search across. + * Valid types are: 'album', 'artist', 'playlist', 'track', 'show', and 'episode'. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example search('Abba', ['track', 'playlist'], { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + search: function (query, types, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/search/') + .withQueryParameters( + { + type: types.join(','), + q: query + }, + options + ) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Search for an album. + * @param {string} query The search query. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchAlbums('Space Oddity', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchAlbums: function (query, options, callback) { + return this.search(query, ['album'], options, callback) + }, + + /** + * Search for an artist. + * @param {string} query The search query. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchArtists('David Bowie', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchArtists: function (query, options, callback) { + return this.search(query, ['artist'], options, callback) + }, + + /** + * Search for a track. + * @param {string} query The search query. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchTracks('Mr. Brightside', { limit : 3, offset : 2 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchTracks: function (query, options, callback) { + return this.search(query, ['track'], options, callback) + }, + + /** + * Search for playlists. + * @param {string} query The search query. + * @param {Object} options The possible options. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchPlaylists('workout', { limit : 1, offset : 0 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchPlaylists: function (query, options, callback) { + return this.search(query, ['playlist'], options, callback) + }, + + /** + * Get an artist's albums. + * @param {string} artistId The artist's ID. + * @options {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getArtistAlbums('0oSGxfWSnnOXhD2fKuz2Gy', { album_type : 'album', country : 'GB', limit : 2, offset : 5 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the albums + * for the given artist. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + getArtistAlbums: function (artistId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/artists/' + artistId + '/albums') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the tracks of an album. + * @param albumId the album's ID. + * @options {Object} [options] The possible options, e.g. limit. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAlbumTracks('41MnTivkwTO3UUJ8DrqEJJ', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * tracks in the album. The result is paginated. If the promise is rejected. + * it contains an error object. Not returned if a callback is given. + */ + getAlbumTracks: function (albumId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/albums/' + albumId + '/tracks') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get an artist's top tracks. + * @param {string} artistId The artist's ID. + * @param {string} country The country/territory where the tracks are most popular. (format: ISO 3166-1 alpha-2) + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getArtistTopTracks('0oSGxfWSnnOXhD2fKuz2Gy', 'GB').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * artist's top tracks in the given country. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + getArtistTopTracks: function (artistId, country, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/artists/' + artistId + '/top-tracks') + .withQueryParameters({ + country + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get related artists. + * @param {string} artistId The artist's ID. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getArtistRelatedArtists('0oSGxfWSnnOXhD2fKuz2Gy').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * related artists. If the promise is rejected, it contains an error object. Not returned if a callback is given. + */ + getArtistRelatedArtists: function (artistId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/artists/' + artistId + '/related-artists') + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get information about a user. + * @param userId The user ID. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getUser('thelinmichael').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object + * containing information about the user. If the promise is + * rejected, it contains an error object. Not returned if a callback is given. + */ + getUser: function (userId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/users/' + encodeURIComponent(userId)) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get information about the user that has signed in (the current user). + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getMe().then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object + * containing information about the user. The amount of information + * depends on the permissions given by the user. If the promise is + * rejected, it contains an error object. Not returned if a callback is given. + */ + getMe: function (callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me') + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get a user's playlists. + * @param {string} userId An optional id of the user. If you know the Spotify URI it is easy + * to find the id (e.g. spotify:user:). If not provided, the id of the user that granted + * the permissions will be used. + * @param {Object} [options] The options supplied to this request. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getUserPlaylists('thelinmichael').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing + * a list of playlists. If rejected, it contains an error object. Not returned if a callback is given. + */ + getUserPlaylists: function (userId, options, callback) { + let path + if (typeof userId === 'string') { + path = '/v1/users/' + encodeURIComponent(userId) + '/playlists' + } else if (typeof userId === 'object') { + callback = options + options = userId + path = '/v1/me/playlists' + } /* undefined */ else { + path = '/v1/me/playlists' + } + + return WebApiRequest.builder(this.getAccessToken()) + .withPath(path) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get a playlist. + * @param {string} playlistId The playlist's ID. + * @param {Object} [options] The options supplied to this request. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getPlaylist('3EsfV6XzCHU8SPNdbnFogK').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing + * the playlist. If rejected, it contains an error object. Not returned if a callback is given. + */ + getPlaylist: function (playlistId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get tracks in a playlist. + * @param {string} playlistId The playlist's ID. + * @param {Object} [options] Optional options, such as fields. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getPlaylistTracks('3ktAYNcRHpazJ9qecm3ptn').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object that containing + * the tracks in the playlist. If rejected, it contains an error object. Not returned if a callback is given. + */ + getPlaylistTracks: function (playlistId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Create a playlist. + * @param {string} [name] The name of the playlist. + * @param {Object} [options] The possible options, being description, collaborative and public. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example createPlaylist('My playlist', {''description': 'My description', 'collaborative' : false, 'public': true}).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing information about the + * created playlist. If rejected, it contains an error object. Not returned if a callback is given. + */ + createPlaylist: function (name, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/playlists') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters({ + name + }, options) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Follow a playlist. + * @param {string} playlistId The playlist's ID + * @param {Object} [options] The possible options, currently only public. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + followPlaylist: function (playlistId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/followers') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(options) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Unfollow a playlist. + * @param {string} playlistId The playlist's ID + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + unfollowPlaylist: function (playlistId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/followers') + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Change playlist details. + * @param {string} playlistId The playlist's ID + * @param {Object} [options] The possible options, e.g. name, public. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example changePlaylistDetails('3EsfV6XzCHU8SPNdbnFogK', {name: 'New name', public: true}).then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + changePlaylistDetails: function (playlistId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId) + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(options) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Replace the image used to represent a specific playlist. + * @param {string} playlistId The playlist's ID + * @param {string} base64URI Base64 encoded JPEG image data, maximum payload size is 256 KB + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example uploadCustomPlaylistCoverImage('3EsfV6XzCHU8SPNdbnFogK', 'longbase64uri').then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + uploadCustomPlaylistCoverImage: function (playlistId, base64URI, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/images') + .withHeaders({ 'Content-Type': 'image/jpeg' }) + .withBodyParameters(base64URI) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Add tracks to a playlist. + * @param {string} playlistId The playlist's ID + * @param {string[]} tracks URIs of the tracks to add to the playlist. + * @param {Object} [options] Options, position being the only one. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example addTracksToPlaylist('3EsfV6XzCHU8SPNdbnFogK', + '["spotify:track:4iV5W9uYEdYUVa79Axb7Rh", "spotify:track:1301WleyT98MSxVHPZCA6M"]').then(...) + * @returns {Promise|undefined} A promise that if successful returns an object containing a snapshot_id. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + addTracksToPlaylist: function (playlistId, tracks, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withQueryParameters(options) + .withBodyParameters({ + uris: tracks + }) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Remove tracks from a playlist. + * @param {string} playlistId The playlist's ID + * @param {Object[]} tracks An array of objects containing a property called uri with the track URI (String), and + * an optional property called positions (int[]), e.g. { uri : "spotify:track:491rM2JN8KvmV6p0oDDuJT", positions : [0, 15] } + * @param {Object} options Options, snapshot_id being the only one. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns an object containing a snapshot_id. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + removeTracksFromPlaylist: function (playlistId, tracks, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters( + { + tracks + }, + options + ) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Remove tracks from a playlist by position instead of specifying the tracks' URIs. + * @param {string} playlistId The playlist's ID + * @param {int[]} positions The positions of the tracks in the playlist that should be removed + * @param {string} snapshot_id The snapshot ID, or version, of the playlist. Required + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns an object containing a snapshot_id. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + removeTracksFromPlaylistByPosition: function ( + playlistId, + positions, + snapshotId, + callback + ) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters({ + positions, + snapshot_id: snapshotId + }) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Replace tracks in a playlist. + * @param {string} playlistId The playlist's ID + * @param {Object[]} uris An array of track URIs (strings) + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + replaceTracksInPlaylist: function (playlistId, uris, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters({ + uris + }) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Reorder tracks in a playlist. + * @param {string} playlistId The playlist's ID + * @param {int} rangeStart The position of the first track to be reordered. + * @param {int} insertBefore The position where the tracks should be inserted. + * @param {Object} options Optional parameters, i.e. range_length and snapshot_id. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns an object containing a snapshot_id. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + reorderTracksInPlaylist: function ( + playlistId, + rangeStart, + insertBefore, + options, + callback + ) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/playlists/' + playlistId + '/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters( + { + range_start: rangeStart, + insert_before: insertBefore + }, + options + ) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Get audio features for a single track identified by its unique Spotify ID. + * @param {string} trackId The track ID + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAudioFeaturesForTrack('38P3Q4QcdjQALGF2Z92BmR').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object + * containing information about the audio features. If the promise is + * rejected, it contains an error object. Not returned if a callback is given. + */ + getAudioFeaturesForTrack: function (trackId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/audio-features/' + trackId) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get audio analysis for a single track identified by its unique Spotify ID. + * @param {string} trackId The track ID + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAudioAnalysisForTrack('38P3Q4QcdjQALGF2Z92BmR').then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object + * containing information about the audio analysis. If the promise is + * rejected, it contains an error object. Not returned if a callback is given. + */ + getAudioAnalysisForTrack: function (trackId, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/audio-analysis/' + trackId) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get audio features for multiple tracks identified by their unique Spotify ID. + * @param {string[]} trackIds The track IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAudioFeaturesForTracks(['38P3Q4QcdjQALGF2Z92BmR', '2HO2bnoMrpnZUbUqiilLHi']).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object + * containing information about the audio features for the tracks. If the promise is + * rejected, it contains an error object. Not returned if a callback is given. + */ + getAudioFeaturesForTracks: function (trackIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/audio-features') + .withQueryParameters({ + ids: trackIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Create a playlist-style listening experience based on seed artists, tracks and genres. + * @param {Object} [options] The options supplied to this request. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getRecommendations({ min_energy: 0.4, seed_artists: ['6mfK6Q2tzLMEchAr0e9Uzu', '4DYFVNKZ1uixa6SQTvzQwJ'], min_popularity: 50 }).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing + * a list of tracks and a list of seeds. If rejected, it contains an error object. Not returned if a callback is given. + */ + getRecommendations: function (options, callback) { + const _opts = {} + const optionsOfTypeArray = ['seed_artists', 'seed_genres', 'seed_tracks'] + for (const option in options) { + if (options.hasOwnProperty(option)) { + if ( + optionsOfTypeArray.indexOf(option) !== -1 && + Object.prototype.toString.call(options[option]) === '[object Array]' + ) { + _opts[option] = options[option].join(',') + } else { + _opts[option] = options[option] + } + } + } + + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/recommendations') + .withQueryParameters(_opts) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve a list of available genres seed parameter values for recommendations. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getAvailableGenreSeeds().then(...) + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing + * a list of available genres to be used as seeds for recommendations. + * If rejected, it contains an error object. Not returned if a callback is given. + */ + getAvailableGenreSeeds: function (callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/recommendations/available-genre-seeds') + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve the tracks that are saved to the authenticated users Your Music library. + * @param {Object} [options] Options, being market, limit, and/or offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which in turn contains + * playlist track objects. Not returned if a callback is given. + */ + getMySavedTracks: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/tracks') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library. + * @param {string[]} trackIds The track IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an array of booleans. The order + * of the returned array's elements correspond to the track ID in the request. + * The boolean value of true indicates that the track is part of the user's library, otherwise false. + * Not returned if a callback is given. + */ + containsMySavedTracks: function (trackIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/tracks/contains') + .withQueryParameters({ + ids: trackIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Remove a track from the authenticated user's Your Music library. + * @param {string[]} trackIds The track IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. + * Not returned if a callback is given. + */ + removeFromMySavedTracks: function (trackIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters({ ids: trackIds }) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Add a track from the authenticated user's Your Music library. + * @param {string[]} trackIds The track IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. Not returned if a callback is given. + */ + addToMySavedTracks: function (trackIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/tracks') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters({ ids: trackIds }) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Remove an album from the authenticated user's Your Music library. + * @param {string[]} albumIds The album IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. + * Not returned if a callback is given. + */ + removeFromMySavedAlbums: function (albumIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/albums') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(albumIds) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Add an album from the authenticated user's Your Music library. + * @param {string[]} albumIds The track IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. Not returned if a callback is given. + */ + addToMySavedAlbums: function (albumIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/albums') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(albumIds) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Retrieve the albums that are saved to the authenticated users Your Music library. + * @param {Object} [options] Options, being market, limit, and/or offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which in turn contains + * playlist album objects. Not returned if a callback is given. + */ + getMySavedAlbums: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/albums') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Check if one or more albums is already saved in the current Spotify user’s “Your Music” library. + * @param {string[]} albumIds The album IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an array of booleans. The order + * of the returned array's elements correspond to the album ID in the request. + * The boolean value of true indicates that the album is part of the user's library, otherwise false. + * Not returned if a callback is given. + */ + containsMySavedAlbums: function (albumIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/albums/contains') + .withQueryParameters({ + ids: albumIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the current user's top artists based on calculated affinity. + * @param {Object} [options] Options, being time_range, limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of artists, + * otherwise an error. Not returned if a callback is given. + */ + getMyTopArtists: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/top/artists') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the current user's top tracks based on calculated affinity. + * @param {Object} [options] Options, being time_range, limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks, + * otherwise an error. Not returned if a callback is given. + */ + getMyTopTracks: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/top/tracks') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the Current User's Recently Played Tracks + * @param {Object} [options] Options, being type, after, limit, before. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of play history objects, + * otherwise an error. Not returned if a callback is given. Note that the response will be empty + * in case the user has enabled private session. + */ + getMyRecentlyPlayedTracks: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/recently-played') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Add track or episode to device queue + * @param {string} [uri] uri of the track or episode to add + * @param {Object} [options] Options, being device_id. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks, + * otherwise an error. Not returned if a callback is given. + */ + addToQueue: function (uri, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/queue') + .withQueryParameters( + { + uri + }, + options + ) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Get the Current User's Available Devices + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an array of device objects, + * otherwise an error. Not returned if a callback is given. + */ + getMyDevices: function (callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/devices') + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the Current User's Currently Playing Track. + * @param {Object} [options] Options, being market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks, + * otherwise an error. Not returned if a callback is given. + */ + getMyCurrentPlayingTrack: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/currently-playing') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get Information About The User's Current Playback State + * @param {Object} [options] Options, being market and additional_types. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks, + * otherwise an error. Not returned if a callback is given. + */ + getMyCurrentPlaybackState: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Transfer a User's Playback + * @param {string[]} [deviceIds] An _array_ containing a device ID on which playback should be started/transferred. + * (NOTE: The API is currently only supporting a single device ID.) + * @param {Object} [options] Options, the only one being 'play'. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + transferMyPlayback: function (deviceIds, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters( + { + device_ids: deviceIds + }, + options + ) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Starts o Resumes the Current User's Playback + * @param {Object} [options] Options, being device_id, context_uri, offset, uris, position_ms. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example play({context_uri: 'spotify:album:5ht7ItJgpBH7W6vJ5BqpPr'}).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + play: function (options, callback) { + /* jshint camelcase: false */ + const _options = options || {} + const queryParams = _options.device_id + ? { device_id: _options.device_id } + : null + const postData = {}; + ['context_uri', 'uris', 'offset', 'position_ms'].forEach(function (field) { + if (field in _options) { + postData[field] = _options[field] + } + }) + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/play') + .withQueryParameters(queryParams) + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(postData) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Pauses the Current User's Playback + * @param {Object} [options] Options, being device_id. If left empty will target the user's currently active device. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example pause().then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + pause: function (options, callback) { + return ( + WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/pause') + /* jshint camelcase: false */ + .withQueryParameters( + options && options.device_id ? { device_id: options.device_id } : null + ) + .withHeaders({ 'Content-Type': 'application/json' }) + .build() + .execute(HttpManager.put, callback) + ) + }, + + /** + * Skip the Current User's Playback To Previous Track + * @param {Object} [options] Options, being device_id. If left empty will target the user's currently active device. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example skipToPrevious().then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + skipToPrevious: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/previous') + .withQueryParameters( + options && options.device_id ? { device_id: options.device_id } : null + ) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Skip the Current User's Playback To Next Track + * @param {Object} [options] Options, being device_id. If left empty will target the user's currently active device. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example skipToNext().then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + skipToNext: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/next') + .withQueryParameters( + options && options.device_id ? { device_id: options.device_id } : null + ) + .build() + .execute(HttpManager.post, callback) + }, + + /** + * Seeks to the given position in the user’s currently playing track. + * + * @param {number} positionMs The position in milliseconds to seek to. Must be a positive number. + * @param {Object} options Options, being device_id. If left empty will target the user's currently active device. + * @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first + * one is the error object (null if no error), and the second is the value if the request succeeded. + * @return {Object} Null if a callback is provided, a `Promise` object otherwise + */ + seek: function (positionMs, options, callback) { + const params = { + /* jshint camelcase: false */ + position_ms: positionMs + } + if (options && 'device_id' in options) { + /* jshint camelcase: false */ + params.device_id = options.device_id + } + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/seek') + .withQueryParameters(params) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Set Repeat Mode On The Current User's Playback + * @param {string} [state] State (track, context, or off) + * @param {Object} [options] Options, being device_id. If left empty will target the user's currently active device. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example setRepeat('context', {}).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + setRepeat: function (state, options, callback) { + const params = { + state + } + if (options && 'device_id' in options) { + /* jshint camelcase: false */ + params.device_id = options.device_id + } + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/repeat') + .withQueryParameters(params) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Set Shuffle Mode On The Current User's Playback + * @param {boolean} [state] State + * @param {Object} [options] Options, being device_id. If left empty will target the user's currently active device. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example setShuffle({state: 'false'}).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an empty response, + * otherwise an error. Not returned if a callback is given. + */ + setShuffle: function (state, options, callback) { + const params = { + state + } + if (options && 'device_id' in options) { + /* jshint camelcase: false */ + params.device_id = options.device_id + } + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/shuffle') + .withQueryParameters(params) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Set the volume for the user’s current playback device. + * @param {number} volumePercent The volume to set. Must be a value from 0 to 100. + * @param {Object} options Options, being device_id. If left empty will target the user's currently active device. + * @param {function(Object,Object)} callback An optional callback that receives 2 parameters. The first + * one is the error object (null if no error), and the second is the value if the request succeeded. + * @return {Object} Null if a callback is provided, a `Promise` object otherwise + */ + setVolume: function (volumePercent, options, callback) { + const params = { + /* jshint camelcase: false */ + volume_percent: volumePercent + } + if (options && 'device_id' in options) { + /* jshint camelcase: false */ + params.device_id = options.device_id + } + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/player/volume') + .withQueryParameters(params) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Add the current user as a follower of one or more other Spotify users. + * @param {string[]} userIds The IDs of the users to be followed. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example followUsers(['thelinmichael', 'wizzler']).then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + followUsers: function (userIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following') + .withQueryParameters({ + ids: userIds.join(','), + type: 'user' + }) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Add the current user as a follower of one or more artists. + * @param {string[]} artistIds The IDs of the artists to be followed. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example followArtists(['0LcJLqbBmaGUft1e9Mm8HV', '3gqv1kgivAc92KnUm4elKv']).then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + followArtists: function (artistIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following') + .withQueryParameters({ + ids: artistIds.join(','), + type: 'artist' + }) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Remove the current user as a follower of one or more other Spotify users. + * @param {string[]} userIds The IDs of the users to be unfollowed. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example unfollowUsers(['thelinmichael', 'wizzler']).then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + unfollowUsers: function (userIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following') + .withQueryParameters({ + ids: userIds.join(','), + type: 'user' + }) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Remove the current user as a follower of one or more artists. + * @param {string[]} artistIds The IDs of the artists to be unfollowed. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example unfollowArtists(['0LcJLqbBmaGUft1e9Mm8HV', '3gqv1kgivAc92KnUm4elKv']).then(...) + * @returns {Promise|undefined} A promise that if successful, simply resolves to an empty object. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + unfollowArtists: function (artistIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following') + .withQueryParameters({ + ids: artistIds.join(','), + type: 'artist' + }) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Check to see if the current user is following one or more other Spotify users. + * @param {string[]} userIds The IDs of the users to check if are followed by the current user. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example isFollowingUsers(['thelinmichael', 'wizzler']).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an array of booleans. The order + * of the returned array's elements correspond to the users IDs in the request. + * The boolean value of true indicates that the user is following that user, otherwise is not. + * Not returned if a callback is given. + */ + isFollowingUsers: function (userIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following/contains') + .withQueryParameters({ + ids: userIds.join(','), + type: 'user' + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the current user's followed artists. + * @param {Object} [options] Options, being after and limit. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which contains + * album objects. Not returned if a callback is given. + */ + getFollowedArtists: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following') + .withQueryParameters( + { + type: 'artist' + }, + options + ) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Check if users are following a playlist. + * @param {string} userId The playlist's owner's user ID + * @param {string} playlistId The playlist's ID + * @param {String[]} User IDs of the following users + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns an array of booleans. If rejected, + * it contains an error object. Not returned if a callback is given. + */ + areFollowingPlaylist: function (userId, playlistId, followerIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath( + '/v1/users/' + + encodeURIComponent(userId) + + '/playlists/' + + playlistId + + '/followers/contains' + ) + .withQueryParameters({ + ids: followerIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Check to see if the current user is following one or more artists. + * @param {string[]} artistIds The IDs of the artists to check if are followed by the current user. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example isFollowingArtists(['0LcJLqbBmaGUft1e9Mm8HV', '3gqv1kgivAc92KnUm4elKv']).then(...) + * @returns {Promise|undefined} A promise that if successful, resolves into an array of booleans. The order + * of the returned array's elements correspond to the artists IDs in the request. + * The boolean value of true indicates that the user is following that artist, otherwise is not. + * Not returned if a callback is given. + */ + isFollowingArtists: function (artistIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/following/contains') + .withQueryParameters({ + ids: artistIds.join(','), + type: 'artist' + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve new releases + * @param {Object} [options] Options, being country, limit and/or offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which contains + * album objects. Not returned if a callback is given. + */ + getNewReleases: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/browse/new-releases') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve featured playlists + * @param {Object} [options] Options, being country, locale, timestamp, limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which contains + * featured playlists. Not returned if a callback is given. + */ + getFeaturedPlaylists: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/browse/featured-playlists') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve a list of categories used to tag items in Spotify (e.g. in the 'Browse' tab) + * @param {Object} [options] Options, being country, locale, limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object of categories. + * Not returned if a callback is given. + */ + getCategories: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/browse/categories') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve a category. + * @param {string} categoryId The id of the category to retrieve. + * @param {Object} [options] Options, being country, locale. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a category object. + * Not returned if a callback is given. + */ + getCategory: function (categoryId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/browse/categories/' + categoryId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Retrieve playlists for a category. + * @param {string} categoryId The id of the category to retrieve playlists for. + * @param {Object} [options] Options, being country, limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to a paging object containing simple playlists. + * Not returned if a callback is given. + */ + getPlaylistsForCategory: function (categoryId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/browse/categories/' + categoryId + '/playlists') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get a show. + * @param {string} showId The show's ID. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getShow('3Qm86XLflmIXVm1wcwkgDK').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the show. Not returned if a callback is given. + */ + getShow: function (showId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/shows/' + showId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up several shows. + * @param {string[]} showIds The IDs of the shows. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getShows(['0oSGxfWSnnOXhD2fKuz2Gy', '3dBVyJ7JuOMt4GE9607Qin']).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the shows. Not returned if a callback is given. + */ + getShows: function (showIds, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/shows') + .withQueryParameters( + { + ids: showIds.join(',') + }, + options + ) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Check if one or more shows is already saved in the current Spotify user’s “Your Music” library. + * @param {string[]} showIds The show IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves into an array of booleans. The order + * of the returned array's elements correspond to the show ID in the request. + * The boolean value of true indicates that the show is part of the user's library, otherwise false. + * Not returned if a callback is given. + */ + containsMySavedShows: function (showIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/shows/contains') + .withQueryParameters({ + ids: showIds.join(',') + }) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Remove an show from the authenticated user's Your Music library. + * @param {string[]} showIds The show IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. + * Not returned if a callback is given. + */ + removeFromMySavedShows: function (showIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/shows') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(showIds) + .build() + .execute(HttpManager.del, callback) + }, + + /** + * Add a show from the authenticated user's Your Music library. + * @param {string[]} showIds The show IDs + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful returns null, otherwise an error. Not returned if a callback is given. + */ + addToMySavedShows: function (showIds, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/shows') + .withHeaders({ 'Content-Type': 'application/json' }) + .withBodyParameters(showIds) + .build() + .execute(HttpManager.put, callback) + }, + + /** + * Retrieve the shows that are saved to the authenticated users Your Music library. + * @param {Object} [options] Options, being market, limit, and/or offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @returns {Promise|undefined} A promise that if successful, resolves to an object containing a paging object which in turn contains + * playlist show objects. Not returned if a callback is given. + */ + getMySavedShows: function (options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/me/shows') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Get the episodes of an show. + * @param showId the show's ID. + * @options {Object} [options] The possible options, being limit, offset, and market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getShowEpisodes('41MnTivkwTO3UUJ8DrqEJJ', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * episodes in the album. The result is paginated. If the promise is rejected. + * it contains an error object. Not returned if a callback is given. + */ + getShowEpisodes: function (showId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/shows/' + showId + '/episodes') + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Search for a show. + * @param {string} query The search query. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchShows('Space Oddity', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchShows: function (query, options, callback) { + return this.search(query, ['show'], options, callback) + }, + + /** + * Search for an episode. + * @param {string} query The search query. + * @param {Object} [options] The possible options, e.g. limit, offset. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example searchEpisodes('Space Oddity', { limit : 5, offset : 1 }).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing the + * search results. The result is paginated. If the promise is rejected, + * it contains an error object. Not returned if a callback is given. + */ + searchEpisodes: function (query, options, callback) { + return this.search(query, ['episode'], options, callback) + }, + + /** + * Look up an episode. + * @param {string} episodeId The episode's ID. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getEpisode('3Qm86XLflmIXVm1wcwkgDK').then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the episode. Not returned if a callback is given. + */ + getEpisode: function (episodeId, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/episodes/' + episodeId) + .withQueryParameters(options) + .build() + .execute(HttpManager.get, callback) + }, + + /** + * Look up several episodes. + * @param {string[]} episodeIds The IDs of the episodes. + * @param {Object} [options] The possible options, currently only market. + * @param {requestCallback} [callback] Optional callback method to be called instead of the promise. + * @example getEpisodes(['0oSGxfWSnnOXhD2fKuz2Gy', '3dBVyJ7JuOMt4GE9607Qin']).then(...) + * @returns {Promise|undefined} A promise that if successful, returns an object containing information + * about the episodes. Not returned if a callback is given. + */ + getEpisodes: function (episodeIds, options, callback) { + return WebApiRequest.builder(this.getAccessToken()) + .withPath('/v1/episodes') + .withQueryParameters( + { + ids: episodeIds.join(',') + }, + options + ) + .build() + .execute(HttpManager.get, callback) + } +} + +SpotifyWebApi._addMethods = function (methods) { + for (const i in methods) { + if (methods.hasOwnProperty(i)) { + this.prototype[i] = methods[i] + } + } +} + +module.exports = SpotifyWebApi diff --git a/spotify-web-api-node/src/webapi-request.js b/spotify-web-api-node/src/webapi-request.js new file mode 100644 index 0000000..8ee3bf0 --- /dev/null +++ b/spotify-web-api-node/src/webapi-request.js @@ -0,0 +1,15 @@ +'use strict' + +const Request = require('./base-request') + +const DEFAULT_HOST = 'api.spotify.com' +const DEFAULT_PORT = 443 +const DEFAULT_SCHEME = 'https' + +module.exports.builder = function (accessToken) { + return Request.builder() + .withHost(DEFAULT_HOST) + .withPort(DEFAULT_PORT) + .withScheme(DEFAULT_SCHEME) + .withAuth(accessToken) +}