oauth_twitter 0.1.0 → 0.2.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    OGI3NTNmYzZhNzNmYzVkMTQ4YjdkNTgyYTgyMTFhOTM4MDNkODQ1Ng==
+    MjJkZWU1ZGM2YjFmNjUyNWRhNGYzN2E1OTI3ODNkYjRhNDU4MDBkYg==
   data.tar.gz: !binary |-
-    NzBmMzgyNjk1MWJmNzFmNGUxMGExYjk3NDlkMDNhYzYyNTlmNjkzNg==
+    OTgzMjA3Zjk2YWMzNjUxYzIzYTRmODM4NjA2NWM1YzJlYjZkM2RlOA==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    NmU0NTcxNzg5OTliOWFlYzVlODFkOWZkNmRjYzg1M2M2NjhlNmY5YzIyOTE5
-    YzIwOGQ1MGM2MDVkNzRhNjUwZDIxZmQ3Y2M0MWQ0MjU1N2ZhNGMwMTU2NDk2
-    YzVmOWQ2MjVkZTlmMTJlZjY2M2NlYmIyYjgyNjRjZWE1YmUwZjY=
+    YzA5YzM5NjUxMDYxZDRkNDU2YjRmZTYzY2FjMGQ2MGQ5ZGEwZGYxMGEwODA4
+    MmQ3MTY0Zjg4ODQ2YzE1ZDcxMDViMDBjY2MzNjIzMWFlZmM3ZGFjNjUzMTA5
+    MjljNmQxZGE2OTdkYTU0OThkOGRhNWFiODI1YTI4OTIzMGE3Y2I=
   data.tar.gz: !binary |-
-    ZmZhZDM2YjYyOTE1ODRlNDI5ZmMyMGExMjYwNDEwZjc2YzY0ZmIyNDlhMGNm
-    MzM4NGUzZmQxMzY1NjBjZGQzYmM1ZTQzNTM0MjBmMzYyNjJhMjA3YTYxNTYz
-    YWEwZmI3MzJiMDgwYmRjZjYwYjZlYzA3OTgyNTE5MzM0Mzg4M2I=
+    NjI0MDE3NDczYzAzMDJkZDczNTE0N2RlODY5Y2YzOTA5OWFlZjE4ZjM1ZDI4
+    YWFkNmZhYjg3N2Q1NDkwZDU0Njk2M2Y3YjNmMGIxOTI5MjlkNGNlNTlmMDkz
+    NDA4OTViMjBhMGEyOGFlN2Y4MDllMjI4ZTc4MDdmODc4ZjcxNzI=

data/README.md

@@ -1,29 +1,64 @@
 # OauthTwitter
 
-TODO: Write a gem description
+An OAuth library to interact with Twitter API v1.1, by simply calling methods on instances. The methods name is designed to be similar to Twitter's API. For example:
 
-## Installation
+If you want to load home timeline for certain user, just do:
+
+	response = your_instance.home_timeline
+	response.each {|r| process_response(r)}
+
+The response is a nested hash that structured the same as Twitter's response JSON.
+
+## 1. Installation
 
 Add this line to your application's Gemfile:
 
     gem 'oauth_twitter'
 
-And then execute:
+Then execute:
 
-    $ bundle
+    $ bundle install
 
-Or install it yourself as:
+Or install it yourself use:
 
     $ gem install oauth_twitter
+    
+## 2. Setup and Usage
+
+1) Configure __OauthTwitter__ on app initialization:
+
+	OauthTwitter::Config.setup do |c|
+	  c.consumer_key = "#{your_twitter_consumer_key}"
+	  c.consumer_secret = "#{twitter_consumer_secret}"
+	  
+	  # Your don't have to include following in your initializer,
+	  # but OauthTwitter will fallback to this url 
+	  # if you don't provide them in certain functions' args
+	  
+	  c.oauth_callback = "#{oauth_request_token_callback_address}"
+	end
+
+2) Include `OauthTwitter` in your class like:
+	
+	class YouClass
+	  include OauthTwitter
+	  …
+	end
+
+3) Implement `attr_accessor` in your class, so __OauthTwitter__ could load tokens from `YourClass`:
+	
+	class YourClass
+	  include OauthTwitter
+	  
+	  attr_accessor :oauth_token, :oauth_token_secret
+	  ...
+	end
 
