documentation (+ builder)

Author: adamint

build.gradle.kts

@@ -22,6 +22,12 @@ java {
     withJavadocJar()
 }
 
+tasks.withType<Test> {
+    this.testLogging {
+        this.showStandardStreams = true
+    }
+}
+
 repositories {
     mavenCentral()
     jcenter()

samples/src/main/kotlin/public/BrowseApiSample.kt

@@ -1,3 +1,4 @@
+/* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
 package public
 
 import com.adamratzman.spotify.spotifyAppApi
@@ -7,4 +8,4 @@ fun main() {
             System.getenv("SPOTIFY_CLIENT_ID"),
             System.getenv("SPOTIFY_CLIENT_SECRET")
     )
-}
+}

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

@@ -27,13 +27,12 @@ fun spotifyAppApi(block: SpotifyAppApiBuilder.() -> Unit) =
 
 @Deprecated("Builder methods are now found in SpotifyBuilder", ReplaceWith("SpotifyBuilder.spotifyClientApi"))
 fun spotifyAppApi(clientId: String, clientSecret: String, redirectUri: String, block: SpotifyClientApiBuilder.() -> Unit = {}) =
-        SpotifyBuilder.spotifyClientApi(clientId, clientSecret,redirectUri, block)
+        SpotifyBuilder.spotifyClientApi(clientId, clientSecret, redirectUri, block)
 
 @Deprecated("Builder methods are now found in SpotifyBuilder", ReplaceWith("SpotifyBuilder.spotifyClientApi"))
 fun spotifyAppApi(block: SpotifyClientApiBuilder.() -> Unit) =
         SpotifyBuilder.spotifyClientApi(block)
 
-
 /**
  * Contains static methods to instantiate [SpotifyAppApi] and [SpotifyClientApi] instances
  */
@@ -91,10 +90,10 @@ class SpotifyBuilder {
          * @return Configurable [SpotifyClientApiBuilder] that, when built, creates a new [SpotifyClientApi]
          */
         fun spotifyClientApi(
-                clientId: String,
-                clientSecret: String,
-                redirectUri: String,
-                block: SpotifyClientApiBuilder.() -> Unit
+            clientId: String,
+            clientSecret: String,
+            redirectUri: String,
+            block: SpotifyClientApiBuilder.() -> Unit
         ) = SpotifyClientApiBuilder().apply(block).apply {
             credentials {
                 this.clientId = clientId
@@ -117,7 +116,6 @@ class SpotifyBuilder {
     }
 }
 
-
 /**
  *  Spotify API builder
  */
@@ -126,7 +124,15 @@ class SpotifyApiBuilder(
     private var clientSecret: String?,
     private var redirectUri: String?
 ) {
+    /**
+     * Allows you to authenticate a [SpotifyClientApi] with an authorization code
+     * or build [SpotifyApi] using a refresh token
+     */
     var authorization: SpotifyUserAuthorization = SpotifyUserAuthorizationBuilder().build()
+
+    /**
+     * Allows you to override default values for caching, token refresh, and logging
+     */
     var options: SpotifyApiOptions = SpotifyApiOptionsBuilder().build()
 
     /**
@@ -237,14 +243,48 @@ class SpotifyApiBuilder(
     }.build()
 }
 
+/**
+ * The type of Spotify authorization used to build an Api instance
+ */
 enum class AuthorizationType {
+    /**
+     * Authorization through explicit affirmative action taken by a client (user) allowing the application to access a/multiple [SpotifyScope]
+     *
+     * [Spotify application settings page](https://developer.spotify.com/documentation/general/guides/app-settings/)
+     */
     CLIENT,
+
+    /**
+     * Authorization through application client id and secret, allowing access only to public endpoints and data
+     *
+     * [Spotify application settings page](https://developer.spotify.com/documentation/general/guides/app-settings/)
+     */
     APPLICATION;
 }
 
+/**
+ * Spotify Api builder interface
+ *
+ * @property T The type of [SpotifyApi] to be built
+ * @property B The associated Api builder for [T]
+ */
 interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>> {
+    /**
+     * A block in which Spotify application credentials (accessible via the Spotify [dashboard](https://developer.spotify.com/dashboard/applications))
+     * should be put
+     */
     var credentials: SpotifyCredentials
+
+    /**
+     * Allows you to authenticate a [SpotifyClientApi] with an authorization code
+     * or build [SpotifyApi] using a refresh token
+     */
     var authorization: SpotifyUserAuthorization
+
+
+    /**
+     * Allows you to override default values for caching, token refresh, and logging
+     */
     var options: SpotifyApiOptions
 
     /**
@@ -276,13 +316,15 @@ interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>
     /**
      * Allows you to override default values for caching, token refresh, and logging
      */
+    @Deprecated("Succeeded by the options method", ReplaceWith("options"))
     fun utilities(block: SpotifyApiOptionsBuilder.() -> Unit) {
         options = SpotifyApiOptionsBuilder().apply(block).build()
     }
 
     /**
      * Allows you to override default values for caching, token refresh, and logging
      */
+    @Deprecated("Succeeded by the options method", ReplaceWith("options"))
     fun config(block: SpotifyApiOptionsBuilder.() -> Unit) {
         options = SpotifyApiOptionsBuilder().apply(block).build()
     }
@@ -294,6 +336,9 @@ interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>
         options = SpotifyApiOptionsBuilder().apply(block).build()
     }
 
+    /**
+     * Allows you to override default values for caching, token refresh, and logging
+     */
     fun options(options: SpotifyApiOptions) = apply { this.options = options }
 
     /**
@@ -323,6 +368,9 @@ interface ISpotifyApiBuilder<T : SpotifyApi<T, B>, B : ISpotifyApiBuilder<T, B>>
     }
 }
 
+/**
+ * Client interface exposing [getAuthorizationUrl]
+ */
 interface ISpotifyClientApiBuilder : ISpotifyApiBuilder<SpotifyClientApi, SpotifyClientApiBuilder> {
     /**
      * Create a Spotify authorization URL from which API access can be obtained
@@ -333,6 +381,9 @@ interface ISpotifyClientApiBuilder : ISpotifyApiBuilder<SpotifyClientApi, Spotif
     fun getAuthorizationUrl(vararg scopes: SpotifyScope): String
 }
 
+/**
+ * [SpotifyClientApi] builder for api creation using client authorization
+ */
 class SpotifyClientApiBuilder(
     override var credentials: SpotifyCredentials = SpotifyCredentialsBuilder().build(),
     override var authorization: SpotifyUserAuthorization = SpotifyUserAuthorizationBuilder().build(),
@@ -348,6 +399,7 @@ class SpotifyClientApiBuilder(
         val clientSecret = credentials.clientSecret
         val redirectUri = credentials.redirectUri
 
+        // either application credentials, or a token is required
         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 -> try {
@@ -427,8 +479,16 @@ class SpotifyClientApiBuilder(
     }
 }
 
+
+/**
+ * App Api builder interface
+ */
 interface ISpotifyAppApiBuilder : ISpotifyApiBuilder<SpotifyAppApi, SpotifyAppApiBuilder>
 
+
+/**
+ * [SpotifyAppApi] builder for api creation using client authorization
+ */
 class SpotifyAppApiBuilder(
     override var credentials: SpotifyCredentials = SpotifyCredentialsBuilder().build(),
     override var authorization: SpotifyUserAuthorization = SpotifyUserAuthorizationBuilder().build(),
@@ -547,6 +607,17 @@ class SpotifyUserAuthorizationBuilder(
     fun build() = SpotifyUserAuthorization(authorizationCode, tokenString, token, refreshTokenString)
 }
 
+/**
+ * User-defined authorization parameters
+ *
+ * @property authorizationCode Only available when building [SpotifyClientApi]. Spotify auth code
+ * @property token Build the API using an existing token. If you're building [SpotifyClientApi], this
+ * will be your **access** token. If you're building [SpotifyApi], it will be your **refresh** token
+ * @property tokenString Build the API using an existing token (string). If you're building [SpotifyClientApi], this
+ * will be your **access** token. If you're building [SpotifyApi], it will be your **refresh** token. There is a *very*
+ * limited time constraint on these before the API automatically refreshes them
+ * @property refreshTokenString Refresh token, given as a string, to be exchanged to Spotify for a new token
+ */
 data class SpotifyUserAuthorization(
     var authorizationCode: String?,
     var tokenString: String?,
@@ -598,6 +669,18 @@ class SpotifyApiOptionsBuilder(
             )
 }
 
+/**
+ * API Utilities
+ *
+ * @property useCache Set whether to cache requests. Default: true
+ * @property cacheLimit The maximum amount of cached requests allowed at one time. Null means no limit
+ * @property automaticRefresh Enable or disable automatic refresh of the Spotify access token
+ * @property retryWhenRateLimited Set whether to block the current thread and wait until the API can retry the request
+ * @property enableLogger Set whether to enable to the exception logger
+ * @property testTokenValidity After API creation, test whether the token is valid by performing a lightweight request
+ * @property enableAllOptions Whether to enable all provided utilities
+ */
+
 data class SpotifyApiOptions(
     var useCache: Boolean,
     var cacheLimit: Int?,

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

@@ -30,10 +30,10 @@ import com.adamratzman.spotify.models.TokenValidityResponse
 import com.adamratzman.spotify.models.serialization.toObject
 import com.adamratzman.spotify.utils.asList
 import com.adamratzman.spotify.utils.runBlocking
-import kotlinx.coroutines.Dispatchers
-import kotlinx.serialization.json.Json
 import kotlin.coroutines.CoroutineContext
 import kotlin.jvm.JvmOverloads
+import kotlinx.coroutines.Dispatchers
+import kotlinx.serialization.json.Json
 
 internal const val base = "https://api.spotify.com/v1"
 

src/commonMain/kotlin/com.adamratzman.spotify/models/PagingObjects.kt

@@ -6,6 +6,7 @@ import com.adamratzman.spotify.http.SpotifyEndpoint
 import com.adamratzman.spotify.models.serialization.toCursorBasedPagingObject
 import com.adamratzman.spotify.models.serialization.toPagingObject
 import com.adamratzman.spotify.utils.runBlocking
+import kotlin.reflect.KClass
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.flow.Flow
@@ -17,7 +18,6 @@ import kotlinx.coroutines.flow.toList
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
-import kotlin.reflect.KClass
 
 /*
     Types used in PagingObjects and CursorBasedPagingObjects:
@@ -209,7 +209,7 @@ abstract class AbstractPagingObject<T : Any>(
     @Transient open val offset: Int = 0,
     @Transient open val previous: String? = null,
     @Transient open val total: Int = -1
-): List<T> by items {
+) : List<T> by items {
     @Transient
     internal var endpoint: SpotifyEndpoint? = null
 

src/commonTest/kotlin/com.adamratzman/spotify/public/PublicUserAPITest.kt

@@ -12,7 +12,7 @@ class PublicUserAPITest : Spek({
     describe("Public User test") {
         describe("get user") {
             it("available user should return author name") {
-                assertTrue { catch {  api.users.getProfile("adamratzman1").complete()!!.followers.total } != null }
+                assertTrue { catch { api.users.getProfile("adamratzman1").complete()!!.followers.total } != null }
             }
             it("unknown user should throw exception") {
                 assertNull(api.users.getProfile("non-existant-user").complete())

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

@@ -7,10 +7,10 @@ import com.adamratzman.spotify.SpotifyClientAPI
 import com.adamratzman.spotify.api
 import com.adamratzman.spotify.block
 import com.adamratzman.spotify.getEnvironmentVariable
+import kotlin.test.assertFailsWith
 import kotlinx.coroutines.GlobalScope
 import org.spekframework.spek2.Spek
 import org.spekframework.spek2.style.specification.describe
-import kotlin.test.assertFailsWith
 
 class UtilityTests : Spek({
     describe("Utility tests") {