add clientplayerapi and clientplaylistapi samples

Author: adamint

samples/src/main/kotlin/private/ClientPlayerApiSample.kt

@@ -2,7 +2,10 @@
 package private
 
 import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+import com.adamratzman.spotify.annotations.SpotifyExperimentalFunctionApi
+import com.adamratzman.spotify.endpoints.client.ClientPlayerApi.PlayerRepeatState.TRACK
 
+@SpotifyExperimentalFunctionApi
 fun main() {
     // instantiate api
     val api = spotifyClientApi(
@@ -13,4 +16,46 @@ fun main() {
             tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
         }
     }.build()
+
+    // print all devices connected to this Spotify account
+    println(api.player.getDevices().complete())
+
+    // get the current context track position
+    println(api.player.getCurrentContext().complete()?.progressMs)
+
+    // get the 20 most recently played (there is a small lag) tracks
+    println(api.player.getRecentlyPlayed().complete().map { it.track.name })
+
+    // get the currenty played PlaybackActions
+    println(api.player.getCurrentlyPlaying().complete()?.actions)
+
+    // pause playback on the current device
+    api.player.pause().complete()
+
+    // seek the beginning of the track currently playing
+    api.player.seek(0).complete()
+
+    // set repeat the current track
+    api.player.setRepeatMode(TRACK).complete()
+
+    // set volume to 50%
+    api.player.setVolume(50).complete()
+
+    // skip to the next track
+    api.player.skipForward().complete()
+
+    // skip back to the last track that was in the user queue
+    api.player.skipBehind().complete()
+
+    // resume playback
+    api.player.resume().complete()
+
+    // play song "I'm Good" by the Mowgli's
+    api.player.startPlayback(tracksToPlay = listOf(api.search.searchTrack("I'm Good the Mowgli's").complete()[0].uri.uri)).complete()
+
+    // toggle shuffling
+    api.player.toggleShuffle(shuffle = true).complete()
+
+    // transfer playback
+    api.player.transferPlayback("your_device_id").complete()
 }

samples/src/main/kotlin/private/ClientPlaylistApiSample.kt

@@ -13,4 +13,43 @@ fun main() {
             tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
         }
     }.build()
+
+    // create and print a new playlist called "Test Playlist"
+    val playlist = api.playlists.createClientPlaylist(
+            "Test Playlist",
+            "My test playlist description",
+            true
+    ).complete()
+
+    println(playlist)
+
+    // add "Reflections" by MisterWives to the end of your newly-created playlist
+    api.playlists.addTrackToClientPlaylist(playlist.id, "spotify:track:2PtBhfoPZ6VYtXkrE5FrCH").complete()
+
+    // change the playlist description to "My awesome playlist"
+    api.playlists.changeClientPlaylistDetails(playlist.id, description = "My awesome playlist").complete()
+
+    // get all your client playlists
+    println(api.playlists.getClientPlaylists(limit = 50).getAllItems().complete())
+
+    // get the number of tracks in a client playlist
+    println(api.playlists.getClientPlaylist(playlist.id).complete()?.tracks?.total)
+
+    // see https://developer.spotify.com/documentation/web-api/reference/playlists/reorder-playlists-tracks/
+    // for an example of re-ordering tracks
+
+    // replace the tracks in a client playlist with two songs by Lorde
+    api.playlists.setClientPlaylistTracks(playlist.id, "spotify:track:6ie2Bw3xLj2JcGowOlcMhb", "").complete()
+
+    // remove the song we just added from our client playlist
+    api.playlists.removeTrackFromClientPlaylist(playlist.id, "spotify:track:6ie2Bw3xLj2JcGowOlcMhb").complete()
+
+    // remove all playlist tracks
+    api.playlists.removeAllClientPlaylistTracks(playlist.id)
+
+    // upload a client playlist cover
+    api.playlists.uploadClientPlaylistCover(playlist.id, imageUrl = "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png").complete()
+
+    // delete a client playlist
+    api.playlists.deleteClientPlaylist(playlist.id).complete()
 }

