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