Rewrite player api methods and add docs

Author: thelinmichael

CHANGELOG.md

@@ -2,9 +2,12 @@
 
 #### 5.0.0 (27 Sep 2020)
 
+* **BREAKING CHANGE**. Some methods controlling the player has changed. If a change has been made, a new primary argument has been added. This is because it's required by Spotify's API and should therefore not be placed in `options`.
 * Bumped dependencies to resolve critical security issues. 
-* Added support for [Implicit Grant flow](https://developer.spotify.com/documentation/general/guides/authorization-guide/#implicit-grant-flow) - Thanks [@gaganza](https://github.com/gaganza) and [@noahp78](https://github.com/noahp78)!
+* 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)!
 * `position_ms` added to `play` method. Thanks [@alqubo](https://github.com/alqubo), [@koflin](https://github.com/koflin), [@DoctorFishy](https://github.com/DoctorFishy).
+* Documentation updates to keep up to date with ES6, thanks [@dandv](https://github.com/dandv)!
+* `reason` added to error object, which is returned by the [Player API](https://developer.spotify.com/documentation/web-api/reference/player/). Much appreciated [@konstantinjdobler](https://github.com/konstantinjdobler)!
 
 More coming before NPM release.
 

README.md

@@ -48,7 +48,7 @@ The library includes helper functions to do the following:
 #### 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
+* Check if a track or album is in the signed in user's Your Music library 
 
 #### Personalization
 
@@ -64,6 +64,22 @@ The library includes helper functions to do the following:
 * 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
@@ -693,21 +709,69 @@ spotifyApi.getPlaylistsForCategory('party', {
     console.log("Something went wrong!", err);
   });
 
+// Get Recommendations Based on Seeds
+// TBD
 
+// Get available genre seeds
+// TBD
 
 /* Player */
 
-// Get information about current playing song for signed in user
-spotifyApi.getMyCurrentPlaybackState({
-  })
+// Get a User's Available Devices
+// TBD
+
+// Get Information About The User's Current Playback State
+spotifyApi.getMyCurrentPlaybackState()
   .then(function(data) {
     // Output items
-    console.log("Now Playing: ",data.body);
+    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 Recommendations Based on Seeds */
+// Get the User's Currently Playing Track 
+// TBD
+
+// Pause a User's Playback
+// TBD
+
+// Seek To Position In Currently Playing Track
+// TBD
+
+// Set Repeat Mode On User’s Playback
+// TBD
+
+// Set Volume For User's Playback
+// TBD
+
+// Skip User’s Playback To Next Track
+// TBD
+
+// Skip User’s Playback To Previous Track 
+// TBD
+
+// Start/Resume a User's Playback 
+// TBD
+
+// Toggle Shuffle For User’s Playback
+// TBD
+
+// Transfer a User's Playback
 // TBD
 
 

src/spotify-web-api.js

@@ -1016,8 +1016,9 @@ SpotifyWebApi.prototype = {
    * 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 tracks,
-   *          otherwise an error. Not returned if a callback is given.
+   * @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())
@@ -1028,9 +1029,9 @@ SpotifyWebApi.prototype = {
   },
 
   /**
-   * Get the Current User's Connect Devices
+   * 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 a paging object of tracks,
+   * @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) {
@@ -1056,8 +1057,8 @@ SpotifyWebApi.prototype = {
   },
 
   /**
-   * Get the Current User's Current Playback State
-   * @param {Object} [options] Options, being market.
+   * 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.
@@ -1072,17 +1073,19 @@ SpotifyWebApi.prototype = {
 
   /**
    * Transfer a User's Playback
-   * @param {Object} [options] Options, being market.
+   * @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 a paging object of tracks,
+   * @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(options, callback) {
+  transferMyPlayback: function(deviceIds, options, callback) {
     return WebApiRequest.builder(this.getAccessToken())
       .withPath('/v1/me/player')
       .withHeaders({ 'Content-Type': 'application/json' })
       .withBodyParameters({
-        device_ids: options.deviceIds,
+        device_ids: deviceIds,
         play: !!options.play
       })
       .build()
@@ -1093,8 +1096,8 @@ SpotifyWebApi.prototype = {
    * 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 playbackResume({context_uri: 'spotify:album:5ht7ItJgpBH7W6vJ5BqpPr'}).then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @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) {
@@ -1120,10 +1123,10 @@ SpotifyWebApi.prototype = {
 
   /**
    * Pauses the Current User's Playback
-   * @param {Object} [options] Options, for now device_id,
+   * @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 playbackPause().then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @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) {
@@ -1142,29 +1145,37 @@ SpotifyWebApi.prototype = {
 
   /**
    * 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 playbackPrevious().then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @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(callback) {
     return WebApiRequest.builder(this.getAccessToken())
       .withPath('/v1/me/player/previous')
+      .withQueryParameters(
+        options && options.device_id ? { device_id: options.device_id } : null
+      )
       .withHeaders({ 'Content-Type': 'application/json' })
       .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 playbackNext().then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @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(callback) {
     return WebApiRequest.builder(this.getAccessToken())
       .withPath('/v1/me/player/next')
+      .withQueryParameters(
+        options && options.device_id ? { device_id: options.device_id } : null
+      )
       .withHeaders({ 'Content-Type': 'application/json' })
       .build()
       .execute(HttpManager.post, callback);
@@ -1174,7 +1185,7 @@ SpotifyWebApi.prototype = {
    * 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 A JSON object with options that can be passed.
+   * @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
@@ -1197,45 +1208,56 @@ SpotifyWebApi.prototype = {
 
   /**
    * Set Repeat Mode On The Current User's Playback
-   * @param {Object} [options] Options, being state (track, context, off).
+   * @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 playbackRepeat({state: 'context'}).then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @example setRepeat({state: '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(options, callback) {
+  setRepeat: function(state, options, callback) {
+    var params = {
+      state: 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({
-        state: options.state || 'off'
-      })
+      .withQueryParameters(params)
       .build()
       .execute(HttpManager.put, callback);
   },
 
   /**
    * Set Shuffle Mode On The Current User's Playback
-   * @param {Object} [options] Options, being state (true, false).
+   * @param {string} [state] State (true, false)
+   * @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 playbackShuffle({state: 'false'}).then(...)
-   * @returns {Promise|undefined} A promise that if successful, resolves into a paging object of tracks,
+   * @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(options, callback) {
+  setShuffle: function(state, options, callback) {
+    var params = {
+      state: 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({
-        state: options.state || 'false'
-      })
+      .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 inclusive.
-   * @param {Object} options A JSON object with options that can be passed.
+   * @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