Add Twitter::API#related_results

Closes #299.

README.md

@@ -164,7 +164,7 @@ Here are some fun facts about the 3.0 release:
 
 * The entire library is implemented in just 2,000 lines of code
 * With over 5,000 lines of specs, the spec-to-code ratio is over 2.5:1
-* The spec suite contains 670 examples and runs in under 2 seconds on a MacBook
+* The spec suite contains 672 examples and runs in under 2 seconds on a MacBook
 * This project has 100% C0 code coverage (the tests execute every line of
   source code at least once)
 * At the time of release, this library is comprehensive: you can request all

lib/twitter/api.rb

@@ -106,6 +106,9 @@ module API
       :privacy => true,
       :rate_limit_status => false,
       :rate_limited? => false,
+      :related_results => true,
+      :related_statuses => true,
+      :related_tweets => true,
       :recommendations => true,
       :relationship => true,
       :report_spam => true,
@@ -1967,6 +1970,24 @@ def statuses(*args)
       threaded_statuses_from_response(:get, "/1/statuses/show", args)
     end
 
+    # Returns tweets related to a given status
+    #
+    # @note {https://dev.twitter.com/discussions/293 Undocumented}
+    # @rate_limited Yes
+    # @authentication_required No, unless the author of the status is protected
+    # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+    # @return [Array<Twitter::Status>]
+    # @param id [Integer] A Twitter status ID.
+    # @param options [Hash] A customizable set of options.
+    # @example Returns tweets related to the status with the ID 25938088801
+    #   Twitter.related_results(25938088801)
+    def related_results(id, options={})
+      array = get("/1/related_results/show/#{id}.json")[:body][0][:results].select{|result| result[:kind].capitalize == "Tweet"}.map{|result| result[:value]}
+      collection_from_array(Twitter::Status, array)
+    end
+    alias related_statuses related_results
+    alias related_tweets related_results
+
     # Returns activity summary for a status
     #
     # @note Undocumented

lib/twitter/client.rb

@@ -1,4 +1,5 @@
 require 'faraday'
+require 'multi_json'
 require 'twitter/api'
 require 'twitter/configurable'
 require 'twitter/error/client_error'

spec/fixtures/related_results.json

