//
//  TWTRAPIClient.h
//
//  Copyright (c) 2015 Twitter. All rights reserved.
//

@class TWTRUser;
@class TWTRTweet;
@class TWTRAuthConfig;
@class TWTRGuestSession;
@protocol TWTRAuthSession;
@protocol TWTRSessionStore;

NS_ASSUME_NONNULL_BEGIN

FOUNDATION_EXPORT NSString *const TWTRTweetsNotLoadedKey;

/**
 *  @name Completion Block Types
 */

/**
 *  Completion block called when the load user request succeeds or fails.
 *
 *  @param user  The Twitter User.
 *  @param error Error that will be set if the API request failed.
 */
typedef void (^TWTRLoadUserCompletion)(TWTRUser *_Nullable user, NSError *_Nullable error);

/**
 *  Completion block called when the load Tweet request succeeds or fails.
 *
 *  @param tweet The Twitter Tweet.
 *  @param error Error that will be set if the API request failed.
 */
typedef void (^TWTRLoadTweetCompletion)(TWTRTweet *_Nullable tweet, NSError *_Nullable error);

/**
 *  Completion block called when the load Tweets request succeeds or fails.
 *
 *  @param tweets Tweets that were successfully retrieved.
 *  @param error  Error that will be set if the API request failed.
 */
typedef void (^TWTRLoadTweetsCompletion)(NSArray<TWTRTweet *> *_Nullable tweets, NSError *_Nullable error);

/**
 *  Completion block called when the network request succeeds or fails.
 *
 *  @param response        Metadata associated with the response to a URL load request.
 *  @param data            Content data of the response.
 *  @param connectionError Error object describing the network error that occurred.
 */
typedef void (^TWTRNetworkCompletion)(NSURLResponse *_Nullable response, NSData *_Nullable data, NSError *_Nullable connectionError);

/**
 *  Completion block called when a JSON request to the Twitter API succeeds or fails.
 *
 *  @param response       Metadata associated with the response to a URL load request.
 *  @param responseObject Content data of the response.
 *  @param error          Error object describing the network error that occurred.
 */
typedef void (^TWTRJSONRequestCompletion)(NSURLResponse *_Nullable response, id _Nullable responseObject, NSError *_Nullable error);

/**
 *  Completion block called when a Tweet action (favorite/retweet) is performed.
 *
 *  @param tweet    The Tweet object representing the new state of this Tweet from
 *                  the perspective of the currently-logged in user.
 *  @param error    Error object describing the error that occurred. This will be either a
 *                  network error or an NSError with an errorCode corresponding to
 *                  TWTRAPIErrorCodeAlreadyFavorited or TWTRAPIErrorCodeAlreadyRetweeted
 *                  for an attempted action that has already been taken from the servers
 *                  point of view for this logged-in user.
 */
typedef void (^TWTRTweetActionCompletion)(TWTRTweet *_Nullable tweet, NSError *_Nullable error);

/**
 *  Completion block called when a media upload request to the Twitter API succeeds or fails.
 *
 *  @param mediaID The media ID of the object that was uploaded which can be used when tweeting.
 *  @param error   Error object describing the network error that occurred.
 */
typedef void (^TWTRMediaUploadResponseCompletion)(NSString *_Nullable mediaID, NSError *_Nullable error);

/**
 *  Completion block called when the send Tweet request succeeds or fails.
 *
 *  @param tweet The Twitter Tweet created.
 *  @param error Error that will be set if the API request failed.
 */
typedef void (^TWTRSendTweetCompletion)(TWTRTweet *_Nullable tweet, NSError *_Nullable error);

/**
 *  Completion block called when a request for the user's email succeeds or fails.
 *
 *  @param email The email of the user
 *  @param error Error object describing the error that occurred.
 */
typedef void (^TWTRRequestEmailCompletion)(NSString *_Nullable email, NSError *_Nullable error);

/**
 *  Client for consuming the Twitter REST API. Provides methods for common API requests, as well as the ability to create and send custom requests.
 */
@interface TWTRAPIClient : NSObject

/**
 *  The Twitter user ID this client is making API requests on behalf of or
 *  nil if it is a guest user.
 */
@property (nonatomic, copy, readonly, nullable) NSString *userID;

/**
 *  Constructs a `TWTRAPIClient` object to perform authenticated API requests with user authentication.
 *
 *  @param userID (optional) ID of the user to make requests on behalf of. If the ID is nil requests will be made using guest authentication.
 *
 *  @return Fully initialized API client to make authenticated requests against the Twitter REST API.
 */
- (instancetype)initWithUserID:(nullable NSString *)userID;

/**
 *  Constructs a `TWTRAPIClient` with the last logged-in user. If no user has been
 *  logged in yet this falls back to Guest authentication.
 *
 *  @return Fully initialized API client to make Guest or User authenticated requests to the Twitter REST API.
 */
+ (instancetype)clientWithCurrentUser;

/**
 *  @name Making Requests
 */