-## Usage
+4) You can start calling methods on `YourClass`:
 
-TODO: Write usage instructions here
+	you_instance = YourClass.new
+	you_instance.request_token("callback_url")
 
-## Contributing
+## Documentation
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Still a work in process...

data/lib/oauth_twitter/api/friends.rb

@@ -2,16 +2,102 @@ module OauthTwitter
   module API
     module Friends
       PATH = {
-        friends_ids: '/1.1/friends/ids.json'
+        :friendships_no_retweets_ids => '/1.1/friendships/no_retweets/ids.json',
+        :friends_ids                 => '/1.1/friends/ids.json',
+        :followers_ids               => '/1.1/followers/ids.json',
+        :friendships_lookup          => '/1.1/friendships/lookup.json',
+        :friendships_incoming        => '/1.1/friendships/incoming.json',
+        :friendships_outgoing        => '/1.1/friendships/outgoing.json',
+        :friendships_create          => '/1.1/friendships/create.json',
+        :friendships_destroy         => '/1.1/friendships/destroy.json',
+        :friendships_update          => '/1.1/friendships/update.json',
+        :friendships_show            => '/1.1/friendships/show.json',
+        :friends_list                => '/1.1/friends/list.json',
+        :followers_list              => '/1.1/followers/list.json'
       }
 
-      def friends_ids(user_id)
+      def friendships_no_retweets_ids(params={}, options={})
+        query = params.clone
         oauth = oauth_params(true)
