twitter4r 0.1.1 → 0.2.0

data/lib/twitter/client/base.rb

@@ -0,0 +1,81 @@
+class Twitter::Client
+  protected
+    attr_accessor :login, :password
+    
+    # Returns the response of the HTTP connection.  
+    def http_connect(body = nil, require_auth = true, &block)
+    	require_block(block_given?)
+    	connection = create_http_connection
+    	connection.start do |connection|
+    		request = yield connection if block_given?
+    		request.basic_auth(@login, @password) if require_auth
+    		response = connection.request(request, body)
+    		handle_rest_response(response)
+    		response
+      end
+    end
+    
+    # "Blesses" model object with client information
+    def bless_model(model)
+    	model.bless(self) if model
+    end
+    
+    def bless_models(list)
+      return bless_model(list) if list.respond_to?(:client=)
+    	list.collect { |model| bless_model(model) } if list.respond_to?(:collect)
+    end
+    
+  private
+    @@http_header = nil
+    
+    def raise_rest_error(response, uri = nil)
+      raise Twitter::RESTError.new(:code => response.code, 
+                                   :message => response.message,
+                                   :uri => uri)        
+    end
+    
+    def handle_rest_response(response, uri = nil)
+      unless response.is_a?(Net::HTTPSuccess)
+        raise_rest_error(response, uri)
+      end
+    end
+    
+    def create_http_connection
+      conn = Net::HTTP.new(@@config.host, @@config.port, 
+                            @@config.proxy_host, @@config.proxy_port,
+                            @@config.proxy_user, @@config.proxy_pass)
+      if @@config.protocol == :ssl
+        conn.use_ssl = true
+        conn.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      end
+      conn
+    end
+
+    def http_header
+      # can cache this in class variable since all "variables" used to 
+      # create the contents of the HTTP header are determined by other 
+      # class variables that are not designed to change after instantiation.
+      @@http_header ||= { 
+      	'User-Agent' => "Twitter4R v#{Twitter::Version.to_version} [#{@@config.user_agent}]",
+      	'Accept' => 'text/x-json',
+      	'X-Twitter-Client' => @@config.application_name,
+      	'X-Twitter-Client-Version' => @@config.application_version,
+      	'X-Twitter-Client-URL' => @@config.application_url,
+      }
+      @@http_header
+    end
+    
+    def create_http_get_request(uri, params = {})
+    	path = (params.size > 0) ? "#{uri}?#{params.to_http_str}" : uri
+      Net::HTTP::Get.new(path, http_header)
+    end
+    
+    def create_http_post_request(uri)
+    	Net::HTTP::Post.new(uri, http_header)
+    end
+    
+    def create_http_delete_request(uri, params = {})
+    	path = (params.size > 0) ? "#{uri}?#{params.to_http_str}" : uri
+    	Net::HTTP::Delete.new(path, http_header)
+    end
+end

data/lib/twitter/client/friendship.rb

@@ -0,0 +1,34 @@
+class Twitter::Client
+	@@FRIENDSHIP_URIS = {
+		:add => 'http://twitter.com/friendships/create',
+		:remove => 'http://twitter.com/friendships/destroy',
+	}
+	
+	# Provides access to the Twitter Friendship API.
+	# 
+	# You can add and remove friends using this method.
+	# 
+	# <tt>action</tt> can be any of the following values:
+	# * <tt>:add</tt> - to add a friend, you would use this <tt>action</tt> value
+	# * <tt>:remove</tt> - to remove an existing friend from your friends list use this.
+	# 
+	# The <tt>value</tt> must be either the user to befriend or defriend's 
+	# screen name, integer unique user ID or Twitter::User object representation.
+	# 
+	# Examples:
+	#  screen_name = 'dictionary'
+	#  client.friend(:add, 'dictionary')
+	#  client.friend(:remove, 'dictionary')
+	#  id = 1260061
+	#  client.friend(:add, id)
+	#  client.friend(:remove, id)
+	#  user = Twitter::User.find(id, client)
+	#  client.friend(:add, user)
+	#  client.friend(:remove, user)
+	def friend(action, value)
+		value = value.to_i unless value.is_a?(String)
+		uri = "#{@@FRIENDSHIP_URIS[action]}/#{value}.json"
+		response = http_connect {|conn| create_http_get_request(uri) }
+		bless_model(Twitter::User.unmarshal(response.body))
+	end
+end

data/lib/twitter/client/messaging.rb

