document Spotify web playback sdk on README and link to example project

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

Author: adamint

README.md

@@ -29,6 +29,8 @@ supporting Kotlin/JS, Kotlin/Android, Kotlin/JVM, and Kotlin/Native
     + [SpotifyApiBuilder block & setting API options](#spotifyapibuilder-block--setting-api-options)
         * [API options](#api-options)
     + [Using the API](#using-the-api)
+* [Platform-specific wrappers and information]("#platform-specific-wrappers-and-information")
+    + [JavaScript: Spotify Web Playback SDK wrapper](#js-spotify-web-playback-sdk-wrapper)
 * [Tips](#tips)
     + [Building the API](#building-the-api)
 * [Notes](#notes)
@@ -51,6 +53,9 @@ repositories {
 implementation("com.adamratzman:spotify-api-kotlin-core:VERSION")
 ```
 
+### JS
+Please see 
+
 ### Android
 **If you declare any release types not named debug or release, you may see "Could not resolve com.adamratzman:spotify-api-kotlin-android:VERSION". You need to do the following for each release type not named debug or release:**
 ```
@@ -369,6 +374,21 @@ APIs available only in `SpotifyClientApi` and `SpotifyImplicitGrantApi` instance
 - `ClientLibraryApi` (get and manage saved tracks and albums)
 - `ClientPlayerApi` (view and control Spotify playback)
 
+## Platform-specific wrappers and information
+### Android authentication
+
+### JS Spotify Web Playback SDK wrapper
+`spotify-web-api-kotlin` provides a wrapper around Spotify's [Web Playback SDK](https://developer.spotify.com/documentation/web-playback-sdk/reference/) 
+for playing music via Spotify in the browser on your own site.
+
+To do this, you need to create a `Player` instance and then use the associated methods to register listeners, play, 
+and get current context.
+
+**Please see an example of how to do this [here](https://github.com/adamint/spotify-web-api-browser-example/blob/95df60810611ddb961a7a2cb0c874a76d4471aa7/src/main/kotlin/com/adamratzman/layouts/HomePageComponent.kt#L38)**. 
+An example project, [spotify-web-api-browser-example](https://github.com/adamint/spotify-web-api-browser-example), 
+demonstrates how to create a frontend JS Kotlin application with Spotify integration and 
+that will play music in the browser.
+
 ## Tips
 
 ### Building the API

gradle/wrapper/gradle-wrapper.jar

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.6.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.2-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

gradle/wrapper/gradle-wrapper.properties

@@ -82,6 +82,7 @@ esac
 
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 
+
 # Determine the Java command to use to start the JVM.
 if [ -n "$JAVA_HOME" ] ; then
     if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
@@ -129,6 +130,7 @@ fi
 if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
     APP_HOME=`cygpath --path --mixed "$APP_HOME"`
     CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+
     JAVACMD=`cygpath --unix "$JAVACMD"`
 
     # We build the pattern for arguments to be converted via cygpath

gradlew

@@ -29,6 +29,9 @@ if "%DIRNAME%" == "" set DIRNAME=.
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
 @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
 set DEFAULT_JVM_OPTS="-Xmx64m" "-Xms64m"
 
@@ -37,7 +40,7 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto init
+if "%ERRORLEVEL%" == "0" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
@@ -51,7 +54,7 @@ goto fail
 set JAVA_HOME=%JAVA_HOME:"=%
 set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
-if exist "%JAVA_EXE%" goto init
+if exist "%JAVA_EXE%" goto execute
 
 echo.
 echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
@@ -61,28 +64,14 @@ echo location of your Java installation.
 
 goto fail
 
-:init
-@rem Get command-line arguments, handling Windows variants
-
-if not "%OS%" == "Windows_NT" goto win9xME_args
-
-:win9xME_args
-@rem Slurp the command line arguments.
-set CMD_LINE_ARGS=
-set _SKIP=2
-
-:win9xME_args_slurp
-if "x%~1" == "x" goto execute
-
-set CMD_LINE_ARGS=%*
-
 :execute
 @rem Setup the command line
 
 set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
+
 @rem Execute Gradle
-"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
 
 :end
 @rem End local scope for the variables with windows NT shell

gradlew.bat

@@ -863,7 +863,7 @@ public class SpotifyUserAuthorization(
  * (https://api.spotify.com/v1).
  * @param retryOnInternalServerErrorTimes Whether and how often to retry once if an internal server error (500..599) has been received. Set to 0
  * to avoid retrying at all, or set to null to keep retrying until success.
- *
+ * @param enableDebugMode Whether to enable debug mode (false by default). With debug mode, all response JSON will be outputted to console.
  */
 public data class SpotifyApiOptions(
     public var useCache: Boolean = true,
@@ -880,5 +880,6 @@ public data class SpotifyApiOptions(
     public var onTokenRefresh: (suspend (GenericSpotifyApi) -> Unit)? = null,
     public var requiredScopes: List<SpotifyScope>? = null,
     public var proxyBaseUrl: String? = null,
-    public var retryOnInternalServerErrorTimes: Int? = 5
+    public var retryOnInternalServerErrorTimes: Int? = 5,
+    public var enableDebugMode: Boolean = false
 )

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

@@ -2,6 +2,7 @@
 package com.adamratzman.spotify.endpoints.client
 
 import com.adamratzman.spotify.GenericSpotifyApi
+import com.adamratzman.spotify.SpotifyException
 import com.adamratzman.spotify.SpotifyException.BadRequestException
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.annotations.SpotifyExperimentalFunctionApi
@@ -97,12 +98,16 @@ public class ClientPlayerApi(api: GenericSpotifyApi) : SpotifyEndpoint(api) {
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/player/get-the-users-currently-playing-track/)**
      */
     public suspend fun getCurrentlyPlaying(): CurrentlyPlayingObject? {
-        val obj =
-            catch {
-                get(endpointBuilder("/me/player/currently-playing").toString())
-                    .toObject(CurrentlyPlayingObject.serializer(), api, json)
-            }
-        return if (obj?.timestamp == null) null else obj
+        return try {
+            val obj =
+                catch {
+                    get(endpointBuilder("/me/player/currently-playing").toString())
+                        .toObject(CurrentlyPlayingObject.serializer(), api, json)
+                }
+            if (obj?.timestamp == null) null else obj
+        } catch (pe: SpotifyException.ParseException) {
+            null
+        }
     }
 
     /**

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

@@ -89,7 +89,7 @@ public class HttpConnection constructor(
         retryIfInternalServerErrorLeft: Int? = SpotifyApiOptions().retryOnInternalServerErrorTimes // default
     ): HttpResponse {
         val httpRequest = buildRequest(additionalHeaders)
-
+        if (api?.spotifyApiOptions?.enableDebugMode == true) println("DEBUG MODE: Request: $this")
         try {
             return HttpClient().request<io.ktor.client.statement.HttpResponse>(httpRequest).let { response ->
                 val respCode = response.status.value
@@ -118,6 +118,8 @@ public class HttpConnection constructor(
                 }
 
                 val body = response.readText()
+                if (api?.spotifyApiOptions?.enableDebugMode == true) println("DEBUG MODE: $body")
+
                 if (respCode == 401 && body.contains("access token") &&
                     api != null && api.spotifyApiOptions.automaticRefresh
                 ) {
@@ -145,12 +147,23 @@ public class HttpConnection constructor(
             throw e
         } catch (e: ResponseException) {
             val errorBody = e.response.readText()
+            if (api?.spotifyApiOptions?.enableDebugMode == true) println("DEBUG MODE: $errorBody")
             try {
-                if (e.response.status.value == 429) {
+                val respCode = e.response.status.value
+
+                if (respCode in 500..599 && (retryIfInternalServerErrorLeft == null || retryIfInternalServerErrorLeft == -1 || retryIfInternalServerErrorLeft > 0)) {
+                    return execute(
+                        additionalHeaders,
+                        retryIfInternalServerErrorLeft =
+                        if (retryIfInternalServerErrorLeft != null && retryIfInternalServerErrorLeft != -1) retryIfInternalServerErrorLeft - 1
+                        else retryIfInternalServerErrorLeft
+                    )
+                }
+
+                if (respCode == 429) {
                     val ratelimit = e.response.headers["Retry-After"]!!.toLong() + 1L
                     if (api?.spotifyApiOptions?.retryWhenRateLimited == true) {
-                        println("The request ($url) was ratelimited for $ratelimit seconds at ${getCurrentTimeMs()}")
-
+                        // println("The request ($url) was ratelimited for $ratelimit seconds at ${getCurrentTimeMs()}")
                         delay(ratelimit * 1000)
                         return execute(
                             additionalHeaders,
@@ -165,7 +178,10 @@ public class HttpConnection constructor(
                     api.refreshToken()
                     val newAdditionalHeaders = additionalHeaders?.toMutableList() ?: mutableListOf()
                     newAdditionalHeaders.add(0, HttpHeader("Authorization", "Bearer ${api.token.accessToken}"))
-                    return execute(newAdditionalHeaders, retryIfInternalServerErrorLeft = retryIfInternalServerErrorLeft)
+                    return execute(
+                        newAdditionalHeaders,
+                        retryIfInternalServerErrorLeft = retryIfInternalServerErrorLeft
+                    )
                 }
 
                 val error = errorBody.toObject(

src/commonMain/kotlin/com.adamratzman.spotify/http/HttpConnection.kt

@@ -11,4 +11,4 @@ public expect class ConcurrentHashMap<K, V>() {
     public val entries: MutableSet<MutableMap.MutableEntry<K, V>>
 }
 
-public expect fun <K, V> ConcurrentHashMap<K, V>.asList(): List<Pair<K, V>>
+public expect fun <K, V> ConcurrentHashMap<K, V>.asList(): List<Pair<K, V>>

src/commonMain/kotlin/com.adamratzman.spotify/utils/Types.kt

@@ -4,6 +4,7 @@ package com.adamratzman.spotify.priv
 import com.adamratzman.spotify.SpotifyClientApi
 import com.adamratzman.spotify.SpotifyException
 import com.adamratzman.spotify.assertFailsWithSuspend
+import com.adamratzman.spotify.buildSpotifyApi
 import com.adamratzman.spotify.endpoints.client.SpotifyTrackPositions
 import com.adamratzman.spotify.models.Playlist
 import com.adamratzman.spotify.models.SimplePlaylist
@@ -22,6 +23,12 @@ class ClientPlaylistApiTest {
     lateinit var createdPlaylist: Playlist
     lateinit var playlistsBefore: List<SimplePlaylist>
 
+    init {
+        runBlockingTest {
+            (buildSpotifyApi() as? SpotifyClientApi)?.let { api = it }
+        }
+    }
+
     private suspend fun init() {
         if (::api.isInitialized) {
             playlistsBefore = api.playlists.getClientPlaylists().getAllItemsNotNull()