Merge pull request #180 from adamint/dev

Update documentation, add samples, add PagingObject#getWithNext

Author: adamint

README.md

@@ -1,49 +1,52 @@
 # Testing
 
-We use [Spek](https://github.com/spekframework/spek) to run unit tests. 
+We use [Spek](https://github.com/spekframework/spek) to run unit tests. You must add Maven Central to the gradle repositories 
+in order to pull Spek.
 
-To run any test, you must have two environment variables, `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` set to a Spotify application in your current shell.
+You must create a Spotify application [here](https://developer.spotify.com/dashboard/applications) to get credentials.
 
-`export SPOTIFY_CLIENT_ID=your_client_id`
+To run **only** public endpoint tests, run
 
-`export SPOTIFY_CLIENT_SECRET=your_client_secret`
+`gradle check`
 
-To run **only** public endpoint and utility tests, run `gradle check`
+Note: You must have `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` as environment variables.
 
-To run **all** tests, you need a valid Spotify redirect uri, and token (string). These are `SPOTIFY_REDIRECT_URI` and `SPOTIFY_TOKEN_STRING` respectively.
+To run **all** tests, you need a valid Spotify application, redirect uri, and token string. use:
 
-Then: `gradle check`
+`gradle check`
+
+Note: In addition to `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`, you also must have the following environment 
+variables set up: `SPOTIFY_REDIRECT_URI` and `SPOTIFY_TOKEN_STRING`
 
 Some tests may fail if you do not allow access to all required scopes. To mitigate this, you can individually grant 
 each scope or use the following code snippet to print out the Spotify token string (given a generated authorization code)
 
 **How to generate an authorization URL**
 ```kotlin
-import com.adamratzman.spotify.SpotifyScope
-import com.adamratzman.spotify.spotifyClientApi
-
-spotifyClientApi {
-    credentials {
-        clientId = "YOUR_CLIENT_ID"
-        clientSecret = "YOUR_CLIENT_SECRET"
-        redirectUri = "YOUR_REDIRECT_URI"
+import com.adamratzman.spotify.main.SpotifyScope
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+
+val api = spotifyClientApi(
+        "SPOTIFY_CLIENT_ID",
+        "SPOTIFY_CLIENT_SECRET",
+        "SPOTIFY_REDIRECT_URI") {
+    authorization {
+        tokenString = "SPOTIFY_TOKEN_STRING"
     }
 }.getAuthorizationUrl(*SpotifyScope.values())
 
 ```
 
 **How to get a Spotify token**
 ```kotlin
-import com.adamratzman.spotify.spotifyClientApi
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
 
-spotifyClientApi {
-    credentials {
-        clientId = "YOUR_CLIENT_ID"
-        clientSecret = "YOUR_CLIENT_SECRET"
-        redirectUri = "YOUR_REDIRECT_URI"
-    }
+val api = spotifyClientApi(
+        "SPOTIFY_CLIENT_ID",
+        "SPOTIFY_CLIENT_SECRET",
+        "SPOTIFY_REDIRECT_URI") {
     authorization {
-        authorizationCode = "SPOTIFY_AUTHORIZATION_CODE"
+        tokenString = "SPOTIFY_TOKEN_STRING"
     }
 }.build().token.accessToken.let { println(it) }
 ```

TESTING.md

@@ -1,5 +1,6 @@
 import org.jetbrains.dokka.gradle.DokkaTask
 import org.jetbrains.kotlin.gradle.dsl.KotlinJsCompile
+import java.net.URI
 
 plugins {
     `maven-publish`
@@ -21,6 +22,12 @@ java {
     withJavadocJar()
 }
 
+tasks.withType<Test> {
+    this.testLogging {
+        this.showStandardStreams = true
+    }
+}
+
 repositories {
     mavenCentral()
     jcenter()
@@ -95,6 +102,9 @@ kotlin {
                 }
             }
 
+            all {
+                languageSettings.useExperimentalAnnotation("kotlin.Experimental")
+            }
         }
     }
 }
@@ -113,7 +123,7 @@ tasks.named<Test>("jvmTest") {
 spotless {
     kotlin {
         target("**/*.kt")
-        licenseHeader("/* Spotify Web API - Kotlin Wrapper; MIT License, 2019; Original author: Adam Ratzman */")
+        licenseHeader("/* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */")
         ktlint()
     }
 }
@@ -123,6 +133,10 @@ nexusStaging {
 }
 
 
+tasks.withType<GenerateModuleMetadata> {
+    enabled = false
+}
+
 publishing {
     publications {
         val jvm by getting(MavenPublication::class) {
@@ -165,17 +179,30 @@ publishing {
         }
     }
     repositories {
-        maven {
-            name = "nexus"
-            val releasesRepoUrl = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
-            val snapshotsRepoUrl = "https://oss.sonatype.org/content/repositories/snapshots/"
-            url = uri(if (version.toString().endsWith("SNAPSHOT")) snapshotsRepoUrl else releasesRepoUrl)
-
-            credentials {
-                val nexusUsername: String? by project.extra
-                val nexusPassword: String? by project.extra
-                username = nexusUsername
-                password = nexusPassword
+        if (project.hasProperty("publishToCentral")) {
+            maven {
+                name = "nexus"
+                val releasesRepoUrl = "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
+                val snapshotsRepoUrl = "https://oss.sonatype.org/content/repositories/snapshots/"
+                url = uri(if (version.toString().endsWith("SNAPSHOT")) snapshotsRepoUrl else releasesRepoUrl)
+
+                credentials {
+                    val nexusUsername: String? by project.extra
+                    val nexusPassword: String? by project.extra
+                    username = nexusUsername
+                    password = nexusPassword
+                }
+            }
+        } else {
+            if (project.extra.has("spaceUser") && project.extra.has("spacePassword")) {
+                maven {
+                    credentials {
+                        username = project.extra["spaceUser"]?.toString()
+                        password = project.extra["spacePassword"]?.toString()
+                    }
+
+                    url = URI.create("https://maven.jetbrains.space/adam/ratzman")
+                }
             }
         }
     }

build.gradle.kts

@@ -0,0 +1,23 @@
+plugins {
+    id 'org.jetbrains.kotlin.jvm' version '1.3.61'
+}
+
+group 'com.adamratzman'
+version '3.0.0'
+
+repositories {
+    mavenLocal()
+    mavenCentral()
+}
+
+dependencies {
+    compile "com.adamratzman:spotify-api-kotlin:3.0.0"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8"
+}
+
+compileKotlin {
+    kotlinOptions.jvmTarget = "1.8"
+}
+compileTestKotlin {
+    kotlinOptions.jvmTarget = "1.8"
+}

samples/build.gradle

@@ -0,0 +1,4 @@
+enableFeaturePreview('GRADLE_METADATA')
+
+rootProject.name = 'samples'
+

samples/settings.gradle

@@ -0,0 +1,57 @@
+/* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
+package private
+
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+import com.adamratzman.spotify.annotations.SpotifyExperimentalHttpApi
+
+@SpotifyExperimentalHttpApi
+fun main() {
+    // instantiate api
+    val api = spotifyClientApi(
+            System.getenv("SPOTIFY_CLIENT_ID"),
+            System.getenv("SPOTIFY_CLIENT_SECRET"),
+            System.getenv("SPOTIFY_REDIRECT_URI")) {
+        authorization {
+            tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
+        }
+    }.build()
+
+    // see if you're following playlist "I'm Good Radio"
+    println(api.following.isFollowingPlaylist("spotify:playlist:37i9dQZF1E8L0j2hm3kP31").complete())
+
+    // see if you're following users adamratzman1 and adamratzman
+    println(api.following.isFollowingUsers("adamratzman1", "adamratzman").complete())
+
+    // see if you're following artist Louane
+    println(api.following.isFollowingArtist("spotify:artist:7wjeXCtRND2ZdKfMJFu6JC").complete())
+
+    // get all followed artists, limiting 1 each request
+    println(api.following.getFollowedArtists(limit = 1).getAllItems().complete())
+
+    // follow and unfollow, if you weren't previously following, the artist Louane
+
+    val isFollowingLouane = api.following.isFollowingArtist("spotify:artist:7wjeXCtRND2ZdKfMJFu6JC").complete()
+
+    if (isFollowingLouane) api.following.unfollowArtist("spotify:artist:7wjeXCtRND2ZdKfMJFu6JC").complete()
+    api.following.followArtist("spotify:artist:7wjeXCtRND2ZdKfMJFu6JC").complete()
+
+    if (!isFollowingLouane) api.following.unfollowArtist("spotify:artist:7wjeXCtRND2ZdKfMJFu6JC").complete()
+
+    // follow and unfollow, if you weren't previously following, the user adamratzman1
+
+    val isFollowingAdam = api.following.isFollowingUser("adamratzman").complete()
+
+    if (isFollowingAdam) api.following.unfollowUser("adamratzman").complete()
+    api.following.followUser("adamratzman").complete()
+
+    if (!isFollowingAdam) api.following.unfollowUser("adamratzman").complete()
+
+    // follow and unfollow, if you weren't previously following, the playlist Today's Top Hits
+
+    val isFollowingTodaysTopHits = api.following.isFollowingPlaylist("spotify:playlist:37i9dQZF1DXcBWIGoYBM5M").complete()
+
+    if (isFollowingTodaysTopHits) api.following.unfollowPlaylist("spotify:playlist:37i9dQZF1DXcBWIGoYBM5M").complete()
+    api.following.followPlaylist("spotify:playlist:37i9dQZF1DXcBWIGoYBM5M").complete()
+
+    if (!isFollowingTodaysTopHits) api.following.unfollowPlaylist("spotify:playlist:37i9dQZF1DXcBWIGoYBM5M").complete()
+}

samples/src/main/kotlin/private/ClientFollowingApiSample.kt

@@ -0,0 +1,30 @@
+/* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
+package private
+
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+import com.adamratzman.spotify.endpoints.client.LibraryType.TRACK
+
+fun main() {
+    // instantiate api
+    val api = spotifyClientApi(
+            System.getenv("SPOTIFY_CLIENT_ID"),
+            System.getenv("SPOTIFY_CLIENT_SECRET"),
+            System.getenv("SPOTIFY_REDIRECT_URI")) {
+        authorization {
+            tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
+        }
+    }.build()
+
+    // get all your saved tracks
+    println(api.library.getSavedTracks(limit = 50).getAllItems().complete().map { it.track.name })
+
+    // get your 11-20th saved albums
+    println(api.library.getSavedAlbums(limit = 10, offset = 10).complete().map { it.album.name })
+
+    // check if your library contains the track "I'm Good" by the Mowgli's
+    println(api.library.contains(TRACK, api.search.searchTrack("I'm Good the Mowgli's").complete()[0].id).complete())
+
+    // add and remove track "Up" by Nav
+    api.library.add(TRACK, "spotify:track:5qbcsZMwL0x46sX7VO37Ye").complete()
+    api.library.remove(TRACK, "spotify:track:5qbcsZMwL0x46sX7VO37Ye").complete()
+}

samples/src/main/kotlin/private/ClientLibraryApiSample.kt

@@ -0,0 +1,24 @@
+/* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
+package private
+
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+import com.adamratzman.spotify.endpoints.client.ClientPersonalizationApi.TimeRange.LONG_TERM
+import com.adamratzman.spotify.endpoints.client.ClientPersonalizationApi.TimeRange.SHORT_TERM
+
+fun main() {
+    // instantiate api
+    val api = spotifyClientApi(
+            System.getenv("SPOTIFY_CLIENT_ID"),
+            System.getenv("SPOTIFY_CLIENT_SECRET"),
+            System.getenv("SPOTIFY_REDIRECT_URI")) {
+        authorization {
+            tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
+        }
+    }.build()
+
+    // print your top 30 artists over the last few years
+    println(api.personalization.getTopArtists(30, timeRange = LONG_TERM).complete().items.map { it.name })
+
+    // print your top 20 tracks in the last 4 weeks
+    println(api.personalization.getTopTracks(timeRange = SHORT_TERM).complete().items.map { track -> "${track.name} by ${track.artists.joinToString(", ") { it.name }}" })
+}

samples/src/main/kotlin/private/ClientPersonalizationApiSample.kt

@@ -0,0 +1,61 @@
+/* Spotify Web API, Kotlin Wrapper; MIT License, 2017-2020; Original author: Adam Ratzman */
+package private
+
+import com.adamratzman.spotify.SpotifyApi.Companion.spotifyClientApi
+import com.adamratzman.spotify.annotations.SpotifyExperimentalFunctionApi
+import com.adamratzman.spotify.endpoints.client.ClientPlayerApi.PlayerRepeatState.TRACK
+
+@SpotifyExperimentalFunctionApi
+fun main() {
+    // instantiate api
+    val api = spotifyClientApi(
+            System.getenv("SPOTIFY_CLIENT_ID"),
+            System.getenv("SPOTIFY_CLIENT_SECRET"),
+            System.getenv("SPOTIFY_REDIRECT_URI")) {
+        authorization {
+            tokenString = System.getenv("SPOTIFY_TOKEN_STRING")
+        }
+    }.build()
+
+    // print all devices connected to this Spotify account
+    println(api.player.getDevices().complete())
+
+    // get the current context track position
+    println(api.player.getCurrentContext().complete()?.progressMs)
+
+    // get the 20 most recently played (there is a small lag) tracks
+    println(api.player.getRecentlyPlayed().complete().map { it.track.name })
+
+    // get the currenty played PlaybackActions
+    println(api.player.getCurrentlyPlaying().complete()?.actions)
+
+    // play song "I'm Good" by the Mowgli's
+    api.player.startPlayback(tracksToPlay = listOf(api.search.searchTrack("I'm Good the Mowgli's").complete()[0].uri.uri)).complete()
+
+    // pause playback on the current device.
+    api.player.pause().complete()
+
+    // seek the beginning of the track currently playing
+    api.player.seek(0).complete()
+
+    // resume playback
+    api.player.resume().complete()
+
+    // set repeat the current track
+    api.player.setRepeatMode(TRACK).complete()
+
+    // set volume to 50%
+    api.player.setVolume(50).complete()
+
+    // skip to the next track
+    api.player.skipForward().complete()
+
+    // skip back to the last track that was in the user queue
+    api.player.skipBehind().complete()
+
+    // toggle shuffling
+    api.player.toggleShuffle(shuffle = true).complete()
+
+    // transfer playback
+    api.player.transferPlayback(api.player.getDevices().complete().first().id!!).complete()
+}