Implement mute functionality

Announcement: https://dev.twitter.com/discussions/28358

Rakefile

@@ -31,7 +31,7 @@ end
 
 require 'yardstick/rake/verify'
 Yardstick::Rake::Verify.new do |verify|
-  verify.threshold = 59.4
+  verify.threshold = 59.5
 end
 
 task :default => [:spec, :rubocop, :verify_measurements]

lib/twitter/rest/friends_and_followers.rb

@@ -151,7 +151,7 @@ def follow!(*args)
       #   @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)
-        parallel_user_objects_from_response(:post, '/1.1/friendships/destroy.json', args)
+        parallel_users_from_response(:post, '/1.1/friendships/destroy.json', args)
       end
       alias_method :destroy_friendship, :unfollow
       deprecate_alias :friendship_destroy, :unfollow

lib/twitter/rest/spam_reporting.rb

@@ -20,7 +20,7 @@ module SpamReporting
       #   @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 report_spam(*args)
-        parallel_user_objects_from_response(:post, '/1.1/users/report_spam.json', args)
+        parallel_users_from_response(:post, '/1.1/users/report_spam.json', args)
       end
     end
   end

lib/twitter/rest/tweets.rb

@@ -39,7 +39,7 @@ def retweets(tweet, options = {})
       # @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 [Boolean, String, Integer] :trim_user Each tweet returned in a timeline will include a user object with only the author's numerical ID when set to true, 't' or 1.
-      # @option options [Boolean] :ids_only ('false') Only return user ids instead of full user objects.
+      # @option options [Boolean] :ids_only ('false') Only return user IDs instead of full user objects.
       def retweeters_of(tweet, options = {})
         ids_only = !!options.delete(:ids_only)
         retweeters = retweets(tweet, options).collect(&:user)

lib/twitter/rest/users.rb

@@ -136,19 +136,21 @@ def update_profile_image(image, options = {})
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Array<Twitter::User>] User objects that the authenticating user is blocking.
       # @param options [Hash] A customizable set of options.
-      # @option options [Integer] :page Specifies the page of results to retrieve.
-      def blocking(options = {})
+      # @option options [Boolean] :include_entities The tweet entities node will be disincluded when set to false.
+      # @option options [Boolean, String, Integer] :skip_status Do not include user's Tweets when set to true, 't' or 1.
+      def blocked(options = {})
         perform_with_cursor(:get, '/1.1/blocks/list.json', options, :users, Twitter::User)
       end
+      deprecate_alias :blocking, :blocked
 
-      # Returns an array of numeric user ids the authenticating user is blocking
+      # Returns an array of numeric user IDs the authenticating user is blocking
       #
       # @see https://dev.twitter.com/docs/api/1.1/get/blocks/ids
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Twitter::Cursor] Numeric user IDs the authenticating user is blocking.
-      # @overload block(options = {})
+      # @overload blocked_ids(options = {})
       #   @param options [Hash] A customizable set of options.
       def blocked_ids(*args)
         arguments = Twitter::Arguments.new(args)
