//
//  PFUser.h
//
//  Copyright 2011-present Parse Inc. All rights reserved.
//

#import <Foundation/Foundation.h>

#if TARGET_OS_IPHONE
#import <Parse/PFConstants.h>
#import <Parse/PFObject.h>
#import <Parse/PFSubclassing.h>
#else
#import <ParseOSX/PFConstants.h>
#import <ParseOSX/PFObject.h>
#import <ParseOSX/PFSubclassing.h>
#endif

PF_ASSUME_NONNULL_BEGIN

typedef void(^PFUserSessionUpgradeResultBlock)(NSError *PF_NULLABLE_S error);
typedef void(^PFUserLogoutResultBlock)(NSError *PF_NULLABLE_S error);


@class PFQuery;

/*!
 The `PFUser` class is a local representation of a user persisted to the Parse Data.
 This class is a subclass of a <PFObject>, and retains the same functionality of a <PFObject>,
 but also extends it with various user specific methods, like authentication, signing up, and validation uniqueness.

 Many APIs responsible for linking a `PFUser` with Facebook or Twitter have been deprecated in favor of dedicated
 utilities for each social network. See <PFFacebookUtils>, <PFTwitterUtils> and <PFAnonymousUtils> for more information.
 */

@interface PFUser : PFObject<PFSubclassing>

///--------------------------------------
/// @name Accessing the Current User
///--------------------------------------

/*!
 @abstract Gets the currently logged in user from disk and returns an instance of it.

 @returns Returns a `PFUser` that is the currently logged in user. If there is none, returns `nil`.
 */
+ (PF_NULLABLE instancetype)currentUser;

/*!
 @abstract The session token for the `PFUser`.

 @discussion This is set by the server upon successful authentication.
 */
@property (PF_NULLABLE_PROPERTY nonatomic, copy, readonly) NSString *sessionToken;

/*!
 @abstract Whether the `PFUser` was just created from a request.

 @discussion This is only set after a Facebook or Twitter login.
 */
@property (assign, readonly) BOOL isNew;

/*!
 @abstract Whether the user is an authenticated object for the device.

 @discussion An authenticated `PFUser` is one that is obtained via a <signUp> or <logIn> method.
 An authenticated object is required in order to save (with altered values) or delete it.

 @returns Returns whether the user is authenticated.
 */
- (BOOL)isAuthenticated;

///--------------------------------------
/// @name Creating a New User
///--------------------------------------

/*!
 @abstract Creates a new `PFUser` object.

 @returns Returns a new `PFUser` object.
 */
+ (PFUser *)user;

/*!
 @abstract Enables automatic creation of anonymous users.

 @discussion After calling this method, <currentUser> will always have a value.
 The user will only be created on the server once the user has been saved,
 or once an object with a relation to that user or an ACL that refers to the user has been saved.

 @warning <[PFObject saveEventually]> will not work on if an item being saved has a relation
 to an automatic user that has never been saved.
 */
+ (void)enableAutomaticUser;

/*!
 @abstract The username for the `PFUser`.
 */
@property (PF_NULLABLE_PROPERTY nonatomic, strong) NSString *username;

/**!
 @abstract The password for the `PFUser`.

 @discussion This will not be filled in from the server with the password.
 It is only meant to be set.
 */
@property (PF_NULLABLE_PROPERTY nonatomic, strong) NSString *password;

/*!
 @abstract The email for the `PFUser`.
 */
@property (PF_NULLABLE_PROPERTY nonatomic, strong) NSString *email;

/*!
 @abstract Signs up the user *synchronously*.

 @discussion This will also enforce that the username isn't already taken.

 @warning Make sure that password and username are set before calling this method.

 @returns Returns `YES` if the sign up was successful, otherwise `NO`.
 */
- (BOOL)signUp;

/*!
 @abstract Signs up the user *synchronously*.

 @discussion This will also enforce that the username isn't already taken.

 @warning Make sure that password and username are set before calling this method.

 @param error Error object to set on error.

 @returns Returns whether the sign up was successful.
 */
- (BOOL)signUp:(NSError **)error;

/*!
 @abstract Signs up the user *asynchronously*.

 @discussion This will also enforce that the username isn't already taken.

 @warning Make sure that password and username are set before calling this method.

 @returns The task, that encapsulates the work being done.
 */
- (BFTask *)signUpInBackground;

/*!
 @abstract Signs up the user *asynchronously*.

 @discussion This will also enforce that the username isn't already taken.

 @warning Make sure that password and username are set before calling this method.

 @param block The block to execute.
 It should have the following argument signature: `^(BOOL succeeded, NSError *error)`.
 */
- (void)signUpInBackgroundWithBlock:(PF_NULLABLE PFBooleanResultBlock)block;

