Added authorization backend protocols to "Authorization Backends" sec…

…tion of jazzy configuration file.

Regenerated docs with jazzy.

Corrected more misspellings and formatting issues in documentation.

Fixed incorrect links in the authorization manager and authorization backend documentation comments.

Added more documentation for the authorization backends.

Fixed some issues with `SpotifyGeneralError.description`.

.jazzy.yaml

@@ -31,10 +31,13 @@ custom_categories:
 
   - name: Authorization Backends
     children:
+    - AuthorizationCodeFlowBackend
     - AuthorizationCodeFlowClientBackend
     - AuthorizationCodeFlowProxyBackend
+    - AuthorizationCodeFlowPKCEBackend
     - AuthorizationCodeFlowPKCEClientBackend
     - AuthorizationCodeFlowPKCEProxyBackend
+    - ClientCredentialsFlowBackend
     - ClientCredentialsFlowClientBackend
     - ClientCredentialsFlowProxyBackend
 

Sources/SpotifyAPITestUtilities/MiscellaneousUtilities.swift

@@ -198,7 +198,7 @@ public extension URLSession {
         var request = request
         request.cachePolicy = .reloadIgnoringLocalAndRemoteCacheData
 
-        return  URLSession.shared.dataTaskPublisher(for: request)
+        return URLSession.shared.dataTaskPublisher(for: request)
             .mapError { $0 as Error }
             .map { data, response -> (data: Data, response: HTTPURLResponse) in
                 guard let httpURLResponse = response as? HTTPURLResponse else {

Sources/SpotifyWebAPI/API/SpotifyAPI+Tracks.swift

@@ -227,7 +227,7 @@ public extension SpotifyAPI {
              empty array will immediately cause an empty array of results to be
              returned without a network request being made.
      - Returns: Results are returned in the order requested. If the audio
-           features for a track  is not found, `nil` is returned in the
+           features for a track is not found, `nil` is returned in the
            appropriate position. Duplicate ids in the request will result in
            duplicate results in the response.
 

Sources/SpotifyWebAPI/API/SpotifyAPI.swift

@@ -44,7 +44,7 @@ public class SpotifyAPI<AuthorizationManager: SpotifyAuthorizationManager>: Coda
 
      It is this property that you should encode to data using a `JSONEncoder` in
      order to save it to persistent storage. This prevents the user from having
-     to login again everytime the app is quit and relaunched. See this
+     to login again every time the app is quit and relaunched. See this
      [article][1] for more information.
 
      Assigning a new authorization manager to this property causes
@@ -69,12 +69,12 @@ public class SpotifyAPI<AuthorizationManager: SpotifyAuthorizationManager>: Coda
     }
 
     /**
-     A function that gets called everytime this class—and only this class—needs
+     A function that gets called every time this class—and only this class—needs
      to make a network request.
 
      Use this function if you need to use a custom networking client. The `url`
      and `httpMethod` properties of the `URLRequest` parameter are guaranteed to
-     be non-`nil`. No  guarantees are made about which thread this function will
+     be non-`nil`. No guarantees are made about which thread this function will
      be called on. By default, `URLSession` will be used for the network
      requests.
 
@@ -178,13 +178,12 @@ public class SpotifyAPI<AuthorizationManager: SpotifyAuthorizationManager>: Coda
                information. It is this property that you should encode to data
                using a `JSONEncoder` in order to save it to persistent storage.
                See this [article][2] for more information.
-         - networkAdaptor: A function that gets called everytime this class—and
+         - networkAdaptor: A function that gets called every time this class—and
                only this class—needs to make a network request. The
-               `authorizationManager` will **NOT** use this function. Instead,
-               you must configure a network adaptor for it as well. Use this
+               `authorizationManager` will **NOT** use this function. Use this
                function if you need to use a custom networking client. The `url`
                and `httpMethod` properties of the `URLRequest` parameter are
-               guaranteed to be non-`nil`. No  guarantees are made about which
+               guaranteed to be non-`nil`. No guarantees are made about which
                thread this function will be called on. The default is `nil`, in
                which case `URLSession` will be used for the network requests.
 

Sources/SpotifyWebAPI/Authorization/AuthorizationCodeFlowManager.swift

@@ -67,7 +67,7 @@ import FoundationNetworking
  information to persistent storage. See this [article][3] for more information.
 
  [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
- [2]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
+ [2]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow-with-proof-key-for-code-exchange-pkce
  [3]: https://github.com/Peter-Schorn/SpotifyAPI/wiki/Saving-authorization-information-to-persistent-storage.
  */
 public class AuthorizationCodeFlowBackendManager<Backend: AuthorizationCodeFlowBackend>:
@@ -263,8 +263,8 @@ public extension AuthorizationCodeFlowBackendManager {
      - Parameters:
        - redirectURI: The location that Spotify will redirect to after the user
              authorizes or denies authorization for your app. Usually, this
-             should be a custom URL scheme that redirects to a location in your
-             app. This URI needs to have been entered in the Redirect URI
+             should contain a custom URL scheme that redirects to a location in
+             your app. This URI needs to have been entered in the Redirect URI
              whitelist that you specified when you [registered your
              application][2].
        - showDialog: Whether or not to force the user to approve the app again
@@ -611,7 +611,7 @@ public extension AuthorizationCodeFlowBackendManager {
  information to persistent storage. See this [article][3] for more information.
 
  [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
- [2]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
+ [2]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow-with-proof-key-for-code-exchange-pkce
  [3]: https://github.com/Peter-Schorn/SpotifyAPI/wiki/Saving-authorization-information-to-persistent-storage.
  */
 public final class AuthorizationCodeFlowManager:

Sources/SpotifyWebAPI/Authorization/AuthorizationCodeFlowManagerBase.swift

@@ -333,7 +333,7 @@ public extension AuthorizationCodeFlowManagerBase {
      */
     func accessTokenIsExpired(tolerance: Double = 120) -> Bool {
         return self.updateAuthInfoQueue.sync {
-            return  accessTokenIsExpiredNOTThreadSafe(tolerance: tolerance)
+            return accessTokenIsExpiredNOTThreadSafe(tolerance: tolerance)
         }
     }
 
@@ -382,7 +382,7 @@ extension AuthorizationCodeFlowManagerBase {
     /// This method should **ALWAYS** be called within
     /// `updateAuthInfoDispatchQueue`, or the thread-safety guarantees
     /// of this class will be violated.
-    func  accessTokenIsExpiredNOTThreadSafe(tolerance: Double = 120) -> Bool {
+    func accessTokenIsExpiredNOTThreadSafe(tolerance: Double = 120) -> Bool {
         if (self._accessToken == nil) != (self._expirationDate == nil) {
             let expirationDateString = self._expirationDate?
                 .description(with: .current) ?? "nil"

Sources/SpotifyWebAPI/Authorization/AuthorizationCodeFlowPKCEManager.swift

@@ -19,7 +19,7 @@ import Logging
 
  The authorization code flow with PKCE is the best option for mobile and desktop
  applications where it is unsafe to store your client secret. It provides an
- additional layer of security compared to the [authorization code flow][2]. For
+ additional layer of security compared to the [Authorization Code Flow][2]. For
  further information about this flow, see [IETF RFC-7636][3].
 
  # Backend
@@ -291,8 +291,8 @@ public extension AuthorizationCodeFlowPKCEBackendManager {
      - Parameters:
        - redirectURI: The location that Spotify will redirect to after the user
              authorizes or denies authorization for your app. Usually, this
-             should be a custom URL scheme that redirects to a location in your
-             app. This URI needs to have been entered in the Redirect URI
+             should contain a custom URL scheme that redirects to a location in
+             your app. This URI needs to have been entered in the Redirect URI
              whitelist that you specified when you [registered your
              application][4].
        - codeChallenge: The code challenge. See above.
@@ -624,14 +624,14 @@ public extension AuthorizationCodeFlowPKCEBackendManager {
 
  The authorization code flow with PKCE is the best option for mobile and desktop
  applications where it is unsafe to store your client secret. It provides an
- additional layer of security compared to the [authorization code flow][2]. For
+ additional layer of security compared to the [Authorization Code Flow][2]. For
  further information about this flow, see [IETF RFC-7636][3].
 
  This class stores the client id locally. Consider using
  `AuthorizationCodeFlowPKCEBackendManager<AuthorizationCodeFlowPKCEProxyBackend>`,
  which allows you to setup a custom backend server that can store these
  sensitive credentials and which communicates with Spotify on your behalf in
- order to retrieve the  authorization information.
+ order to retrieve the authorization information.
 
  # Authorization
 
@@ -709,8 +709,8 @@ public final class AuthorizationCodeFlowPKCEManager:
     }
 
     /**
-     Creates an authorization manager for the
-     [Authorization Code Flow with Proof Key for Code Exchange][1].
+     Creates an authorization manager for the [Authorization Code Flow with
+     Proof Key for Code Exchange][1].
 
      **In general, only use this initializer if you have retrieved the**
      **authorization information from an external source.** Otherwise, use

Sources/SpotifyWebAPI/Authorization/Backends/AuthorizationCodeFlowClientBackend.swift

@@ -17,7 +17,10 @@ import OpenCombineFoundation
  authorization information and refresh the access token using the [Authorization
  Code Flow][1].
 
- Compare with `AuthorizationCodeFlowProxyBackend`.
+ If you are communicating with a custom backend server, then use
+ `AuthorizationCodeFlowProxyBackend` instead, which does not send the `clientId`
+ and `clientSecret` in network requests because these values should be securely
+ stored on your backend server.
 
  Usually you should not need to create instances of this type directly.
  `AuthorizationCodeFlowManager` uses this type internally by inheriting from

Sources/SpotifyWebAPI/Authorization/Backends/AuthorizationCodeFlowPKCEClientBackend.swift

@@ -17,15 +17,18 @@ import OpenCombineFoundation
  authorization information and refresh the access token using the [Authorization
  Code Flow with Proof Key for Code Exchange][1].
 
- Compare with `AuthorizationCodeFlowPKCEProxyBackend`.
+ If you are communicating with a custom backend server, then use
+ `AuthorizationCodeFlowPKCEProxyBackend` instead, which does not send the
+ `clientId` in network requests because this value should be securely stored on
+ your backend server.
 
  Usually you should not need to create instances of this type directly.
  `AuthorizationCodeFlowPKCEManager` uses this type internally by inheriting from
  `AuthorizationCodeFlowPKCEBackendManager<AuthorizationCodeFlowPKCEClientBackend>`.
 
  [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow-with-proof-key-for-code-exchange-pkce
  */
-public struct  AuthorizationCodeFlowPKCEClientBackend: AuthorizationCodeFlowPKCEBackend {
+public struct AuthorizationCodeFlowPKCEClientBackend: AuthorizationCodeFlowPKCEBackend {
 
     /// The logger for this struct.
     public static var logger = Logger(

Sources/SpotifyWebAPI/Authorization/Backends/AuthorizationCodeFlowPKCEProxyBackend.swift

@@ -18,10 +18,22 @@ import OpenCombineFoundation
  authorization information and refresh the access token using the [Authorization
  Code Flow with Proof Key for Code Exchange][1].
 
- Compare with `AuthorizationCodeFlowPKCEClientBackend`.
+ This server must have the following endpoints:
 
- This type requires a custom backend server that can store your client secret
- and redirect URI.
+ * `tokensURL`: Accepts a post request with the authorization code and coder
+   verifier in the body in x-www-form-urlencoded format and must return the
+   authorization information. See
+   `self.requestAccessAndRefreshTokens(code:codeVerifier:redirectURIWithQuery:)`
+   for more information.
+
+ * `tokenRefreshURL`: Accepts a post request with the refresh token in the body
+   in x-www-form-urlencoded format and which must return the authorization
+   information. See `self.refreshTokens(refreshToken:)` for more information.
+
+ In contrast with `AuthorizationCodeFlowPKCEClientBackend`, which can be used if
+ you are communicating directly with Spotify, this type does not send the
+ `clientSecret` in network requests because this value should be securely
+ stored on your backend server.
 
  [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow-with-proof-key-for-code-exchange-pkce
  */
@@ -44,8 +56,13 @@ public struct AuthorizationCodeFlowPKCEProxyBackend: AuthorizationCodeFlowPKCEBa
      authorization code and coder verifier in the body in x-www-form-urlencoded
      format and which must return the authorization information.
 
+     The [/authorization-code-flow-pkce/retrieve-tokens][1] endpoint of
+     SpotifyAPIServer can be used for this URL.
+
      See `self.requestAccessAndRefreshTokens(code:codeVerifier:redirectURIWithQuery:)`
      for more information.
+
+     [1]: https://github.com/Peter-Schorn/SpotifyAPIServer#post-authorization-code-flow-pkceretrieve-tokens
      */
     public let tokensURL: URL
 
@@ -54,7 +71,12 @@ public struct AuthorizationCodeFlowPKCEProxyBackend: AuthorizationCodeFlowPKCEBa
      refresh token in the body in x-www-form-urlencoded format and which must
      return the authorization information.
 
+     The [/authorization-code-flow-pkce/refresh-tokens][1] endpoint of
+     SpotifyAPIServer can be used for this URL.
+
      See `self.refreshTokens(refreshToken:)` for more information.
+
+     [1]: https://github.com/Peter-Schorn/SpotifyAPIServer#post-authorization-code-flow-pkcerefresh-tokens
      */
     public let tokenRefreshURL: URL
 
@@ -97,23 +119,28 @@ public struct AuthorizationCodeFlowPKCEProxyBackend: AuthorizationCodeFlowPKCEBa
        - tokensURL: The URL to your custom backend server that accepts a post
              request with the authorization code and coder verifier in the body
              in "x-www-form-urlencoded" format and which must return the
-             authorization information. See
+             authorization information. The
+             [/authorization-code-flow-pkce/retrieve-tokens][3] endpoint of
+             SpotifyAPIServer can be used for this URL. See
              `self.requestAccessAndRefreshTokens(code:codeVerifier:redirectURIWithQuery:)`
              for more information.
        - tokenRefreshURL: The URL to your custom backend server that accepts a
              post request with the refresh token in the body in
              "x-www-form-urlencoded" format and which must return the
-             authorization information. See
-             `self.refreshTokens(refreshToken:)` for more
-             information.
+             authorization information. The
+             [/authorization-code-flow-pkce/refresh-tokens][4] endpoint of
+             SpotifyAPIServer can be used for this URL. See
+             `self.refreshTokens(refreshToken:)` for more information.
        - decodeServerError: A hook for decoding an error produced by your
              backend server into an error type, which will then be thrown to
              downstream subscribers. Do not use this function to decode the
              documented error objects produced by Spotify, such as
              `SpotifyAuthenticationError`. This will be done elsewhere.
 
-     [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow
+     [1]: https://developer.spotify.com/documentation/general/guides/authorization-guide/#authorization-code-flow-with-proof-key-for-code-exchange-pkce
      [2]: https://developer.spotify.com/documentation/general/guides/app-settings/#register-your-app
+     [3]: https://github.com/Peter-Schorn/SpotifyAPIServer#post-authorization-code-flow-pkceretrieve-tokens
+     [4]: https://github.com/Peter-Schorn/SpotifyAPIServer#post-authorization-code-flow-pkcerefresh-tokens
      */
     public init(
         clientId: String,