src/commonMain/kotlin/com.adamratzman.spotify/annotations/ExperimentalAnnotations.kt

@@ -5,3 +5,8 @@ package com.adamratzman.spotify.annotations
 @Retention(AnnotationRetention.BINARY)
 @Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
 annotation class SpotifyExperimentalHttpApi
+
+@Experimental
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
+annotation class SpotifyExperimentalFunctionApi

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

@@ -6,9 +6,9 @@ import com.adamratzman.spotify.SpotifyException.BadRequestException
 import com.adamratzman.spotify.SpotifyRestAction
 import com.adamratzman.spotify.SpotifyRestActionPaging
 import com.adamratzman.spotify.SpotifyScope
+import com.adamratzman.spotify.annotations.SpotifyExperimentalFunctionApi
 import com.adamratzman.spotify.http.EndpointBuilder
 import com.adamratzman.spotify.http.SpotifyEndpoint
-import com.adamratzman.spotify.http.encodeUrl
 import com.adamratzman.spotify.models.AlbumUri
 import com.adamratzman.spotify.models.ArtistUri
 import com.adamratzman.spotify.models.CurrentlyPlayingContext
@@ -153,7 +153,7 @@ class ClientPlayerApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
     }
 
     /**
-     * Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off.
+     * Set the repeat mode for the user’s playback. Options are [PlayerRepeatState.TRACK], [PlayerRepeatState.CONTEXT], and [PlayerRepeatState.OFF].
      *
      * **Requires** the [SpotifyScope.USER_MODIFY_PLAYBACK_STATE] scope
      *
@@ -264,7 +264,7 @@ class ClientPlayerApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
         offsetNum: Int? = null,
         offsetTrackId: String? = null,
         deviceId: String? = null,
-        vararg tracksToPlay: String
+        tracksToPlay: List<String> = listOf()
     ): SpotifyRestAction<Unit> {
         return toAction {
             val url = EndpointBuilder("/me/player/play").with("device_id", deviceId).toString()
@@ -330,13 +330,14 @@ class ClientPlayerApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
      * @param deviceId The device to play on
      * @param play Whether to immediately start playback on the transferred device
      */
-    fun transferPlayback(vararg deviceId: String, play: Boolean = true): SpotifyRestAction<Unit> {
-        require(deviceId.size <= 1) { "Although an array is accepted, only a single device_id is currently supported. Supplying more than one will  400 Bad Request" }
+    @SpotifyExperimentalFunctionApi
+    fun transferPlayback(deviceId: String, play: Boolean? = null): SpotifyRestAction<Unit> {
+    //    require(deviceId.size <= 1) { "Although an array is accepted, only a single device_id is currently supported. Supplying more than one will  400 Bad Request" }
         return toAction {
-            put(
-                EndpointBuilder("/me/player").with("device_ids", deviceId.joinToString(",") { it.encodeUrl() })
-                    .with("play", play).toString()
-            )
+            val json = jsonMap()
+            play?.let { json += json { "play" to it } }
+            json += json { "device_ids" to JsonArray(listOf(deviceId).map(::JsonPrimitive)) }
+            put(EndpointBuilder("/me/player").toString(), json.toJson())
             Unit
         }
     }

src/commonTest/kotlin/com.adamratzman/spotify/utilities/RestActionTests.kt

@@ -1,13 +1,15 @@
 /* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
 package com.adamratzman.spotify.utilities
 
+import com.adamratzman.spotify.annotations.SpotifyExperimentalHttpApi
 import com.adamratzman.spotify.api
 import com.adamratzman.spotify.endpoints.public.SearchApi.SearchType.TRACK
 import com.adamratzman.spotify.utils.runBlocking
 import kotlin.test.assertEquals
 import org.spekframework.spek2.Spek
 import org.spekframework.spek2.style.specification.describe
 
+@SpotifyExperimentalHttpApi
 class RestActionTests : Spek({
     describe("Paging Object") {
         it("next test") {