twitter 4.8.1 → 5.0.0

data/lib/twitter/rate_limit.rb

@@ -1,30 +1,26 @@
 module Twitter
-  class RateLimit
-    attr_reader :attrs
-    alias to_hash attrs
-
-    # @return [Twitter::RateLimit]
-    def initialize(attrs={})
-      @attrs = attrs
-    end
+  class RateLimit < Twitter::Base
 
     # @return [Integer]
     def limit
       limit = @attrs['x-rate-limit-limit']
       limit.to_i if limit
     end
+    memoize :limit
 
     # @return [Integer]
     def remaining
       remaining = @attrs['x-rate-limit-remaining']
       remaining.to_i if remaining
     end
+    memoize :remaining
 
     # @return [Time]
     def reset_at
       reset = @attrs['x-rate-limit-reset']
       Time.at(reset.to_i) if reset
     end
+    memoize :reset_at
 
     # @return [Integer]
     def reset_in
@@ -32,14 +28,5 @@ module Twitter
     end
     alias retry_after reset_in
 
-    # Update the attributes of a RateLimit
-    #
-    # @param attrs [Hash]
-    # @return [Twitter::RateLimit]
-    def update(attrs)
-      @attrs.update(attrs)
-      self
-    end
-
   end
 end

data/lib/twitter/relationship.rb

@@ -2,6 +2,8 @@ require 'twitter/base'
 
 module Twitter
   class Relationship < Twitter::Base
+    object_attr_reader :SourceUser, :source
+    object_attr_reader :TargetUser, :target
 
     # Initializes a new object
     #
@@ -11,24 +13,5 @@ module Twitter
       @attrs = attrs[:relationship]
     end
 
-    # @return [Twitter::SourceUser]
-    def source
-      @source ||= Twitter::SourceUser.fetch_or_new(@attrs[:source])
-    end
-
-    # @return [Twitter::TargetUser]
-    def target
-      @target ||= Twitter::TargetUser.fetch_or_new(@attrs[:target])
-    end
-
-    # Update the attributes of a Relationship
-    #
-    # @param attrs [Hash]
-    # @return [Twitter::Relationship]
-    def update(attrs)
-      @attrs.update(attrs[:relationship]) unless attrs[:relationship].nil?
-      self
-    end
-
   end
 end

data/lib/twitter/rest/api/direct_messages.rb

@@ -0,0 +1,138 @@
+require 'twitter/arguments'
+require 'twitter/direct_message'
+require 'twitter/rest/api/utils'
+require 'twitter/user'
+
+module Twitter
+  module REST
+    module API
+      module DirectMessages
+        include Twitter::REST::API::Utils
+
+        # Returns the 20 most recent direct messages sent to the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages
+        # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::DirectMessage>] Direct messages sent to the authenticating user.
+        # @param options [Hash] A customizable set of options.
+        # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
+        # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
+        # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
+        # @option options [Integer] :page Specifies the page of results to retrieve.
+        def direct_messages_received(options={})
+          objects_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages.json", options)
+        end
+
+        # Returns the 20 most recent direct messages sent by the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/sent
+        # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::DirectMessage>] Direct messages sent by the authenticating user.
+        # @param options [Hash] A customizable set of options.
+        # @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
+        # @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
+        # @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
+        # @option options [Integer] :page Specifies the page of results to retrieve.
+        def direct_messages_sent(options={})
+          objects_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/sent.json", options)
+        end
+
+        # Returns a direct message
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
+        # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::DirectMessage] The requested messages.
+        # @param id [Integer] A direct message ID.
+        # @param options [Hash] A customizable set of options.
+        def direct_message(id, options={})
+          options[:id] = id
+          object_from_response(Twitter::DirectMessage, :get, "/1.1/direct_messages/show.json", options)
+        end
+
+        # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::DirectMessage>] The requested messages.
+        # @overload direct_messages(options={})
+        #   Returns the 20 most recent direct messages sent to the authenticating user
+        #
+        #   @see https://dev.twitter.com/docs/api/1.1/get/direct_messages
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
+        #   @option options [Integer] :max_id Returns results with an ID less than (that is, older than) or equal to the specified ID.
+        #   @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 200.
+        #   @option options [Integer] :page Specifies the page of results to retrieve.
+        # @overload direct_messages(*ids)
+        #   Returns direct messages
+        #
+        #   @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
+        #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
+        # @overload direct_messages(*ids, options)
+        #   Returns direct messages
+        #
+        #   @see https://dev.twitter.com/docs/api/1.1/get/direct_messages/show
+        #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
+        #   @param options [Hash] A customizable set of options.
+        def direct_messages(*args)
+          arguments = Twitter::Arguments.new(args)
+          if arguments.empty?
+            direct_messages_received(arguments.options)
+          else
+            arguments.flatten.threaded_map do |id|
+              direct_message(id, arguments.options)
+            end
+          end
+        end
+
+        # Destroys direct messages
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/direct_messages/destroy
+        # @note This method requires an access token with RWD (read, write & direct message) permissions. Consult The Application Permission Model for more information.
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::DirectMessage>] Deleted direct message.
+        # @overload destroy_direct_message(*ids)
+        #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
+        # @overload destroy_direct_message(*ids, options)
+        #   @param ids [Enumerable<Integer>] A collection of direct message IDs.
+        #   @param options [Hash] A customizable set of options.
+        def destroy_direct_message(*args)
+          threaded_objects_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/destroy.json", args)
+        end
+        deprecate_alias :direct_message_destroy, :destroy_direct_message
+
+        # Sends a new direct message to the specified user from the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/direct_messages/new
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::DirectMessage] The sent message.
+        # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        # @param text [String] The text of your direct message, up to 140 characters.
+        # @param options [Hash] A customizable set of options.
+        def create_direct_message(user, text, options={})
+          merge_user!(options, user)
+          options[:text] = text
+          object_from_response(Twitter::DirectMessage, :post, "/1.1/direct_messages/new.json", options)
+        end
+        alias d create_direct_message
+        alias m create_direct_message
+        alias dm create_direct_message
+        deprecate_alias :direct_message_create, :create_direct_message
+
+      end
+    end
+  end
+end

