add scope documentation to endpoints #87

Author: adamint

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientFollowingAPI.kt

@@ -1,13 +1,14 @@
 /* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
 package com.adamratzman.spotify.endpoints.client
 
-import com.adamratzman.spotify.endpoints.public.FollowingAPI
-import com.adamratzman.spotify.http.EndpointBuilder
-import com.adamratzman.spotify.http.encode
 import com.adamratzman.spotify.SpotifyAPI
 import com.adamratzman.spotify.SpotifyClientAPI
 import com.adamratzman.spotify.SpotifyRestAction
 import com.adamratzman.spotify.SpotifyRestActionPaging
+import com.adamratzman.spotify.SpotifyScope
+import com.adamratzman.spotify.endpoints.public.FollowingAPI
+import com.adamratzman.spotify.http.EndpointBuilder
+import com.adamratzman.spotify.http.encode
 import com.adamratzman.spotify.models.Artist
 import com.adamratzman.spotify.models.ArtistURI
 import com.adamratzman.spotify.models.CursorBasedPagingObject
@@ -22,11 +23,14 @@ import java.util.function.Supplier
  */
 class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
-     * Check to see if the current user is following another Spotify users.
+     * Check to see if the current user is following another Spotify user.
+     *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_READ] scope
      *
-     * @param user user id or uri to check.
+     * @param user The user id or uri to check.
      *
      * @throws BadRequestException if [user] is a non-existing id
+     * @return Whether the current user is following [user]
      */
     fun isFollowingUser(user: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -35,14 +39,18 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     }
 
     /**
-     * Check to see if the logged-in Spotify user is following the specified playlist.
+     * Check to see if the current Spotify user is following the specified playlist.
+     *
+     * Checking if the user is privately following a playlist is only possible for the current user when
+     * that user has granted access to the [SpotifyScope.PLAYLIST_READ_PRIVATE] scope.
      *
      * @param playlistOwner id or uri of the creator of the playlist
      * @param playlistId playlist id or uri
      *
-     * @return booleans representing whether the user follows the playlist. User IDs **not** found will return false
+     * @return Boolean representing whether the user follows the playlist
      *
      * @throws [BadRequestException] if the playlist is not found
+     * @return Whether the current user is following [playlistId]
      */
     fun isFollowingPlaylist(playlistOwner: String, playlistId: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -57,9 +65,12 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following one or more other Spotify users.
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_READ] scope
+     *
      * @param users List of the user Spotify IDs to check. Max 50
      *
      * @throws BadRequestException if [users] contains a non-existing id