@@ -0,0 +1,61 @@
+class Twitter::Client
+
+  @@MESSAGING_URIS = {
+    :received => 'http://twitter.com/direct_messages.json',
+    :sent => 'http://twitter.com/direct_messages/sent.json',
+    :post => 'http://twitter.com/direct_messages/new.json',
+    :delete => 'http://twitter.com/direct_messages/destroy',
+  }
+
+  # Provides access to Twitter's Messaging API for received and 
+  # sent direct messages.
+  # 
+  # 
+  def messages(action)
+    uri = @@MESSAGING_URIS[action]
+  	response = http_connect {|conn|	create_http_get_request(uri) }
+  	bless_models(Twitter::Message.unmarshal(response.body))
+  end
+  
+  # Provides access to Twitter's Messaging API for sending and deleting 
+  # direct messages to other users.
+  # 
+  # <tt>action</tt> can be:
+  # * <tt>:post</tt> - to send a new direct message, <tt>value</tt>, to <tt>user</tt> given.
+  # * <tt>:delete</tt> - to delete direct message with message ID <tt>value</tt>.
+  # 
+  # <tt>value</tt> should be:
+  # * <tt>String</tt> when action is <tt>:post</tt>.  Will be the message text sent to given <tt>user</tt>.
+  # * <tt>Integer</tt> or <tt>Twitter::Message</tt> object when action is <tt>:delete</tt>.  Will refer to the unique message ID to delete.  When passing in an instance of <tt>Twitter::Message</tt> that Status will be 
+  # 
+  # <tt>user</tt> should be:
+  # * <tt>Twitter::User</tt> or <tt>Integer</tt> object when <tt>action</tt> is <tt>:post</tt>.
+  # * totally ignore when <tt>action</tt> is <tt>:delete</tt>.  It has no purpose in this use case scenario.
+  # 
+  # Examples:
+  # The example below sends the message text 'Are you coming over at 6pm for the BBQ tonight?' to user with screen name 'myfriendslogin'...
+  #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 'myfriendslogin')
+  # The example below sends the same message text as above to user with unique integer ID of 1234567890...
+  # the example below sends the same message text as above to user represented by <tt>user</tt> object instance of <tt>Twitter::User</tt>...
+  #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', user)
+  #  message = @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 1234567890)
+  # the example below delete's the message send directly above to user with unique ID 1234567890...
+  #  @twitter.message(:delete, message)
+  # Or the following can also be done...
+  #  @twitter.message(:delete, message.id)
+  # 
+  # In both scenarios (<tt>action</tt> is <tt>:post</tt> or 
+  # <tt>:delete</tt>) a blessed <tt>Twitter::Message</tt> object is 
+  # returned that represents the newly posted or newly deleted message.
+  def message(action, value, user = nil)
+    uri = @@MESSAGING_URIS[action]
+    case action
+    when :post
+      response = http_connect({:text => value, :user => user.to_i}.to_http_str) {|conn| create_http_post_request(uri) }
+    when :delete
+      response = http_connect {|conn| create_http_delete_request(uri, :id => value.to_i) }
+    end
+    message = Twitter::Message.unmarshal(response.body)
+    bless_model(message)
+  end
+end

data/lib/twitter/client/status.rb

@@ -0,0 +1,39 @@
+class Twitter::Client
+  @@STATUS_URIS = {
+  	:get => '/statuses/show.json',
+  	:post => '/statuses/update.json',
+  	:delete => '/statuses/destroy.json',
+  }
+  
+  # Provides access to individual statuses via Twitter's Status APIs
+  # 
+  # <tt>action</tt> can be of the following values:
+  # * <tt>:get</tt> to retrieve status content.  Assumes <tt>value</tt> given responds to :to_i message in meaningful way to yield intended status id.
+  # * <tt>:post</tt> to publish a new status
+  # * <tt>:delete</tt> to remove an existing status.  Assumes <tt>value</tt> given responds to :to_i message in meaningful way to yield intended status id.
+  # 
+  # <tt>value</tt> should be set to:
+  # * the status identifier for <tt>:get</tt> case
+  # * the status text message for <tt>:post</tt> case
+  # * none necessary for <tt>:delete</tt> case
+  # 
+  # Examples:
+  #  twitter.status(:get, 107786772)
+  #  twitter.status(:post, "New Ruby open source project Twitter4R version 0.2.0 released.")
+  #  twitter.status(:delete, 107790712)
+  # 
+  def status(action, value)
+    return nil unless value
+  	uri = @@STATUS_URIS[action]
+  	response = nil
+    case action
+    when :get
+    	response = http_connect {|conn|	create_http_get_request(uri, :id => value.to_i) }
+    when :post
+    	response = http_connect({:status => value}.to_http_str) {|conn| create_http_post_request(uri) }
+    when :delete
+    	response = http_connect {|conn| create_http_delete_request(uri, :id => value.to_i) }
+    end
+    bless_model(Twitter::Status.unmarshal(response.body))
+  end
+end

data/lib/twitter/client/timeline.rb