data/lib/twitter/rest/api/favorites.rb

@@ -0,0 +1,115 @@
+require 'twitter/arguments'
+require 'twitter/error/already_favorited'
+require 'twitter/error/forbidden'
+require 'twitter/rest/api/utils'
+require 'twitter/tweet'
+require 'twitter/user'
+
+module Twitter
+  module REST
+    module API
+      module Favorites
+        include Twitter::REST::API::Utils
+
+        # @see https://dev.twitter.com/docs/api/1.1/get/favorites/list
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::Tweet>] favorite Tweets.
+        # @overload favorites(options={})
+        #   Returns the 20 most recent favorite Tweets for the authenticating user
+        #
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100.
+        #   @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
+        # @overload favorites(user, options={})
+        #   Returns the 20 most recent favorite Tweets for the specified user
+        #
+        #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :count Specifies the number of records to retrieve. Must be less than or equal to 100.
+        #   @option options [Integer] :since_id Returns results with an ID greater than (that is, more recent than) the specified ID.
+        def favorites(*args)
+          arguments = Twitter::Arguments.new(args)
+          merge_user!(arguments.options, arguments.pop) if arguments.last
+          objects_from_response(Twitter::Tweet, :get, "/1.1/favorites/list.json", arguments.options)
+        end
+
+        # Un-favorites the specified Tweets as the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/favorites/destroy
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::Tweet>] The un-favorited Tweets.
+        # @overload unfavorite(*tweets)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        # @overload unfavorite(*tweets, options)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        #   @param options [Hash] A customizable set of options.
+        def unfavorite(*args)
+          threaded_objects_from_response(Twitter::Tweet, :post, "/1.1/favorites/destroy.json", args)
+        end
+        alias destroy_favorite unfavorite
+        deprecate_alias :favorite_destroy, :unfavorite
+
+        # Favorites the specified Tweets as the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/favorites/create
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::Tweet>] The favorited Tweets.
+        # @overload favorite(*tweets)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        # @overload favorite(*tweets, options)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        #   @param options [Hash] A customizable set of options.
+        def favorite(*args)
+          arguments = Twitter::Arguments.new(args)
+          arguments.flatten.threaded_map do |tweet|
+            id = extract_id(tweet)
+            begin
+              object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", arguments.options.merge(:id => id))
+            rescue Twitter::Error::Forbidden => error
+              raise unless error.message == Twitter::Error::AlreadyFavorited::MESSAGE
+            end
+          end.compact
+        end
+        alias fav favorite
+        alias fave favorite
+        deprecate_alias :favorite_create, :favorite
+
+        # Favorites the specified Tweets as the authenticating user and raises an error if one has already been favorited
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/favorites/create
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::AlreadyFavorited] Error raised when tweet has already been favorited.
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::Tweet>] The favorited Tweets.
+        # @overload favorite(*tweets)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        # @overload favorite(*tweets, options)
+        #   @param tweets [Enumerable<Integer, String, URI, Twitter::Tweet>] A collection of Tweet IDs, URIs, or objects.
+        #   @param options [Hash] A customizable set of options.
+        def favorite!(*args)
+          arguments = Twitter::Arguments.new(args)
+          arguments.flatten.threaded_map do |tweet|
+            id = extract_id(tweet)
+            begin
+              object_from_response(Twitter::Tweet, :post, "/1.1/favorites/create.json", arguments.options.merge(:id => id))
+            rescue Twitter::Error::Forbidden => error
+              handle_forbidden_error(Twitter::Error::AlreadyFavorited, error)
+            end
+          end
+        end
+        alias create_favorite! favorite!
+        alias fav! favorite!
+        alias fave! favorite!
+        deprecate_alias :favorite_create!, :favorite!
+
+      end
+    end
+  end
+end