@@ -0,0 +1 @@
+[{"groupName":"TweetsWithConversation","resultType":"Tweet","results":[{"score":1.0,"annotations":{"ConversationRole":"Ancestor"},"kind":"Tweet","value":{"contributors":null,"coordinates":null,"user":{"show_all_inline_media":true,"id":10452222,"location":"Walifornia","follow_request_sent":null,"profile_image_url":"http:\/\/a0.twimg.com\/profile_images\/1056235466\/Screen_Shot_2010-07-06_at_1.41.21_PM_normal.png","profile_background_color":"FFFFFF","statuses_count":7718,"utc_offset":3600,"profile_image_url_https":"https:\/\/si0.twimg.com\/profile_images\/1056235466\/Screen_Shot_2010-07-06_at_1.41.21_PM_normal.png","name":"Laurent Sansonetti","default_profile":false,"profile_background_image_url":"http:\/\/a0.twimg.com\/images\/themes\/theme1\/bg.png","screen_name":"lrz","friends_count":196,"profile_link_color":"6E6E6E","protected":false,"notifications":null,"profile_use_background_image":false,"lang":"en","listed_count":233,"profile_text_color":"000000","description":"Belgian software hacker, husband, dad and cat wrangler. Founder of @HipByte. Creator and developer of @RubyMotion and @MacRuby. Former Apple employee (7 years).","followers_count":2719,"url":"http:\/\/chopine.be","is_translator":false,"created_at":"Wed Nov 21 21:48:30 +0000 2007","profile_sidebar_border_color":"181A1E","contributors_enabled":false,"verified":false,"time_zone":"Paris","geo_enabled":true,"id_str":"10452222","default_profile_image":false,"profile_background_tile":false,"profile_background_image_url_https":"https:\/\/si0.twimg.com\/images\/themes\/theme1\/bg.png","following":null,"profile_sidebar_fill_color":"EBEBEB","favourites_count":95},"retweeted":false,"in_reply_to_status_id":null,"in_reply_to_user_id":null,"truncated":false,"in_reply_to_status_id_str":null,"retweet_count":0,"source":"\u003Ca href=\"http:\/\/itunes.apple.com\/us\/app\/twitter\/id409789998?mt=12\" rel=\"nofollow\"\u003ETwitter for Mac\u003C\/a\u003E","id_str":"233293738510802944","geo":null,"id":233293738510802944,"created_at":"Wed Aug 08 20:08:56 +0000 2012","in_reply_to_user_id_str":null,"place":null,"in_reply_to_screen_name":null,"favorited":false,"text":"Upcoming trips this year\u2026 Berlin, Aarhus, New Delhi, New York, Tokyo. Time to get a frequent flyer card?"}},{"score":1.0,"annotations":{"ConversationRole":"Ancestor"},"kind":"Tweet","value":{"contributors":null,"coordinates":null,"user":{"show_all_inline_media":true,"id":18713,"location":"","follow_request_sent":null,"profile_image_url":"http:\/\/a0.twimg.com\/profile_images\/357750272\/small_3_normal.png","profile_background_color":"E5E9EB","statuses_count":22966,"utc_offset":-28800,"profile_image_url_https":"https:\/\/si0.twimg.com\/profile_images\/357750272\/small_3_normal.png","name":"Alex Payne","default_profile":false,"profile_background_image_url":"http:\/\/a0.twimg.com\/images\/themes\/theme1\/bg.png","screen_name":"al3x","friends_count":318,"profile_link_color":"336699","protected":false,"notifications":null,"profile_use_background_image":false,"lang":"en","listed_count":2265,"profile_text_color":"232323","description":"Programmer. Writer. Secular Humanist.","followers_count":36241,"url":"http:\/\/al3x.net","is_translator":false,"created_at":"Thu Nov 23 19:29:11 +0000 2006","profile_sidebar_border_color":"333333","contributors_enabled":false,"verified":false,"time_zone":"Pacific Time (US & Canada)","geo_enabled":true,"id_str":"18713","default_profile_image":false,"profile_background_tile":false,"profile_background_image_url_https":"https:\/\/si0.twimg.com\/images\/themes\/theme1\/bg.png","following":null,"profile_sidebar_fill_color":"C3CBD0","favourites_count":4515},"retweeted":false,"in_reply_to_status_id":233293738510802944,"in_reply_to_user_id":10452222,"truncated":false,"in_reply_to_status_id_str":"233293738510802944","retweet_count":0,"source":"\u003Ca href=\"http:\/\/twitter.com\/download\/iphone\" rel=\"nofollow\"\u003ETwitter for iPhone\u003C\/a\u003E","id_str":"233331068873367552","geo":null,"id":233331068873367552,"created_at":"Wed Aug 08 22:37:16 +0000 2012","in_reply_to_user_id_str":"10452222","place":null,"in_reply_to_screen_name":"lrz","favorited":false,"text":"@lrz When will you be in Berlin? Headed there myself before long."}},{"score":1.0,"annotations":{"ConversationRole":"Descendant"},"kind":"Tweet","value":{"contributors":null,"coordinates":null,"user":{"show_all_inline_media":true,"id":10452222,"location":"Walifornia","follow_request_sent":null,"profile_image_url":"http:\/\/a0.twimg.com\/profile_images\/1056235466\/Screen_Shot_2010-07-06_at_1.41.21_PM_normal.png","profile_background_color":"FFFFFF","statuses_count":7718,"utc_offset":3600,"profile_image_url_https":"https:\/\/si0.twimg.com\/profile_images\/1056235466\/Screen_Shot_2010-07-06_at_1.41.21_PM_normal.png","name":"Laurent Sansonetti","default_profile":false,"profile_background_image_url":"http:\/\/a0.twimg.com\/images\/themes\/theme1\/bg.png","screen_name":"lrz","friends_count":196,"profile_link_color":"6E6E6E","protected":false,"notifications":null,"profile_use_background_image":false,"lang":"en","listed_count":233,"profile_text_color":"000000","description":"Belgian software hacker, husband, dad and cat wrangler. Founder of @HipByte. Creator and developer of @RubyMotion and @MacRuby. Former Apple employee (7 years).","followers_count":2719,"url":"http:\/\/chopine.be","is_translator":false,"created_at":"Wed Nov 21 21:48:30 +0000 2007","profile_sidebar_border_color":"181A1E","contributors_enabled":false,"verified":false,"time_zone":"Paris","geo_enabled":true,"id_str":"10452222","default_profile_image":false,"profile_background_tile":false,"profile_background_image_url_https":"https:\/\/si0.twimg.com\/images\/themes\/theme1\/bg.png","following":null,"profile_sidebar_fill_color":"EBEBEB","favourites_count":95},"retweeted":false,"in_reply_to_status_id":233338791128096768,"in_reply_to_user_id":7505382,"truncated":false,"in_reply_to_status_id_str":"233338791128096768","retweet_count":0,"source":"\u003Ca href=\"http:\/\/itunes.apple.com\/us\/app\/twitter\/id409789998?mt=12\" rel=\"nofollow\"\u003ETwitter for Mac\u003C\/a\u003E","id_str":"233339564763275264","geo":null,"id":233339564763275264,"created_at":"Wed Aug 08 23:11:02 +0000 2012","in_reply_to_user_id_str":"7505382","place":null,"in_reply_to_screen_name":"sferik","favorited":false,"text":"@sferik @al3x @eurucamp awesome, let's grab beers & kebabs :)"}}],"score":1.0,"annotations":{"FromUser":"sferik"}}]

spec/twitter/api/statuses_spec.rb

@@ -382,6 +382,24 @@
     end
   end
 
+  describe "#related_results" do
+    before do
+      stub_get("/1/related_results/show/233338791128096768.json").
+        to_return(:body => fixture("related_results.json"), :headers => {:content_type => "application/json; charset=utf-8"})
+    end
+    it "requests the correct resource" do
+      @client.related_results(233338791128096768)
+      a_get("/1/related_results/show/233338791128096768.json").
+        should have_been_made
+    end
+    it "returns statuses related to a given tweet" do
+      statuses = @client.related_results(233338791128096768)
+      statuses.should be_an Array
+      statuses.last.should be_a Twitter::Status
+      statuses.last.text.should eq "@sferik @al3x @eurucamp awesome, let's grab beers & kebabs :)"
+    end
+  end
+
   describe "#status_activity" do
     before do
       stub_get("/i/statuses/25938088801/activity/summary.json").