/*
 @abstract Signs up the user *asynchronously*.

 @discussion This will also enforce that the username isn't already taken.

 @warning Make sure that password and username are set before calling this method.

 @param target Target object for the selector.
 @param selector The selector that will be called when the asynchrounous request is complete.
 It should have the following signature: `(void)callbackWithResult:(NSNumber *)result error:(NSError *)error`.
 `error` will be `nil` on success and set if there was an error.
 `[result boolValue]` will tell you whether the call succeeded or not.
 */
- (void)signUpInBackgroundWithTarget:(PF_NULLABLE_S id)target selector:(PF_NULLABLE_S SEL)selector;

///--------------------------------------
/// @name Logging In
///--------------------------------------

/*!
 @abstract Makes a *synchronous* request to login a user with specified credentials.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param username The username of the user.
 @param password The password of the user.

 @returns Returns an instance of the `PFUser` on success.
 If login failed for either wrong password or wrong username, returns `nil`.
 */
+ (PF_NULLABLE instancetype)logInWithUsername:(NSString *)username
                                     password:(NSString *)password;

/*!
 @abstract Makes a *synchronous* request to login a user with specified credentials.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param username The username of the user.
 @param password The password of the user.
 @param error The error object to set on error.

 @returns Returns an instance of the `PFUser` on success.
 If login failed for either wrong password or wrong username, returns `nil`.
 */
+ (PF_NULLABLE instancetype)logInWithUsername:(NSString *)username
                                     password:(NSString *)password
                                        error:(NSError **)error;

/*!
 @abstract Makes an *asynchronous* request to login a user with specified credentials.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param username The username of the user.
 @param password The password of the user.

 @returns The task, that encapsulates the work being done.
 */
+ (BFTask *)logInWithUsernameInBackground:(NSString *)username
                                 password:(NSString *)password;

/*
 @abstract Makes an *asynchronous* request to login a user with specified credentials.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param username The username of the user.
 @param password The password of the user.
 @param target Target object for the selector.
 @param selector The selector that will be called when the asynchrounous request is complete.
 It should have the following signature: `(void)callbackWithUser:(PFUser *)user error:(NSError *)error`.
 */
+ (void)logInWithUsernameInBackground:(NSString *)username
                             password:(NSString *)password
                               target:(PF_NULLABLE_S id)target
                             selector:(PF_NULLABLE_S SEL)selector;

/*!
 @abstract Makes an *asynchronous* request to log in a user with specified credentials.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param username The username of the user.
 @param password The password of the user.
 @param block The block to execute.
 It should have the following argument signature: `^(PFUser *user, NSError *error)`.
 */
+ (void)logInWithUsernameInBackground:(NSString *)username
                             password:(NSString *)password
                                block:(PF_NULLABLE PFUserResultBlock)block;

///--------------------------------------
/// @name Becoming a User
///--------------------------------------

/*!
 @abstract Makes a *synchronous* request to become a user with the given session token.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param sessionToken The session token for the user.

 @returns Returns an instance of the `PFUser` on success.
 If becoming a user fails due to incorrect token, it returns `nil`.
 */
+ (PF_NULLABLE instancetype)become:(NSString *)sessionToken;

/*!
 @abstract Makes a *synchronous* request to become a user with the given session token.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This will also cache the user locally so that calls to <currentUser> will use the latest logged in user.

 @param sessionToken The session token for the user.
 @param error The error object to set on error.

 @returns Returns an instance of the `PFUser` on success.
 If becoming a user fails due to incorrect token, it returns `nil`.
 */
+ (PF_NULLABLE instancetype)become:(NSString *)sessionToken error:(NSError **)error;

/*!
 @abstract Makes an *asynchronous* request to become a user with the given session token.

 @discussion Returns an instance of the successfully logged in `PFUser`.
 This also caches the user locally so that calls to <currentUser> will use the latest logged in user.

 @param sessionToken The session token for the user.

 @returns The task, that encapsulates the work being done.
 */
+ (BFTask *)becomeInBackground:(NSString *)sessionToken;

/*
 @abstract Makes an *asynchronous* request to become a user with the given session token.

 @discussion Returns an instance of the successfully logged in `PFUser`. This also caches the user locally
 so that calls to <currentUser> will use the latest logged in user.

 @param sessionToken The session token for the user.
 @param target Target object for the selector.
 @param selector The selector that will be called when the asynchrounous request is complete.
 It should have the following signature: `(void)callbackWithUser:(PFUser *)user error:(NSError *)error`.
 */
+ (void)becomeInBackground:(NSString *)sessionToken
                    target:(PF_NULLABLE_S id)target
                  selector:(PF_NULLABLE_S SEL)selector;

/*!
 @abstract Makes an *asynchronous* request to become a user with the given session token.

 @discussion Returns an instance of the successfully logged in `PFUser`. This also caches the user locally
 so that calls to <currentUser> will use the latest logged in user.

 @param sessionToken The session token for the user.
 @param block The block to execute. The block should have the following argument signature: (PFUser *user, NSError *error)
 */
