public class CloverPaymentSDK {

    /// Initialize the Clover Payment SDK
    /// - Throws: A `CloverGenericError` in the event of an issue during setup
    /// - Parameters:
    ///   - configuration: Provide the necessary `Configuration` parameters used to communicate with Clover.
    public func setup(configuration: Configuration) async throws

    /// Provides configuration parameters to the SDK, specifying how to communicate with Clover's servers
    public struct Configuration {

        /// The server environment that we will send all server calls to.
        public let environment: CloverEnvironment.EnvironmentType

        /// App ID registered on your Clover Developer Portal, used by the OAuth Flow to match permissions to your app when your merchant logs in.
        public let appID: String

        /// App Secret obtained from your Clover Developer Portal. This is the secret associated with your App ID.
        public let appSecret: String

        /// API Key for server access. Contact your Developer Relations representative for a valid Key and Secret.
        public let apiKey: String

        /// API Secret for server access. Contact your Developer Relations representative for a valid Key and Secret.
        public let apiSecret: String

        /// Specifier for how the SDK should handle OAuth within your application. 
        /// Provide a FullOAuth object to enable the SDK to provide login capabilities automatically. 
        /// Provide a PartialOAuth object to enable the SDK to only maintain the OAuthToken that you have acquired outside of the SDK.
        public var oauthFlowType: OAuthFlowType
    }

    /// Specifies that the SDK should provide full OAuth login capabilities for your application. 
    /// If specified, when needed the SDK will kick out to the default browser for user authentication, and return via the redirectURI.
    public struct FullOAuth: OAuthFlowType {

        /// The redirectURI to provide to the OAuth server. This URI will be called containing the code or token after the user logs in.
        /// - Precondition: The redirectURI must be configured in your app using either Associated Domains or Custom URL Scheme.
        /// - Precondition: The redirectURI must be entered into your associated Clover App on Developer Home.
        public var redirectURI: String
    }

    /// Specifies that the SDK should provide partial OAuth login capabilities for your application.
    /// If specified, the SDK will not attempt to authenticate the user, and instead expects that the host app will provide the authentication mechanism. The SDK will provide refresh capabilities.
    /// - Remark: `codeResponse` is optional, and should only be provided if you received a new code response. The eventual token will be stored securely by the SDK between instances.
    public struct PartialOAuth: OAuthFlowType {

        /// The response you received from the OAuth flow implemented in your app.
        /// - Remark: This value is optional, and should only be provided if you received a new code response. The eventual token will be stored securely by the SDK between instances.
        public var codeResponse: OAuthCodeResponse?
    }

    /// Specifies that the SDK should provide no OAuth login capabilities for your application.
    /// If specified, the SDK will rely on the passed in token, and will not attempt any OAuth or token refresh operations.
    public struct NoOAuth: OAuthFlowType {

        /// The token used to communicate with Clover servers, obtained via the OAuth flow in your application.
        public var token: String
    }

    /// True if we have valid OAuth credentials, signifying the User is logged in.
    public var isLoggedIn: Bool

    /// Deletes the OAuth credentials and triggers an onTokenChangeCallback.
    public func logout()

    /// The onTokenChangeCallbacks will be executed whenever a token changes (new token, refreshed token, deleted token, invalidated token).
    /// - Parameter callback: The callback to execute when the token changes.
    /// - Returns: A unique identifier to be used for removing a callback when no longer needed.
    public func addOnTokenChangeCallback(_ callback: @escaping () -> ()) -> String

    /// Removes an onTokenChangeCallback from the call list.
    /// - Parameter identifier: The unique identifier returned when adding the callback to the call list.
    /// - Returns: True if the passed in identifier was found to be associated with a callback in the call list, and therefore the callback was removed from the call list.
    public func removeOnTokenChangeCallback(identifier: String) -> Bool

    /// Updates the token to use when utilizing the NoOAuth flow. Note, this will trigger a re-download of merchant information, as the token must be verified to belong to the merchant in use prior to being used for payments.
    public func updateToken(_ token: String) async throws
}