@@ -191,7 +193,7 @@ def block?(user, 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 block(*args)
-        parallel_user_objects_from_response(:post, '/1.1/blocks/create.json', args)
+        parallel_users_from_response(:post, '/1.1/blocks/create.json', args)
       end
 
       # Un-blocks the users specified by the authenticating user
@@ -207,7 +209,7 @@ def block(*args)
       #   @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 unblock(*args)
-        parallel_user_objects_from_response(:post, '/1.1/blocks/destroy.json', args)
+        parallel_users_from_response(:post, '/1.1/blocks/destroy.json', args)
       end
 
       # Returns extended information for up to 100 users
@@ -305,7 +307,7 @@ def user_search(query, options = {})
       #   @param options [Hash] A customizable set of options.
       #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
       def contributees(*args)
-        user_objects_from_response(:get, '/1.1/users/contributees.json', args)
+        users_from_response(:get, '/1.1/users/contributees.json', args)
       end
 
       # Returns an array of users who can contribute to the specified account
@@ -323,7 +325,7 @@ def contributees(*args)
       #   @param options [Hash] A customizable set of options.
       #   @option options [Boolean, String, Integer] :skip_status Do not include contributee's Tweets when set to true, 't' or 1.
       def contributors(*args)
-        user_objects_from_response(:get, '/1.1/users/contributors.json', args)
+        users_from_response(:get, '/1.1/users/contributors.json', args)
       end
 
       # Removes the authenticating user's profile banner image
@@ -378,6 +380,68 @@ def profile_banner(*args)
         merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options[:user_id] || arguments.options[:screen_name]
         perform_with_object(:get, '/1.1/users/profile_banner.json', arguments.options, Twitter::ProfileBanner)
       end
+
+      # Mutes the users specified by the authenticating user
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/post/mutes/users/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 muted users.
+      # @overload mute(*users)
+      #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+      # @overload mute(*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 mute(*args)
+        parallel_users_from_response(:post, '/1.1/mutes/users/create.json', args)
+      end
+
+      # Un-mutes the user specified by the authenticating user.
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/post/mutes/users/destroy
+      # @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 un-muted users.
+      # @overload unmute(*users)
+      #   @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen names, or objects.
+      # @overload unmute(*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 unmute(*args)
+        parallel_users_from_response(:post, '/1.1/mutes/users/destroy.json', args)
+      end
+
+      # Returns an array of user objects that the authenticating user is muting
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/get/mutes/users/list
+      # @rate_limited Yes
+      # @authentication Requires user context
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @return [Array<Twitter::User>] User objects that the authenticating user is muting.
+      # @param options [Hash] A customizable set of options.
+      # @option options [Boolean] :include_entities The tweet entities node will be disincluded when set to false.
+      # @option options [Boolean, String, Integer] :skip_status Do not include user's Tweets when set to true, 't' or 1.
+      def muted(options = {})
+        perform_with_cursor(:get, '/1.1/mutes/users/list.json', options, :users, Twitter::User)
+      end
+      deprecate_alias :muting, :muted
+
+      # Returns an array of numeric user IDs the authenticating user is muting
+      #
+      # @see https://dev.twitter.com/docs/api/1.1/get/mutes/users/ids
+      # @rate_limited Yes
+      # @authentication Requires user context
+      # @raise [Twitter::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @return [Twitter::Cursor] Numeric user IDs the authenticating user is muting
+      # @overload muted_ids(options = {})
+      #   @param options [Hash] A customizable set of options.
+      def muted_ids(*args)
+        arguments = Twitter::Arguments.new(args)
+        merge_user!(arguments.options, arguments.pop)
+        perform_with_cursor(:get, '/1.1/mutes/users/ids.json', arguments.options, :ids)
+      end
     end
   end
 end

lib/twitter/rest/utils.rb

@@ -62,7 +62,7 @@ def perform_with_cursor(request_method, path, options, collection_name, klass =
       # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::User>]
-      def parallel_user_objects_from_response(request_method, path, args)
+      def parallel_users_from_response(request_method, path, args)
         arguments = Twitter::Arguments.new(args)
         pmap(arguments) do |user|
           perform_with_object(request_method, path, merge_user(arguments.options, user), Twitter::User)
@@ -73,7 +73,7 @@ def parallel_user_objects_from_response(request_method, path, args)
       # @param path [String]
       # @param args [Array]
       # @return [Array<Twitter::User>]
-      def user_objects_from_response(request_method, path, args)
+      def users_from_response(request_method, path, args)
         arguments = Twitter::Arguments.new(args)
         merge_user!(arguments.options, arguments.pop || user_id) unless arguments.options[:user_id] || arguments.options[:screen_name]
         perform_with_objects(request_method, path, arguments.options, Twitter::User)

lib/twitter/source_user.rb

@@ -3,6 +3,7 @@
 module Twitter
   class SourceUser < Twitter::BasicUser
     predicate_attr_reader :all_replies, :blocking, :can_dm, :followed_by,
-                          :marked_spam, :notifications_enabled, :want_retweets
+                          :marked_spam, :muting, :notifications_enabled,
+                          :want_retweets
   end
 end

lib/twitter/user.rb

@@ -28,7 +28,7 @@ class User < Twitter::BasicUser
     alias_method :tweeted?, :status?
     predicate_attr_reader :contributors_enabled, :default_profile,
                           :default_profile_image, :follow_request_sent,
-                          :geo_enabled, :needs_phone_verification,
+                          :geo_enabled, :muting, :needs_phone_verification,
                           :notifications, :protected, :profile_background_tile,
                           :profile_use_background_image, :suspended, :verified
     define_predicate_method :translator, :is_translator

spec/fixtures/following.json

@@ -1 +1 @@
-{"relationship":{"target":{"followed_by":true,"id_str":"14100886","following":false,"screen_name":"pengwynn","id":14100886},"source":{"marked_spam":false,"notifications_enabled":false,"followed_by":false,"want_retweets":true,"id_str":"7505382","blocking":false,"all_replies":false,"following":true,"screen_name":"sferik","id":7505382}}}
+{"relationship":{"target":{"followed_by":true,"id_str":"14100886","following":false,"screen_name":"pengwynn","id":14100886},"source":{"marked_spam":false,"notifications_enabled":false,"muting":false,"followed_by":false,"want_retweets":true,"id_str":"7505382","blocking":false,"all_replies":false,"following":true,"screen_name":"sferik","id":7505382}}}

spec/twitter/rest/users_spec.rb

@@ -171,26 +171,26 @@
     end
   end
 
-  describe '#blocking' do
+  describe '#blocked' do
     before do
       stub_get('/1.1/blocks/list.json').with(:query => {:cursor => '-1'}).to_return(:body => fixture('users_list.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
     end
     it 'requests the correct resource' do
-      @client.blocking
+      @client.blocked
       expect(a_get('/1.1/blocks/list.json').with(:query => {:cursor => '-1'})).to have_been_made
     end
     it 'returns an array of user objects that the authenticating user is blocking' do
-      blocking = @client.blocking
-      expect(blocking).to be_a Twitter::Cursor
-      expect(blocking.first).to be_a Twitter::User
-      expect(blocking.first.id).to eq(7_505_382)
+      blocked = @client.blocked
+      expect(blocked).to be_a Twitter::Cursor
+      expect(blocked.first).to be_a Twitter::User
+      expect(blocked.first.id).to eq(7_505_382)
     end
     context 'with each' do
       before do
         stub_get('/1.1/blocks/list.json').with(:query => {:cursor => '1322801608223717003'}).to_return(:body => fixture('users_list2.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
       end
       it 'requests the correct resource' do
-        @client.blocking.each {}
+        @client.blocked.each {}
         expect(a_get('/1.1/blocks/list.json').with(:query => {:cursor => '-1'})).to have_been_made
         expect(a_get('/1.1/blocks/list.json').with(:query => {:cursor => '1322801608223717003'})).to have_been_made
       end
@@ -712,4 +712,86 @@
     end
   end
 
+  describe '#mute' do
+    before do
+      stub_post('/1.1/mutes/users/create.json').with(:body => {:screen_name => 'sferik'}).to_return(:body => fixture('sferik.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+    end
+    it 'requests the correct resource' do
+      @client.mute('sferik')
+      expect(a_post('/1.1/mutes/users/create.json')).to have_been_made
+    end
+    it 'returns an array of muteed users' do
+      users = @client.mute('sferik')
+      expect(users).to be_an Array
+      expect(users.first).to be_a Twitter::User
+      expect(users.first.id).to eq(7_505_382)
+    end
+  end
+
+  describe '#unmute' do
+    before do
+      stub_post('/1.1/mutes/users/destroy.json').with(:body => {:screen_name => 'sferik'}).to_return(:body => fixture('sferik.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+    end
+    it 'requests the correct resource' do
+      @client.unmute('sferik')
+      expect(a_post('/1.1/mutes/users/destroy.json').with(:body => {:screen_name => 'sferik'})).to have_been_made
+    end
+    it 'returns an array of un-muteed users' do
+      users = @client.unmute('sferik')
+      expect(users).to be_an Array
+      expect(users.first).to be_a Twitter::User
+      expect(users.first.id).to eq(7_505_382)
+    end
+  end
+
+  describe '#muted' do
+    before do
+      stub_get('/1.1/mutes/users/list.json').with(:query => {:cursor => '-1'}).to_return(:body => fixture('users_list.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+    end
+    it 'requests the correct resource' do
+      @client.muted
+      expect(a_get('/1.1/mutes/users/list.json').with(:query => {:cursor => '-1'})).to have_been_made
+    end
+    it 'returns an array of user objects that the authenticating user is muting' do
+      muted = @client.muted
+      expect(muted).to be_a Twitter::Cursor
+      expect(muted.first).to be_a Twitter::User
+      expect(muted.first.id).to eq(7_505_382)
+    end
+    context 'with each' do
+      before do
+        stub_get('/1.1/mutes/users/list.json').with(:query => {:cursor => '1322801608223717003'}).to_return(:body => fixture('users_list2.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+      end
+      it 'requests the correct resource' do
+        @client.muted.each {}
+        expect(a_get('/1.1/mutes/users/list.json').with(:query => {:cursor => '-1'})).to have_been_made
+        expect(a_get('/1.1/mutes/users/list.json').with(:query => {:cursor => '1322801608223717003'})).to have_been_made
+      end
+    end
+  end
+
+  describe '#muted_ids' do
+    before do
+      stub_get('/1.1/mutes/users/ids.json').with(:query => {:cursor => '-1'}).to_return(:body => fixture('ids_list.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+    end
+    it 'requests the correct resource' do
+      @client.muted_ids
+      expect(a_get('/1.1/mutes/users/ids.json').with(:query => {:cursor => '-1'})).to have_been_made
+    end
+    it 'returns an array of numeric user IDs the authenticating user is muting' do
+      muted_ids = @client.muted_ids
+      expect(muted_ids).to be_a Twitter::Cursor
+      expect(muted_ids.first).to eq(20_009_713)
+    end
+    context 'with each' do
+      before do
+        stub_get('/1.1/mutes/users/ids.json').with(:query => {:cursor => '1305102810874389703'}).to_return(:body => fixture('ids_list2.json'), :headers => {:content_type => 'application/json; charset=utf-8'})
+      end
+      it 'requests the correct resource' do
+        @client.muted_ids.each {}
+        expect(a_get('/1.1/mutes/users/ids.json').with(:query => {:cursor => '-1'})).to have_been_made
+        expect(a_get('/1.1/mutes/users/ids.json').with(:query => {:cursor => '1305102810874389703'})).to have_been_made
+      end
+    end
+  end
 end