document the auth wrapper

Signed-off-by: Adam Ratzman <[email protected]>

Author: adamint

src/androidMain/kotlin/com/adamratzman/spotify/auth/AbstractSpotifyLoginActivity.kt

@@ -11,16 +11,50 @@ import com.adamratzman.spotify.spotifyImplicitGrantApi
 import com.spotify.sdk.android.auth.AuthorizationClient
 import com.spotify.sdk.android.auth.AuthorizationRequest
 import com.spotify.sdk.android.auth.AuthorizationResponse
+import com.spotify.sdk.android.auth.LoginActivity
 
+/**
+ * Wrapper around spotify-auth's [LoginActivity] that allows configuration of the authentication process, along with
+ * callbacks on successful and failed authentication. Pair this with [SpotifyDefaultCredentialStore] to easily store credentials.
+ *
+ * @property state The state to use to verify the login request.
+ * @property clientId Your application's Spotify client id.
+ * @property clientId Your application's Spotify client secret.
+ * @property redirectUri Your application's Spotify redirect id - NOTE that this should be an android scheme (such as spotifyapp://authback)
+ * and that this must be registered in your manifest.
+ * @property useDefaultRedirectHandler Disable if you will not be using [useDefaultRedirectHandler] but will be setting [SpotifyDefaultAuthHelper.activityBack].
+ *
+ */
 public abstract class AbstractSpotifyLoginActivity : Activity() {
     public abstract val state: Int
     public abstract val clientId: String
     public abstract val redirectUri: String
-    public abstract val useDefaultRedirectHandler: Boolean
+    public open val useDefaultRedirectHandler: Boolean = true
+
+    /**
+     * Return the scopes that you are going to request from the user here.
+     */
     public abstract fun getRequestingScopes(): List<SpotifyScope>
 
+    /**
+     * Override this to define what to do after authentication has been successfully completed. A valid, usable
+     * [spotifyApi] is provided to you. You may likely want to use [SpotifyDefaultCredentialStore] to store/retrieve this token.
+     *
+     * @param spotifyApi Valid, usable [SpotifyImplicitGrantApi] that you can use to make requests.
+     */
     public abstract fun onSuccessfulAuthentication(spotifyApi: SpotifyImplicitGrantApi)
+
+    /**
+     * Override this to define what to do after authentication has failed. You may want to use [SpotifyDefaultCredentialStore] to remove any stored token.
+     */
     public abstract fun onAuthenticationFailed(errorMessage: String)
+
+
+    /**
+     * Override this to define what to do after [onSuccessfulAuthentication] has run.
+     * The default behavior is to finish the activity, and redirect the user back to the activity set on [SpotifyDefaultAuthHelper.activityBack]
+     * only if [guardValidSpotifyApi] has been used or if [SpotifyDefaultAuthHelper.activityBack] has been set.
+     */
     public open fun redirectAfterOnSuccessAuthentication() {
         if (useDefaultRedirectHandler && SpotifyDefaultAuthHelper.activityBack != null) {
             startActivity(Intent(this, SpotifyDefaultAuthHelper.activityBack))
@@ -35,15 +69,21 @@ public abstract class AbstractSpotifyLoginActivity : Activity() {
         triggerLoginActivity()
     }
 
+    /**
+     * Trigger the actual spotify-auth login activity to authenticate the user.
+     */
     public fun triggerLoginActivity() {
-        val authorizationRequest =
-            AuthorizationRequest.Builder(clientId, AuthorizationResponse.Type.TOKEN, redirectUri)
-                .setScopes(getRequestingScopes().map { it.uri }.toTypedArray())
-                .setState(state.toString())
-                .build()
+        val authorizationRequest = AuthorizationRequest.Builder(clientId, AuthorizationResponse.Type.TOKEN, redirectUri)
+            .setScopes(getRequestingScopes().map { it.uri }.toTypedArray())
+            .setState(state.toString())
+            .build()
+
         AuthorizationClient.openLoginActivity(this, state, authorizationRequest)
     }
 
+    /**
+     * Processes the result of [LoginActivity], invokes callbacks, then finishes.
+     */
     override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
         super.onActivityResult(requestCode, resultCode, intent)
         if (requestCode == state) {
@@ -58,9 +98,7 @@ public abstract class AbstractSpotifyLoginActivity : Activity() {
                     val api = spotifyImplicitGrantApi(
                         clientId = clientId,
                         token = token
-                    ) {
-                        refreshTokenProducer = { throw SpotifyException.ReAuthenticationNeededException() }
-                    }
+                    )
 
                     onSuccessfulAuthentication(api)
                     redirectAfterOnSuccessAuthentication()

src/androidMain/kotlin/com/adamratzman/spotify/auth/AuthUtils.kt

@@ -107,7 +107,7 @@ public class SpotifyDefaultCredentialStore constructor(private val clientId: Str
         )
 
     /**
-     *
+     * Get/set when the Spotify access token will expire, in milliseconds from UNIX epoch. This will be one hour from authentication.
      */
     public var spotifyTokenExpiresAt: Long?
         get() {
@@ -119,10 +119,17 @@ public class SpotifyDefaultCredentialStore constructor(private val clientId: Str
             else encryptedPreferences.edit().putLong(SpotifyTokenExpiryKey, value).apply()
         }
 
+    /**
+     * Get/set the Spotify access token (the access token string, not the wrapped [Token]).
+     */
     public var spotifyAccessToken: String?
         get() = encryptedPreferences.getString(SpotifyAccessTokenKey, null)
         set(value) = encryptedPreferences.edit().putString(SpotifyAccessTokenKey, value).apply()
 
+    /**
+     * Get/set the Spotify [Token] obtained from [spotifyToken].
+     * If the token has expired according to [spotifyTokenExpiresAt], this will return null.
+     */
     public var spotifyToken: Token?
         get() {
             val tokenExpiresAt = spotifyTokenExpiresAt ?: return null
@@ -141,15 +148,28 @@ public class SpotifyDefaultCredentialStore constructor(private val clientId: Str
             }
         }
 
+    /**
+     * Create a new [SpotifyImplicitGrantApi] instance using the [spotifyToken] stored using this credential store.
+     *
+     * @param block Applied configuration to the [SpotifyImplicitGrantApi]
+     */
     public fun getSpotifyImplicitGrantApi(block: ((SpotifyApiOptions).() -> Unit)? = null): SpotifyImplicitGrantApi? {
         val token = spotifyToken ?: return null
         return spotifyImplicitGrantApi(clientId, token, block ?: {})
     }
 
+    /**
+     * Sets [spotifyToken] using [SpotifyImplicitGrantApi.token]. This wraps around [spotifyToken]'s setter.
+     *
+     * @param api A valid [SpotifyImplicitGrantApi]
+     */
     public fun setSpotifyImplicitGrantApi(api: SpotifyImplicitGrantApi) {
         spotifyToken = api.token
     }
 
+    /**
+     * Clear the [SharedPreferences] instance corresponding to the Spotify credentials.
+     */
     @SuppressLint("ApplySharedPref")
     public fun clear(): Boolean = try {
         encryptedPreferences.edit().clear().commit()