-        query = {
-          user_id: user_id,
-          count: 5000
-        }
-        return send_request(:GET, PATH[:friends_ids], query, oauth)
+        response = send_request(:GET, PATH[:friendships_no_retweets_ids], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friends_ids(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friends_ids], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def followers_ids(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:followers_ids], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_lookup(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friendships_lookup], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_incoming(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friendships_incoming], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_outgoing(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friendships_outgoing], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_create(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:POST, PATH[:friendships_create], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_destroy(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:POST, PATH[:friendships_destroy], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_update(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:POST, PATH[:friendships_update], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friendships_show(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friendships_show], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def friends_list(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:friends_list], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def followers_list(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:followers_list], query, oauth)
+        return results_with_error_explained(response, options)
       end
 
     end

data/lib/oauth_twitter/api/oauth.rb

@@ -2,21 +2,38 @@ module OauthTwitter
   module API
     module Oauth
       PATH = {
-        request_token: '/oauth/request_token',
-         access_token: '/oauth/access_token'
+        :oauth_authenticate => '/oauth/authenticate',
+        :oauth_authorize => '/oauth/authorize',
+        :oauth_access_token => '/oauth/access_token',
+        :oauth_request_token => '/oauth/request_token'
       }
 
-      def request_token(oauth_callback=nil)
-        callback_url = oauth_callback || Config.oauth_callback
-        oauth = oauth_params(
-          false,
-          {oauth_callback: callback_url})
-        return send_request(:POST, PATH[:request_token], nil, oauth)
+      def oauth_authenticate(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:oauth_authenticate], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def oauth_authorize(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:oauth_authorize], query, oauth)
+        return results_with_error_explained(response, options)
       end
 
-      def access_token(oauth_verifier)
+      def oauth_access_token(params={}, options={})
+        query = params.clone
         oauth = oauth_params(true)
-        return send_request(:POST, PATH[:access_token], {oauth_verifier: oauth_verifier}, oauth)
+        response = send_request(:POST, PATH[:oauth_access_token], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def oauth_request_token(params={}, options={})
+        callback_url = params[:oauth_callback] || Config.oauth_callback
+        oauth = oauth_params(false, {oauth_callback: callback_url})
+        response = send_request(:POST, PATH[:oauth_request_token], nil, oauth)
+        return results_with_error_explained(response, options)
       end
 
     end

data/lib/oauth_twitter/api/statuses.rb

@@ -1,21 +1,83 @@
 module OauthTwitter
   module API
     module Statuses
+
+      ##
+      # Url path of status API
       PATH = {
-        home_timeline: "/1.1/statuses/home_timeline.json"
+        :mentions_timeline => '/1.1/statuses/mentions_timeline.json',
+        :user_timeline     => '/1.1/statuses/user_timeline.json',
+        :home_timeline     => '/1.1/statuses/home_timeline.json',
+        :retweets_of_me    => '/1.1/statuses/retweets_of_me.json'
       }
 
-      def home_timeline(since_id=nil)
-        oauth = oauth_params(true)
-        query = {
-          count: 200,
-          trim_user: false,
-          exclude_replies: true,
-          contributor_details: false,
-          include_entities: true
-        }
-        query[:since_id] = since_id if since_id
-        return send_request(:GET, PATH[:home_timeline], query, oauth)
+      ##
+      # Load current user's Tweet with @user_name mentioned, include user
+      # mention themselves.
+      #
+      # @param params [Hash] always supply a user_id or screen_name. If both
+      #   are supplied, user_id will be used
+      # @param options [Hash]
+      #
+      # @return [Array]
+      def mentions_timeline(params={}, options={})
+        query = params.clone
+        return send_status_request(:mentions_timeline, query, options)
+      end
+
+      ##
+      #
+      def user_timeline(params={}, options={})
+        query = params.clone
+        return send_status_request(:user_timeline, query, options)
+      end
+
+      ##
+      # Load current use's (determined by oauth_token and oauth_token_secret
+      # variables) home time.
+      #
+      # @param params [Hash] parameters that consistent with Twitter's API.
+      # @param options [Hash] options to perform more operations.
+      #
+      #   :pages => [Int] indicate many pages will return, for example,
+      #   if count = 5, pages = 3, then it will return 5 * 3 = 15 tweets
+      #   from the user's timeline. Cursor stops if response no more reponse.
+      #
+      #   :explain_error => [Bool] if true, will return a HTTP Code indicate
+      #   the error
+      #
+      # @return [Array] hash structured the same as Twitter's JSON response.
+      #
+      #   if :explain_error => true, will return array like:
+      #   [json, response.body, response.code]
+      def home_timeline(params={}, options={})
+        query = params.clone
+        return send_status_request(:home_timeline, query, options)
+      end
+
+      ##
+      #
+      def retweets_of_me(params={}, options={})
+        query = params.clone
+        return send_status_request(:retweets_of_me, query, options)
+      end
+
+      private
+      ##
+      # Private helper for each of the status API
+      def send_status_request(api_symbol, query, options)
+        full_response = []
+        response = nil
+        options[:pages] ||= 1
+        options[:pages].times do |page_num|
+          oauth = oauth_params(true)
+          response = send_request(:GET, PATH[api_symbol], query, oauth)
+          break unless response[0]
+          break if response[1].empty?
+          full_response += response[1]
+          query[:max_id] = response[1].last['id'] - 1
+        end
+        return results_with_error_explained(response, options, full_response)
       end
 
     end

data/lib/oauth_twitter/api/users.rb

@@ -2,26 +2,77 @@ module OauthTwitter
   module API
     module Users
       PATH = {
-        users_lookup: "/1.1/users/lookup.json"
+        :users_lookup         => '/1.1/users/lookup.json',
+        :users_show           => '/1.1/users/show.json',
+        :users_search         => '/1.1/users/search.json',
+        :users_contributees   => '/1.1/users/contributees.json',
+        :users_contributors   => '/1.1/users/contributors.json',
+        :users_profile_banner => '/1.1/users/profile_banner.json'
       }
 
-      def users_lookup(id_array, include_entities=true)
-        oauth = oauth_params(true)
+      ##
+      # @param params [Hash] :screen_name => Array, :user_id => Array,
+      #   :include_entities => Boolean
+      def users_lookup(params, options={})
+        query = params.clone
+        users_array = query[:screen_name] || query[:user_id]
+        users_array_type = (query[:screen_name]) ? :screen_name : :user_id
         # slice id_array for multiple request
-        num_of_set = id_array.size / 100
-        num_of_set += 1 if id_array.size % 100 > 0
-        id_sets = num_of_set.times.map {|i| id_array.slice(i*100, (i+1)*100)}
+        num_of_set = users_array.size / 100
+        num_of_set += 1 if users_array.size % 100 > 0
+        id_sets = num_of_set.times.map {|i| users_array.slice(i*100, (i+1)*100)}
         # send request
-        result = []
+        full_response = []
+        response = nil
         id_sets.each do |set|
-          query = {
-            user_id: set.join(','),
-            include_entities: include_entities
-          }
+          oauth = oauth_params(true)
+          query[users_array_type] = set.join(',')
           method = set.size <= 10 ? :GET : :POST
-          result += send_request(method, PATH[:users_lookup], query, oauth)
+          response = send_request(method, PATH[:users_lookup], query, oauth)
+          if response[0]
+            full_response += response[1]
+          else
+            break
+          end
         end
-        return result
+        return results_with_error_explained(response, options, full_response)
+      end
+
+      def users_show(params, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:users_show], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def users_search(params, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:users_search], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def users_contributees(params, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:users_contributees], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      def users_contributors(params, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:users_contributors], query, oauth)
+        return results_with_error_explained(response, options)
+      end
+
+      ##
+      #
+      def users_profile_banner(params={}, options={})
+        query = params.clone
+        oauth = oauth_params(true)
+        response = send_request(:GET, PATH[:users_profile_banner], query, oauth)
+        return results_with_error_explained(response, options)
       end
 
     end

data/lib/oauth_twitter/helper.rb

@@ -7,24 +7,44 @@ require "multi_json"
 
 module OauthTwitter
   module Helper
+
+    ##
+    # Generate oauth params
     def oauth_params(include_oauth_token=true, addional_oauth_params={})
       oauth = {
-        oauth_consumer_key: Config.consumer_key,
-        oauth_nonce: SecureRandom.hex(21),
-        oauth_signature_method: "HMAC-SHA1",
-        oauth_timestamp: Time.now.to_i,
-        oauth_version: "1.0"
+        :oauth_consumer_key     => Config.consumer_key,
+        :oauth_nonce            => SecureRandom.hex(21),
+        :oauth_signature_method => "HMAC-SHA1",
+        :oauth_timestamp        => Time.now.to_i,
+        :oauth_version          => "1.0"
       }
-      oauth[:oauth_token] = self.oauth_token if include_oauth_token
+      oauth[:oauth_token] = self.oauth_token if include_oauth_token == true
       return oauth.merge(addional_oauth_params)
     end
 
+    ##
+    # percent_encode disallowed char
     RESERVED_CHARS = /[^a-zA-Z0-9\-\.\_\~]/
+
+    ##
+    # percent_encode strigns
     def self.percent_encode(raw)
       return URI.escape(raw.to_s, RESERVED_CHARS)
     end
 
+    ##
+    # Twitter API root url
     HOST = "https://api.twitter.com"
+
+    ##
+    # Helper method to send request to Twitter API
+    # @param method [Symbol] HTTP method, support :GET or :POST
+    # @param path [String] request url path
+    # @param query [Hash] request parameters
+    # @param oauth [Hash] oauth request header
+    #
+    # @return [Array] 0: indicate successful or not, 1: response content,
+    #   2: error messages if any
     def send_request(method, path, query, oauth)
       # Make base_str and signing_key
       base_str = method.to_s.upcase << "&"
@@ -36,7 +56,7 @@ module OauthTwitter
       signing_key = String.new(Config.consumer_secret) << "&"
       signing_key << self.oauth_token_secret if hash[:oauth_token]
       signature = Helper.sign(base_str, signing_key)
-      signed_oauth = oauth.merge(oauth_signature: signature)
+      signed_oauth = oauth.merge(:oauth_signature => signature)
       # Header
       auth_header = Helper.auth_header(signed_oauth)
       # HTTP request
@@ -52,29 +72,23 @@ module OauthTwitter
         request = Net::HTTP::Get.new(uri.request_uri)
       end
       request["Authorization"] = auth_header
-      # Response
-      begin
-        response = https.request(request)
-      rescue SocketError
-        return false
-      end
+      ##
+      # Might raise SocketError if no internet connection
+      response = https.request(request)
       case response.code
       when "200"
         begin
-          return MultiJson.load(response.body)
+          return true, MultiJson.load(response.body)
         rescue MultiJson::LoadError
-          return Rack::Utils.parse_nested_query(response.body)
+          return true, Rack::Utils.parse_nested_query(response.body)
         end
-      when "401"
-        return false
-      when "408"
-        return false
       else
-        p response.code, response.body
-        raise "HTTP request failed."
+        return false, MultiJson.load(response.body), response.code
       end
     end
 
+    ##
+    # Sign oauth params
     def self.sign(base_str, signing_key)
       hex_str = OpenSSL::HMAC.hexdigest(
         OpenSSL::Digest::Digest.new('sha1'),
@@ -88,5 +102,18 @@ module OauthTwitter
       params = signed_oauth.map { |key, val| "#{key}=\"#{val}\"" }
       return "OAuth " << params.join(",")
     end
+
+    def results_with_error_explained(response, options, full_response=nil)
+      if full_response && options[:explain_error] == true
+        return response[0] ? [response[0], full_response] : (response + [full_response])
+      elsif full_response
+        return full_response
+      elsif options[:explain_error] == true
+        return response
+      else
+        return response[0] ? response[1] : false
+      end
+    end
+
   end
 end

data/lib/oauth_twitter/version.rb

@@ -1,3 +1,3 @@
 module OauthTwitter
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/oauth_twitter.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = OauthTwitter::VERSION
   spec.authors       = ["Daiwei Lu"]
   spec.email         = ["daiweilu123@gmail.com"]
-  spec.description   = %q{Simple twitter oauth api to add methods to module for rails module.}
-  spec.summary       = %q{Include module to add methods for rails module.}
-  spec.homepage      = ""
+  spec.description   = %q{An OAuth library to interact with Twitter API v1.1, by simply calling methods on instances.}
+  spec.summary       = %q{Load data from Twitter API}
+  spec.homepage      = "https://github.com/daiweilu/oauth_twitter"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: oauth_twitter
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Daiwei Lu
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-04 00:00:00.000000000 Z
+date: 2013-05-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,7 +66,8 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.7'
-description: Simple twitter oauth api to add methods to module for rails module.
+description: An OAuth library to interact with Twitter API v1.1, by simply calling
+  methods on instances.
 email:
 - daiweilu123@gmail.com
 executables: []
@@ -87,7 +88,7 @@ files:
 - lib/oauth_twitter/helper.rb
 - lib/oauth_twitter/version.rb
 - oauth_twitter.gemspec
-homepage: ''
+homepage: https://github.com/daiweilu/oauth_twitter
 licenses:
 - MIT
 metadata: {}
@@ -110,5 +111,6 @@ rubyforge_project:
 rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
-summary: Include module to add methods for rails module.
+summary: Load data from Twitter API
 test_files: []
+has_rdoc: