document utilities

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

Author: adamint

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientPlayerAPI.kt

@@ -29,6 +29,9 @@ import java.util.function.Supplier
  * 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) {
+    /**
+     * Get information about a user’s available devices.
+     */
     fun getDevices(): SpotifyRestAction<List<Device>> {
         return toAction(Supplier {
             get(EndpointBuilder("/me/player/devices").toString()).toInnerObject<List<Device>>(
@@ -37,6 +40,9 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Get information about the user’s current playback state, including track, track progress, and active device.
+     */
     fun getCurrentContext(): SpotifyRestAction<CurrentlyPlayingContext?> {
         return toAction(Supplier {
             val obj = catch {
@@ -47,6 +53,9 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Get tracks from the current user’s recently played tracks.
+     */
     fun getRecentlyPlayed(): SpotifyRestActionPaging<PlayHistory, CursorBasedPagingObject<PlayHistory>> {
         return toActionPaging(Supplier {
             get(EndpointBuilder("/me/player/recently-played").toString()).toCursorBasedPagingObject<PlayHistory>(
@@ -55,6 +64,9 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Get the object currently being played on the user’s Spotify account.
+     */
     fun getCurrentlyPlaying(): SpotifyRestAction<CurrentlyPlayingObject?> {
         return toAction(Supplier {
             val obj =
@@ -66,14 +78,26 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
-    fun pausePlayback(deviceId: String? = null): SpotifyRestAction<Unit> {
+    /**
+     * Pause playback on the user’s account.
+     *
+     * @param deviceId the device to play on
+     */
+    fun pause(deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             put(EndpointBuilder("/me/player/pause").with("device_id", deviceId).toString())
             Unit
         })
     }
 
-    fun seekPosition(positionMs: Long, deviceId: String? = null): SpotifyRestAction<Unit> {
+    /**
+     * Seeks to the given position in the user’s currently playing track.
+     *
+     * @param positionMs The position in milliseconds to seek to. Must be a positive number. Passing in a position
+     * that is greater than the length of the track will cause the player to start playing the next song.
+     * @param deviceId the device to play on
+     */
+    fun seek(positionMs: Long, deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             if (positionMs < 0) throw IllegalArgumentException("Position must not be negative!")
             put(
@@ -86,6 +110,12 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Set the repeat mode for the user’s playback. Options are repeat-track, repeat-context, and off.
+     *
+     * @param state mode to describe how to repeat in the current context
+     * @param deviceId the device to play on
+     */
     fun setRepeatMode(state: PlayerRepeatState, deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             put(
@@ -98,6 +128,12 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Set the volume for the user’s current playback device.
+     *
+     * @param volume The volume to set. Must be a value from 0 to 100 inclusive.
+     * @param deviceId the device to play on
+     */
     fun setVolume(volume: Int, deviceId: String? = null): SpotifyRestAction<Unit> {
         if (volume !in 0..100) throw IllegalArgumentException("Volume must be within 0 to 100 inclusive. Provided: $volume")
         return toAction(Supplier {
@@ -111,14 +147,24 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
-    fun skipToNextTrack(deviceId: String? = null): SpotifyRestAction<Unit> {
+    /**
+     * Skips to next track in the user’s queue.
+     *
+     * @param deviceId the device to play on
+     */
+    fun skipForward(deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             post(EndpointBuilder("/me/player/next").with("device_id", deviceId).toString())
             Unit
         })
     }
 
-    fun rewindToLastTrack(deviceId: String? = null): SpotifyRestAction<Unit> {
+    /**
+     * Skips to previous track in the user’s queue.
+     *
+     * @param deviceId the device to play on
+     */
+    fun skipBehind(deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             post(EndpointBuilder("/me/player/previous").with("device_id", deviceId).toString())
             Unit
@@ -178,15 +224,26 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      *
      * @param deviceId the device to play on
      */
-    fun resumePlayback(deviceId: String? = null) = startPlayback(deviceId = deviceId)
+    fun resume(deviceId: String? = null) = startPlayback(deviceId = deviceId)
 
-    fun shufflePlayback(shuffle: Boolean = true, deviceId: String? = null): SpotifyRestAction<Unit> {
+    /**
+     * Toggle shuffle on or off for user’s playback.
+     *
+     * @param deviceId the device to play on
+     */
+    fun toggleShuffle(shuffle: Boolean = true, deviceId: String? = null): SpotifyRestAction<Unit> {
         return toAction(Supplier {
             put(EndpointBuilder("/me/player/shuffle").with("state", shuffle).with("device_id", deviceId).toString())
             Unit
         })
     }
 
+    /**
+     * Transfer playback to a new device and determine if it should start playing.
+     *
+     * @param deviceId the device to play on
+     * @param play whether to immediately start playback on the transferred device
+     */
     fun transferPlayback(vararg deviceId: String, play: Boolean = true): SpotifyRestAction<Unit> {
         if (deviceId.size > 1) throw IllegalArgumentException("Although an array is accepted, only a single device_id is currently supported. Supplying more than one will  400 Bad Request")
         return toAction(Supplier {
@@ -198,5 +255,21 @@ class ClientPlayerAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
-    enum class PlayerRepeatState { TRACK, CONTEXT, OFF }
+    /**
+     * What state the player can repeat in.
+     */
+    enum class PlayerRepeatState {
+        /**
+         * Repeat the current track
+         */
+        TRACK,
+        /**
+         * Repeat the current context
+         */
+        CONTEXT,
+        /**
+         * Will turn repeat off
+         */
+        OFF
+    }
 }

src/main/kotlin/com/adamratzman/spotify/endpoints/client/ClientPlaylistAPI.kt

@@ -18,6 +18,7 @@ import com.adamratzman.spotify.utils.UserURI
 import com.adamratzman.spotify.utils.encode
 import com.adamratzman.spotify.utils.toObject
 import com.adamratzman.spotify.utils.toPagingObject
+import com.beust.klaxon.Json
 import com.beust.klaxon.JsonArray
 import com.beust.klaxon.JsonObject
 import java.awt.image.BufferedImage
@@ -370,7 +371,17 @@ class ClientPlaylistAPI(api: SpotifyAPI) : PlaylistsAPI(api) {
         return DatatypeConverter.printBase64Binary(bos.toByteArray())
     }
 
-    data class Snapshot(val snapshot_id: String)
+    /**
+     * Contains the snapshot id, returned from API responses
+     *
+     * @param snapshotId playlist state identifier
+     */
+    data class Snapshot(@Json(name = "snapshot_id") val snapshotId: String)
 }
 
+/**
+ * Represents the positions inside a playlist's items list of where to locate the track
+ *
+ * @param positions positions (zero-based)
+ */
 class SpotifyTrackPositions(vararg val positions: Int) : ArrayList<Int>(positions.toList())

src/main/kotlin/com/adamratzman/spotify/endpoints/public/ArtistsAPI.kt

@@ -69,7 +69,7 @@ class ArtistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         limit: Int? = null,
         offset: Int? = null,
         market: Market? = null,
-        include: List<AlbumInclusionStrategy> = listOf()
+        vararg include: AlbumInclusionStrategy
     ): SpotifyRestAction<LinkedResult<SimpleAlbum>> {
         return toAction(Supplier {
             get(
@@ -82,6 +82,11 @@ class ArtistsAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
         })
     }
 
+    /**
+     * Describes object types to include when finding albums
+     *
+     * @param keyword the spotify id of the strategy
+     */
     enum class AlbumInclusionStrategy(val keyword: String) {
         ALBUM("album"), SINGLE("single"), APPEARS_ON("appears_on"), COMPILATION("compilation")
     }

src/main/kotlin/com/adamratzman/spotify/endpoints/public/BrowseAPI.kt

@@ -254,20 +254,97 @@ class BrowseAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
     }
 }
 
-enum class TuneableTrackAttribute(val attribute: String) {
+/**
+ * Describes a track attribute
+ *
+ * @param attribute the spotify id for the track attribute
+ */
+enum class TuneableTrackAttribute(private val attribute: String) {
+    /**
+     * A confidence measure from 0.0 to 1.0 of whether the track is acoustic.
+     * 1.0 represents high confidence the track is acoustic.
+     */
     ACOUSTICNESS("acousticness"),
+    /**
+     * Danceability describes how suitable a track is for dancing based on a combination of musical
+     * elements including tempo, rhythm stability, beat strength, and overall regularity. A value of 0.0 is
+     * least danceable and 1.0 is most danceable.
+     */
     DANCEABILITY("danceability"),
+    /**
+     * The duration of the track in milliseconds.
+     */
     DURATION_IN_MILLISECONDS("duration_ms"),
+    /**
+     * Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity.
+     * Typically, energetic tracks feel fast, loud, and noisy. For example, death metal has high energy,
+     * while a Bach prelude scores low on the scale. Perceptual features contributing to this attribute
+     * include dynamic range, perceived loudness, timbre, onset rate, and general entropy.
+     */
     ENERGY("energy"),
+    /**
+     * Predicts whether a track contains no vocals. “Ooh” and “aah” sounds are treated as
+     * instrumental in this context. Rap or spoken word tracks are clearly “vocal”. The
+     * closer the instrumentalness value is to 1.0, the greater likelihood the track contains
+     * no vocal content. Values above 0.5 are intended to represent instrumental tracks, but
+     * confidence is higher as the value approaches 1.0.
+     */
     INSTRUMENTALNESS("instrumentalness"),
+    /**
+     * The key the track is in. Integers map to pitches using standard Pitch Class notation.
+     * E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.
+     */
     KEY("key"),
+    /**
+     * Detects the presence of an audience in the recording. Higher liveness values represent an increased
+     * probability that the track was performed live. A value above 0.8 provides strong likelihood
+     * that the track is live.
+     */
     LIVENESS("liveness"),
+    /**
+     * The overall loudness of a track in decibels (dB). Loudness values are averaged across the
+     * entire track and are useful for comparing relative loudness of tracks. Loudness is the
+     * quality of a sound that is the primary psychological correlate of physical strength (amplitude).
+     * Values typical range between -60 and 0 db.
+     */
     LOUDNESS("loudness"),
+    /**
+     * Mode indicates the modality (major or minor) of a track, the type of scale from which its
+     * melodic content is derived. Major is represented by 1 and minor is 0.
+     */
     MODE("mode"),
+    /**
+     * The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
+     * The popularity is calculated by algorithm and is based, in the most part, on the total number of
+     * plays the track has had and how recent those plays are. Note: When applying track relinking via
+     * the market parameter, it is expected to find relinked tracks with popularities that do not match
+     * min_*, max_*and target_* popularities. These relinked tracks are accurate replacements for unplayable tracks with the expected popularity scores. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response.
+     */
     POPULARITY("popularity"),
+    /**
+     * Speechiness detects the presence of spoken words in a track. The more exclusively speech-like the
+     * recording (e.g. talk show, audio book, poetry), the closer to 1.0 the attribute value. Values above
+     * 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66
+     * describe tracks that may contain both music and speech, either in sections or layered, including
+     * such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like
+     * tracks.
+     */
     SPEECHINESS("speechiness"),
+    /**
+     * The overall estimated tempo of a track in beats per minute (BPM). In musical terminology, tempo is the
+     * speed or pace of a given piece and derives directly from the average beat duration.
+     */
     TEMPO("tempo"),
+    /**
+     * An estimated overall time signature of a track. The time signature (meter)
+     * is a notational convention to specify how many beats are in each bar (or measure).
+     */
     TIME_SIGNATURE("time_signature"),
+    /**
+     * A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track. Tracks with high
+     * valence sound more positive (e.g. happy, cheerful, euphoric), while tracks with low valence
+     * sound more negative (e.g. sad, depressed, angry).
+     */
     VALENCE("valence");
 
     override fun toString() = attribute

src/main/kotlin/com/adamratzman/spotify/endpoints/public/SearchAPI.kt

@@ -22,7 +22,12 @@ import java.util.function.Supplier
  * Get Spotify catalog information about artists, albums, tracks or playlists that match a keyword string.
  */
 class SearchAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
-    enum class SearchType(val id: String) {
+    /**
+     * Describes which object to search for
+     *
+     * @param id internal spotify id
+     */
+    enum class SearchType(internal val id: String) {
         ALBUM("album"), TRACK("track"), ARTIST("artist"), PLAYLIST("playlist")
     }
 

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

@@ -2,20 +2,20 @@
 package com.adamratzman.spotify.utils
 
 import com.adamratzman.spotify.main.SpotifyScope
+import com.beust.klaxon.Json
 
+/**
+ * Represents a Spotify Token, retrieved through instantiating a new [SpotifyAPI]
+ */
 data class Token(
-    val access_token: String,
-    val token_type: String,
-    val expires_in: Int,
-    val refresh_token: String? = null,
-    val scope: String?
+    @Json(name = "access_token") val accessToken: String,
+    @Json(name = "token_type") val tokenType: String,
+    @Json(name = "expires_in")val expiresIn: Int,
+    @Json(name = "refresh_token") val refreshToken: String? = null,
+    @Json(ignored = false) private val scopeString: String? = null
 ) {
-    fun getScopes(): List<SpotifyScope> {
-        val scopes = mutableListOf<SpotifyScope>()
-        scope?.split(" ")?.forEach { split ->
-            SpotifyScope.values().forEach { if (split == it.uri) scopes.add(it) }
-        }
-        return scopes
+    @Json(ignored = true) val scopes: List<SpotifyScope>? = scopeString?.let { str ->
+        str.split(" ").mapNotNull { scope -> SpotifyScope.values().find { it.uri == scope } }
     }
 }
 

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

@@ -4,10 +4,10 @@ package com.adamratzman.spotify.utils
 import java.net.HttpURLConnection
 import java.net.URL
 
-enum class HttpRequestMethod { GET, POST, PUT, DELETE }
-data class HttpHeader(val key: String, val value: String)
+internal enum class HttpRequestMethod { GET, POST, PUT, DELETE }
+internal data class HttpHeader(val key: String, val value: String)
 
-class HttpConnection(
+internal class HttpConnection(
     private val url: String,
     private val method: HttpRequestMethod,
     private val body: String?,
@@ -50,4 +50,4 @@ class HttpConnection(
     }
 }
 
-data class HttpResponse(val responseCode: Int, val body: String, val headers: List<HttpHeader>)
+internal data class HttpResponse(val responseCode: Int, val body: String, val headers: List<HttpHeader>)