Consolidate builders and DSLs to use common interface bases #122 #116

- Disable automatic token refresh by default
- Split spotifyApi(block) function into spotifyAppApi(..) and spotifyClientApi(..)
- Remove redundant logic shared between DSL builders and SpotifyApiBuilder

Author: adamint

README.md

@@ -80,12 +80,12 @@ To build a new `SpotifyAPI`, you must pass the application id and secret.
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.spotifyApi
 
-spotifyApi {
+val spotifyApi: SpotifyAPI = spotifyAppApi {
     credentials {
         clientId = "YOUR_CLIENT_ID"
         clientSecret = "YOUR_CLIENT_SECRET"
     }
-}.buildCredentialed()
+}.build()
 ```
 *Note:* You are **unable** to use any client endpoint without authenticating with the methods below. 
 
@@ -98,7 +98,7 @@ an authorization code or a `Token` object. Otherwise, it will expire `Token.expi
 You have two options when building the Client API.
 1. You can use [Implicit Grant access tokens](https://developer.spotify.com/web-api/authorization-guide/#implicit_grant_flow) by
 setting the value of `tokenString` in the builder `authentication` block. However, this is a one-time token that cannot be refreshed.
-2. You can use the [Authorization code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow) by 
+2. You can use the [Authorization   code flow](https://developer.spotify.com/web-api/authorization-guide/#authorization_code_flow) by 
 setting the value of `authorizationCode` in a builder. You may generate an authentication flow url allowing you to request specific 
 Spotify scopes using the `getAuthorizationUrl` method in any builder. This library does not provide a method to retrieve the code from your 
 callback URL; you must implement that with a web server.
@@ -157,18 +157,18 @@ the synchronous format is also shown.
 import com.adamratzman.spotify.SpotifyScope
 import com.adamratzman.spotify.spotifyApi
 
-val api = spotifyApi {
+val api: SpotifyAPI = spotifyAppApi {
     credentials {
         clientId = "YOUR_CLIENT_ID"
         clientSecret = "YOUR_CLIENT_SECRET"
     }
-}.buildCredentialed()
+}.build()
 
 // block and print out the names of the twenty most similar songs to the search
-println(api.search.searchTrack("Début de la Suite").complete().map { it.name }.joinToString())
+println(api.search.searchTrack("Début de la Suite").complete().joinToString { it.name })
 
 // now, let's do it asynchronously
-api.search.searchTrack("Début de la Suite").queue { println(it.map { it.name }.joinToString()) }
+api.search.searchTrack("Début de la Suite").queue { tracks -> println(tracks.joinToString { track -> track.name }) }
 
 // simple, right? what about if we want to print out the featured playlists message from the "Overview" tab?
 println(api.browse.getFeaturedPlaylists().complete().message)
@@ -177,6 +177,7 @@ println(api.browse.getFeaturedPlaylists().complete().message)
 // let's find out Bénabar's Spotify ID, find his top tracks, and print them out
 
 val benabarId = api.search.searchArtist("Bénabar").complete()[0].id
+// this works, but a better way would be: api.artists.getArtist("spotify:artist:6xoAWsIOZxJVPpo7Qvqaqv").complete().id
 
 println(api.artists.getArtistTopTracks(benabarId).complete().joinToString { it.name })
 ```
@@ -190,7 +191,7 @@ In both Track and SimpleTrack objects in an endpoint response, there is a nullab
 If the track is unable to be played in the specified market and there is an alternative that *is* playable, this 
 will be populated with the href, uri, and, most importantly, the id of the track.
 
-You can then use this track in `SpotifyClientAPI` actions such as playing or saving the track, knowing that it will be playable 
+You can then use this track in `SpotifyClientAPI` endpoints such as playing or saving the track, knowing that it will be playable 
 in your market!
 
 ### Contributing

docs/com/adamratzman/spotify/SpotifyApiBuilderDsl.html

@@ -189,7 +189,7 @@ <h3>Method Summary</h3>
 </tr>
 <tr id="i5" class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#config-block-">config</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#config-block-">config</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
@@ -208,13 +208,13 @@ <h3>Method Summary</h3>
 </tr>
 <tr id="i8" class="altColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#options-block-">options</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#options-block-">options</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
 <tr id="i9" class="rowColor">
 <td class="colFirst"><code>void</code></td>
-<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#utilities-block-">utilities</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</code>
+<td class="colLast"><code><span class="memberNameLink"><a href="../../../com/adamratzman/spotify/SpotifyApiBuilderDsl.html#utilities-block-">utilities</a></span>(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</code>
 <div class="block">Allows you to override default values for caching, token refresh, and logging</div>
 </td>
 </tr>
@@ -288,7 +288,7 @@ <h4>authentication</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>utilities</h4>
-<pre>public&nbsp;void&nbsp;utilities(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;utilities(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>
@@ -298,7 +298,7 @@ <h4>utilities</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>config</h4>
-<pre>public&nbsp;void&nbsp;config(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;config(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>
@@ -308,7 +308,7 @@ <h4>config</h4>
 <ul class="blockList">
 <li class="blockList">
 <h4>options</h4>
-<pre>public&nbsp;void&nbsp;options(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyUtilitiesBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
+<pre>public&nbsp;void&nbsp;options(kotlin.jvm.functions.Function1&lt;? super com.adamratzman.spotify.SpotifyApiOptionsBuilder,kotlin.Unit&gt;&nbsp;block)</pre>
 <div class="block"><p><p>Allows you to override default values for caching, token refresh, and logging</p></p></div>
 </li>
 </ul>

docs/com/adamratzman/spotify/SpotifyUtilities.html

@@ -6,7 +6,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>SpotifyUtilities</title>
 <meta name="date" content="2019-08-13">
-<meta name="keywords" content="com.adamratzman.spotify.SpotifyUtilities class">
+<meta name="keywords" content="com.adamratzman.spotify.SpotifyApiOptions class">
 <meta name="keywords" content="getUseCache()">
 <meta name="keywords" content="getCacheLimit()">
 <meta name="keywords" content="getAutomaticRefresh()">
@@ -114,7 +114,7 @@ <h2 title="Class SpotifyUtilities" class="title">Class SpotifyUtilities</h2>
 </div>
 <div class="contentContainer">
 <ul class="inheritance">
-<li>com.adamratzman.spotify.SpotifyUtilities</li>
+<li>com.adamratzman.spotify.SpotifyApiOptions</li>
 </ul>
 <div class="description">
 <ul class="blockList">

docs/com/adamratzman/spotify/SpotifyUtilitiesBuilder.html

@@ -6,7 +6,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <title>SpotifyUtilitiesBuilder</title>
 <meta name="date" content="2019-08-13">
-<meta name="keywords" content="com.adamratzman.spotify.SpotifyUtilitiesBuilder class">
+<meta name="keywords" content="com.adamratzman.spotify.SpotifyApiOptionsBuilder class">
 <meta name="keywords" content="build()">
 <meta name="keywords" content="getUseCache()">
 <meta name="keywords" content="setUseCache()">
@@ -113,7 +113,7 @@ <h2 title="Class SpotifyUtilitiesBuilder" class="title">Class SpotifyUtilitiesBu
 </div>
 <div class="contentContainer">
 <ul class="inheritance">
-<li>com.adamratzman.spotify.SpotifyUtilitiesBuilder</li>
+<li>com.adamratzman.spotify.SpotifyApiOptionsBuilder</li>
 </ul>
 <div class="description">
 <ul class="blockList">