twitter 4.8.1 → 5.0.0.rc.1

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

@@ -0,0 +1,219 @@
+require 'twitter/arguments'
+require 'twitter/cursor'
+require 'twitter/user'
+require 'uri'
+
+module Twitter
+  module REST
+    module API
+      module Utils
+
+        DEFAULT_CURSOR = -1
+        URI_SUBSTRING = "://"
+
+      private
+
+        # Take a URI string or Twitter::Identity object and return its ID
+        #
+        # @param object [Integer, String, URI, Twitter::Identity] An ID, URI, or object.
+        # @return [Integer]
+        def extract_id(object)
+          case object
+          when ::Integer
+            object
+          when ::String
+            object.split("/").last.to_i
+          when ::URI
+            object.path.split("/").last.to_i
+          when Twitter::Identity
+            object.id
+          end
+        end
+
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param args [Array]
+        # @return [Array<Twitter::User>]
+        def threaded_user_objects_from_response(request_method, path, args)
+          arguments = Twitter::Arguments.new(args)
+          arguments.flatten.threaded_map do |user|
+            object_from_response(Twitter::User, request_method, path, merge_user(arguments.options, user))
+          end
+        end
+
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param args [Array]
+        # @return [Array<Twitter::User>]
+        def user_objects_from_response(request_method, path, args)
+          arguments = Twitter::Arguments.new(args)
+          merge_user!(arguments.options, arguments.pop || screen_name) unless arguments.options[:user_id] || arguments.options[:screen_name]
+          objects_from_response(Twitter::User, request_method, path, arguments.options)
+        end
+
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param args [Array]
+        # @return [Array]
+        def objects_from_response_with_user(klass, request_method, path, args)
+          arguments = Twitter::Arguments.new(args)
+          merge_user!(arguments.options, arguments.pop)
+          objects_from_response(klass, request_method, path, arguments.options)
+        end
+
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param options [Hash]
+        # @return [Array]
+        def objects_from_response(klass, request_method, path, options={})
+          response = send(request_method.to_sym, path, options)[:body]
+          objects_from_array(klass, response)
+        end
+
+        # @param klass [Class]
+        # @param array [Array]
+        # @return [Array]
+        def objects_from_array(klass, array)
+          array.map do |element|
+            klass.new(element)
+          end
+        end
+
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param args [Array]
+        # @return [Array]
+        def threaded_objects_from_response(klass, request_method, path, args)
+          arguments = Twitter::Arguments.new(args)
+          arguments.flatten.threaded_map do |object|
+            id = extract_id(object)
+            object_from_response(klass, request_method, path, arguments.options.merge(:id => id))
+          end
+        end
+
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param options [Hash]
+        # @return [Object]
+        def object_from_response(klass, request_method, path, options={})
+          response = send(request_method.to_sym, path, options)
+          klass.from_response(response)
+        end
+
+        # @param collection_name [Symbol]
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param args [Array]
+        # @return [Twitter::Cursor]
+        def cursor_from_response_with_user(collection_name, klass, request_method, path, args)
+          arguments = Twitter::Arguments.new(args)
+          merge_user!(arguments.options, arguments.pop || screen_name) unless arguments.options[:user_id] || arguments.options[:screen_name]
+          cursor_from_response(collection_name, klass, request_method, path, arguments.options)
+        end
+
+        # @param collection_name [Symbol]
+        # @param klass [Class]
+        # @param request_method [Symbol]
+        # @param path [String]
+        # @param options [Hash]
+        # @return [Twitter::Cursor]
+        def cursor_from_response(collection_name, klass, request_method, path, options)
+          merge_default_cursor!(options)
+          response = send(request_method.to_sym, path, options)
+          Twitter::Cursor.from_response(response, collection_name.to_sym, klass, self, request_method, path, options)
+        end
+
+        def handle_forbidden_error(klass, error)
+          if error.message == klass::MESSAGE
+            raise klass.new
+          else
+            raise error
+          end
+        end
+
+        def merge_default_cursor!(options)
+          options[:cursor] = DEFAULT_CURSOR unless options[:cursor]
+        end
+
+        def screen_name
+          @screen_name ||= verify_credentials.screen_name
+        end
+
+        # Take a user and merge it into the hash with the correct key
+        #
+        # @param hash [Hash]
+        # @param user [Integer, String, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        # @return [Hash]
+        def merge_user(hash, user, prefix=nil)
+          merge_user!(hash.dup, user, prefix)
+        end
+
+        # Take a user and merge it into the hash with the correct key
+        #
+        # @param hash [Hash]
+        # @param user [Integer, String, URI, Twitter::User] A Twitter user ID, screen name, URI, or object.
+        # @return [Hash]
+        def merge_user!(hash, user, prefix=nil)
+          case user
+          when Integer
+            hash[[prefix, "user_id"].compact.join("_").to_sym] = user
+          when String
+            if user[URI_SUBSTRING]
+              hash[[prefix, "screen_name"].compact.join("_").to_sym] = user.split("/").last
+            else
+              hash[[prefix, "screen_name"].compact.join("_").to_sym] = user
+            end
+          when ::URI
+            hash[[prefix, "screen_name"].compact.join("_").to_sym] = user.path.split("/").last
+          when Twitter::User
+            hash[[prefix, "user_id"].compact.join("_").to_sym] = user.id
+          end
+          hash
+        end
+
+        # Take a multiple users and merge them into the hash with the correct keys
+        #
+        # @param hash [Hash]
+        # @param users [Enumerable<Integer, String, Twitter::User>] A collection of Twitter user IDs, screen_names, or objects.
+        # @return [Hash]
+        def merge_users(hash, users)
+          merge_users!(hash.dup, users)
+        end
+
+        # Take a multiple users and merge them into the hash with the correct keys
+        #
+        # @param hash [Hash]
+        # @param users [Enumerable<Integer, String, URI, Twitter::User>] A collection of Twitter user IDs, screen_names, URIs, or objects.
+        # @return [Hash]
+        def merge_users!(hash, users)
+          user_ids, screen_names = [], []
+          users.flatten.each do |user|
+            case user
+            when Integer
+              user_ids << user
+            when String
+              if user[URI_SUBSTRING]
+                screen_names << user.split("/").last
+              else
+                screen_names << user
+              end
+            when ::URI
+              screen_names << user.path.split("/").last
+            when Twitter::User
+              user_ids << user.id
+            end
+          end
+          hash[:user_id] = user_ids.join(',') unless user_ids.empty?
+          hash[:screen_name] = screen_names.join(',') unless screen_names.empty?
+          hash
+        end
+
+      end
+    end
+  end
+end

