pk-twitter_oauth 0.2.1

data/README.textile

@@ -0,0 +1,92 @@
+h1. Twitter OAuth REST API client library for Ruby
+
+h2. Install
+
+h3. Ruby 1.8
+
+You need to require and install oauth manually. You can use either official 
+oauth gem or use any of the forks on the github.
+
+h3. Ruby 1.9
+
+The same as for 1.8 but to make twitter_oauth and oauth on Ruby 1.9 you need to
+install:
+
+# gem sources --add http://gems.github.com
+# sudo gem install entangledstate-ruby-hmac
+# sudo gem install sporkd-oauth
+
+To make authorized requests with the client library you'll need to [create a Twitter OAuth Application](http://twitter.com/oauth_clients/new).
+
+See [sinitter](http://github.com/moomerman/sinitter/tree/master) for a full website integration example.
+
+h2. Unauthorized request example
+
+The Twitter API can be called to make public requests without needing any client credentials.
+Most methods will not work in this mode but some of them do.  An example to retrieve the public details
+about a Twitter user is below. 
+
+<pre><code>client = TwitterOAuth::Client.new  
+
+puts client.show('twitter')
+=> => {"status"=>{"truncated"=>false, "favorited"=>false, "text"=>"Update on service issues http://tinyurl.com/ca872j", "id"=>1357776683, "in_reply_to_user_id"=>nil, "in_reply_to_status_id"=>nil, "source"=>"<a href=\"http://twitterfeed.com\">twitterfeed</a>", "created_at"=>"Fri Mar 20 01:17:35 +0000 2009"}, "name"=>"Twitter", "profile_sidebar_fill_color"=>"CDFFFF", "profile_sidebar_border_color"=>"8a6447", "profile_background_tile"=>false, "profile_link_color"=>"0000ff", "url"=>"http://twitter.com", "favourites_count"=>0, "id"=>783214, "description"=>"Always wondering what everyone's doing.", "profile_text_color"=>"000000", "protected"=>false, "utc_offset"=>-28800, "screen_name"=>"twitter", "profile_background_color"=>"9ae4e8", "time_zone"=>"Pacific Time (US & Canada)", "followers_count"=>469150, "profile_background_image_url"=>"http://static.twitter.com/images/themes/theme1/bg.gif", "friends_count"=>30, "statuses_count"=>290, "location"=>"San Francisco, CA", "profile_image_url"=>"http://s3.amazonaws.com/twitter_production/profile_images/75075164/twitter_bird_profile_normal.png", "created_at"=>"Tue Feb 20 14:35:54 +0000 2007"}
+</code></pre>
+
+You can also access to the search API which is available in either authorized or unauthorized modes.
+
+<pre><code>search = client.search('twitter')
+search.results.size => 20
+search.results.first.from_user => "josephpred"
+search.results.first.text
+=> "Useful public service Twitter account for those of you hitting Tahoe or just needing to cross the pass to Reno: @i80chains"
+</code></pre>
+
+h2. Authorized request example
+
+To use the full power of the Twitter API you need to authorize your application and a valid Twitter user via OAuth.
+An example showing how to update the status of an authorized user is below.
+
+Firstly we need to create an instance of the client with your application client credentials you have been given by Twitter
+when you set up your application.
+
+<pre><code>client = TwitterOAuth::Client.new(
+    :consumer_key => 'YOUR_APP_CONSUMER_KEY',
+    :consumer_secret => 'YOURA_APP_CONSUMER_SECRET'
+)
+request_token = client.request_token(:oauth_callback => oauth_confirm_url)
+#:oauth_callback required for web apps, since oauth gem by default forse PIN-based flow 
+#( see http://groups.google.com/group/twitter-development-talk/browse_thread/thread/472500cfe9e7cdb9/848f834227d3e64d )
+
+
+request_token.authorize_url
+=> http://twitter.com/oauth/authorize?oauth_token=TOKEN
+</code></pre>
+
+In your application your user would be redirected to Twitter to authorize the application at this point.  You'll need to store
+the request token (usually in the session) for later.  The code continues below assuming the user has authorized your application.
+
+<pre><code>access_token = client.authorize(
+  request_token.token,
+  request_token.secret,
+  :oauth_verifier => params[:oauth_verifier]
+)
+
+client.authorized?
+=> true
+
+client.update('checking out the twitter_oauth library') # sends a twitter status update
+</code></pre>
+
+Now if you keep hold of the access_token (usually in the database) for this user you won't need to re-authorize them next time.  When you create an instance of the client you can just pass in the access token and secret that you have stored.
+
+<pre><code>access_token = @user.access_token # assuming @user
+client = TwitterOAuth::Client.new(
+    :consumer_key => 'YOUR_CONSUMER_KEY',
+    :consumer_secret => 'YOUR-CONSUMER-SECRET',
+    :token => access_token.token, 
+    :secret => access_token.secret
+)
+
+client.authorized?
+=> true
+</code></pre>

data/lib/twitter_oauth/account.rb

@@ -0,0 +1,45 @@
+module TwitterOAuth
+  class Client
+    
+    # Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; 
+    # returns a 401 status code and an error message if not.
+    def authorized?
+      oauth_response = access_token.get('/account/verify_credentials.json')
+      return oauth_response.class == Net::HTTPOK
+    end
+    
+    # Returns client info
+    def info
+      oauth_response = access_token.get('/account/verify_credentials.json')
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the remaining number of API requests available to the requesting user before the API limit is reached for the current hour.
+    def rate_limit_status
+      oauth_response = access_token.get('/account/rate_limit_status.json')
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Updates profile background image. Takes a File object and optional tile argument.
+    # Returns extended user info object.
+    def update_profile_background_image(image, tile = false)
+      body, headers = http_multipart_data({:image => image, :tile => tile})
+      oauth_response = access_token.post('/account/update_profile_background_image.json', body, headers)
+    end
+    
+    # Updates profile avatar image. Takes a File object which should be an image.
+    # Returns extended user info object.
+    def update_profile_image(image)
+      body, headers = http_multipart_data({:image => image})
+      oauth_response = access_token.post('/account/update_profile_image.json', body, headers)
+    end
+    
+    # colors hash must contain at least one or more of the following keys :profile_background_color, :profile_text_color, :profile_link_color, :profile_sidebar_fill_color, :profile_sidebar_border_color 
+    # returns extended user info object.
+    def update_profile_colors(colors)
+      oauth_response = access_token.post('/account/update_profile_colors.json', colors)
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/blocks.rb

@@ -0,0 +1,17 @@
+module TwitterOAuth
+  class Client
+    
+    # unblock this user.
+    def block(id)
+      oauth_response = access_token.post("/blocks/create/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # block this user.
+    def unblock(id)
+      oauth_response = access_token.post("/blocks/destroy/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/client.rb

@@ -0,0 +1,61 @@
+require 'twitter_oauth/timeline'
+require 'twitter_oauth/status'
+require 'twitter_oauth/account'
+require 'twitter_oauth/direct_messages'
+require 'twitter_oauth/search'
+require 'twitter_oauth/notifications'
+require 'twitter_oauth/blocks'
+require 'twitter_oauth/friendships'
+require 'twitter_oauth/user'
+require 'twitter_oauth/favorites'
+require 'twitter_oauth/utils'
+
+module TwitterOAuth
+  class Client
+    
+    def initialize(options = {})
+      @consumer_key = options[:consumer_key]
+      @consumer_secret = options[:consumer_secret]
+      @token = options[:token]
+      @secret = options[:secret]
+    end
+  
+    def authorize(token, secret, options = {})
+      request_token = OAuth::RequestToken.new(
+        consumer, token, secret
+      )
+      @access_token = request_token.get_access_token(options)
+      @token = @access_token.token
+      @secret = @access_token.secret
+      @access_token
+    end
+  
+    def show(username)
+      oauth_response = access_token.get("/users/show/#{username}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    def request_token(options={})
+      consumer.get_request_token(options)
+    end
+    
+    def authentication_request_token(options={})
+      consumer.options[:authorize_path] = '/oauth/authenticate'
+      request_token(options)
+    end
+    
+    private
+      def consumer
+        @consumer ||= OAuth::Consumer.new(
+          @consumer_key,
+          @consumer_secret,
+          { :site=>"http://twitter.com" }
+        )
+      end
+
+      def access_token
+        @access_token ||= OAuth::AccessToken.new(consumer, @token, @secret)
+      end
+  end
+end
+   

data/lib/twitter_oauth/direct_messages.rb

@@ -0,0 +1,29 @@
+module TwitterOAuth
+  class Client
+    
+    # Returns a list of the 20 most recent direct messages sent to the authenticating user.
+    def messages(page=1)
+      oauth_response = access_token.get("/direct_messages.json?page=#{page}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns a list of the 20 most recent direct messages sent by the authenticating user.
+    def sent_messages
+      oauth_response = access_token.get('/direct_messages/sent.json')
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Sends a new direct message to the specified user from the authenticating user.
+    def message(user, text)
+      oauth_response = access_token.post('/direct_messages/new.json', :user => user, :text => text)
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Destroys the direct message specified in the required ID parameter.
+    def message_destroy(id)
+      oauth_response = access_token.post("/direct_messages/destroy/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/favorites.rb

@@ -0,0 +1,20 @@
+module TwitterOAuth
+  class Client
+    
+    def favorites(page=1)
+      oauth_response = access_token.get("/favorites.json?page=#{page}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    def favorite
+      oauth_response = access_token.post("/favorites/create/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    def unfavorite
+      oauth_response = access_token.post("/favorites/destroy/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/friendships.rb

@@ -0,0 +1,35 @@
+module TwitterOAuth
+  class Client
+    
+    def friends_ids(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/friends/ids.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    def followers_ids(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/followers/ids.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # friend this user.
+    def friend(id)
+      oauth_response = access_token.post("/friendships/create/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # unfriend.
+    def unfriend(id)
+      oauth_response = access_token.post("/friendships/destroy/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # exists?.
+    def exists?(a, b)
+      oauth_response = access_token.get("/friendships/exists.json?user_a=#{a}&user_b=#{b}")
+      oauth_response.body.strip == 'true'
+    end
+    
+  end
+end

data/lib/twitter_oauth/notifications.rb

@@ -0,0 +1,17 @@
+module TwitterOAuth
+  class Client
+    
+    # follow this user.
+    def follow(id)
+      oauth_response = access_token.post("/notifications/follow/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # unfollow.
+    def leave(id)
+      oauth_response = access_token.post("/notifications/leave/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/search.rb

@@ -0,0 +1,18 @@
+require 'open-uri'
+require 'ostruct'
+
+module TwitterOAuth
+  class Client
+    
+    def search(q, options={})
+      options[:page] ||= 1
+      options[:per_page] ||= 20
+      response = open("http://search.twitter.com/search.json?q=#{URI.escape(q)}&page=#{options[:page]}&rpp=#{options[:per_page]}&since_id=#{options[:since_id]}")
+      search_result = JSON.parse(response.read)
+      search_result = OpenStruct.new(search_result)
+      search_result.results = search_result.results.collect{|x| OpenStruct.new(x)}
+      search_result
+    end
+  
+  end
+end

data/lib/twitter_oauth/status.rb

@@ -0,0 +1,29 @@
+module TwitterOAuth
+  class Client
+    
+    # Returns a single status, specified by the id parameter below.
+    def status(id)
+      oauth_response = access_token.get("/statuses/show/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Updates the authenticating user's status.
+    def update(message, options={})
+      oauth_response = access_token.post('/statuses/update.json', options.merge(:status => message))
+      JSON.parse(oauth_response.body)
+    end
+
+    # Destroys the status specified by the required ID parameter
+    def status_destroy(id)
+      oauth_response = access_token.post("/statuses/destroy/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Retweets the tweet specified by the id parameter. Returns the original tweet with retweet details embedded.
+    def retweet(id)
+      oauth_response = access_token.post("/statuses/retweet/#{id}.json")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/timeline.rb

@@ -0,0 +1,64 @@
+module TwitterOAuth
+  class Client
+    
+    # Returns the 20 most recent statuses from non-protected users who have set a custom user icon.
+    def public_timeline(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/public_timeline.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the 20 most recent statuses, including retweets, posted by the authenticating user and that user's friends. 
+    # This is the equivalent of /timeline/home on the Web.
+    def home_timeline(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/home_timeline.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the 20 most recent statuses posted by the authenticating user and that user's friends.
+    def friends_timeline(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/friends_timeline.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the 20 most recent statuses posted from the authenticating user.
+    def user_timeline(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/user_timeline.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    alias :user :user_timeline
+    
+    # Returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user.
+    def mentions(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/mentions.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    alias :replies :mentions
+    
+    # Returns the 20 most recent retweets posted by the authenticating user
+    def retweeted_by_me(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/retweeted_by_me.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the 20 most recent retweets posted by the authenticating user's friends.
+    def retweeted_to_me(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/retweeted_to_me.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+    # Returns the 20 most recent tweets of the authenticated user that have been retweeted by others.
+    def retweets_of_me(options={})
+      args = options.map{|k,v| "#{k}=#{v}"}.join('&')
+      oauth_response = access_token.get("/statuses/retweets_of_me.json?#{args}")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/user.rb

@@ -0,0 +1,17 @@
+module TwitterOAuth
+  class Client
+     
+    # Returns the 100 last friends
+    def friends(page=1)
+      oauth_response = access_token.get("/statuses/friends.json?page=#{page}")
+      JSON.parse(oauth_response.body)
+    end 
+    
+    # Returns the 100 last followers
+    def followers(page=1)
+      oauth_response = access_token.get("/statuses/followers.json?page=#{page}")
+      JSON.parse(oauth_response.body)
+    end
+    
+  end
+end

data/lib/twitter_oauth/utils.rb

@@ -0,0 +1,34 @@
+module TwitterOAuth
+  class Client
+    CRLF = "\r\n"
+    
+    private
+      # Properly encodes images in form/multipart specification for upload via OAuth.
+      def http_multipart_data(params)
+        body    = ""
+        headers = {}
+        
+        boundary = Time.now.to_i.to_s(16)
+        
+        headers["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+        params.each do |key,value|
+          esc_key = OAuth::Helper.escape(key.to_s)
+          body <<  "--#{boundary}#{CRLF}"
+          
+          if value.respond_to?(:read)
+            mime_type = MIME::Types.type_for(value.path)[0] || MIME::Types["application/octet-stream"][0]
+            body << "Content-Disposition: form-data; name=\"#{esc_key}\"; filename=\"#{File.basename(value.path)}\"#{CRLF}"
+            body << "Content-Type: #{mime_type.simplified}#{CRLF*2}"
+            body << value.read
+          else
+            body << "Content-Disposition: form-data; name=\"#{esc_key}\"#{CRLF*2}#{value}"
+          end
+        end
+        
+        body << "--#{boundary}--#{CRLF*2}"
+        headers["Content-Length"] = body.size.to_s
+        
+        return [ body, headers ]
+      end
+  end
+end

data/lib/twitter_oauth.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'oauth'
+require 'json'
+require 'mime/types'
+
+require 'twitter_oauth/client'
+
+module TwitterOAuth
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: pk-twitter_oauth
+version: !ruby/object:Gem::Version 
+  version: 0.2.1
+platform: ruby
+authors: 
+- Pavel Kunc
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-20 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.1.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mime-types
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.15"
+    version: 
+description: twitter_oauth is a Ruby library for talking to twitter using the new oauth method.
+email: pavel.kunc@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.textile
+- lib/twitter_oauth
+- lib/twitter_oauth.rb
+- lib/twitter_oauth/client.rb
+- lib/twitter_oauth/timeline.rb
+- lib/twitter_oauth/account.rb
+- lib/twitter_oauth/status.rb
+- lib/twitter_oauth/direct_messages.rb
+- lib/twitter_oauth/search.rb
+- lib/twitter_oauth/blocks.rb
+- lib/twitter_oauth/friendships.rb
+- lib/twitter_oauth/notifications.rb
+- lib/twitter_oauth/user.rb
+- lib/twitter_oauth/favorites.rb
+- lib/twitter_oauth/utils.rb
+has_rdoc: false
+homepage: http://github.com/pk/twitter_oauth
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: twitter_oauth
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: twitter_oauth is a Ruby library for talking to twitter using the new oauth method.
+test_files: []
+