+     * @return A list of booleans corresponding to [users] of whether the current user is following that user
      */
     fun isFollowingUsers(vararg users: String): SpotifyRestAction<List<Boolean>> {
         return toAction(Supplier {
@@ -73,9 +84,12 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following a Spotify artist.
      *
-     * @param artist artist id to check.
+     * **Requires** the [SpotifyScope.USER_FOLLOW_READ] scope
+     *
+     * @param artist The artist id to check.
      *
      * @throws BadRequestException if [artist] is a non-existing id
+     * @return Whether the current user is following [artist]
      */
     fun isFollowingArtist(artist: String): SpotifyRestAction<Boolean> {
         return toAction(Supplier {
@@ -86,9 +100,12 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Check to see if the current user is following one or more artists.
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_READ] scope
+     *
      * @param artists List of the artist ids or uris to check. Max 50
      *
      * @throws BadRequestException if [artists] contains a non-existing id
+     * @return A list of booleans corresponding to [artists] of whether the current user is following that artist
      */
     fun isFollowingArtists(vararg artists: String): SpotifyRestAction<List<Boolean>> {
         return toAction(Supplier {
@@ -102,6 +119,11 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Get the current user’s followed artists.
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_READ] scope
+     *
+     * @param limit The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param after The last artist ID retrieved from the previous request.
+     *
      * @return [CursorBasedPagingObject] ([Information about them](https://github.com/adamint/spotify-web-api-kotlin/blob/master/README.md#the-benefits-of-linkedresults-pagingobjects-and-cursor-based-paging-objects)
      * with full [Artist] objects
      */
@@ -122,6 +144,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of another user
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followUser(user: String): SpotifyRestAction<Unit> {
@@ -133,6 +157,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of other users
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followUsers(vararg users: String): SpotifyRestAction<Unit> {
@@ -148,6 +174,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of an artist
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followArtist(artistId: String): SpotifyRestAction<Unit> {
@@ -159,6 +187,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of other artists
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @throws BadRequestException if an invalid id is provided
      */
     fun followArtists(vararg artists: String): SpotifyRestAction<Unit> {
@@ -174,6 +204,13 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Add the current user as a follower of a playlist.
      *
+     * Following a playlist publicly requires authorization of the [SpotifyScope.PLAYLIST_MODIFY_PUBLIC] scope;
+     * following it privately requires the [SpotifyScope.PLAYLIST_MODIFY_PRIVATE] scope.
+     *
+     * Note that the scopes you provide determine only whether the current user can themselves follow the playlist
+     * publicly or privately (i.e. show others what they are following), not whether the playlist itself is
+     * public or private.
+     *
      * @param playlist the spotify id or uri of the playlist. Any playlist can be followed, regardless of its
      * public/private status, as long as you know its playlist ID.
      * @param followPublicly Defaults to true. If true the playlist will be included in user’s public playlists,
@@ -194,6 +231,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of another user
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @param user The user to be unfollowed from
      *
      * @throws BadRequestException if [user] is not found
@@ -207,6 +246,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of other users
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @param users The users to be unfollowed from
      *
      * @throws BadRequestException if an invalid id is provided
@@ -224,6 +265,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of an artist
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @param artist The artist to be unfollowed from
      *
      * @throws BadRequestException if an invalid id is provided
@@ -237,6 +280,8 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of artists
      *
+     * **Requires** the [SpotifyScope.USER_FOLLOW_MODIFY] scope
+     *
      * @param artists The artists to be unfollowed from
      *
      * @throws BadRequestException if an invalid id is provided
@@ -254,7 +299,13 @@ class ClientFollowingAPI(api: SpotifyAPI) : FollowingAPI(api) {
     /**
      * Remove the current user as a follower of a playlist.
      *
-     * @param playlist the spotify id or uri of the playlist that is to be no longer followed.
+     * Unfollowing a publicly followed playlist for a user requires authorization of the [SpotifyScope.PLAYLIST_MODIFY_PUBLIC] scope;
+     * unfollowing a privately followed playlist requires the [SpotifyScope.PLAYLIST_MODIFY_PRIVATE] scope.
+     *
+     * Note that the scopes you provide relate only to whether the current user is following the playlist publicly or
+     * privately (i.e. showing others what they are following), not whether the playlist itself is public or private.
+     *
+     * @param playlist The spotify id or uri of the playlist that is to be no longer followed.
      *
      * @throws BadRequestException if the playlist is not found
      */

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientLibraryAPI.kt

@@ -4,6 +4,7 @@ package com.adamratzman.spotify.endpoints.client
 import com.adamratzman.spotify.SpotifyAPI
 import com.adamratzman.spotify.SpotifyRestAction
 import com.adamratzman.spotify.SpotifyRestActionPaging
+import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.http.EndpointBuilder
 import com.adamratzman.spotify.http.SpotifyEndpoint
 import com.adamratzman.spotify.http.encode
@@ -24,12 +25,14 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.
      *
+     * **Requires** the [SpotifyScope.USER_LIBRARY_READ] scope
+     *
      * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
      * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
      * If omitted, the returned items will be relevant to all countries.
      *
-     * @return Paging Object of [SavedTrack] ordered by position in library
+     * @return [PagingObject] of [SavedTrack] ordered by position in library
      */
     fun getSavedTracks(
         limit: Int? = null,
@@ -47,6 +50,8 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Get a list of the albums saved in the current Spotify user’s ‘Your Music’ library.
      *
+     * **Requires** the [SpotifyScope.USER_LIBRARY_READ] scope
+     *
      * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
      * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
@@ -70,8 +75,10 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Check if the [LibraryType] with id [id] is already saved in the current Spotify user’s ‘Your Music’ library.
      *
-     * @param type the type of object (album or track)
-     * @param id the spotify id or uri of the object
+     * **Requires** the [SpotifyScope.USER_LIBRARY_READ] scope
+     *
+     * @param type The type of object (album or track)
+     * @param id The spotify id or uri of the object
      *
      * @throws BadRequestException if [id] is not found
      */
@@ -84,8 +91,10 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Check if one or more of [LibraryType] is already saved in the current Spotify user’s ‘Your Music’ library.
      *
-     * @param type the type of objects (album or track)
-     * @param ids the spotify ids or uris of the objects
+     * **Requires** the [SpotifyScope.USER_LIBRARY_READ] scope
+     *
+     * @param type The type of objects (album or track)
+     * @param ids The spotify ids or uris of the objects
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
@@ -101,8 +110,10 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Save one of [LibraryType] to the current user’s ‘Your Music’ library.
      *
-     * @param type the type of object (album or track)
-     * @param id the spotify id or uri of the object
+     * **Requires** the [SpotifyScope.USER_LIBRARY_MODIFY] scope
+     *
+     * @param type The type of object (album or track)
+     * @param id The spotify id or uri of the object
      *
      * @throws BadRequestException if the id is invalid
      */
@@ -115,8 +126,10 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Save one or more of [LibraryType] to the current user’s ‘Your Music’ library.
      *
-     * @param type the type of objects to check against (album or track)
-     * @param ids the spotify ids or uris of the objects
+     * **Requires** the [SpotifyScope.USER_LIBRARY_MODIFY] scope
+     *
+     * @param type The type of objects to check against (album or track)
+     * @param ids The spotify ids or uris of the objects
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
@@ -130,8 +143,12 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Remove one of [LibraryType] (track or album) from the current user’s ‘Your Music’ library.
      *
-     * @param type the type of object to check against (album or track)
-     * @param id the spotify id or uri of the object
+     * Changes to a user’s saved items may not be visible in other Spotify applications immediately.
+     *
+     * **Requires** the [SpotifyScope.USER_LIBRARY_MODIFY] scope
+     *
+     * @param type The type of object to check against (album or track)
+     * @param id The spotify id or uri of the object
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
@@ -144,8 +161,12 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     /**
      * Remove one or more of the [LibraryType] (tracks or albums) from the current user’s ‘Your Music’ library.
      *
-     * @param type the type of objects to check against (album or track)
-     * @param ids the spotify ids or uris of the objects
+     * Changes to a user’s saved items may not be visible in other Spotify applications immediately.
+
+     * **Requires** the [SpotifyScope.USER_LIBRARY_MODIFY] scope
+     *
+     * @param type The type of objects to check against (album or track)
+     * @param ids The spotify ids or uris of the objects
      *
      * @throws BadRequestException if any of the provided ids is invalid
      */
@@ -161,7 +182,7 @@ class ClientLibraryAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
  * Type of object in a user's Spotify library
  *
  * @param value Spotify id for the type
- * @param id how to transform an id (or uri) input into its Spotify id
+ * @param id How to transform an id (or uri) input into its Spotify id
  */
 enum class LibraryType(private val value: String, internal val id: (String) -> String) {
     TRACK("tracks", { TrackURI(it).id }), ALBUM("albums", { AlbumURI(it).id });

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientPersonalizationAPI.kt

@@ -1,10 +1,11 @@
 /* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
 package com.adamratzman.spotify.endpoints.client
 
-import com.adamratzman.spotify.http.EndpointBuilder
-import com.adamratzman.spotify.http.SpotifyEndpoint
 import com.adamratzman.spotify.SpotifyAPI
 import com.adamratzman.spotify.SpotifyRestActionPaging
+import com.adamratzman.spotify.SpotifyScope
+import com.adamratzman.spotify.http.EndpointBuilder
+import com.adamratzman.spotify.http.SpotifyEndpoint
 import com.adamratzman.spotify.models.Artist
 import com.adamratzman.spotify.models.PagingObject
 import com.adamratzman.spotify.models.Track
@@ -28,6 +29,7 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
 
     /**
      * Get the current user’s top artists based on calculated affinity.
+     *
      * Affinity is a measure of the expected preference a user has for a particular track or artist.  It is based on user
      * behavior, including play history, but does not include actions made while in incognito mode. Light or infrequent
      * users of Spotify may not have sufficient play history to generate a full affinity data set. As a user’s behavior
@@ -36,9 +38,11 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      * for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
      * once each day for each user.
      *
+     * **Requires** the [SpotifyScope.USER_TOP_READ] scope
+     *
      * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
-     * @param timeRange the time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
+     * @param timeRange The time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
      *
      * @return [PagingObject] of full [Artist] objects sorted by affinity
      */
@@ -58,6 +62,7 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
 
     /**
      * Get the current user’s top tracks based on calculated affinity.
+     *
      * Affinity is a measure of the expected preference a user has for a particular track or artist.  It is based on user
      * behavior, including play history, but does not include actions made while in incognito mode. Light or infrequent
      * users of Spotify may not have sufficient play history to generate a full affinity data set. As a user’s behavior
@@ -66,9 +71,11 @@ class ClientPersonalizationAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      * for each user. In the future, it is likely that this restriction will be relaxed. This data is typically updated
      * once each day for each user.
      *
+     * **Requires** the [SpotifyScope.USER_TOP_READ] scope
+     *
      * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
      * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
-     * @param timeRange the time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
+     * @param timeRange The time range to which to compute this. The default is [TimeRange.MEDIUM_TERM]
      *
      * @return [PagingObject] of full [Track] objects sorted by affinity
      */