1 var Util = require('util');
  2 var Client = require('./Client');
  3 var Constants = require('./Constants');
  4 var RestParameterValidator = require('./RestParameterValidator');
  5 var UploadClient = require('./UploadClient');
  6 
  7 /**
  8  * Creates an instance of RestClient.
  9  *
 10  * @constructor
 11  * @this {RestClient}
 12  * @param {String} consumerKey OAuth consumer key.
 13  * @param {String} consumerSecret OAuth consumer secret.
 14  * @param {String} token OAuth token.
 15  * @param {String} tokenSecret OAuth token secret.
 16  */
 17 var RestClient = function(consumerKey, consumerSecret, token, tokenSecret)
 18 {
 19     Client.call(this, consumerKey, consumerSecret, token, tokenSecret);
 20 
 21     this._apiBaseUrlString = Constants.RestApiBaseURLString;
 22     this._apiVersion = Constants.RestApiVersion;
 23     this._validator = new RestParameterValidator();
 24 };
 25 
 26 Util.inherits(RestClient, Client);
 27 
 28 // Timelines
 29 //
 30 // Timelines are collections of Tweets, ordered with the most recent first.
 31 
 32 /**
 33  * Returns the 20 most recent tweets (including retweets), posted by the authenticated user and the user they follow.
 34  *
 35  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/home_timeline">Twitter documenation</a>.
 36  *
 37  * @this {RestClient}
 38  * @param {Dictionary} parameters
 39  * @param {Function} callback The callback function.
 40  */
 41 RestClient.prototype.statusesHomeTimeline = function(parameters, callback)
 42 {
 43     this._validator.validateContributorDetails(parameters);
 44     this._validator.validateCount(parameters);
 45     this._validator.validateExcludeReplies(parameters);
 46     this._validator.validateIncludeEntities(parameters);
 47     this._validator.validateIncludeRetweets(parameters);
 48     this._validator.validateMaxId(parameters);
 49     this._validator.validatePage(parameters);
 50     this._validator.validateSinceId(parameters);
 51     this._validator.validateTrimUser(parameters);
 52 
 53 	this._createGetRequest('statuses/home_timeline', 'json', parameters, callback);
 54 };
 55 
 56 /**
 57  * Retrieves the most recent mentions for the authenticated user.
 58  *
 59  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/mentions">Twitter documentation</a>.
 60  *
 61  * @this {RestClient}
 62  * @param {Dictionary} parameters
 63  * @param {Function} callback The callback function.
 64  */
 65 RestClient.prototype.statusesMentions = function(parameters, callback)
 66 {
 67     this._validator.validateContributorDetails(parameters);
 68     this._validator.validateCount(parameters);
 69     this._validator.validateExcludeReplies(parameters);
 70     this._validator.validateIncludeEntities(parameters);
 71     this._validator.validateIncludeRetweets(parameters);
 72     this._validator.validateMaxId(parameters);
 73     this._validator.validatePage(parameters);
 74     this._validator.validateSinceId(parameters);
 75     this._validator.validateTrimUser(parameters);
 76 
 77     this._createGetRequest('statuses/mentions', 'json', parameters, callback);
 78 };
 79 
 80 /**
 81  * Retrieves the most recent statuses, including retweets if they exist, from non-protected users.
 82  *
 83  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/public_timeline">Twitter documenation</a>.
 84  *
 85  * @this {RestClient}
 86  * @param {Dictionary} parameters
 87  * @param {Function} callback The callback function.
 88  */
 89 RestClient.prototype.statusesPublicTimeline = function(parameters, callback)
 90 {
 91     this._validator.validateCount(parameters);
 92     this._validator.validateIncludeEntities(parameters);
 93     this._validator.validateTrimUser(parameters);
 94 
 95     this._createGetRequest('statuses/public_timeline', 'json', parameters, callback);
 96 };
 97 
 98 /**
 99  * Retrieves the most recent statuses retweeted by the authenticated user.
100  *
101  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweeted_by_me">Twitter documenation</a>.
102  *
103  * @this {RestClient}
104  * @param {Dictionary} parameters
105  * @param {Function} callback The callback function.
106  */
107 RestClient.prototype.statusesRetweetedByMe = function(parameters, callback)
108 {
109     this._validator.validateCount(parameters);
110     this._validator.validateIncludeEntities(parameters);
111     this._validator.validateMaxId(parameters);
112     this._validator.validatePage(parameters);
113     this._validator.validateSinceId(parameters);
114     this._validator.validateTrimUser(parameters);
115 
116     this._createGetRequest('statuses/retweeted_by_me', 'json', parameters, callback);
117 };
118 
119 /**
120  * Retrieves the most recent retweets posted by the specified user.
121  *
122  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweeted_by_user">Twitter documenation</a>.
123  *
124  * @this {RestClient}
125  * @param {Dictionary} parameters
126  * @param {Function} callback The callback function.
127  */
128 RestClient.prototype.statusesRetweetedByUser = function(parameters, callback)
129 {
130     this._validator.validateCount(parameters);
131     this._validator.validateIncludeEntities(parameters);
132     this._validator.validateMaxId(parameters);
133     this._validator.validatePage(parameters);
134     this._validator.validateScreenName(parameters);
135     this._validator.validateSinceId(parameters);
136     this._validator.validateTrimUser(parameters);
137     this._validator.validateUserId(parameters);
138 
139     this._createGetRequest('statuses/retweeted_by_user', 'json', parameters, callback);
140 };
141 
142 /**
143  * Retrieves the most recent retweets posted by users the authenticated user follows.
144  *
145  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweeted_to_me">Twitter documenation</a>.
146  *
147  * @this {RestClient}
148  * @param {Dictionary} parameters
149  * @param {Function} callback The callback function.
150  */
151 RestClient.prototype.statusesRetweetedToMe = function(parameters, callback)
152 {
153     this._validator.validateCount(parameters);
154     this._validator.validateIncludeEntities(parameters);
155     this._validator.validateMaxId(parameters);
156     this._validator.validatePage(parameters);
157     this._validator.validateSinceId(parameters);
158     this._validator.validateTrimUser(parameters);
159 
160     this._createGetRequest('statuses/retweeted_to_me', 'json', parameters, callback);
161 };
162 
163 /**
164  * Retrieves the most recent retweets posted by users the specified user follows.
165  * This method is identical to statusesRetweetedToMe except you can specify the user.
166  *
167  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweeted_to_user">Twitter documenation</a>.
168  *
169  * @this {RestClient}
170  * @param {Dictionary} parameters
171  * @param {Function} callback The callback function.
172  */
173 RestClient.prototype.statusesRetweetedToUser = function(parameters, callback)
174 {
175     this._validator.validateCount(parameters);
176     this._validator.validateIncludeEntities(parameters);
177     this._validator.validateMaxId(parameters);
178     this._validator.validatePage(parameters);
179     this._validator.validateScreenName(parameters);
180     this._validator.validateSinceId(parameters);
181     this._validator.validateTrimUser(parameters);
182     this._validator.validateUserId(parameters);
183 
184     this._createGetRequest('statuses/retweeted_to_user', 'json', parameters, callback);
185 };
186 
187 /**
188  * Returns recent tweets by the authenticated user that have been retweeted by others.
189  *
190  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweets_of_me">Twitter documenation</a>.
191  *
192  * @this {RestClient}
193  * @param {Dictionary} parameters
194  * @param {Function} callback The callback function.
195  */
196 RestClient.prototype.statusesRetweetsOfMe = function(parameters, callback)
197 {
198     this._validator.validateCount(parameters);
199     this._validator.validateIncludeEntities(parameters);
200     this._validator.validateMaxId(parameters);
201     this._validator.validatePage(parameters);
202     this._validator.validateSinceId(parameters);
203     this._validator.validateTrimUser(parameters);
204 
205     this._createGetRequest('statuses/retweets_of_me', 'json', parameters, callback);
206 };
207 
208 /**
209  *
210  *
211  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/user_timeline">Twitter documenation</a>.
212  *
213  * @this {RestClient}
214  * @param {Dictionary} parameters
215  * @param {Function} callback The callback function.
216  */
217 RestClient.prototype.statusesUserTimeline = function(parameters, callback)
218 {
219     this._validator.validateContributorDetails(parameters);
220     this._validator.validateCount(parameters);
221     this._validator.validateExcludeReplies(parameters);
222     this._validator.validateIncludeEntities(parameters);
223     this._validator.validateIncludeRetweets(parameters);
224     this._validator.validateMaxId(parameters);
225     this._validator.validatePage(parameters);
226     this._validator.validateSinceId(parameters);
227     this._validator.validateScreenName(parameters);
228     this._validator.validateTrimUser(parameters);
229     this._validator.validateUserId(parameters);
230 
231     this._createGetRequest('statuses/user_timeline', 'json', parameters, callback);
232 };
233 
234 // Tweets
235 
236 /**
237  * Destroys the status specified by the id parameter if it is owned by the authenticated user.
238  *
239  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/post/statuses/destroy/%3Aid">Twitter documenation</a>.
240  *
241  * @this {RestClient}
242  * @param {Dictionary} parameters
243  * @param {Function} callback The callback function.
244  */
245 RestClient.prototype.statusesDestroy = function(parameters, callback)
246 {
247     var id = parameters['id'];
248     if (id === undefined)
249     {
250         throw new Error('Missing required parameter: id.');
251     }
252 
253     this._validator.validateId(parameters);
254     this._validator.validateIncludeEntities(parameters);
255     this._validator.validateTrimUser(parameters);
256 
257     var resource = 'statuses/destroy/' + id;
258 
259     // Remove the id key from the list of query parameters.
260     delete(parameters['id']);
261 
262     this._createPostRequest(resource, 'json', parameters, callback);
263 };
264 
265 /**
266  * Retrieves information needed to embed a status on third party sites.
267  *
268  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/oembed">Twitter documenation</a>.
269  *
270  * @this {RestClient}
271  * @param {Dictionary} parameters
272  * @param {Function} callback The callback function.
273  */
274 RestClient.prototype.statusesOEmbed = function(parameters, callback)
275 {
276     var id = parameters['id'];
277     if (id === undefined)
278     {
279         var url = parameters['url'];
280         if (url === undefined)
281         {
282             throw new Error('Missing required parameter: id or url.');
283         }
284     }
285 
286     this._validator.validateId(parameters);
287     this._validator.validateUrl(parameters);
288 
289     this._validator.validateAlign(parameters);
290     this._validator.validateHideMedia(parameters);
291     this._validator.validateHideThread(parameters);
292     this._validator.validateLanguage(parameters);
293     this._validator.validateMaxWidth(parameters);
294     this._validator.validateOmitScript(parameters);
295     this._validator.validateRelated(parameters);
296 
297     var resource = 'statuses/oembed';
298 
299     this._createGetRequest(resource, 'json', parameters, callback);
300 };
301 
302 /**
303  * Retweets the status associated with the specified id parameter.
304  *
305  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/post/statuses/retweet/%3Aid">Twitter documenation</a>.
306  *
307  * @this {RestClient}
308  * @param {Dictionary} parameters
309  * @param {Function} callback The callback function.
310  */
311 RestClient.prototype.statusesRetweet = function(parameters, callback)
312 {
313     var id = parameters['id'];
314     if (id === undefined)
315     {
316         throw new Error('Missing required parameter: id.');
317     }
318 
319     this._validator.validateId(parameters);
320     this._validator.validateIncludeEntities(parameters);
321     this._validator.validateCount(parameters);
322     this._validator.validatePage(parameters);
323     this._validator.validateTrimUser(parameters);
324 
325     var resource = 'statuses/retweet/' + id;
326 
327     // Remove the id key from the list of query parameters.
328     delete(parameters['id']);
329 
330     this._createPostRequest(resource, 'json', parameters, callback);
331 };
332 
333 /**
334  * Retrieves the users who retweeted the status associated with the specified id parameter.
335  *
336  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/%3Aid/retweeted_by">Twitter documenation</a>.
337  *
338  * @this {RestClient}
339  * @param {Dictionary} parameters
340  * @param {Function} callback The callback function.
341  */
342 RestClient.prototype.statusesRetweetedBy = function(parameters, callback)
343 {
344     var id = parameters['id'];
345     if (id === undefined)
346     {
347         throw new Error('Missing required parameter: id.');
348     }
349 
350     this._validator.validateId(parameters);
351     this._validator.validateCount(parameters);
352     this._validator.validatePage(parameters);
353 
354     var resource = 'statuses/' + id + '/retweeted_by';
355 
356     // Remove the id key from the list of query parameters.
357     delete(parameters['id']);
358 
359     this._createGetRequest(resource, 'json', parameters, callback);
360 };
361 
362 /**
363  * Retrieves the ids of the users who retweeted the status associated with the specified id parameter.
364  *
365  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/%3Aid/retweeted_by/ids">Twitter documenation</a>.
366  *
367  * @this {RestClient}
368  * @param {Dictionary} parameters
369  * @param {Function} callback The callback function.
370  */
371 RestClient.prototype.statusesRetweetedByIds = function(parameters, callback)
372 {
373     var id = parameters['id'];
374     if (id === undefined)
375     {
376         throw new Error('Missing required parameter: id.');
377     }
378 
379     this._validator.validateId(parameters);
380     this._validator.validateCount(parameters);
381     this._validator.validatePage(parameters);
382     this._validator.validateStringifyIds(parameters);
383 
384     var resource = 'statuses/' + id + '/retweeted_by/ids';
385 
386     // Remove the id key from the list of query parameters.
387     delete(parameters['id']);
388 
389     // JavaScript cannot consume tweet ID due to their size. Add the 
390     // stringify_ids parameter to ensure tweet IDs are returned as strings.
391     parameters['stringify_ids'] = true;
392 
393     this._createGetRequest(resource, 'json', parameters, callback);
394 };
395 
396 /**
397  * Retrieves the retweets of a given status.
398  *
399  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/retweets/%3Aid">Twitter documenation</a>.
400  *
401  * @this {RestClient}
402  * @param {Dictionary} parameters
403  * @param {Function} callback The callback function.
404  */
405 RestClient.prototype.statusesRetweets = function(parameters, callback)
406 {
407     var id = parameters['id'];
408     if (id === undefined)
409     {
410         throw new Error('Missing required parameter: id.');
411     }
412 
413     this._validator.validateId(parameters);
414     this._validator.validateIncludeEntities(parameters);
415     this._validator.validateCount(parameters);
416     this._validator.validatePage(parameters);
417     this._validator.validateTrimUser(parameters);
418 
419     var resource = 'statuses/retweets/' + id;
420 
421     // Remove the id key from the list of query parameters.
422     delete(parameters['id']);
423 
424     this._createGetRequest(resource, 'json', parameters, callback);
425 };
426 
427 /**
428  * Retrieves the status associated with the specified id parameter.
429  *
430  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/get/statuses/show/%3Aid">Twitter documenation</a>.
431  *
432  * @this {RestClient}
433  * @param {Dictionary} parameters
434  * @param {Function} callback The callback function.
435  */
436 RestClient.prototype.statusesShow = function(parameters, callback)
437 {
438     var id = parameters['id'];
439     if (id === undefined)
440     {
441         throw new Error('Missing required parameter: id.');
442     }
443 
444     this._validator.validateId(parameters);
445     this._validator.validateIncludeEntities(parameters);
446     this._validator.validateTrimUser(parameters);
447 
448     var resource = 'statuses/show';
449 
450     this._createGetRequest(resource, 'json', parameters, callback);
451 };
452 
453 /**
454  * Posts a new status for the authenticated user.
455  *
456  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/post/statuses/update">Twitter documenation</a>.
457  *
458  * @this {RestClient}
459  * @param {Dictionary} parameters
460  * @param {Function} callback The callback function.
461  * @return This method returns an integer.
462  */
463 RestClient.prototype.statusesUpdate = function(parameters, callback)
464 {
465     var status = parameters['status'];
466     if (status === undefined)
467     {
468         throw new Error('Missing required parameter: status.');
469     }
470 
471     this._validator.validateDisplayCoordinates(parameters);
472     this._validator.validateIncludeEntities(parameters);
473     this._validator.validateInReplyToStatusId(parameters);
474     this._validator.validatePlaceId(parameters);
475     this._validator.validateLatitude(parameters);
476     this._validator.validateLongitude(parameters);
477     this._validator.validateStatus(parameters);
478     this._validator.validateTrimUser(parameters);
479 
480     var resource = 'statuses/update';
481 
482     this._createPostRequest(resource, 'json', parameters, callback);
483 };
484 
485 /**
486  * Posts a new status for the authenticated user and attaches media for upload.
487  *
488  * For information on acceptable parameters see the official <a href="https://dev.twitter.com/docs/api/1/post/statuses/update_with_media">Twitter documenation</a>.
489  *
490  * @this {RestClient}
491  * @param {Dictionary} parameters
492  * @param {Function} callback The callback function.
493  */
494 RestClient.prototype.statusesUpdateWithMedia = function(parameters, callback)
495 {
496     var uploadClient = new UploadClient(
497         this._oauth.consumer_key,
498         this._oauth.consumer_secret,
499         this._oauth.token,
500         this._oauth.token_secret
501     );
502 
503     uploadClient.statusesUpdateWithMedia(parameters, callback);
504 };
505 
506 module.exports = RestClient;
507