/*! @file OIDAuthState.h
    @brief AppAuth iOS SDK
    @copyright
        Copyright 2015 Google Inc. All Rights Reserved.
    @copydetails
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
        See the License for the specific language governing permissions and
        limitations under the License.
 */
#import <Foundation/Foundation.h>

@class OIDAuthorizationRequest;
@class OIDAuthorizationResponse;
@class OIDAuthState;
@class OIDRegistrationResponse;
@class OIDTokenResponse;
@class OIDTokenRequest;
@protocol OIDAuthStateChangeDelegate;
@protocol OIDAuthStateErrorDelegate;
@protocol OIDExternalUserAgent;
@protocol OIDExternalUserAgentSession;

NS_ASSUME_NONNULL_BEGIN

/*! @brief Represents a block used to call an action with a fresh access token.
    @param accessToken A valid access token if available.
    @param idToken A valid ID token if available.
    @param error The error if an error occurred.
 */
typedef void (^OIDAuthStateAction)(NSString *_Nullable accessToken,
                                   NSString *_Nullable idToken,
                                   NSError *_Nullable error);

/*! @brief The method called when the @c
        OIDAuthState.authStateByPresentingAuthorizationRequest:presentingViewController:callback:
        method has completed or failed.
    @param authState The auth state, if the authorization request succeeded.
    @param error The error if an error occurred.
 */
typedef void (^OIDAuthStateAuthorizationCallback)(OIDAuthState *_Nullable authState,
                                                  NSError *_Nullable error);

/*! @brief A convenience class that retains the auth state between @c OIDAuthorizationResponse%s
        and @c OIDTokenResponse%s.
 */
@interface OIDAuthState : NSObject <NSSecureCoding>

/*! @brief The most recent refresh token received from the server.
    @discussion Rather than using this property directly, you should call
        @c OIDAuthState.performActionWithFreshTokens:.
    @remarks refresh_token
    @see https://tools.ietf.org/html/rfc6749#section-5.1
 */
@property(nonatomic, readonly, nullable) NSString *refreshToken;

/*! @brief The scope of the current authorization grant.
    @discussion This represents the latest scope returned by the server and may be a subset of the
        scope that was initially granted.
    @remarks scope
 */
@property(nonatomic, readonly, nullable) NSString *scope;

/*! @brief The most recent authorization response used to update the authorization state. For the
        implicit flow, this will contain the latest access token.
 */
@property(nonatomic, readonly) OIDAuthorizationResponse *lastAuthorizationResponse;

/*! @brief The most recent token response used to update this authorization state. This will
        contain the latest access token.
 */
@property(nonatomic, readonly, nullable) OIDTokenResponse *lastTokenResponse;

/*! @brief The most recent registration response used to update this authorization state. This will
        contain the latest client credentials.
 */
@property(nonatomic, readonly, nullable) OIDRegistrationResponse *lastRegistrationResponse;

/*! @brief The authorization error that invalidated this @c OIDAuthState.
    @discussion The authorization error encountered by @c OIDAuthState or set by the user via
        @c OIDAuthState.updateWithAuthorizationError: that invalidated this @c OIDAuthState.
        Authorization errors from @c OIDAuthState will always have a domain of
        @c ::OIDOAuthAuthorizationErrorDomain or @c ::OIDOAuthTokenErrorDomain. Note: that after
        unarchiving the @c OIDAuthState object, the \NSError_userInfo property of this error will
        be nil.
 */
@property(nonatomic, readonly, nullable) NSError *authorizationError;

/*! @brief Returns YES if the authorization state is not known to be invalid.
    @discussion Returns YES if no OAuth errors have been received, and the last call resulted in a
        successful access token or id token. This does not mean that the access is fresh - just
        that it was valid the last time it was used. Note that network and other transient errors
        do not invalidate the authorized state.  If NO, you should authenticate the user again,
        using a fresh authorization request. Invalid @c OIDAuthState objects may still be useful in
        that case, to hint at the previously authorized user and streamline the re-authentication
        experience.
 */
@property(nonatomic, readonly) BOOL isAuthorized;

