Simplify ApiBuilderDsl implementation

* Added suspend building
* Moved some code into common interface instead of reimplementing
  the same stuff
* Specify the BuilderType for common SpotifyApi
* Make SpotifyApi sealed
* Added isTokenValid suspending function

Author: molikuner

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

@@ -7,19 +7,16 @@ import com.adamratzman.spotify.models.SpotifyAuthenticationException
 import com.adamratzman.spotify.models.Token
 import com.adamratzman.spotify.models.serialization.toObject
 import com.adamratzman.spotify.utils.runBlocking
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.GlobalScope
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
-import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.launch
-import kotlinx.coroutines.withContext
 
 // Kotlin DSL builders
 
 fun spotifyAppApi(block: SpotifyAppApiBuilder.() -> Unit) = SpotifyAppApiBuilder().apply(block)
 fun spotifyClientApi(block: SpotifyClientApiBuilder.() -> Unit) = SpotifyClientApiBuilder().apply(block)
 
-/** //TODO add suspend functions
+/**
  *  Spotify API builder
  */
 class SpotifyApiBuilder(
@@ -101,7 +98,7 @@ class SpotifyApiBuilder(
      * Create a [SpotifyApi] instance with the given [SpotifyApiBuilder] parameters and the type -
      * [AuthorizationType.CLIENT] for client authentication, or otherwise [AuthorizationType.APPLICATION]
      */
-    fun build(type: AuthorizationType): SpotifyApi {
+    fun build(type: AuthorizationType): SpotifyApi<*, *> {
         return if (type == AuthorizationType.CLIENT) buildClient()
         else buildCredentialed()
     }
@@ -114,7 +111,7 @@ class SpotifyApiBuilder(
     /**
      * Create a new [SpotifyAppApi] that only has access to *public* endpoints and data
      */
-    fun buildCredentialed(): SpotifyApi = spotifyAppApi {
+    fun buildCredentialed(): SpotifyAppApi = spotifyAppApi {
         credentials {
             clientId = this@SpotifyApiBuilder.clientId
             clientSecret = this@SpotifyApiBuilder.clientSecret
@@ -143,7 +140,7 @@ enum class AuthorizationType {
     APPLICATION;
 }
 
-interface ISpotifyApiBuilder {
+interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B: ISpotifyApiBuilder<T, B>> {
     var credentials: SpotifyCredentials
     var authorization: SpotifyUserAuthorization
     var options: SpotifyApiOptions
@@ -196,27 +193,35 @@ interface ISpotifyApiBuilder {
     }
 
     fun options(options: SpotifyApiOptions) = apply { this.options = options }
-}
 
-interface ISpotifyClientApiBuilder : ISpotifyApiBuilder {
     /**
-     * Build the client api by providing an authorization code, token string, or token object. Only one of the following
-     * needs to be provided
+     * Build the [T] by provided information
+     */
+    suspend fun suspendBuild(): T
+
+    /**
+     * Build the [T] by provided information
+     */
+    fun build(): T = runBlocking { suspendBuild() }
+
+    /**
+     * Build the [T] by provided information
      *
-     * @param authorizationCode Spotify authorization code retrieved after authentication
-     * @param tokenString Spotify authorization token
-     * @param token [Token] object (useful if you already have exchanged an authorization code yourself
+     * Provide a consumer object to be executed after the api has been successfully built
      */
-    fun build(): SpotifyClientApi
+    fun buildAsyncAt(scope: CoroutineScope, consumer: (T) -> Unit): Job = with(scope) { buildAsync(consumer) }
 
     /**
-     * Build the client api using a provided authorization code, token string, or token object (only one of which
-     * is necessary)
+     * Build the [T] by provided information
      *
-     * Provide a consumer object to be executed after the client has been successfully built
+     * Provide a consumer object to be executed after the api has been successfully built
      */
-    suspend fun buildAsync(consumer: (SpotifyClientApi) -> Unit)
+    fun CoroutineScope.buildAsync(consumer: (T) -> Unit): Job = launch {
+        consumer(suspendBuild())
+    }
+}
 
+interface ISpotifyClientApiBuilder : ISpotifyApiBuilder<SpotifyClientApi, SpotifyClientApiBuilder> {
     /**
      * Create a Spotify authorization URL from which API access can be obtained
      *
@@ -236,15 +241,14 @@ class SpotifyClientApiBuilder(
         return getAuthUrlFull(*scopes, clientId = credentials.clientId!!, redirectUri = credentials.redirectUri!!)
     }
 
-    override fun build(): SpotifyClientApi {
+    override suspend fun suspendBuild(): SpotifyClientApi {
         val clientId = credentials.clientId
         val clientSecret = credentials.clientSecret
         val redirectUri = credentials.redirectUri
 
         require((clientId != null && clientSecret != null && redirectUri != null) || authorization.token != null || authorization.tokenString != null) { "You need to specify a valid clientId, clientSecret, and redirectUri in the credentials block!" }
         return when {
-            authorization.authorizationCode != null -> runBlocking {
-                try {
+            authorization.authorizationCode != null -> try {
                     require(clientId != null && clientSecret != null && redirectUri != null) { "You need to specify a valid clientId, clientSecret, and redirectUri in the credentials block!" }
 
                     val response = executeTokenRequest(
@@ -278,7 +282,6 @@ class SpotifyClientApiBuilder(
                 } catch (e: Exception) {
                     throw SpotifyAuthenticationException("Invalid credentials provided in the login process", e)
                 }
-            }
             authorization.token != null -> SpotifyClientApi(
                 clientId,
                 clientSecret,
@@ -315,49 +318,19 @@ class SpotifyClientApiBuilder(
             )
         }
     }
-
-    override suspend fun buildAsync(consumer: (SpotifyClientApi) -> Unit) = coroutineScope {
-        withContext(Dispatchers.Default) { consumer(build()) }
-    }
 }
 
-interface ISpotifyAppApiBuilder : ISpotifyApiBuilder {
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     *
-     * @param consumer Consumer to be executed after the api has been successfully built
-     */
-    fun buildAsync(consumer: (SpotifyApi) -> Unit): Job
-
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     */
-    fun build(): SpotifyApi
-}
+interface ISpotifyAppApiBuilder : ISpotifyApiBuilder<SpotifyAppApi, SpotifyAppApiBuilder>
 
 class SpotifyAppApiBuilder(
     override var credentials: SpotifyCredentials = SpotifyCredentialsBuilder().build(),
     override var authorization: SpotifyUserAuthorization = SpotifyUserAuthorizationBuilder().build(),
     override var options: SpotifyApiOptions = SpotifyApiOptionsBuilder().build()
 ) : ISpotifyAppApiBuilder {
-    /**
-     * Create a new [SpotifyAppApi] that only has access to *public* endpoints and data
-     */
-    fun buildPublic() = build()
-
-    /**
-     * Build a public [SpotifyAppApi] using the provided credentials
-     *
-     * Provide a consumer object to be executed after the api has been successfully built
-     */
-    override fun buildAsync(consumer: (SpotifyApi) -> Unit) = GlobalScope.launch {
-        withContext(Dispatchers.Default) { consumer(build()) }
-    }
-
     /**
      * Build a public [SpotifyAppApi] using the provided credentials
      */
-    override fun build(): SpotifyApi {
+    override suspend fun suspendBuild(): SpotifyAppApi {
         val clientId = credentials.clientId
         val clientSecret = credentials.clientSecret
         require((clientId != null && clientSecret != null) || authorization.token != null || authorization.tokenString != null) { "You didn't specify a client id or client secret in the credentials block!" }
@@ -393,7 +366,7 @@ class SpotifyAppApiBuilder(
             }
             else -> try {
                 require(clientId != null && clientSecret != null) { "Illegal credentials provided" }
-                val token = runBlocking { getCredentialedToken(clientId, clientSecret, null) }
+                val token = getCredentialedToken(clientId, clientSecret, null)
                 SpotifyAppApi(
                     clientId,
                     clientSecret,

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

@@ -28,6 +28,9 @@ import com.adamratzman.spotify.models.TokenValidityResponse
 import com.adamratzman.spotify.models.serialization.toObject
 import com.adamratzman.spotify.utils.runBlocking
 import com.adamratzman.spotify.utils.toList
+import kotlinx.coroutines.Dispatchers
+import kotlin.coroutines.CoroutineContext
+import kotlin.jvm.JvmOverloads
 
 internal const val base = "https://api.spotify.com/v1"
 
@@ -52,7 +55,7 @@ internal const val base = "https://api.spotify.com/v1"
  * @property logger The Spotify event logger
  *
  */
-abstract class SpotifyApi internal constructor(
+sealed class SpotifyApi<T: SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>(
     val clientId: String?,
     val clientSecret: String?,
     var token: Token,
@@ -126,7 +129,7 @@ abstract class SpotifyApi internal constructor(
     /**
      * Return a new [SpotifyApiBuilderDsl] with the parameters provided to this api instance
      */
-    abstract fun getApiBuilderDsl(): ISpotifyApiBuilder
+    abstract fun getApiBuilderDsl(): B
 
     private fun clearCaches(vararg endpoints: SpotifyEndpoint) {
         endpoints.forEach { it.cache.clear() }
@@ -155,23 +158,29 @@ abstract class SpotifyApi internal constructor(
         return getAuthUrlFull(*scopes, clientId = clientId, redirectUri = redirectUri)
     }
 
-    /** //TODO add suspend version of it
+    /**
      * Tests whether the current [token] is actually valid. By default, an endpoint is called *once* to verify
      * validity.
      *
      * @param makeTestRequest Whether to also make an endpoint request to verify authentication.
      *
      * @return [TokenValidityResponse] containing whether this token is valid, and if not, an Exception explaining why
      */
-    fun isTokenValid(makeTestRequest: Boolean = true): TokenValidityResponse {
+    @JvmOverloads
+    fun isTokenValid(makeTestRequest: Boolean = true): TokenValidityResponse = runBlocking {
+        suspendIsTokenValid(makeTestRequest)
+    }
+
+    @JvmOverloads
+    suspend fun suspendIsTokenValid(makeTestRequest: Boolean = true, context: CoroutineContext = Dispatchers.Default): TokenValidityResponse {
         if (token.shouldRefresh()) return TokenValidityResponse(
             false,
             SpotifyAuthenticationException("Token needs to be refreshed (is it expired?)")
         )
         if (!makeTestRequest) return TokenValidityResponse(true, null)
 
         return try {
-            browse.getAvailableGenreSeeds().complete()
+            browse.getAvailableGenreSeeds().suspendComplete(context)
             TokenValidityResponse(true, null)
         } catch (e: Exception) {
             TokenValidityResponse(false, e)
@@ -202,7 +211,7 @@ class SpotifyAppApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean
-) : SpotifyApi(
+) : SpotifyApi<SpotifyAppApi, SpotifyAppApiBuilder>(
     clientId,
     clientSecret,
     token,
@@ -303,7 +312,7 @@ class SpotifyClientApi internal constructor(
     retryWhenRateLimited: Boolean,
     enableLogger: Boolean,
     testTokenValidity: Boolean
-) : SpotifyApi(
+) : SpotifyApi<SpotifyClientApi, SpotifyClientApiBuilder>(
     clientId,
     clientSecret,
     token,
@@ -500,7 +509,7 @@ class SpotifyClientApi internal constructor(
                 scopes.all { token.scopes.contains(it) }
 }
 
-typealias SpotifyAPI = SpotifyApi
+typealias SpotifyAPI<T, B> = SpotifyApi<T, B>
 typealias SpotifyClientAPI = SpotifyClientApi
 typealias SpotifyAppAPI = SpotifyAppApi
 
@@ -511,7 +520,7 @@ fun getAuthUrlFull(vararg scopes: SpotifyScope, clientId: String, redirectUri: S
             if (scopes.isEmpty()) "" else "&scope=${scopes.joinToString("%20") { it.uri }}"
 }
 
-suspend fun getCredentialedToken(clientId: String, clientSecret: String, api: SpotifyApi?): Token {
+suspend fun getCredentialedToken(clientId: String, clientSecret: String, api: SpotifyApi<*, *>?): Token {
     val response = executeTokenRequest(
         HttpConnection(
             "https://accounts.spotify.com/api/token",

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

@@ -28,7 +28,7 @@ import kotlin.jvm.JvmOverloads
 /**
  * Provides a uniform interface to retrieve, whether synchronously or asynchronously, [T] from Spotify
  */
-open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyApi, val supplier: suspend () -> T) {
+open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyApi<*, *>, val supplier: suspend () -> T) {
     private var hasRunBacking: Boolean = false
     private var hasCompletedBacking: Boolean = false
 
@@ -126,7 +126,7 @@ open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyA
     override fun toString() = complete().toString()
 }
 
-class SpotifyRestActionPaging<Z : Any, T : AbstractPagingObject<Z>>(api: SpotifyApi, supplier: suspend () -> T) :
+class SpotifyRestActionPaging<Z : Any, T : AbstractPagingObject<Z>>(api: SpotifyApi<*, *>, supplier: suspend () -> T) :
     SpotifyRestAction<T>(api, supplier) {
 
     /**

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

@@ -24,7 +24,7 @@ typealias ClientFollowingAPI = ClientFollowingApi
 /**
  * These endpoints allow you manage the artists, users and playlists that a Spotify user follows.
  */
-class ClientFollowingApi(api: SpotifyApi) : FollowingApi(api) {
+class ClientFollowingApi(api: SpotifyApi<*, *>) : FollowingApi(api) {
     /**
      * Check to see if the current user is following another Spotify user.
      *

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

@@ -24,7 +24,7 @@ typealias ClientLibraryAPI = ClientLibraryApi
 /**
  * Endpoints for retrieving information about, and managing, tracks that the current user has saved in their “Your Music” library.
  */
-class ClientLibraryApi(api: SpotifyApi) : SpotifyEndpoint(api) {
+class ClientLibraryApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
     /**
      * Get a list of the songs saved in the current Spotify user’s ‘Your Music’ library.
      *

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

@@ -16,7 +16,7 @@ typealias ClientPersonalizationAPI = ClientPersonalizationApi
 /**
  * Endpoints for retrieving information about the user’s listening habits.
  */
-class ClientPersonalizationApi(api: SpotifyApi) : SpotifyEndpoint(api) {
+class ClientPersonalizationApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
     /**
      * The time frame for which attribute affinities are computed.
      *

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

@@ -34,7 +34,7 @@ typealias ClientPlayerAPI = ClientPlayerApi
  * These endpoints allow for viewing and controlling user playback. Please view [the official documentation](https://developer.spotify.com/web-api/working-with-connect/)
  * for more information on how this works. This is in beta and is available for **premium users only**. Endpoints are **not** guaranteed to work
  */
-class ClientPlayerApi(api: SpotifyApi) : SpotifyEndpoint(api) {
+class ClientPlayerApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
     /**
      * Get information about a user’s available devices.
      *

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

@@ -39,7 +39,7 @@ typealias ClientPlaylistAPI = ClientPlaylistApi
 /**
  * Endpoints for retrieving information about a user’s playlists and for managing a user’s playlists.
  */
-class ClientPlaylistApi(api: SpotifyApi) : PlaylistApi(api) {
+class ClientPlaylistApi(api: SpotifyApi<*, *>) : PlaylistApi(api) {
     /**
      * Create a playlist for a Spotify user. (The playlist will be empty until you add tracks.)
      *

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

@@ -14,7 +14,7 @@ typealias ClientUserAPI = ClientProfileApi
 /**
  * Endpoints for retrieving information about a user’s profile.
  */
-class ClientProfileApi(api: SpotifyApi) : UserApi(api) {
+class ClientProfileApi(api: SpotifyApi<*, *>) : UserApi(api) {
     /**
      * Get detailed profile information about the current user (including the current user’s username).
      *

src/commonMain/kotlin/com.adamratzman.spotify/endpoints/public/AlbumApi.kt

@@ -22,7 +22,7 @@ typealias AlbumAPI = AlbumApi
 /**
  * Endpoints for retrieving information about one or more albums from the Spotify catalog.
  */
-class AlbumApi(api: SpotifyApi) : SpotifyEndpoint(api) {
+class AlbumApi(api: SpotifyApi<*, *>) : SpotifyEndpoint(api) {
     /**
      * Get Spotify catalog information for a single album.
      *