data/lib/twitter/rest/api/friends_and_followers.rb

@@ -0,0 +1,287 @@
+require 'twitter/arguments'
+require 'twitter/cursor'
+require 'twitter/error/forbidden'
+require 'twitter/relationship'
+require 'twitter/rest/api/utils'
+require 'twitter/user'
+
+module Twitter
+  module REST
+    module API
+      module FriendsAndFollowers
+        include Twitter::REST::API::Utils
+
+        # @see https://dev.twitter.com/docs/api/1.1/get/friends/ids
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @overload friend_ids(options={})
+        #   Returns an array of numeric IDs for every user the authenticated user is following
+        #
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+        # @overload friend_ids(user, options={})
+        #   Returns an array of numeric IDs for every user the specified user is following
+        #
+        #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        def friend_ids(*args)
+          cursor_from_response_with_user(:ids, nil, :get, "/1.1/friends/ids.json", args)
+        end
+
+        # @see https://dev.twitter.com/docs/api/1.1/get/followers/ids
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @overload follower_ids(options={})
+        #   Returns an array of numeric IDs for every user following the authenticated user
+        #
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        # @overload follower_ids(user, options={})
+        #   Returns an array of numeric IDs for every user following the specified user
+        #
+        #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+        def follower_ids(*args)
+          cursor_from_response_with_user(:ids, nil, :get, "/1.1/followers/ids.json", args)
+        end
+
+        # Returns the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none.
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/lookup
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::User>] The requested users.
+        # @overload friendships(*users)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        # @overload friendships(*users, options)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        #   @param options [Hash] A customizable set of options.
+        def friendships(*args)
+          arguments = Twitter::Arguments.new(args)
+          merge_users!(arguments.options, arguments)
+          objects_from_response(Twitter::User, :get, "/1.1/friendships/lookup.json", arguments.options)
+        end
+
+        # Returns an array of numeric IDs for every user who has a pending request to follow the authenticating user
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/incoming
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @param options [Hash] A customizable set of options.
+        # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        def friendships_incoming(options={})
+          cursor_from_response(:ids, nil, :get, "/1.1/friendships/incoming.json", options)
+        end
+
+        # Returns an array of numeric IDs for every protected user for whom the authenticating user has a pending follow request
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/outgoing
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @param options [Hash] A customizable set of options.
+        # @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        def friendships_outgoing(options={})
+          cursor_from_response(:ids, nil, :get, "/1.1/friendships/outgoing.json", options)
+        end
+
+        # Allows the authenticating user to follow the specified users, unless they are already followed
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/friendships/create
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::User>] The followed users.
+        # @overload follow(*users)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        # @overload follow(*users, options)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Boolean] :follow (false) Enable notifications for the target user.
+        def follow(*args)
+          arguments = Twitter::Arguments.new(args)
+          existing_friends = Thread.new do
+            friend_ids.to_a
+          end
+          new_friends = Thread.new do
+            users(args).map(&:id)
+          end
+          follow!(new_friends.value - existing_friends.value, arguments.options)
+        end
+        alias create_friendship follow
+        deprecate_alias :friendship_create, :follow
+
+        # Allows the authenticating user to follow the specified users
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/friendships/create
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::User>] The followed users.
+        # @overload follow!(*users)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        # @overload follow!(*users, options)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Boolean] :follow (false) Enable notifications for the target user.
+        def follow!(*args)
+          arguments = Twitter::Arguments.new(args)
+          arguments.flatten.threaded_map do |user|
+            begin
+              object_from_response(Twitter::User, :post, "/1.1/friendships/create.json", merge_user(arguments.options, user))
+            rescue Twitter::Error::Forbidden
+              # This error will be raised if the user doesn't have permission to
+              # follow list_member, for whatever reason.
+            end
+          end.compact
+        end
+        alias create_friendship! follow!
+        deprecate_alias :friendship_create!, :follow!
+
+        # Allows the authenticating user to unfollow the specified users
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/friendships/destroy
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Twitter::User>] The unfollowed users.
+        # @overload unfollow(*users)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        # @overload unfollow(*users, options)
+        #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+        #   @param options [Hash] A customizable set of options.
+        def unfollow(*args)
+          threaded_user_objects_from_response(:post, "/1.1/friendships/destroy.json", args)
+        end
+        alias destroy_friendship unfollow
+        deprecate_alias :friendship_destroy, :unfollow
+
+        # Allows one to enable or disable retweets and device notifications from the specified user.
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/post/friendships/update
+        # @rate_limited No
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Relationship]
+        # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        # @param options [Hash] A customizable set of options.
+        # @option options [Boolean] :device Enable/disable device notifications from the target user.
+        # @option options [Boolean] :retweets Enable/disable retweets from the target user.
+        def friendship_update(user, options={})
+          merge_user!(options, user)
+          object_from_response(Twitter::Relationship, :post, "/1.1/friendships/update.json", options)
+        end
+
+        # Returns detailed information about the relationship between two users
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Relationship]
+        # @param source [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the source user.
+        # @param target [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the target user.
+        # @param options [Hash] A customizable set of options.
+        def friendship(source, target, options={})
+          merge_user!(options, source, "source")
+          options[:source_id] = options.delete(:source_user_id) unless options[:source_user_id].nil?
+          merge_user!(options, target, "target")
+          options[:target_id] = options.delete(:target_user_id) unless options[:target_user_id].nil?
+          object_from_response(Twitter::Relationship, :get, "/1.1/friendships/show.json", options)
+        end
+        alias friendship_show friendship
+        alias relationship friendship
+
+        # Test for the existence of friendship between two users
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Boolean] true if user_a follows user_b, otherwise false.
+        # @param source [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the source user.
+        # @param target [Integer, String, Twitter::User] The Twitter user ID, screen name, or object of the target user.
+        # @param options [Hash] A customizable set of options.
+        def friendship?(source, target, options={})
+          friendship(source, target, options).source.following?
+        end
+
+        # Returns a cursored collection of user objects for users following the specified user.
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/followers/list
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @overload followers(options={})
+        #   Returns a cursored collection of user objects for users following the authenticated user.
+        #
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+        #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+        #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+        # @overload followers(user, options={})
+        #   Returns a cursored collection of user objects for users following the specified user.
+        #
+        #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+        #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+        def followers(*args)
+          cursor_from_response_with_user(:users, Twitter::User, :get, "/1.1/followers/list.json", args)
+        end
+
+        # Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends").
+        #
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/show
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Twitter::Cursor]
+        # @overload friends(options={})
+        #   Returns a cursored collection of user objects for every user the authenticated user is following (otherwise known as their "friends").
+        #
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. This is recommended for users who are following many users. Provide a value of -1 to begin paging. Provide values as returned in the response body's next_cursor and previous_cursor attributes to page back and forth in the list.
+        #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+        #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+        # @overload friends(user, options={})
+        #   Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends").
+        #
+        #   @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        #   @param options [Hash] A customizable set of options.
+        #   @option options [Integer] :cursor (-1) Breaks the results into pages. Provide values as returned in the response objects's next_cursor and previous_cursor attributes to page back and forth in the list.
+        #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
+        #   @option options [Boolean, String, Integer] :include_user_entities The user entities node will be disincluded when set to false.
+        def friends(*args)
+          cursor_from_response_with_user(:users, Twitter::User, :get, "/1.1/friends/list.json", args)
+        end
+        alias following friends
+
+        # Returns a collection of user IDs that the currently authenticated user does not want to receive retweets from.
+        # @see https://dev.twitter.com/docs/api/1.1/get/friendships/no_retweets/ids
+        # @rate_limited Yes
+        # @authentication Requires user context
+        # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+        # @return [Array<Integer>]
+        # @param options [Hash] A customizable set of options.
+        def no_retweet_ids(options={})
+          get("/1.1/friendships/no_retweets/ids.json", options)[:body].map(&:to_i)
+        end
+        alias no_retweets_ids no_retweet_ids
+
+      end
+    end
+  end
+end