add scope checks

Signed-off-by: Adam Ratzman <adam@adamratzman.com>

Author: adamint

src/commonMain/kotlin/com.adamratzman.spotify/SpotifyApi.kt

@@ -11,7 +11,6 @@ import com.adamratzman.spotify.endpoints.client.ClientPersonalizationApi
 import com.adamratzman.spotify.endpoints.client.ClientPlayerApi
 import com.adamratzman.spotify.endpoints.client.ClientPlaylistApi
 import com.adamratzman.spotify.endpoints.client.ClientProfileApi
-import com.adamratzman.spotify.endpoints.client.ClientSearchApi
 import com.adamratzman.spotify.endpoints.client.ClientShowApi
 import com.adamratzman.spotify.endpoints.pub.AlbumApi
 import com.adamratzman.spotify.endpoints.pub.ArtistApi
@@ -491,8 +490,7 @@ public open class SpotifyClientApi(
     override val browse: BrowseApi = BrowseApi(this)
     override val artists: ArtistApi = ArtistApi(this)
     override val tracks: TrackApi = TrackApi(this)
-
-    override val search: ClientSearchApi = ClientSearchApi(this)
+    override val search: SearchApi = SearchApi(this)
 
     override val episodes: ClientEpisodeApi = ClientEpisodeApi(this)
     override val shows: ClientShowApi = ClientShowApi(this)

src/commonMain/kotlin/com.adamratzman.spotify/SpotifyExceptions.kt

@@ -9,45 +9,74 @@ public sealed class SpotifyException(message: String, cause: Throwable? = null)
     public abstract class UnNullableException(message: String) : SpotifyException(message)
 
     /**
-     * Thrown when a request fails
+     * Thrown when a request fails.
+     *
+     * @param statusCode The status code of the request, if this exception is thrown after the completion of an HTTP request.
+     * @param reason The reason for the failure, as a readable message.
      */
-    public open class BadRequestException(message: String, public val statusCode: Int? = null, public val reason: String? = null, cause: Throwable? = null) :
-            SpotifyException(message, cause) {
+    public open class BadRequestException(
+        message: String,
+        public val statusCode: Int? = null,
+        public val reason: String? = null,
+        cause: Throwable? = null
+    ) :
+        SpotifyException(message, cause) {
         public constructor(message: String, cause: Throwable? = null) : this(message, null, null, cause)
         public constructor(error: ErrorObject?, cause: Throwable? = null) : this(
-                "Received Status Code ${error?.status}. Error cause: ${error?.message}" + (error?.reason?.let { ". Reason: ${error.reason}" }
-                        ?: ""),
-                error?.status,
-                error?.reason,
-                cause
+            "Received Status Code ${error?.status}. Error cause: ${error?.message}" + (error?.reason?.let { ". Reason: ${error.reason}" }
+                ?: ""),
+            error?.status,
+            error?.reason,
+            cause
         )
 
         public constructor(authenticationError: AuthenticationError) :
                 this(
-                        "Authentication error: ${authenticationError.error}. Description: ${authenticationError.description}",
-                        401
+                    "Authentication error: ${authenticationError.error}. Description: ${authenticationError.description}",
+                    401
                 )
 
         public constructor(responseException: ResponseException) :
                 this(
-                        responseException.message ?: "Bad Request",
-                        responseException.response.status.value,
-                        null,
-                        responseException
+                    responseException.message ?: "Bad Request",
+                    responseException.response.status.value,
+                    null,
+                    responseException
                 )
     }
 
+    /**
+     * Exception signifying that JSON (de)serialization failed. This is likely a library error rather than user error.
+     */
     public class ParseException(message: String, cause: Throwable? = null) : SpotifyException(message, cause)
 
+    /**
+     * Exception signifying that authentication (via token or code) was unsuccessful, likely due to an invalid access token, code,
+     * or refresh token.
+     */
     public class AuthenticationException(message: String, cause: Throwable? = null) : SpotifyException(message, cause) {
         public constructor(authenticationError: AuthenticationError?) :
                 this("Authentication error: ${authenticationError?.error}. Description: ${authenticationError?.description}")
     }
 
+    /**
+     * Exception signifying that the HTTP request associated with this API endpoint timed out (by default, after 100 seconds).
+     */
     public class TimeoutException(message: String, cause: Throwable? = null) : SpotifyException(message, cause)
 
     /**
      * Exception signifying that re-authentication via spotify-auth is necessary. Thrown by default when refreshTokenProducer is null.
      */
-    public class ReAuthenticationNeededException(cause: Throwable? = null, message: String? = null) : SpotifyException(message ?: "Re-authentication is needed.", cause)
+    public class ReAuthenticationNeededException(cause: Throwable? = null, message: String? = null) :
+        SpotifyException(message ?: "Re-authentication is needed.", cause)
+
+    /**
+     * Exception signifying that the current api token does not have the necessary scope to complete this request
+     *
+     */
+    public class SpotifyScopesNeededException(cause: Throwable? = null, public val missingScopes: List<SpotifyScope>) :
+        BadRequestException(
+            cause = cause,
+            message = "You tried to call a method that requires the following missing scopes: $missingScopes. Please make sure that your token is requested with these scopes."
+        )
 }

src/commonMain/kotlin/com.adamratzman.spotify/endpoints/client/ClientEpisodeApi.kt

@@ -52,7 +52,9 @@ public class ClientEpisodeApi(api: GenericSpotifyApi) : EpisodeApi(api) {
      *
      * @return possibly-null [Episode].
      */
-    public fun getEpisodeRestAction(id: String): SpotifyRestAction<Episode?> = SpotifyRestAction { getEpisode(id) }
+    public fun getEpisodeRestAction(id: String): SpotifyRestAction<Episode?> {
+        return SpotifyRestAction { getEpisode(id) }
+    }
 
     /**
      * Get Spotify catalog information for multiple episodes based on their Spotify IDs. The [Market] associated with
@@ -70,7 +72,9 @@ public class ClientEpisodeApi(api: GenericSpotifyApi) : EpisodeApi(api) {
      * @throws BadRequestException If any invalid show id is provided
      */
     public suspend fun getEpisodes(vararg ids: String): List<Episode?> {
+        requireScopes(SpotifyScope.USER_READ_PLAYBACK_POSITION)
         checkBulkRequesting(50, ids.size)
+
         return bulkRequest(50, ids.toList()) { chunk ->
             get(
                 endpointBuilder("/episodes")
@@ -95,7 +99,9 @@ public class ClientEpisodeApi(api: GenericSpotifyApi) : EpisodeApi(api) {
      * @return List of possibly-null [Episode] objects.
      * @throws BadRequestException If any invalid show id is provided
      */
-    public fun getEpisodesRestAction(vararg ids: String): SpotifyRestAction<List<Episode?>> = SpotifyRestAction {
-        getEpisodes(*ids)
+    public fun getEpisodesRestAction(vararg ids: String): SpotifyRestAction<List<Episode?>> {
+        return SpotifyRestAction {
+            getEpisodes(*ids)
+        }
     }
 }

src/commonMain/kotlin/com.adamratzman.spotify/endpoints/client/ClientFollowingApi.kt

@@ -36,7 +36,10 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if [user] is a non-existing id
      * @return Whether the current user is following [user]
      */
-    public suspend fun isFollowingUser(user: String): Boolean = isFollowingUsers(user)[0]
+    public suspend fun isFollowingUser(user: String): Boolean {
+        requireScopes(SpotifyScope.USER_FOLLOW_READ)
+        return isFollowingUsers(user)[0]
+    }
 
     /**
      * Check to see if the current user is following another Spotify user.
@@ -50,8 +53,9 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if [user] is a non-existing id
      * @return Whether the current user is following [user]
      */
-    public fun isFollowingUserRestAction(user: String): SpotifyRestAction<Boolean> =
-        SpotifyRestAction { isFollowingUser(user) }
+    public fun isFollowingUserRestAction(user: String): SpotifyRestAction<Boolean> {
+        return SpotifyRestAction { isFollowingUser(user) }
+    }
 
     /**
      * Check to see if the current Spotify user is following the specified playlist.
@@ -68,11 +72,12 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws [BadRequestException] if the playlist is not found
      * @return Whether the current user is following [playlistId]
      */
-    public suspend fun isFollowingPlaylist(playlistId: String): Boolean =
-        isFollowingPlaylist(
+    public suspend fun isFollowingPlaylist(playlistId: String): Boolean {
+        return isFollowingPlaylist(
             playlistId,
             (api as SpotifyClientApi).getUserId()
         )
+    }
 
     /**
      * Check to see if the current Spotify user is following the specified playlist.
@@ -105,6 +110,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @return A list of booleans corresponding to [users] of whether the current user is following that user
      */
     public suspend fun isFollowingUsers(vararg users: String): List<Boolean> {
+        requireScopes(SpotifyScope.USER_FOLLOW_READ)
         checkBulkRequesting(50, users.size)
         return bulkRequest(50, users.toList()) { chunk ->
             get(
@@ -126,8 +132,9 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @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
      */
-    public fun isFollowingUsersRestAction(vararg users: String): SpotifyRestAction<List<Boolean>> =
-        SpotifyRestAction { isFollowingUsers(*users) }
+    public fun isFollowingUsersRestAction(vararg users: String): SpotifyRestAction<List<Boolean>> {
+        return SpotifyRestAction { isFollowingUsers(*users) }
+    }
 
     /**
      * Check to see if the current user is following a Spotify artist.
@@ -155,8 +162,9 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if [artist] is a non-existing id
      * @return Whether the current user is following [artist]
      */
-    public fun isFollowingArtistRestAction(artist: String): SpotifyRestAction<Boolean> =
-        SpotifyRestAction { isFollowingArtist(artist) }
+    public fun isFollowingArtistRestAction(artist: String): SpotifyRestAction<Boolean> {
+        return SpotifyRestAction { isFollowingArtist(artist) }
+    }
 
     /**
      * Check to see if the current user is following one or more artists.
@@ -171,6 +179,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @return A list of booleans corresponding to [artists] of whether the current user is following that artist
      */
     public suspend fun isFollowingArtists(vararg artists: String): List<Boolean> {
+        requireScopes(SpotifyScope.USER_FOLLOW_READ)
         checkBulkRequesting(50, artists.size)
         return bulkRequest(50, artists.toList()) { chunk ->
             get(
@@ -192,8 +201,9 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @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
      */
-    public fun isFollowingArtistsRestAction(vararg artists: String): SpotifyRestAction<List<Boolean>> =
-        SpotifyRestAction { isFollowingArtists(*artists) }
+    public fun isFollowingArtistsRestAction(vararg artists: String): SpotifyRestAction<List<Boolean>> {
+        return SpotifyRestAction { isFollowingArtists(*artists) }
+    }
 
     /**
      * Get the current user’s followed artists.
@@ -211,12 +221,15 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
     public suspend fun getFollowedArtists(
         limit: Int? = api.spotifyApiOptions.defaultLimit,
         after: String? = null
-    ): CursorBasedPagingObject<Artist> = get(
-        endpointBuilder("/me/following").with("type", "artist").with("limit", limit).with(
-            "after",
-            after
-        ).toString()
-    ).toCursorBasedPagingObject(Artist::class, Artist.serializer(), "artists", api, json)
+    ): CursorBasedPagingObject<Artist> {
+        requireScopes(SpotifyScope.USER_FOLLOW_READ)
+        return get(
+            endpointBuilder("/me/following").with("type", "artist").with("limit", limit).with(
+                "after",
+                after
+            ).toString()
+        ).toCursorBasedPagingObject(Artist::class, Artist.serializer(), "artists", api, json)
+    }
 
     /**
      * Get the current user’s followed artists.
@@ -270,6 +283,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if an invalid id is provided
      */
     public suspend fun followUsers(vararg users: String) {
+        requireScopes(SpotifyScope.USER_FOLLOW_MODIFY)
         checkBulkRequesting(50, users.size)
         bulkRequest(50, users.toList()) { chunk ->
             put(
@@ -313,7 +327,8 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      *
      * @throws BadRequestException if an invalid id is provided
      */
-    public fun followArtistRestAction(artistId: String): SpotifyRestAction<Unit> = SpotifyRestAction { followArtist(artistId) }
+    public fun followArtistRestAction(artistId: String): SpotifyRestAction<Unit> =
+        SpotifyRestAction { followArtist(artistId) }
 
     /**
      * Add the current user as a follower of other artists
@@ -327,6 +342,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if an invalid id is provided
      */
     public suspend fun followArtists(vararg artists: String) {
+        requireScopes(SpotifyScope.USER_FOLLOW_MODIFY)
         checkBulkRequesting(50, artists.size)
         bulkRequest(50, artists.toList()) { chunk ->
             put(
@@ -369,10 +385,14 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      *
      * @throws BadRequestException if the playlist is not found
      */
-    public suspend fun followPlaylist(playlist: String, followPublicly: Boolean = true): String = put(
-        endpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString(),
-        "{\"public\": $followPublicly}"
-    )
+    public suspend fun followPlaylist(playlist: String, followPublicly: Boolean = true): String {
+        requireScopes(SpotifyScope.PLAYLIST_MODIFY_PUBLIC, SpotifyScope.PLAYLIST_MODIFY_PRIVATE, anyOf = true)
+
+        return put(
+            endpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString(),
+            "{\"public\": $followPublicly}"
+        )
+    }
 
     /**
      * Add the current user as a follower of a playlist.
@@ -393,10 +413,13 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      *
      * @throws BadRequestException if the playlist is not found
      */
-    public fun followPlaylistRestAction(playlist: String, followPublicly: Boolean): SpotifyRestAction<String> =
-        SpotifyRestAction {
+    public fun followPlaylistRestAction(playlist: String, followPublicly: Boolean): SpotifyRestAction<String> {
+        requireScopes(SpotifyScope.PLAYLIST_MODIFY_PUBLIC, SpotifyScope.PLAYLIST_MODIFY_PRIVATE, anyOf = true)
+
+        return SpotifyRestAction {
             followPlaylist(playlist, followPublicly)
         }
+    }
 
     /**
      * Remove the current user as a follower of another user
@@ -437,6 +460,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if an invalid id is provided
      */
     public suspend fun unfollowUsers(vararg users: String) {
+        requireScopes(SpotifyScope.USER_FOLLOW_MODIFY)
         checkBulkRequesting(50, users.size)
         bulkRequest(50, users.toList()) { list ->
             delete(
@@ -502,6 +526,7 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      * @throws BadRequestException if an invalid id is provided
      */
     public suspend fun unfollowArtists(vararg artists: String) {
+        requireScopes(SpotifyScope.USER_FOLLOW_MODIFY)
         checkBulkRequesting(50, artists.size)
         bulkRequest(50, artists.toList()) { list ->
             delete(
@@ -542,8 +567,11 @@ public class ClientFollowingApi(api: GenericSpotifyApi) : FollowingApi(api) {
      *
      * @throws BadRequestException if the playlist is not found
      */
-    public suspend fun unfollowPlaylist(playlist: String): String =
-        delete(endpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString())
+    public suspend fun unfollowPlaylist(playlist: String): String {
+        requireScopes(SpotifyScope.PLAYLIST_MODIFY_PUBLIC, SpotifyScope.PLAYLIST_MODIFY_PRIVATE, anyOf = true)
+
+        return delete(endpointBuilder("/playlists/${PlaylistUri(playlist).id}/followers").toString())
+    }
 
     /**
      * Remove the current user as a follower of a playlist.