Moar docs and TooManyRequests exception

SpotifyAPI.Web.Examples/Example.TokenSwap/Client/Program.cs

@@ -11,7 +11,7 @@ namespace Client
     private static readonly string clientId = Environment.GetEnvironmentVariable("SPOTIFY_CLIENT_ID");
     private static EmbedIOAuthServer _server;
 
-    public static async Task Main(string[] args)
+    public static async Task Main()
     {
       _server = new EmbedIOAuthServer(new Uri("http://localhost:5000/callback"), 5000);
       await _server.Start();

SpotifyAPI.Web/Clients/Interfaces/IOAuthClient.cs

@@ -11,7 +11,7 @@ namespace SpotifyAPI.Web
     /// Requests a new token using client_ids and client_secrets.
     /// If the token is expired, simply call the funtion again to get a new token
     /// </summary>
-    /// <param name="request"></param>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
     /// <remarks>
     /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#client-credentials-flow
     /// </remarks>
@@ -21,7 +21,7 @@ namespace SpotifyAPI.Web
     /// <summary>
     /// Refresh an already received token via Authorization Code Auth
     /// </summary>
-    /// <param name="request"></param>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
     /// <remarks>
     /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
     /// </remarks>
@@ -31,11 +31,31 @@ namespace SpotifyAPI.Web
     /// <summary>
     /// Reequest an initial token via Authorization Code Auth
     /// </summary>
-    /// <param name="request"></param>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
     /// <remarks>
     /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
     /// </remarks>
     /// <returns></returns>
     Task<AuthorizationCodeTokenResponse> RequestToken(AuthorizationCodeTokenRequest request);
+
+    /// <summary>
+    /// Swaps out a received code with a access token using a remote server
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/ios/guides/token-swap-and-refresh/
+    /// </remarks>
+    /// <returns></returns>
+    Task<AuthorizationCodeTokenResponse> RequestToken(TokenSwapTokenRequest request);
+
+    /// <summary>
+    /// Gets a refreshed access token using an already received refresh token using a remote server
+    /// </summary>
+    /// <param name="request"></param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/ios/guides/token-swap-and-refresh/
+    /// </remarks>
+    /// <returns></returns>
+    Task<AuthorizationCodeRefreshResponse> RequestToken(TokenSwapRefreshRequest request);
   }
 }

SpotifyAPI.Web/Clients/OAuthClient.cs

@@ -15,26 +15,67 @@ namespace SpotifyAPI.Web
     [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Design", "CA1062")]
     public OAuthClient(SpotifyClientConfig config) : base(ValidateConfig(config)) { }
 
+    /// <summary>
+    /// Requests a new token using client_ids and client_secrets.
+    /// If the token is expired, simply call the funtion again to get a new token
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#client-credentials-flow
+    /// </remarks>
+    /// <returns></returns>1
     public Task<CredentialsTokenResponse> RequestToken(ClientCredentialsRequest request)
     {
       return RequestToken(request, API);
     }
 
+    /// <summary>
+    /// Refresh an already received token via Authorization Code Auth
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
+    /// </remarks>
+    /// <returns></returns>
     public Task<AuthorizationCodeRefreshResponse> RequestToken(AuthorizationCodeRefreshRequest request)
     {
       return RequestToken(request, API);
     }
 
+    /// <summary>
+    /// Reequest an initial token via Authorization Code Auth
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
+    /// </remarks>
+    /// <returns></returns>
     public Task<AuthorizationCodeTokenResponse> RequestToken(AuthorizationCodeTokenRequest request)
     {
       return RequestToken(request, API);
     }
 
+    /// <summary>
+    /// Swaps out a received code with a access token using a remote server
+    /// </summary>
+    /// <param name="request">The request-model which contains required and optional parameters.</param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/ios/guides/token-swap-and-refresh/
+    /// </remarks>
+    /// <returns></returns>
     public Task<AuthorizationCodeTokenResponse> RequestToken(TokenSwapTokenRequest request)
     {
       return RequestToken(request, API);
     }
 
+    /// <summary>
+    /// Gets a refreshed access token using an already received refresh token using a remote server
+    /// </summary>
+    /// <param name="request"></param>
+    /// <remarks>
+    /// https://developer.spotify.com/documentation/ios/guides/token-swap-and-refresh/
+    /// </remarks>
+    /// <returns></returns>
     public Task<AuthorizationCodeRefreshResponse> RequestToken(TokenSwapRefreshRequest request)
     {
       return RequestToken(request, API);

SpotifyAPI.Web/Exceptions/APITooManyRequestsException.cs

@@ -0,0 +1,31 @@
+using System.Globalization;
+using System.Runtime.Serialization;
+using System;
+using SpotifyAPI.Web.Http;
+
+namespace SpotifyAPI.Web
+{
+  [Serializable]
+  public class APITooManyRequestsException : APIException
+  {
+    public TimeSpan RetryAfter { get; }
+
+    public APITooManyRequestsException(IResponse response) : base(response)
+    {
+      Ensure.ArgumentNotNull(response, nameof(response));
+
+      if (response.Headers.TryGetValue("Retry-After", out string retryAfter))
+      {
+        RetryAfter = TimeSpan.FromSeconds(int.Parse(retryAfter, CultureInfo.InvariantCulture));
+      }
+    }
+
+    public APITooManyRequestsException() { }
+
+    public APITooManyRequestsException(string message) : base(message) { }
+
+    public APITooManyRequestsException(string message, Exception innerException) : base(message, innerException) { }
+
+    protected APITooManyRequestsException(SerializationInfo info, StreamingContext context) : base(info, context) { }
+  }
+}

SpotifyAPI.Web/Http/APIConnector.cs

@@ -283,6 +283,8 @@ namespace SpotifyAPI.Web.Http
       {
         case HttpStatusCode.Unauthorized:
           throw new APIUnauthorizedException(response);
+        case HttpStatusCode.TooManyRequests:
+          throw new APITooManyRequestsException(response);
         default:
           throw new APIException(response);
       }

SpotifyAPI.Web/Http/Authenticators/AuthorizationCodeAuthenticator.cs

@@ -9,8 +9,6 @@ namespace SpotifyAPI.Web.Http
   /// </summary>
   public class AuthorizationCodeAuthenticator : IAuthenticator
   {
-    public event EventHandler<AuthorizationCodeTokenResponse>? TokenRefreshed;
-
     /// <summary>
     ///   Initiate a new instance. The token will be refreshed once it expires.
     ///   The initialToken will be updated with the new values on refresh!
@@ -26,6 +24,12 @@ namespace SpotifyAPI.Web.Http
       ClientSecret = clientSecret;
     }
 
+    /// <summary>
+    /// This event is called once a new refreshed token was aquired
+    /// </summary>
+    public event EventHandler<AuthorizationCodeTokenResponse>? TokenRefreshed;
+
+
     /// <summary>
     ///   The ClientID, defined in a spotify application in your Spotify Developer Dashboard
     /// </summary>