@@ -0,0 +1,62 @@
+class Twitter::Client
+  @@TIMELINE_URIS = {
+    :public => '/statuses/public_timeline.json',
+    :friends => '/statuses/friends_timeline.json',
+    :friend => '/statuses/friends_timeline.json',
+    :user => '/statuses/user_timeline.json',
+    :me => '/statuses/user_timeline.json',
+  }  
+
+  # Provides access to Twitter's Timeline APIs
+  # 
+  # Returns timeline for given <tt>type</tt>.  
+  # 
+  # <tt>type</tt> can take the following values:
+  # * <tt>public</tt>
+  # * <tt>friends</tt> or <tt>friend</tt>
+  # * <tt>user</tt> or <tt>me</tt>
+  # 
+  # <tt>:id</tt> is on key applicable to be defined in </tt>options</tt>:
+  # * the id or screen name (aka login) for :friends
+  # * the id or screen name (aka login) for :user
+  # * meaningless for the :me case, since <tt>twitter.timeline_for(:user, 'mylogin')</tt> and <tt>twitter.timeline_for(:me)</tt> are the same assuming 'mylogin' is the authenticated user's screen name (aka login).
+  # 
+  # Examples:
+  #  # returns the public statuses since status with id of 6543210
+  #  twitter.timeline_for(:public, id => 6543210)
+  #  # returns the statuses for friend with user id 43210
+  #  twitter.timeline_for(:friend, :id => 43210)
+  #  # returns the statuses for friend with screen name (aka login) of 'otherlogin'
+  #  twitter.timeline_for(:friend, :id => 'otherlogin')
+  #  # returns the statuses for user with screen name (aka login) of 'otherlogin'
+  #  twitter.timeline_for(:user, :id => 'otherlogin')
+  # 
+  # <tt>options</tt> can also include the following keys:
+  # * <tt>:id</tt> is the user ID, screen name of Twitter::User representation of a <tt>Twitter</tt> user.
+  # * <tt>:since</tt> is a Time object specifying the date-time from which to return results for.  Applicable for the :friend, :friends, :user and :me cases.
+  # * <tt>:count</tt> specifies the number of statuses to retrieve.  Only applicable for the :user case.
+  # * <tt>since_id</tt> is the status id of the public timeline from which to retrieve statuses for <tt>:public</tt>.  Only applicable for the :public case.
+  # 
+  # You can also pass this method a block, which will iterate through the results
+  # of the requested timeline and apply the block logic for each status returned.
+  # 
+  # Example:
+  #  twitter.timeline_for(:public) do |status|
+  #    puts status.user.screen_name, status.text
+  #  end
+  #  
+  #  twitter.timeline_for(:friend, :id => 'myfriend', :since => 30.minutes.ago) do |status|
+  #    puts status.user.screen_name, status.text
+  #  end
+  #  
+  #  timeline = twitter.timeline_for(:me) do |status|
+  #    puts status.text
+  #  end
+  def timeline_for(type, options = {}, &block)
+    uri = @@TIMELINE_URIS[type]
+    response = http_connect {|conn| create_http_get_request(uri, options) }
+    timeline = Twitter::Status.unmarshal(response.body)
+    timeline.each {|status| bless_model(status); yield status if block_given? }
+    timeline
+  end
+end

data/lib/twitter/client/user.rb

@@ -0,0 +1,33 @@
+class Twitter::Client
+  @@USER_URIS = {
+  	:info => 'http://twitter.com/users/show',
+  	:friends => 'http://twitter.com/statuses/friends.json',
+  	:followers => 'http://twitter.com/statuses/followers.json',
+  }
+  
+  # Provides access to Twitter's User APIs
+  # 
+  # Returns user instance for the <tt>id</tt> given.  The <tt>id</tt>
+  # can either refer to the numeric user ID or the user's screen name.
+  # 
+  # For example,
+  #  @twitter.user(234943) #=> Twitter::User object instance for user with numeric id of 234943
+  #  @twitter.user('mylogin') #=> Twitter::User object instance for user with screen name 'mylogin'
+  def user(id, action = :info)
+  	response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], :id => id) }
+  	bless_models(Twitter::User.unmarshal(response.body))
+  end
+  
+  # Syntactic sugar for queries relating to authenticated user in Twitter's User API
+  # 
+  # When <tt>action</tt> is:
+  # * <tt>:info</tt> - Returns user instance for the authenticated user.
+  # * <tt>:friends</tt> - Returns Array of users that are authenticated user's friends
+  # * <tt>:followers</tt> - Returns Array of users that are authenticated user's followers
+  def my(action)
+  	response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], :id => @login) }
+  	json = response.body
+  	users = Twitter::User.unmarshal(json)
+  	bless_models(users)
+  end
+end

data/lib/twitter/client.rb