data/lib/twitter/rest/client.rb

@@ -0,0 +1,193 @@
+require 'base64'
+require 'faraday'
+require 'faraday/request/multipart'
+require 'json'
+require 'twitter/client'
+require 'twitter/error'
+require 'twitter/error/configuration_error'
+require 'twitter/rest/api/direct_messages'
+require 'twitter/rest/api/favorites'
+require 'twitter/rest/api/friends_and_followers'
+require 'twitter/rest/api/help'
+require 'twitter/rest/api/lists'
+require 'twitter/rest/api/oauth'
+require 'twitter/rest/api/places_and_geo'
+require 'twitter/rest/api/saved_searches'
+require 'twitter/rest/api/search'
+require 'twitter/rest/api/spam_reporting'
+require 'twitter/rest/api/suggested_users'
+require 'twitter/rest/api/timelines'
+require 'twitter/rest/api/trends'
+require 'twitter/rest/api/tweets'
+require 'twitter/rest/api/undocumented'
+require 'twitter/rest/api/users'
+require 'twitter/rest/request/multipart_with_file'
+require 'twitter/rest/response/parse_json'
+require 'twitter/rest/response/raise_error'
+
+module Twitter
+  module REST
+    # Wrapper for the Twitter REST API
+    #
+    # @note All methods have been separated into modules and follow the same grouping used in {http://dev.twitter.com/doc the Twitter API Documentation}.
+    # @see http://dev.twitter.com/pages/every_developer
+    class Client < Twitter::Client
+      include Twitter::REST::API::DirectMessages
+      include Twitter::REST::API::Favorites
+      include Twitter::REST::API::FriendsAndFollowers
+      include Twitter::REST::API::Help
+      include Twitter::REST::API::Lists
+      include Twitter::REST::API::OAuth
+      include Twitter::REST::API::PlacesAndGeo
+      include Twitter::REST::API::SavedSearches
+      include Twitter::REST::API::Search
+      include Twitter::REST::API::SpamReporting
+      include Twitter::REST::API::SuggestedUsers
+      include Twitter::REST::API::Timelines
+      include Twitter::REST::API::Trends
+      include Twitter::REST::API::Tweets
+      include Twitter::REST::API::Undocumented
+      include Twitter::REST::API::Users
+
+      attr_writer :bearer_token, :connection_options, :middleware
+
+      ENDPOINT = 'https://api.twitter.com'
+
+      # @return [String]
+      def bearer_token
+        if instance_variable_defined?(:@bearer_token)
+          @bearer_token
+        else
+          ENV['TWITTER_BEARER_TOKEN']
+        end
+      end
+
+      def connection_options
+        {
+          :builder => middleware,
+          :headers => {
+            :accept => 'application/json',
+            :user_agent => user_agent,
+          },
+          :request => {
+            :open_timeout => 5,
+            :timeout => 10,
+          },
+        }
+      end
+
+      # @note Faraday's middleware stack implementation is comparable to that of Rack middleware.  The order of middleware is important: the first middleware on the list wraps all others, while the last middleware is the innermost one.
+      # @see https://github.com/technoweenie/faraday#advanced-middleware-usage
+      # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
+      # @return [Faraday::Builder]
+      def middleware
+        @middleware ||= Faraday::Builder.new do |builder|
+          # Convert file uploads to Faraday::UploadIO objects
+          builder.use Twitter::REST::Request::MultipartWithFile
+          # Checks for files in the payload
+          builder.use Faraday::Request::Multipart
+          # Convert request params to "www-form-urlencoded"
+          builder.use Faraday::Request::UrlEncoded
+          # Handle error responses
+          builder.use Twitter::REST::Response::RaiseError
+          # Parse JSON response bodies
+          builder.use Twitter::REST::Response::ParseJson
+          # Set Faraday's HTTP adapter
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      # Perform an HTTP DELETE request
+      def delete(path, params={})
+        request(:delete, path, params)
+      end
+
+      # Perform an HTTP GET request
+      def get(path, params={})
+        request(:get, path, params)
+      end
+
+      # Perform an HTTP POST request
+      def post(path, params={})
+        signature_params = params.values.any?{|value| value.respond_to?(:to_io)} ? {} : params
+        request(:post, path, params, signature_params)
+      end
+
+      # Perform an HTTP PUT request
+      def put(path, params={})
+        request(:put, path, params)
+      end
+
+      # @return [Boolean]
+      def bearer_token?
+        !!bearer_token
+      end
+
+      # @return [Boolean]
+      def credentials?
+        super || bearer_token?
+      end
+
+    private
+
+      # Returns a proc that can be used to setup the Faraday::Request headers
+      #
+      # @param method [Symbol]
+      # @param path [String]
+      # @param params [Hash]
+      # @return [Proc]
+      def request_setup(method, path, params, signature_params)
+        Proc.new do |request|
+          if params.delete(:bearer_token_request)
+            request.headers[:authorization] = bearer_token_credentials_auth_header
+            request.headers[:content_type] = 'application/x-www-form-urlencoded; charset=UTF-8'
+            request.headers[:accept] = '*/*' # It is important we set this, otherwise we get an error.
+          elsif params.delete(:app_auth) || !user_token?
+            @bearer_token = token unless bearer_token?
+            request.headers[:authorization] = bearer_auth_header
+          else
+            request.headers[:authorization] = oauth_auth_header(method, ENDPOINT + path, signature_params).to_s
+          end
+        end
+      end
+
+      def request(method, path, params={}, signature_params=params)
+        request_setup = request_setup(method, path, params, signature_params)
+        connection.send(method.to_sym, path, params, &request_setup).env
+      rescue Faraday::Error::ClientError, JSON::ParserError
+        raise Twitter::Error
+      end
+
+      # Returns a Faraday::Connection object
+      #
+      # @return [Faraday::Connection]
+      def connection
+        @connection ||= Faraday.new(ENDPOINT, connection_options)
+      end
+
+      # Generates authentication header for a bearer token request
+      #
+      # @return [String]
+      def bearer_token_credentials_auth_header
+        basic_auth_token = strict_encode64("#{@consumer_key}:#{@consumer_secret}")
+        "Basic #{basic_auth_token}"
+      end
+
+      def bearer_auth_header
+        if bearer_token.is_a?(Twitter::Token) && bearer_token.bearer?
+          "Bearer #{bearer_token.access_token}"
+        else
+          "Bearer #{bearer_token}"
+        end
+      end
+
+    private
+
+      # Base64.strict_encode64 is not available on Ruby 1.8.7
+      def strict_encode64(str)
+        Base64.encode64(str).gsub("\n", "")
+      end
+
+    end
+  end
+end

