update dependencies, add state testing token validity

Author: adamint

README.md

@@ -29,7 +29,7 @@ repositories {
     jcenter()
 }
 
-compile group: 'com.adamratzman', name: 'spotify-api-kotlin', version: '2.3.0'
+compile group: 'com.adamratzman', name: 'spotify-api-kotlin', version: '2.3.01'
 ```
 
 To use the latest snapshot instead, you must add the Jitpack repository as well
@@ -51,7 +51,7 @@ dependencies {
 <dependency>
     <groupId>com.adamratzman</groupId>
     <artifactId>spotify-api-kotlin</artifactId>
-    <version>2.3.0</version>
+    <version>2.3.01</version>
 </dependency>
 
 <repository>

build.gradle

@@ -14,15 +14,15 @@ buildscript {
 plugins {
     id "com.diffplug.gradle.spotless" version "3.23.0"
     id "base"
-    id "io.codearte.nexus-staging" version "0.20.0"
+    id "io.codearte.nexus-staging" version "0.21.0"
     id "com.bmuschko.nexus" version "2.3.1"
 }
 
 apply plugin: 'kotlin'
 apply plugin: 'org.jetbrains.dokka'
 
 group 'com.adamratzman'
-version '2.3.0'
+version '2.3.01'
 
 archivesBaseName = 'spotify-api-kotlin'
 
@@ -39,7 +39,7 @@ dependencies {
     compile "com.squareup.moshi:moshi:1.8.0"
     compile "com.squareup.moshi:moshi-kotlin:1.8.0"
 
-    compile group: 'com.google.http-client', name: 'google-http-client', version: '1.23.0'
+    compile group: 'com.google.http-client', name: 'google-http-client', version: '1.29.1'
 
     compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$kotlin_version"
     compile "org.jetbrains.kotlin:kotlin-reflect:$kotlin_version"

src/main/kotlin/com/adamratzman/spotify/SpotifyAPI.kt

@@ -24,6 +24,7 @@ import com.adamratzman.spotify.http.byteEncode
 import com.adamratzman.spotify.models.AuthenticationError
 import com.adamratzman.spotify.models.BadRequestException
 import com.adamratzman.spotify.models.Token
+import com.adamratzman.spotify.models.TokenValidityResponse
 import com.adamratzman.spotify.models.serialization.toObject
 import com.squareup.moshi.Moshi
 import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
@@ -149,6 +150,26 @@ abstract class SpotifyAPI internal constructor(
     fun getAuthorizationUrl(vararg scopes: SpotifyScope, redirectUri: String): String {
         return getAuthUrlFull(*scopes, clientId = clientId, redirectUri = redirectUri)
     }
+
+    /**
+     * 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 {
+        if (!token.shouldRefresh()) return TokenValidityResponse(false, SpotifyException("Token expired"))
+        if (!makeTestRequest) return TokenValidityResponse(true, null)
+
+        return try {
+            browse.getAvailableGenreSeeds().complete()
+            TokenValidityResponse(true, null)
+        } catch (e: Exception) {
+            TokenValidityResponse(false, e)
+        }
+    }
 }
 
 /**
@@ -365,6 +386,17 @@ class SpotifyClientAPI internal constructor(
     fun getAuthorizationUrl(vararg scopes: SpotifyScope): String {
         return getAuthUrlFull(*scopes, clientId = clientId, redirectUri = redirectUri)
     }
+
+    /**
+     * Whether the current access token allows access to scope [scope]
+     */
+    fun hasScope(scope: SpotifyScope): Boolean = hasScopes(scope)
+
+    /**
+     * Whether the current access token allows access to all of the provided scopes
+     */
+    fun hasScopes(scope: SpotifyScope, vararg scopes: SpotifyScope): Boolean =
+            !isTokenValid(false).isValid && (scopes.toList() + scope).all { token.scopes.contains(it) }
 }
 
 fun getAuthUrlFull(vararg scopes: SpotifyScope, clientId: String, redirectUri: String): String {

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

@@ -10,13 +10,28 @@ import java.util.function.Supplier
  * Provides a uniform interface to retrieve, whether synchronously or asynchronously, [T] from Spotify
  */
 open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyAPI, private val supplier: Supplier<T>) {
+    private var hasRunBacking: Boolean = false
+    private var hasCompletedBacking: Boolean = false
+
+    /**
+     * Whether this REST action has been *commenced*.
+     *
+     * Not to be confused with [hasCompleted]
+     */
+    fun hasRun() = hasRunBacking
+
+    /**
+     * Whether this REST action has been fully *completed*
+     */
+    fun hasCompleted() = hasCompletedBacking
 
     /**
      * Invoke [supplier] and synchronously retrieve [T]
      */
     fun complete(): T {
+        hasRunBacking = true
         return try {
-            supplier.get()
+            supplier.get().also { hasCompletedBacking = true }
         } catch (e: Throwable) {
             throw e
         }
@@ -25,22 +40,23 @@ open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyA
     /**
      * Invoke [supplier] asynchronously with no consumer
      */
-    fun queue() = queue({}, { throw it })
+    fun queue(): SpotifyRestAction<T> = queue({}, { throw it })
 
     /**
      * Invoke [supplier] asynchronously and consume [consumer] with the [T] value returned
      *
      * @param consumer to be invoked with [T] after successful completion of [supplier]
      */
-    fun queue(consumer: (T) -> Unit) = queue(consumer, {})
+    fun queue(consumer: (T) -> Unit): SpotifyRestAction<T> = queue(consumer, {})
 
     /**
      * Invoke [supplier] asynchronously and consume [consumer] with the [T] value returned
      *
      * @param failure Consumer to invoke when an exception is thrown by [supplier]
      * @param consumer to be invoked with [T] after successful completion of [supplier]
      */
-    fun queue(consumer: ((T) -> Unit), failure: ((Throwable) -> Unit)) {
+    fun queue(consumer: ((T) -> Unit), failure: ((Throwable) -> Unit)): SpotifyRestAction<T> {
+        hasRunBacking = true
         api.executor.execute {
             try {
                 val result = complete()
@@ -49,12 +65,13 @@ open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyA
                 failure(t)
             }
         }
+        return this
     }
 
     /**
      * Return [supplier] as a [CompletableFuture]
      */
-    fun asFuture() = CompletableFuture.supplyAsync(supplier)
+    fun asFuture(): CompletableFuture<T> = CompletableFuture.supplyAsync(supplier)
 
     /**
      * Invoke [supplier] asynchronously immediately and invoke [consumer] after the specified quantity of time
@@ -63,11 +80,12 @@ open class SpotifyRestAction<T> internal constructor(protected val api: SpotifyA
      * @param timeUnit the unit that [quantity] is in
      * @param consumer to be invoked with [T] after successful completion of [supplier]
      */
-    fun queueAfter(quantity: Int, timeUnit: TimeUnit = TimeUnit.SECONDS, consumer: (T) -> Unit) {
+    fun queueAfter(quantity: Int, timeUnit: TimeUnit = TimeUnit.SECONDS, consumer: (T) -> Unit): SpotifyRestAction<T> {
         val runAt = System.currentTimeMillis() + timeUnit.toMillis(quantity.toLong())
         queue { result ->
             api.executor.schedule({ consumer(result) }, runAt - System.currentTimeMillis(), TimeUnit.MILLISECONDS)
         }
+        return this
     }
 
     override fun toString() = complete().toString()

src/main/kotlin/com/adamratzman/spotify/http/Endpoints.kt

@@ -10,6 +10,7 @@ import com.adamratzman.spotify.models.AbstractPagingObject
 import com.adamratzman.spotify.models.BadRequestException
 import com.adamratzman.spotify.models.ErrorObject
 import com.adamratzman.spotify.models.ErrorResponse
+import com.adamratzman.spotify.models.SpotifyAuthenticationException
 import com.adamratzman.spotify.models.serialization.toObject
 import java.net.HttpURLConnection
 import java.net.URLEncoder
@@ -33,21 +34,24 @@ abstract class SpotifyEndpoint(val api: SpotifyAPI) {
     }
 
     internal fun delete(
-            url: String,
-            body: String? = null,
-            contentType: String? = null
+        url: String,
+        body: String? = null,
+        contentType: String? = null
     ): String {
         return execute(url, body, HttpRequestMethod.DELETE, contentType = contentType)
     }
 
     private fun execute(
-            url: String,
-            body: String? = null,
-            method: HttpRequestMethod = HttpRequestMethod.GET,
-            retry202: Boolean = true,
-            contentType: String? = null
+        url: String,
+        body: String? = null,
+        method: HttpRequestMethod = HttpRequestMethod.GET,
+        retry202: Boolean = true,
+        contentType: String? = null
     ): String {
-        if (api is SpotifyAppAPI && System.currentTimeMillis() >= api.expireTime) api.refreshToken()
+        if (api is SpotifyAppAPI && System.currentTimeMillis() >= api.expireTime) {
+            if (!api.automaticRefresh) throw SpotifyAuthenticationException("The access token has expired.")
+            else api.refreshToken()
+        }
 
         val spotifyRequest = SpotifyRequest(url, method, body, api)
         val cacheState = if (api.useCache) cache[spotifyRequest] else null
@@ -73,15 +77,15 @@ abstract class SpotifyEndpoint(val api: SpotifyAPI) {
     }
 
     private fun handleResponse(
-            document: HttpResponse,
-            cacheState: CacheState?,
-            spotifyRequest: SpotifyRequest,
-            retry202: Boolean
+        document: HttpResponse,
+        cacheState: CacheState?,
+        spotifyRequest: SpotifyRequest,
+        retry202: Boolean
     ): String? {
         val statusCode = document.responseCode
 
         if (statusCode == HttpURLConnection.HTTP_NOT_MODIFIED) {
-            if (cacheState?.eTag == null) throw BadRequestException("304 status only allowed on Etag-able endpoints")
+            if (cacheState?.eTag == null) throw IllegalArgumentException("304 status only allowed on Etag-able endpoints")
             return cacheState.data
         }
 
@@ -109,10 +113,10 @@ abstract class SpotifyEndpoint(val api: SpotifyAPI) {
     }
 
     private fun createConnection(
-            url: String,
-            body: String? = null,
-            method: HttpRequestMethod = HttpRequestMethod.GET,
-            contentType: String? = null
+        url: String,
+        body: String? = null,
+        method: HttpRequestMethod = HttpRequestMethod.GET,
+        contentType: String? = null
     ) = HttpConnection(
             url,
             method,
@@ -185,10 +189,10 @@ class SpotifyCache {
 }
 
 data class SpotifyRequest(
-        val url: String,
-        val method: HttpRequestMethod,
-        val body: String?,
-        val api: SpotifyAPI
+    val url: String,
+    val method: HttpRequestMethod,
+    val body: String?,
+    val api: SpotifyAPI
 )
 
 data class CacheState(val data: String, val eTag: String?, val expireBy: Long = 0) {

src/main/kotlin/com/adamratzman/spotify/models/Authentication.kt

@@ -15,6 +15,7 @@ import com.squareup.moshi.Json
  * null if the token was created using a method that does not support token refresh
  * @property scopes A list of scopes granted access for this [accessToken]. An
  * empty list means that the token can only be used to acces public information.
+ * @property expiresAt The time, in milliseconds, at which this Token expires
  */
 data class Token(
     @Json(name = "access_token") val accessToken: String,
@@ -25,4 +26,10 @@ data class Token(
     @Transient val scopes: List<SpotifyScope> = scopeString?.let { str ->
         str.split(" ").mapNotNull { scope -> SpotifyScope.values().find { it.uri.equals(scope, true) } }
     } ?: listOf()
-)
+) {
+    @Transient val expiresAt: Long = System.currentTimeMillis() + expiresIn * 1000
+
+    fun shouldRefresh(): Boolean = System.currentTimeMillis() > expiresAt
+}
+
+data class TokenValidityResponse(val isValid: Boolean, val exception: Exception?)

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

@@ -1,6 +1,4 @@
 /* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */
-@file:Suppress("UNCHECKED_CAST")
-
 package com.adamratzman.spotify.models
 
 import com.adamratzman.spotify.SpotifyAPI
@@ -73,6 +71,7 @@ class PagingObject<T>(
         }
     })
 
+    @Suppress("UNCHECKED_CAST")
     override fun getImpl(type: PagingTraversalType): AbstractPagingObject<T>? {
         return (if (type == PagingTraversalType.FORWARDS) next else previous)?.let { endpoint.get(it) }?.let { json ->
             when (itemClazz) {
@@ -113,6 +112,7 @@ class PagingObject<T>(
     /**
      * Get all PagingObjects associated with the request
      */
+    @Suppress("UNCHECKED_CAST")
     fun getAll() = endpoint.toAction(Supplier { (getAllImpl() as Sequence<PagingObject<T>>).toList() })
 
     /**
@@ -153,6 +153,7 @@ class CursorBasedPagingObject<T>(
     /**
      * Get all CursorBasedPagingObjects associated with the request
      */
+    @Suppress("UNCHECKED_CAST")
     fun getAll() = endpoint.toAction(Supplier {
         getAllImpl() as Sequence<CursorBasedPagingObject<T>>
     })
@@ -164,6 +165,7 @@ class CursorBasedPagingObject<T>(
         getAll().complete().map { it.items }.flatten().toList()
     })
 
+    @Suppress("UNCHECKED_CAST")
     override fun getImpl(type: PagingTraversalType): AbstractPagingObject<T>? {
         if (type == PagingTraversalType.BACKWARDS) {
             throw IllegalArgumentException("CursorBasedPagingObjects only can go forwards")

src/main/kotlin/com/adamratzman/spotify/models/ResultObjects.kt

@@ -37,7 +37,8 @@ abstract class CoreObject(
     @Transient val uri: SpotifyUri,
     _externalUrls: Map<String, String>
 ) : Identifiable(_href, _id) {
-    @Transient val externalUrls: List<ExternalUrl> = _externalUrls.map { ExternalUrl(it.key, it.value) }
+    @Transient
+    val externalUrls: List<ExternalUrl> = _externalUrls.map { ExternalUrl(it.key, it.value) }
 }
 
 abstract class RelinkingAvailableResponse(
@@ -90,6 +91,8 @@ data class ErrorResponse(val error: ErrorObject)
  */
 data class ErrorObject(val status: Int, val message: String)
 
+class SpotifyAuthenticationException(message: String) : Exception(message)
+
 data class AuthenticationError(
     val error: String,
     @Json(name = "error_description") val description: String
@@ -103,17 +106,17 @@ class SpotifyUriException(message: String) : BadRequestException(message)
  * @param time the time, in seconds, until the next request can be sent
  */
 class SpotifyRatelimitedException(time: Long) :
-    UnNullableException("Calls to the Spotify API have been ratelimited for $time seconds until ${System.currentTimeMillis() + time * 1000}ms")
+        UnNullableException("Calls to the Spotify API have been ratelimited for $time seconds until ${System.currentTimeMillis() + time * 1000}ms")
 
 abstract class UnNullableException(message: String) : SpotifyException(message)
 
 /**
  * Thrown when a request fails
  */
-open class BadRequestException(message: String) : SpotifyException(message) {
-    constructor(error: ErrorObject) : this("Received Status Code ${error.status}. Error cause: ${error.message}")
+open class BadRequestException(message: String, val statusCode: Int? = null) : SpotifyException(message) {
+    constructor(error: ErrorObject) : this("Received Status Code ${error.status}. Error cause: ${error.message}", error.status)
     constructor(authenticationError: AuthenticationError) :
-            this("Authentication error: ${authenticationError.error}. Description: ${authenticationError.description}")
+            this("Authentication error: ${authenticationError.error}. Description: ${authenticationError.description}", 401)
 }
 
 typealias Market = CountryCode

src/main/kotlin/com/adamratzman/spotify/utils/MiscUtils.kt

@@ -10,6 +10,7 @@ internal fun <T> catch(function: () -> T): T? {
     return try {
         function()
     } catch (e: BadRequestException) {
+        if (e.statusCode != 400) throw e // we should only ignore the exception if it's a bad request (400)
         null
     }
 }