@setoelkahfi / JomloTableView
Code Commits Issues Pulls Sessions CI/CD
release-0.2.1
develop feature/spm main release-0.1.0 release-0.2.0 release-0.2.1
h 205 lines 8.33 KB
Raw
1 //
2 // TWTRAPIClient.h
3 //
4 // Copyright (c) 2015 Twitter. All rights reserved.
5 //
6
7 @class TWTRUser;
8 @class TWTRTweet;
9 @class TWTRAuthConfig;
10 @class TWTRGuestSession;
11 @protocol TWTRAuthSession;
12 @protocol TWTRSessionStore;
13
14 NS_ASSUME_NONNULL_BEGIN
15
16 FOUNDATION_EXPORT NSString * const TWTRTweetsNotLoadedKey;
17
18 /**
19 * @name Completion Block Types
20 */
21
22 /**
23 * Completion block called when the load user request succeeds or fails.
24 *
25 * @param user The Twitter User.
26 * @param error Error that will be set if the API request failed.
27 */
28 typedef void (^TWTRLoadUserCompletion)(TWTRUser * _Nullable user, NSError * _Nullable error);
29
30 /**
31 * Completion block called when the load Tweet request succeeds or fails.
32 *
33 * @param tweet The Twitter Tweet.
34 * @param error Error that will be set if the API request failed.
35 */
36 typedef void (^TWTRLoadTweetCompletion)(TWTRTweet * _Nullable tweet, NSError * _Nullable error);
37
38 /**
39 * Completion block called when the load Tweets request succeeds or fails.
40 *
41 * @param tweets Tweets that were successfully retrieved.
42 * @param error Error that will be set if the API request failed.
43 */
44 typedef void (^TWTRLoadTweetsCompletion)(NSArray<TWTRTweet *> * _Nullable tweets, NSError * _Nullable error);
45
46 /**
47 * Completion block called when the network request succeeds or fails.
48 *
49 * @param response Metadata associated with the response to a URL load request.
50 * @param data Content data of the response.
51 * @param connectionError Error object describing the network error that occurred.
52 */
53 typedef void (^TWTRNetworkCompletion)(NSURLResponse * _Nullable response, NSData * _Nullable data, NSError * _Nullable connectionError);
54
55 /**
56 * Completion block called when a JSON request to the Twitter API succeeds or fails.
57 *
58 * @param response Metadata associated with the response to a URL load request.
59 * @param responseObject Content data of the response.
60 * @param error Error object describing the network error that occurred.
61 */
62 typedef void (^TWTRJSONRequestCompletion)(NSURLResponse * _Nullable response, id _Nullable responseObject, NSError * _Nullable error);
63
64 /**
65 * Completion block called when a Tweet action (favorite/retweet) is performed.
66 *
67 * @param response Metadata associated with the response to a URL load request.
68 * @param tweet The Tweet object representing the new state of this Tweet from
69 * the perspective of the currently-logged in user.
70 * @param error Error object describing the error that occurred. This will be either a
71 * network error or an NSError with an errorCode corresponding to
72 * TWTRAPIErrorCodeAlreadyFavorited or TWTRAPIErrorCodeAlreadyRetweeted
73 * for an attempted action that has already been taken from the servers
74 * point of view for this logged-in user.
75 */
76 typedef void (^TWTRTweetActionCompletion)(TWTRTweet * _Nullable tweet, NSError * _Nullable error);
77
78 /**
79 * Completion block called when a media upload request to the Twitter API succeeds or fails.
80 *
81 * @param mediaID The media ID of the object that was uploaded which can be used when tweeting.
82 * @param error Error object describing the network error that occurred.
83 */
84 typedef void (^TWTRMediaUploadResponseCompletion)(NSString * _Nullable mediaID, NSError * _Nullable error);
85
86 /**
87 * Completion block called when a request for the user's email succeeds or fails.
88 *
89 * @param email The email of the user
90 * @param error Error object describing the error that occurred.
91 */
92 typedef void(^TWTRRequestEmailCompletion)(NSString * _Nullable email, NSError * _Nullable error);
93
94 /**
95 * Client for consuming the Twitter REST API. Provides methods for common API requests, as well as the ability to create and send custom requests.
96 */
97 @interface TWTRAPIClient : NSObject
98
99 /**
100 * The Twitter user ID this client is making API requests on behalf of or
101 * nil if it is a guest user.
102 */
103 @property (nonatomic, copy, readonly, nullable) NSString *userID;
104
105
106 /**
107 * Constructs a `TWTRAPIClient` object to perform authenticated API requests with user authentication.
108 *
109 * @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.
110 *
111 * @return Fully initialized API client to make authenticated requests against the Twitter REST API.
112 */
113 - (instancetype)initWithUserID:(nullable NSString *)userID;
114
115 /**
116 * Constructs a `TWTRAPIClient` with the last logged-in user. If no user has been
117 * logged in yet this falls back to Guest authentication.
118 *
119 * @return Fully initialized API client to make Guest or User authenticated requests to the Twitter REST API.
120 */
121 + (instancetype)clientWithCurrentUser;
122
123
124 /**
125 * @name Making Requests
126 */
127
128 /**
129 * Returns a signed URL request.
130 *
131 * @param method Request method, GET, POST, PUT, DELETE, etc.
132 * @param URL Request URL. This is the full Twitter API URL. E.g. https://api.twitter.com/1.1/statuses/user_timeline.json
133 * @param parameters Request parameters.
134 * @param error Error that will be set if there was an error signing the request.
135 *
136 * @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.
137 */
138 - (NSURLRequest *)URLRequestWithMethod:(NSString *)method URL:(NSString *)URLString parameters:(nullable NSDictionary *)parameters error:(NSError **)error;
139
140 /**
141 * Sends a Twitter request.
142 *
143 * @param request The request that will be sent asynchronously.
144 * @param completion Completion block to be called on response. Called on main queue.
145 * @return an NSProgress object which can be used to cancel the request.
146 */
147 - (NSProgress *)sendTwitterRequest:(NSURLRequest *)request completion:(TWTRNetworkCompletion)completion;
148
149 /**
150 * @name Common API Actions
151 */
152
153 /**
154 * Loads a Twitter User.
155 *
156 * @param userID (required) The Twitter user ID of the desired user.
157 * @param completion Completion block to be called on response. Called on main queue.
158 */
159 - (void)loadUserWithID:(NSString *)userID completion:(TWTRLoadUserCompletion)completion;
160
161 /**
162 * Loads a single Tweet from the network or cache.
163 *
164 * @param tweetID (required) The ID of the desired Tweet.
165 * @param completion Completion bock to be called on response. Called on main queue.
166 */
167 - (void)loadTweetWithID:(NSString *)tweetID completion:(TWTRLoadTweetCompletion)completion;
168
169 /**
170 * Loads a series of Tweets in a batch. The completion block will be passed an array of zero or more
171 * Tweets that loaded successfully. If some Tweets fail to load the array will contain less Tweets than
172 * number of requested IDs. If any Tweets fail to load, the IDs of the Tweets that did not load will
173 * be provided in the userInfo dictionary property of the error parameter under `TWTRTweetsNotLoadedKey`.
174 *
175 * @param tweetIDStrings (required) An array of Tweet IDs.
176 * @param completion Completion block to be called on response. Called on main queue.
177 */
178 - (void)loadTweetsWithIDs:(NSArray *)tweetIDStrings completion:(TWTRLoadTweetsCompletion)completion;
179
180 /**
181 * Uploads media to the media server. Returns a media ID to be used when tweeting.
182 *
183 * @param media The media to upload
184 * @param contentType The HTTP content type of the media that you are uploading.
185 * @param completion The completion handler to invoke.
186 */
187 - (void)uploadMedia:(NSData *)media contentType:(NSString *)contentType completion:(TWTRMediaUploadResponseCompletion)completion;
188
189 /**
190 * Requests the email for the user id which the API client was instantiated with.
191 * This method requires that you are using an API Client which was instantiated with
192 * a logged in user otherwise you will receive a "Request failed: forbidden (403)" error.
193 *
194 * @param completion A completion block to invoke when the request completes. The email address may
195 * be a nil if the user does not have an email address, the email address
196 * is unverified or you do not have the correct permissions to request the email address.
197 *
198 * @note Requesting a user’s email address requires your application to be whitelisted by Twitter.
199 * To request access, please visit https://support.twitter.com/forms/platform.
200 */
201 - (void)requestEmailForCurrentUser:(TWTRRequestEmailCompletion)completion;
202
203 @end
204
205 NS_ASSUME_NONNULL_END