/**
 *  Returns a signed URL request.
 *
 *  @param method     Request method, GET, POST, PUT, DELETE, etc.
 *  @param URLString  Request URL. This is the full Twitter API URL. E.g. https://api.twitter.com/1.1/statuses/user_timeline.json
 *  @param parameters Request parameters.
 *  @param error      Error that will be set if there was an error signing the request.
 *
 *  @note If the request is not sent with the -[TWTRAPIClient sendTwitterRequest:completion:] method it is the developers responsibility to ensure that there is a valid guest session before this method is called.
 */
- (NSURLRequest *)URLRequestWithMethod:(NSString *)method URL:(NSString *)URLString parameters:(nullable NSDictionary *)parameters error:(NSError **)error;

/**
 *  Sends a Twitter request.
 *
 *  @param request    The request that will be sent asynchronously.
 *  @param completion Completion block to be called on response. Called on main queue.
 *  @return an NSProgress object which can be used to cancel the request.
 */
- (NSProgress *)sendTwitterRequest:(NSURLRequest *)request completion:(TWTRNetworkCompletion)completion;

/**
 *  @name Common API Actions
 */

/**
 *  Loads a Twitter User.
 *
 *  @param userID       (required) The Twitter user ID of the desired user.
 *  @param completion   Completion block to be called on response. Called on main queue.
 */
- (void)loadUserWithID:(NSString *)userID completion:(TWTRLoadUserCompletion)completion;

/**
 *  Loads a single Tweet from the network or cache.
 *
 *  @param tweetID      (required) The ID of the desired Tweet.
 *  @param completion   Completion bock to be called on response. Called on main queue.
 */
- (void)loadTweetWithID:(NSString *)tweetID completion:(TWTRLoadTweetCompletion)completion;

/**
 *  Loads a series of Tweets in a batch. The completion block will be passed an array of zero or more
 *  Tweets that loaded successfully. If some Tweets fail to load the array will contain less Tweets than
 *  number of requested IDs. If any Tweets fail to load, the IDs of the Tweets that did not load will
 *  be provided in the userInfo dictionary property of the error parameter under `TWTRTweetsNotLoadedKey`.
 *
 *  @param tweetIDStrings (required) An array of Tweet IDs.
 *  @param completion     Completion block to be called on response. Called on main queue.
 */
- (void)loadTweetsWithIDs:(NSArray *)tweetIDStrings completion:(TWTRLoadTweetsCompletion)completion;

/**
 *  Uploads media to the media server. Returns a media ID to be used when tweeting.
 *
 *  @param media       The media to upload
 *  @param contentType The HTTP content type of the media that you are uploading.
 *  @param completion  The completion handler to invoke.
 */
- (void)uploadMedia:(NSData *)media contentType:(NSString *)contentType completion:(TWTRMediaUploadResponseCompletion)completion;

/**
 *  Create and send a Tweet.
 *
 *  @param tweetText    (required) The text for a Tweet
 *  @param completion   Completion block to be called on response. Called on main queue.
 */
- (void)sendTweetWithText:(NSString *)tweetText completion:(TWTRSendTweetCompletion)completion;

/**
 *  Upload media and create a Tweet. Returns TWTRTweet to be used when debugging.
 *
 *  @param tweetText   The text for a Tweet
 *  @param image       UIImage to upload
 *  @param completion  The completion handler to invoke.
 */
- (void)sendTweetWithText:(NSString *)tweetText image:(UIImage *)image completion:(TWTRSendTweetCompletion)completion;

/**
 *  Create a Tweet with a video. Returns TWTRTweet to be used when debugging.
 *
 *  Note: there are several requirements of the video being uploaded:
 *  - Duration should be between 0.5 seconds and 30 seconds
 *  - File size should not exceed 15 mb
 *  - Dimensions should be between 32x32 and 1280x1024
 *  - Aspect ratio should be between 1:3 and 3:1
 *  - Frame rate should be 40fps or less
 *
 *  @param tweetText   The text for a Tweet
 *  @param videoData   The video to be uploaded. Please follow guideline https://dev.twitter.com/rest/media/uploading-media
 *  @param completion  The completion handler to invoke.
 */
- (void)sendTweetWithText:(NSString *)tweetText videoData:(NSData *)videoData completion:(TWTRSendTweetCompletion)completion;

/**
 *  Requests the email for the user id which the API client was instantiated with.
 *  This method requires that you are using an API Client which was instantiated with
 *  a logged in user otherwise you will receive a "Request failed: forbidden (403)" error.
 *
 *  @param completion A completion block to invoke when the request completes. The email address may
 *                    be a nil if the user does not have an email address, the email address
 *                    is unverified or you do not have the correct permissions to request the email address.
 *
 *  @note Requesting a user’s email address requires your application to be whitelisted by Twitter.
 *  To request access, please visit the "Permissions" section for your app at https://apps.twitter.com/
 */
- (void)requestEmailForCurrentUser:(TWTRRequestEmailCompletion)completion;

@end

NS_ASSUME_NONNULL_END
