Merge pull request #235 from adamint/dev

make episode and show descriptions nullable, lint

Author: adamint

.gitignore

@@ -334,4 +334,4 @@ gradle-app.setting
 **/build/
 
 # End of https://www.toptal.com/developers/gitignore/api/gradle,kotlin,android,intellij+all,node
-docs
+docs/

README.md

@@ -37,7 +37,7 @@ repositories {
     jcenter()
 }
 
-implementation("com.adamratzman:spotify-api-kotlin-core:3.4.01")
+implementation("com.adamratzman:spotify-api-kotlin-core:3.4.03")
 ```
 
 Note that images and profiles are not supported on the Kotlin/JS target.

build.gradle.kts

@@ -32,7 +32,7 @@ buildscript {
 }
 
 group = "com.adamratzman"
-version = "3.4.01"
+version = "3.4.03"
 
 tasks.withType<Test> {
     this.testLogging {

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

@@ -2,6 +2,7 @@
 package com.adamratzman.spotify.endpoints.public
 
 import com.adamratzman.spotify.GenericSpotifyApi
+import com.adamratzman.spotify.SpotifyAppApi
 import com.adamratzman.spotify.SpotifyException.BadRequestException
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.http.SpotifyEndpoint
@@ -89,6 +90,8 @@ public open class PlaylistApi(api: GenericSpotifyApi) : SpotifyEndpoint(api) {
      *
      * **Note that** both Public and Private playlists belonging to any user are retrievable on provision of a valid access token.
      *
+     * **Warning:** if the playlist contains podcasts, the tracks will be null if you are using [SpotifyAppApi].
+     *
      * **[Api Reference](https://developer.spotify.com/documentation/web-api/reference/playlists/get-playlists-tracks/)**
      *
      * @param playlist The id or uri for the playlist.

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

@@ -37,7 +37,7 @@ public data class SimpleAlbum(
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
     override val href: String,
     override val id: String,
-    override val uri: AlbumUri,
+    override val uri: SpotifyUri,
 
     val artists: List<SimpleArtist>,
     val images: List<SpotifyImage>,

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

@@ -17,7 +17,7 @@ public data class SimpleArtist(
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
     override val href: String,
     override val id: String,
-    override val uri: ArtistUri,
+    override val uri: SpotifyUri,
 
     val name: String,
     val type: String

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

@@ -8,6 +8,64 @@ import com.adamratzman.spotify.utils.Market
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
+/**
+ * An episode (podcast) on Spotify
+ *
+ * @param album The album on which the track appears. The album object includes a link in
+ * href to full information about the album.
+ * @param artists The artists who performed the track. Each artist object includes a link in href
+ * to more detailed information about the artist.
+ * @property availableMarkets A list of the countries in which the track can be played, identified by their ISO 3166-1 alpha-2 code.
+ * @param discNumber The disc number (usually 1 unless the album consists of more than one disc).
+ * @param durationMs The track length in milliseconds.
+ *
+ * @param explicit Whether or not the track has explicit lyrics ( true = yes it does; false = no it does not OR unknown).
+ * @param isLocal Whether or not the track is from a local file.
+ * @param isPlayable Part of the response when Track Relinking is applied. If true , the track is playable in the
+ * given market. Otherwise false.
+ * @param name The name of the track.
+ * @param popularity The popularity of the track. The value will be between 0 and 100, with 100 being the most
+ * popular. The popularity of a track is a value 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. Generally speaking, songs that are being played a lot now will have a higher popularity
+ * than songs that were played a lot in the past. Duplicate tracks (e.g. the same track from a single and an album)
+ * are rated independently. Artist and album popularity is derived mathematically from track popularity. Note that
+ * the popularity value may lag actual popularity by a few days: the value is not updated in real time.
+ * @param previewUrl A link to a 30 second preview (MP3 format) of the track. Can be null.
+ * @param track Whether this episode is also a track.
+ * @param trackNumber The number of the track. If an album has several discs, the track number is the number on the specified disc.
+ * @param type The object type: “episode”.
+ *
+ */
+@Serializable
+public data class PodcastEpisodeTrack(
+    val album: SimpleAlbum,
+    val artists: List<SimpleArtist>,
+    @SerialName("available_markets") private val availableMarketsString: List<String> = listOf(),
+    @SerialName("disc_number") val discNumber: Int,
+    @SerialName("duration_ms") val durationMs: Int,
+    val episode: Boolean? = null,
+    val explicit: Boolean,
+    @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
+    @SerialName("external_ids") private val externalIdsString: Map<String, String> = hashMapOf(),
+    override val href: String,
+    override val id: String,
+    @SerialName("is_local") val isLocal: Boolean? = null,
+    @SerialName("is_playable") val isPlayable: Boolean = true,
+    val name: String,
+    val popularity: Int,
+    @SerialName("preview_url") val previewUrl: String? = null,
+    val track: Boolean? = null,
+    @SerialName("track_number") val trackNumber: Int,
+    override val type: String,
+    override val uri: PlayableUri,
+    override val linkedTrack: LinkedTrack? = null
+) : RelinkingAvailableResponse(), Playable {
+    val availableMarkets: List<Market> get() = availableMarketsString.map { Market.valueOf(it) }
+
+    val externalIds: List<ExternalId> get() = externalIdsString.map { ExternalId(it.key, it.value) }
+}
+
 /**
  * An episode (podcast) on Spotify
  *
@@ -30,7 +88,7 @@ import kotlinx.serialization.Serializable
 @Serializable
 public data class Episode(
     @SerialName("audio_preview_url") val audioPreviewUrl: String? = null,
-    val description: String,
+    val description: String? = null,
     @SerialName("duration_ms") val durationMs: Int,
     val explicit: Boolean,
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
@@ -47,9 +105,9 @@ public data class Episode(
     @SerialName("release_date_precision") val releaseDatePrecisionString: String,
     @SerialName("resume_point") val resumePoint: ResumePoint? = null,
     val show: SimpleShow,
-    override val type: String,
+    val type: String,
     override val uri: EpisodeUri
-) : CoreObject(), Playable {
+) : CoreObject() {
     val releaseDate: ReleaseDate get() = getReleaseDate(releaseDateString)
 
     @Suppress("DEPRECATION")
@@ -80,7 +138,7 @@ public data class Episode(
 @Serializable
 public data class SimpleEpisode(
     @SerialName("audio_preview_url") val audioPreviewUrl: String? = null,
-    val description: String,
+    val description: String? = null,
     @SerialName("duration_ms") val durationMs: Int,
     val explicit: Boolean,
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
@@ -96,22 +154,23 @@ public data class SimpleEpisode(
     @SerialName("release_date") private val releaseDateString: String,
     @SerialName("release_date_precision") val releaseDatePrecisionString: String,
     @SerialName("resume_point") val resumePoint: ResumePoint? = null,
-    override val type: String,
-    override val uri: EpisodeUri
-) : CoreObject(), Playable {
+    val type: String,
+    override val uri: SpotifyUri
+) : CoreObject() {
     val releaseDate: ReleaseDate get() = getReleaseDate(releaseDateString)
 
     @Suppress("DEPRECATION")
     val languages: List<Locale>
         get() = (language?.let { showLanguagesPrivate + it } ?: showLanguagesPrivate)
-                .map { Locale.valueOf(it.replace("-", "_")) }
+            .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.
      */
-    public suspend fun toFullEpisode(market: Market? = null): Episode? = (api as? SpotifyClientApi)?.episodes?.getEpisode(id, market)
+    public suspend fun toFullEpisode(market: Market? = null): Episode? =
+        (api as? SpotifyClientApi)?.episodes?.getEpisode(id, market)
 }
 
 /**

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

@@ -9,20 +9,45 @@ import kotlinx.serialization.json.JsonObject
 import kotlinx.serialization.json.contentOrNull
 import kotlinx.serialization.json.jsonPrimitive
 
+/**
+ * A local track, episode, or track.
+ *
+ * @property href A link to the Web API endpoint providing full details of the playable.
+ * @property id The Spotify ID for the playable.
+ * @property uri The URI associated with the object.
+ * @property type The type of the playable.
+ */
 public interface Playable {
     public val href: String?
     public val id: String?
     public val uri: PlayableUri
     public val type: String
 
+    /**
+     * This Playable as a local track.
+     *
+     */
+    public val asLocalTrack: LocalTrack? get() = this as? LocalTrack
+
+    /**
+     * This Playable as an episode.
+     *
+     */
+    public val asPodcastEpisodeTrack: PodcastEpisodeTrack? get() = this as? PodcastEpisodeTrack
+
+    /**
+     * This Playable as a track.
+     *
+     */
+    public val asTrack: Track? get() = this as? Track
+
     @Suppress("EXPERIMENTAL_API_USAGE")
     @Serializer(forClass = Playable::class)
     public companion object : KSerializer<Playable> by object : JsonContentPolymorphicSerializer<Playable>(Playable::class) {
         override fun selectDeserializer(element: JsonElement): KSerializer<out Playable> {
-
             return when (val uri: PlayableUri? = (element as? JsonObject)?.get("uri")?.jsonPrimitive?.contentOrNull?.let { PlayableUri(it) }) {
                 is LocalTrackUri -> LocalTrack.serializer()
-                is EpisodeUri -> Episode.serializer()
+                is EpisodeUri -> PodcastEpisodeTrack.serializer()
                 is SpotifyTrackUri -> Track.serializer()
                 null -> throw IllegalStateException("Couldn't find a serializer for uri $uri")
             }

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

@@ -1,6 +1,7 @@
 /* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2021; Original author: Adam Ratzman */
 package com.adamratzman.spotify.models
 
+import com.adamratzman.spotify.SpotifyAppApi
 import com.adamratzman.spotify.endpoints.client.PlaylistSnapshot
 import com.adamratzman.spotify.utils.Market
 import kotlinx.serialization.SerialName
@@ -34,7 +35,7 @@ public data class SimplePlaylist(
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
     override val href: String,
     override val id: String,
-    override val uri: PlaylistUri,
+    override val uri: SpotifyUri,
 
     val collaborative: Boolean,
     val images: List<SpotifyImage>,
@@ -67,6 +68,7 @@ public data class SimplePlaylist(
  * @param addedBy The Spotify user who added the track. Note that some very old playlists may return null in this field.
  * @param isLocal Whether this track is a local file or not.
  * @param track Information about the track. In rare occasions, this field may be null if this track's API entry is broken.
+ * **Warning:** if this is a podcast, the track will be null if you are using [SpotifyAppApi].
  */
 @Serializable
 public data class PlaylistTrack(

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

@@ -28,7 +28,7 @@ public data class SimpleShow(
     @SerialName("available_markets") private val availableMarketsString: List<String> = listOf(),
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,
     val copyrights: List<SpotifyCopyright>,
-    val description: String,
+    val description: String? = null,
     val explicit: Boolean,
     override val href: String,
     override val id: String,
@@ -39,7 +39,7 @@ public data class SimpleShow(
     val name: String,
     val publisher: String,
     val type: String,
-    override val uri: ShowUri
+    override val uri: SpotifyUri
 ) : CoreObject() {
     val availableMarkets: List<Market> get() = availableMarketsString.map { Market.valueOf(it) }
 
@@ -74,7 +74,7 @@ public data class SimpleShow(
 public data class Show(
     @SerialName("available_markets") private val availableMarketsString: List<String> = listOf(),
     val copyrights: List<SpotifyCopyright>,
-    val description: String,
+    val description: String? = null,
     val explicit: Boolean,
     val episodes: NullablePagingObject<SimpleEpisode>,
     @SerialName("external_urls") override val externalUrlsString: Map<String, String>,