@@ -0,0 +1,18 @@
+# client.rb contains the classes, methods and extends <tt>Twitter4R</tt> 
+# features to define client calls to the Twitter REST API.
+# 
+# See:
+# * <tt>Twitter::Client</tt>
+
+# Used to query or post to the Twitter REST API to simplify code.
+class Twitter::Client
+  include Twitter::ClassUtilMixin
+end
+
+require('twitter/client/base.rb')
+require('twitter/client/timeline.rb')
+require('twitter/client/status.rb')
+require('twitter/client/friendship.rb')
+require('twitter/client/messaging.rb')
+require('twitter/client/user.rb')
+

data/lib/twitter/config.rb

@@ -0,0 +1,69 @@
+# config.rb contains classes, methods and extends existing Twitter4R classes 
+# to provide easy configuration facilities.
+
+module Twitter
+  # Represents global configuration for Twitter::Client.
+  # Can override the following configuration options:
+  # * <tt>protocol</tt> - <tt>:http</tt>, <tt>:https</tt> or <tt>:ssl</tt> supported.  <tt>:ssl</tt> is an alias for <tt>:https</tt>.  Defaults to <tt>:ssl</tt>
+  # * <tt>host</tt> - hostname to connect to for the Twitter service.  Defaults to <tt>'twitter.com'</tt>.
+  # * <tt>port</tt> - port to connect to for the Twitter service.  Defaults to <tt>443</tt>.
+  # * <tt>proxy_host</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_port</tt> - proxy host to use.  Defaults to nil.
+  # * <tt>proxy_user</tt> - proxy username to use.  Defaults to nil.
+  # * <tt>proxy_pass</tt> - proxy password to use.  Defaults to nil.
+  # * <tt>user_agent</tt> - user agent string to use for each request of the HTTP header.
+  # * <tt>application_name</tt> - name of your client application.  Defaults to 'Twitter4R'
+  # * <tt>application_version</tt> - version of your client application.  Defaults to current <tt>Twitter::Version.to_version</tt>.
+  # * <tt>application_url</tt> - URL of your client application.  Defaults to http://twitter4r.rubyforge.org.
+  
+  class Config
+    include ClassUtilMixin
+    @@ATTRIBUTES = [
+      :protocol, 
+      :host, 
+      :port, 
+      :proxy_host, 
+      :proxy_port, 
+      :proxy_user, 
+      :proxy_pass, 
+      :user_agent,
+      :application_name,
+      :application_version,
+      :application_url,
+    ]
+    attr_accessor *@@ATTRIBUTES
+    
+    # Override of Object#eql? to ensure RSpec specifications run 
+    # correctly. Also done to follow Ruby best practices.
+    def eql?(other)
+      return true if self == other
+      @@ATTRIBUTES.each do |att|
+        return false unless self.send(att).eql?(other.send(att))
+      end
+      true
+    end
+  end
+
+  class Client
+    @@defaults = { :host => 'twitter.com', 
+                   :port => 443, 
+                   :protocol => :ssl,
+                   :proxy_host => nil,
+                   :proxy_port => nil,
+                   :user_agent => "default",
+                   :application_name => 'Twitter4R',
+                   :application_version => Twitter::Version.to_version,
+                   :application_url => 'http://twitter4r.rubyforge.org',
+    }
+    @@config = Twitter::Config.new(@@defaults)
+
+    # Twitter::Client class methods
+    class << self
+      # Yields to given <tt>block</tt> to configure the Twitter4R API.
+      def configure(&block)
+        raise ArgumentError, "Block must be provided to configure" unless block_given?
+        yield @@config
+      end # configure
+    end # class << self    
+  end # Client class
+end # Twitter module

data/lib/twitter/console.rb

@@ -0,0 +1,28 @@
+# Contains hooks for the twitter console
+
+module Twitter
+  class Client
+    class << self
+      # Helper method mostly for irb shell prototyping.
+      # 
+      # Reads in login/password Twitter credentials from YAML file
+      # found at the location given by <tt>config_file</tt> that has 
+      # the following format:
+      #  envname:
+      #    login: mytwitterlogin
+      #    password: mytwitterpassword
+      # 
+      # Where <tt>envname</tt> is the name of the environment like 'test', 
+      # 'dev' or 'prod'.  The <tt>env</tt> argument defaults to 'test'.
+      # 
+      # To use this in the shell you would do something like the following 
+      # examples:
+      #  twitter = Twitter::Client.from_config('config/twitter.yml', 'dev')
+      #  twitter = Twitter::Client.from_config('config/twitter.yml')
+      def from_config(config_file, env = 'test')
+        yaml_hash = YAML.load(File.read(config_file))
+        self.new yaml_hash[env]
+      end
+    end # class << self
+  end
+end