data/lib/twitter/rest/request/multipart_with_file.rb

@@ -0,0 +1,36 @@
+require 'faraday'
+
+module Twitter
+  module REST
+    module Request
+      class MultipartWithFile < Faraday::Middleware
+        CONTENT_TYPE = 'Content-Type'
+
+        def call(env)
+          env[:body].each do |key, value|
+            if value.respond_to?(:to_io)
+              env[:body][key] = Faraday::UploadIO.new(value, mime_type(value.path), value.path)
+            end
+          end if env[:body].is_a?(::Hash)
+          @app.call(env)
+        end
+
+      private
+
+        def mime_type(path)
+          case path
+          when /\.jpe?g/i
+            'image/jpeg'
+          when /\.gif$/i
+            'image/gif'
+          when /\.png$/i
+            'image/png'
+          else
+            'application/octet-stream'
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/twitter/rest/response/parse_json.rb

@@ -0,0 +1,27 @@
+require 'faraday'
+require 'json'
+
+module Twitter
+  module REST
+    module Response
+      class ParseJson < Faraday::Response::Middleware
+
+        def parse(body)
+          case body
+          when /\A^\s*$\z/, nil
+            nil
+          else
+            JSON.parse(body, :symbolize_names => true)
+          end
+        end
+
+        def on_complete(env)
+          if respond_to?(:parse)
+            env[:body] = parse(env[:body]) unless [204, 301, 302, 304].include?(env[:status])
+          end
+        end
+
+      end
+    end
+  end
+end