/*! @brief The @c OIDAuthStateChangeDelegate delegate.
    @discussion Use the delegate to observe state changes (and update storage) as well as error
        states.
 */
@property(nonatomic, weak, nullable) id<OIDAuthStateChangeDelegate> stateChangeDelegate;

/*! @brief The @c OIDAuthStateErrorDelegate delegate.
    @discussion Use the delegate to observe state changes (and update storage) as well as error
        states.
 */
@property(nonatomic, weak, nullable) id<OIDAuthStateErrorDelegate> errorDelegate;

/*! @brief Convenience method to create a @c OIDAuthState by presenting an authorization request
        and performing the authorization code exchange in the case of code flow requests. For
        the hybrid flow, the caller should validate the id_token and c_hash, then perform the token
        request (@c OIDAuthorizationService.performTokenRequest:callback:)
        and update the OIDAuthState with the results (@c
        OIDAuthState.updateWithTokenResponse:error:).
    @param authorizationRequest The authorization request to present.
    @param externalUserAgent A external user agent that can present an external user-agent request.
    @param callback The method called when the request has completed or failed.
    @return A @c OIDExternalUserAgentSession instance which will terminate when it
        receives a @c OIDExternalUserAgentSession.cancel message, or after processing a
        @c OIDExternalUserAgentSession.resumeExternalUserAgentFlowWithURL: message.
 */
+ (id<OIDExternalUserAgentSession>)
    authStateByPresentingAuthorizationRequest:(OIDAuthorizationRequest *)authorizationRequest
                            externalUserAgent:(id<OIDExternalUserAgent>)externalUserAgent
                                     callback:(OIDAuthStateAuthorizationCallback)callback;

/*! @internal
    @brief Unavailable. Please use @c initWithAuthorizationResponse:.
 */
- (instancetype)init NS_UNAVAILABLE;

/*! @brief Creates an auth state from an authorization response.
    @param authorizationResponse The authorization response.
 */
- (instancetype)initWithAuthorizationResponse:(OIDAuthorizationResponse *)authorizationResponse;

/*! @brief Creates an auth state from an authorization and token response.
    @param authorizationResponse The authorization response.
    @param tokenResponse The token response.
 */
- (instancetype)initWithAuthorizationResponse:(OIDAuthorizationResponse *)authorizationResponse
                                tokenResponse:(nullable OIDTokenResponse *)tokenResponse;

/*! @brief Creates an auth state from an registration response.
    @param registrationResponse The registration response.
 */
- (instancetype)initWithRegistrationResponse:(OIDRegistrationResponse *)registrationResponse;

/*! @brief Creates an auth state from an authorization, token and registration response.
    @param authorizationResponse The authorization response.
    @param tokenResponse The token response.
    @param registrationResponse The registration response.
 */
- (instancetype)initWithAuthorizationResponse:
    (nullable OIDAuthorizationResponse *)authorizationResponse
           tokenResponse:(nullable OIDTokenResponse *)tokenResponse
    registrationResponse:(nullable OIDRegistrationResponse *)registrationResponse
    NS_DESIGNATED_INITIALIZER;

/*! @brief Updates the authorization state based on a new authorization response.
    @param authorizationResponse The new authorization response to update the state with.
    @param error Any error encountered when performing the authorization request. Errors in the
        domain @c ::OIDOAuthAuthorizationErrorDomain are reflected in the auth state, other errors
        are assumed to be transient, and ignored.
    @discussion Typically called with the response from an incremental authorization request,
        or if using the implicit flow. Will clear the @c #lastTokenResponse property.
 */
- (void)updateWithAuthorizationResponse:(nullable OIDAuthorizationResponse *)authorizationResponse
                                  error:(nullable NSError *)error;

/*! @brief Updates the authorization state based on a new token response.
    @param tokenResponse The new token response to update the state from.
    @param error Any error encountered when performing the authorization request. Errors in the
        domain @c ::OIDOAuthTokenErrorDomain are reflected in the auth state, other errors
        are assumed to be transient, and ignored.
    @discussion Typically called with the response from an authorization code exchange, or a token
        refresh.
 */
