add convenience getters for artist, episode, track, show models

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

Author: adamint

README.md

@@ -39,7 +39,7 @@ repositories {
     jcenter()
 }
 
-compile group: 'com.adamratzman', name: 'spotify-api-kotlin-core', version: '3.2.13'
+compile group: 'com.adamratzman', name: 'spotify-api-kotlin-core', version: '3.2.14'
 ```
 
 Note that images and profiles are not supported on the Kotlin/JS target.

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

@@ -23,7 +23,6 @@ import com.adamratzman.spotify.models.serialization.toObject
 import com.adamratzman.spotify.utils.catch
 import com.adamratzman.spotify.utils.jsonMap
 import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.builtins.list
 import kotlinx.serialization.json.JsonArray
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonObject

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

@@ -21,7 +21,6 @@ import com.adamratzman.spotify.models.serialization.toPagingObject
 import com.adamratzman.spotify.utils.Market
 import com.adamratzman.spotify.utils.catch
 import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.builtins.list
 
 @Deprecated("Endpoint name has been updated for kotlin convention consistency", ReplaceWith("ArtistApi"))
 typealias ArtistsAPI = ArtistApi

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

@@ -25,9 +25,8 @@ import com.adamratzman.spotify.models.serialization.toPagingObject
 import com.adamratzman.spotify.utils.Locale
 import com.adamratzman.spotify.utils.Market
 import com.adamratzman.spotify.utils.formatDate
-import kotlinx.serialization.builtins.ListSerializer
 import kotlin.reflect.KClass
-import kotlinx.serialization.builtins.list
+import kotlinx.serialization.builtins.ListSerializer
 import kotlinx.serialization.builtins.serializer
 
 @Deprecated("Endpoint name has been updated for kotlin convention consistency", ReplaceWith("BrowseApi"))

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

@@ -11,7 +11,6 @@ import com.adamratzman.spotify.models.PlaylistUri
 import com.adamratzman.spotify.models.UserUri
 import com.adamratzman.spotify.models.serialization.toList
 import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.builtins.list
 import kotlinx.serialization.builtins.serializer
 
 @Deprecated("Endpoint name has been updated for kotlin convention consistency", ReplaceWith("FollowingApi"))

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

@@ -22,7 +22,6 @@ import com.adamratzman.spotify.models.serialization.toPagingObject
 import com.adamratzman.spotify.utils.Market
 import com.adamratzman.spotify.utils.catch
 import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.builtins.list
 
 @Deprecated("Endpoint name has been updated for kotlin convention consistency", ReplaceWith("PlaylistApi"))
 typealias PlaylistAPI = PlaylistApi

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

@@ -23,9 +23,15 @@ data class SimpleArtist(
     val type: String
 ) : CoreObject() {
 
+    /**
+     * This [SimpleArtist] into a full [Artist] object
+     */
+    val fullArtist by lazy { api.artists.getArtist(id) }
+
     /**
      * Converts this [SimpleArtist] into a full [Artist] object
      */
+    @Deprecated("Replaced with a lazy fullArtist property", ReplaceWith("fullArtist"))
     fun toFullArtist() = api.artists.getArtist(id)
 }
 

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

@@ -1,8 +1,10 @@
 /* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
 package com.adamratzman.spotify.models
 
+import com.adamratzman.spotify.SpotifyClientApi
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.utils.Locale
+import com.adamratzman.spotify.utils.Market
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.Transient
@@ -104,6 +106,13 @@ data class SimpleEpisode(
     val languages
         get() = (language?.let { showLanguagesPrivate + it } ?: showLanguagesPrivate)
                 .map { Locale.valueOf(it.replace("-", "_")) }
+
+    /**
+     * Converts this [SimpleEpisode] into a full [Episode] object
+     *
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     */
+    fun toFullEpisode(market: Market? = null) = (api as? SpotifyClientApi)?.episodes?.getEpisode(id, market)
 }
 
 /**

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

@@ -1,6 +1,7 @@
 /* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
 package com.adamratzman.spotify.models
 
+import com.adamratzman.spotify.utils.Market
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
@@ -68,4 +69,15 @@ data class LocalTrack(
     @SerialName("track_number") val trackNumber: Int? = null,
     override val type: String,
     override val uri: LocalTrackUri
-) : IdentifiableNullable(), Playable
+) : IdentifiableNullable(), Playable {
+
+    /**
+     * Search for this local track by name in Spotify's track catalog.
+     *
+     * @param limit The number of objects to return. Default: 50 (or api limit). Minimum: 1. Maximum: 50.
+     * @param offset The index of the first item to return. Default: 0. Use with limit to get the next set of items
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     * If omitted, the returned items will be relevant to all countries.
+     */
+    fun searchForSpotifyTrack(limit: Int? = null, offset: Int? = null, market: Market? = null) = api.search.searchTrack(name, limit, offset, market)
+}

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

@@ -10,6 +10,14 @@ import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.contentOrNull
 import kotlinx.serialization.json.jsonPrimitive
 
+/**
+ * A Playable object represents a [Track], [Episode], or [LocalTrack] that has been returned by the Spotify api.
+ *
+ * @property href A link to the Web API endpoint providing full details of the album.
+ * @property id The Spotify ID for the album.
+ * @property uri The URI associated with the object
+ * @property type The object type
+ */
 interface Playable {
     val href: String?
     val id: String?
@@ -33,4 +41,19 @@ interface Playable {
             }
         }
     }
+
+    /**
+     * This Playable object as a [LocalTrack]
+     */
+    val asLocalTrack get() = this as LocalTrack
+
+    /**
+     * This Playable object as a [Track]
+     */
+    val asTrack get() = this as Track
+
+    /**
+     * This Playable object as an [Episode]
+     */
+    val asEpisode get() = this as Episode
 }