+ (void)becomeInBackground:(NSString *)sessionToken block:(PF_NULLABLE PFUserResultBlock)block;

///--------------------------------------
/// @name Revocable Session
///--------------------------------------

/*!
 @abstract Enables revocable sessions and migrates the currentUser session token to use revocable session if needed.

 @discussion This method is required if you want to use <PFSession> APIs
 and you application's 'Require Revocable Session' setting is turned off on `http://parse.com` app settings.
 After returned `BFTask` completes - <PFSession> class and APIs will be available for use.

 @returns An instance of `BFTask` that is completed when
 revocable sessions are enabled and currentUser token is migrated.
 */
+ (BFTask *)enableRevocableSessionInBackground;

/*!
 @abstract Enables revocable sessions and upgrades the currentUser session token to use revocable session if needed.

 @discussion This method is required if you want to use <PFSession> APIs
 and legacy sessions are enabled in your application settings on `http://parse.com/`.
 After returned `BFTask` completes - <PFSession> class and APIs will be available for use.

 @param block Block that will be called when revocable sessions are enabled and currentUser token is migrated.
 */
+ (void)enableRevocableSessionInBackgroundWithBlock:(PF_NULLABLE PFUserSessionUpgradeResultBlock)block;

///--------------------------------------
/// @name Logging Out
///--------------------------------------

/*!
 @abstract *Synchronously* logs out the currently logged in user on disk.
 */
+ (void)logOut;

/*!
 @abstract *Asynchronously* logs out the currenlt logged in user.

 @discussion This will also remove the session from disk, log out of linked services
 and all future calls to <currentUser> will return `nil`. This is preferrable to using <logOut>,
 unless your code is already running from a background thread.

 @returns An instance of `BFTask`, that is resolved with `nil` result when logging out completes.
 */
+ (BFTask *)logOutInBackground;

/*!
 @abstract *Asynchronously* logs out the currenlt logged in user.

 @discussion This will also remove the session from disk, log out of linked services
 and all future calls to <currentUser> will return `nil`. This is preferrable to using <logOut>,
 unless your code is already running from a background thread.

 @param block A block that will be called when logging out completes or fails.
 */
+ (void)logOutInBackgroundWithBlock:(PF_NULLABLE PFUserLogoutResultBlock)block;

///--------------------------------------
/// @name Requesting a Password Reset
///--------------------------------------

/*!
 @abstract *Synchronously* Send a password reset request for a specified email.

 @discussion If a user account exists with that email, an email will be sent to that address
 with instructions on how to reset their password.

 @param email Email of the account to send a reset password request.

 @returns Returns `YES` if the reset email request is successful. `NO` - if no account was found for the email address.
 */
+ (BOOL)requestPasswordResetForEmail:(NSString *)email;

/*!
 @abstract *Synchronously* send a password reset request for a specified email and sets an error object.

 @discussion If a user account exists with that email, an email will be sent to that address
 with instructions on how to reset their password.

 @param email Email of the account to send a reset password request.
 @param error Error object to set on error.
 @returns Returns `YES` if the reset email request is successful. `NO` - if no account was found for the email address.
 */
+ (BOOL)requestPasswordResetForEmail:(NSString *)email
                               error:(NSError **)error;

/*!
 @abstract Send a password reset request asynchronously for a specified email and sets an
 error object. If a user account exists with that email, an email will be sent to
 that address with instructions on how to reset their password.
 @param email Email of the account to send a reset password request.
 @returns The task, that encapsulates the work being done.
 */
+ (BFTask *)requestPasswordResetForEmailInBackground:(NSString *)email;

/*
 @abstract Send a password reset request *asynchronously* for a specified email and sets an error object.

 @discussion If a user account exists with that email, an email will be sent to that address
 with instructions on how to reset their password.

 @param email Email of the account to send a reset password request.
 @param target Target object for the selector.
 @param selector The selector that will be called when the asynchronous request is complete.
 It should have the following signature: `(void)callbackWithResult:(NSNumber *)result error:(NSError *)error`.
 `error` will be `nil` on success and set if there was an error.
 `[result boolValue]` will tell you whether the call succeeded or not.
 */
+ (void)requestPasswordResetForEmailInBackground:(NSString *)email
                                          target:(PF_NULLABLE_S id)target
                                        selector:(PF_NULLABLE_S SEL)selector;

/*!
 @abstract Send a password reset request *asynchronously* for a specified email.

 @discussion If a user account exists with that email, an email will be sent to that address
 with instructions on how to reset their password.

 @param email Email of the account to send a reset password request.
 @param block The block to execute.
 It should have the following argument signature: `^(BOOL succeeded, NSError *error)`.
 */
+ (void)requestPasswordResetForEmailInBackground:(NSString *)email
                                           block:(PF_NULLABLE PFBooleanResultBlock)block;

@end

PF_ASSUME_NONNULL_END