- (void)updateWithTokenResponse:(nullable OIDTokenResponse *)tokenResponse
                          error:(nullable NSError *)error;

/*! @brief Updates the authorization state based on a new registration response.
    @param registrationResponse The new registration response to update the state with.
    @discussion Typically called with the response from a successful client registration
        request. Will reset the auth state.
 */
- (void)updateWithRegistrationResponse:(nullable OIDRegistrationResponse *)registrationResponse;

/*! @brief Updates the authorization state based on an authorization error.
    @param authorizationError The authorization error.
    @discussion Call this method if you receive an authorization error during an API call to
        invalidate the authentication state of this @c OIDAuthState. Don't call with errors
        unrelated to authorization, such as transient network errors.
        The OIDAuthStateErrorDelegate.authState:didEncounterAuthorizationError: method of
        @c #errorDelegate will be called with the error.
        You may optionally use the convenience method
        OIDErrorUtilities.resourceServerAuthorizationErrorWithCode:errorResponse:underlyingError:
        to create \NSError objects for use here.
        The latest error received is stored in @c #authorizationError. Note: that after unarchiving
        this object, the \NSError_userInfo property of this error will be nil.
 */
- (void)updateWithAuthorizationError:(NSError *)authorizationError;

/*! @brief Calls the block with a valid access token (refreshing it first, if needed), or if a
        refresh was needed and failed, with the error that caused it to fail.
    @param action The block to execute with a fresh token. This block will be executed on the main
        thread.
 */
- (void)performActionWithFreshTokens:(OIDAuthStateAction)action;

/*! @brief Calls the block with a valid access token (refreshing it first, if needed), or if a
        refresh was needed and failed, with the error that caused it to fail.
    @param action The block to execute with a fresh token. This block will be executed on the main
        thread.
    @param additionalParameters Additional parameters for the token request if token is
        refreshed.
 */
- (void)performActionWithFreshTokens:(OIDAuthStateAction)action
         additionalRefreshParameters:
    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters;

/*! @brief Calls the block with a valid access token (refreshing it first, if needed), or if a
        refresh was needed and failed, with the error that caused it to fail.
    @param action The block to execute with a fresh token. This block will be executed on the main
        thread.
    @param additionalParameters Additional parameters for the token request if token is
        refreshed.
    @param dispatchQueue The dispatchQueue on which to dispatch the action block.
 */
- (void)performActionWithFreshTokens:(OIDAuthStateAction)action
         additionalRefreshParameters:
    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters
                       dispatchQueue:(dispatch_queue_t)dispatchQueue;

/*! @brief Forces a token refresh the next time @c OIDAuthState.performActionWithFreshTokens: is
        called, even if the current tokens are considered valid.
 */
- (void)setNeedsTokenRefresh;

/*! @brief Creates a token request suitable for refreshing an access token.
    @return A @c OIDTokenRequest suitable for using a refresh token to obtain a new access token.
    @discussion After performing the refresh, call @c OIDAuthState.updateWithTokenResponse:error:
        to update the authorization state based on the response. Rather than doing the token refresh
        yourself, you should use @c OIDAuthState.performActionWithFreshTokens:.
    @see https://tools.ietf.org/html/rfc6749#section-1.5
 */
- (nullable OIDTokenRequest *)tokenRefreshRequest;

/*! @brief Creates a token request suitable for refreshing an access token.
    @param additionalParameters Additional parameters for the token request.
    @return A @c OIDTokenRequest suitable for using a refresh token to obtain a new access token.
    @discussion After performing the refresh, call @c OIDAuthState.updateWithTokenResponse:error:
        to update the authorization state based on the response. Rather than doing the token refresh
        yourself, you should use @c OIDAuthState.performActionWithFreshTokens:.
    @see https://tools.ietf.org/html/rfc6749#section-1.5
 */
- (nullable OIDTokenRequest *)tokenRefreshRequestWithAdditionalParameters:
    (nullable NSDictionary<NSString *, NSString *> *)additionalParameters;

@end

NS_ASSUME_NONNULL_END