craigtmackenzie-twitter4r 0.3.1

data/lib/twitter/client/blocks.rb

@@ -0,0 +1,35 @@
+class Twitter::Client
+  @@BLOCK_URIS = {
+    :add => '/blocks/create',
+    :remove => '/blocks/destroy',
+  }
+	
+  # Provides access to the Twitter Block API.
+  # 
+  # You can add and remove blocks to users using this method.
+  # 
+  # <tt>action</tt> can be any of the following values:
+  # * <tt>:add</tt> - to add a block, you would use this <tt>action</tt> value
+  # * <tt>:remove</tt> - to remove a block use this.
+  # 
+  # The <tt>value</tt> must be either the user screen name, integer unique user ID or Twitter::User 
+  # object representation.
+  # 
+  # Examples:
+  #  screen_name = 'dictionary'
+  #  client.block(:add, 'dictionary')
+  #  client.block(:remove, 'dictionary')
+  #  id = 1260061
+  #  client.block(:add, id)
+  #  client.block(:remove, id)
+  #  user = Twitter::User.find(id, client)
+  #  client.block(:add, user)
+  #  client.block(:remove, user)
+  def block(action, value)
+    raise ArgumentError, "Invalid friend action provided: #{action}" unless @@BLOCK_URIS.keys.member?(action)
+    value = value.to_i unless value.is_a?(String)
+    uri = "#{@@BLOCK_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/favorites.rb

@@ -0,0 +1,53 @@
+class Twitter::Client
+  # Why Twitter.com developers can't correctly document their API, I do not know!
+  @@FAVORITES_URIS = {
+    :add => '/favourings/create',
+    :remove => '/favourings/destroy',
+  }
+
+  # Provides access to the Twitter list favorites API.
+  # 
+  # You can access the authenticated [Twitter] user's favorites list using this method.
+  # 
+  # By default you will receive the last twenty statuses added to your favorites list.
+  # To get a previous page you can provide options to this method.  For example,
+  #  statuses = client.favorites(:page => 2)
+  # The above one-liner will get the second page of favorites for the authenticated user.
+  def favorites(options = nil)
+    def uri_suffix(opts); opts && opts[:page] ? "?page=#{opts[:page]}" : ""; end
+    uri = '/favorites.json' + uri_suffix(options)
+    response = http_connect {|conn|	create_http_get_request(uri) }
+    bless_models(Twitter::Status.unmarshal(response.body))
+  end
+	
+  # Provides access to the Twitter add/remove favorite API.
+  # 
+  # You can add and remove favorite status using this method.
+  # 
+  # <tt>action</tt> can be any of the following values:
+  # * <tt>:add</tt> - to add a status to your favorites, you would use this <tt>action</tt> value
+  # * <tt>:remove</tt> - to remove an status from your existing favorites list use this.
+  # 
+  # The <tt>value</tt> must be either the status object to add or remove or 
+  # the integer unique status ID.
+  # 
+  # Examples:
+  #  id = 126006103423
+  #  client.favorite(:add, id)
+  #  client.favorite(:remove, id)
+  #  status = Twitter::Status.find(id, client)
+  #  client.favorite(:add, status)
+  #  client.favorite(:remove, status)
+  def favorite(action, value)
+    raise ArgumentError, "Invalid favorite action provided: #{action}" unless @@FAVORITES_URIS.keys.member?(action)
+    value = value.to_i.to_s unless value.is_a?(String)
+    uri = "#{@@FAVORITES_URIS[action]}/#{value}.json"
+    case action
+    when :add
+      response = http_connect {|conn| create_http_post_request(uri) }
+    when :remove
+      response = http_connect {|conn| create_http_delete_request(uri) }
+    end
+    bless_model(Twitter::Status.unmarshal(response.body))
+  end
+end

data/lib/twitter/client/friendship.rb

@@ -0,0 +1,35 @@
+class Twitter::Client
+  @@FRIENDSHIP_URIS = {
+    :add => '/friendships/create',
+    :remove => '/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)
+    raise ArgumentError, "Invalid friend action provided: #{action}" unless @@FRIENDSHIP_URIS.keys.member?(action)
+    value = value.to_i unless value.is_a?(String)
+    uri = "#{@@FRIENDSHIP_URIS[action]}/#{value}.json"
+    response = http_connect {|conn| create_http_post_request(uri) }
+    bless_model(Twitter::User.unmarshal(response.body))
+  end
+end

data/lib/twitter/client/graph.rb

@@ -0,0 +1,37 @@
+class Twitter::Client
+  @@GRAPH_URIS = {
+    :friends => '/friends/ids',
+    :followers => '/followers/ids',
+  }
+	
+  # Provides access to the Twitter Social Graphing API.
+  # 
+  # You can retrieve the full graph of a user's friends or followers in one method call.
+  # 
+  # <tt>action</tt> can be any of the following values:
+  # * <tt>:friends</tt> - retrieves ids of all friends of a given user.
+  # * <tt>:followers</tt> - retrieves ids of all followers of a given user.
+  # 
+  # The <tt>value</tt> must be either the user screen name, integer unique user ID or Twitter::User 
+  # object representation.
+  # 
+  # Examples:
+  #  screen_name = 'dictionary'
+  #  client.graph(:friends, 'dictionary')
+  #  client.graph(:followers, 'dictionary')
+  #  id = 1260061
+  #  client.graph(:friends, id)
+  #  client.graph(:followers, id)
+  #  user = Twitter::User.find(id, client)
+  #  client.graph(:friends, user)
+  #  client.graph(:followers, user)
+  def graph(action, value = nil)
+    raise ArgumentError, "Invalid friend action provided: #{action}" unless @@GRAPH_URIS.keys.member?(action)
+    id = value.to_i unless value.nil? || value.is_a?(String)
+    id ||= value
+    id ||= @login
+    uri = "#{@@GRAPH_URIS[action]}.json"
+    response = http_connect {|conn| create_http_get_request(uri, :id => id) }
+    JSON.parse(response.body)
+  end
+end

data/lib/twitter/client/messaging.rb

@@ -0,0 +1,79 @@
+class Twitter::Client
+
+  @@MESSAGING_URIS = {
+    :received => '/direct_messages.json',
+    :sent => '/direct_messages/sent.json',
+    :post => '/direct_messages/new.json',
+    :delete => '/direct_messages/destroy',
+  }
+
+  # Provides access to Twitter's Messaging API for received and 
+  # sent direct messages.
+  # 
+  # Example:
+  #  received_messages = @twitter.messages(:received)
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:received+
+  # * +:sent+
+  def messages(action, options = {})
+    raise ArgumentError, "Invalid messaging action: #{action}" unless [:sent, :received].member?(action)
+    uri = @@MESSAGING_URIS[action]
+    response = http_connect {|conn|	create_http_get_request(uri, options) }
+    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>, <tt>Integer</tt> or <tt>String</tt> object when <tt>action</tt> is <tt>:post</tt>.  The <tt>Integer</tt> must be the unique ID of the Twitter user you wish to send the direct message to and any <tt>String</tt>s passed in must be the screen name of the user you wish to send the direct message to.
+  # * 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.
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:post+
+  # * +:delete+
+  # 
+  # An <tt>ArgumentError</tt> is also raised when no user argument is 
+  # supplied when <tt>action</tt> is +:post+.
+  def message(action, value, user = nil)
+    raise ArgumentError, "Invalid messaging action: #{action}" unless [:post, :delete].member?(action)
+    raise ArgumentError, "User argument must be supplied for :post case" if action.eql?(:post) and user.nil?
+    uri = @@MESSAGING_URIS[action]
+    user = user.to_i if user and user.is_a?(Twitter::User)
+    case action
+    when :post
+      response = http_connect({:text => value, :user => user, :source => @@config.source}.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/profile.rb

@@ -0,0 +1,29 @@
+class Twitter::Client
+  @@PROFILE_URIS = {
+    :info => '/account/update_profile',
+    :colors => '/account/update_profile_colors',
+    :device => '/account/update_delivery_device',
+  }
+  
+  # Provides access to the Twitter Profile API.
+  # 
+  # You can update profile information.  You can update the types of profile 
+  # information:
+  # * :info (name, email, url, location, description)
+  # * :colors (background_color, text_color, link_color, sidebar_fill_color, 
+  # sidebar_border_color)
+  # * :device (set device to either "sms", "im" or "none")
+  # 
+  # Example:
+  #  user = client.profile(:info, :location => "University Library")
+  #  puts user.inspect
+  def profile(action, attributes)
+    connection = create_http_connection
+    connection.start do |connection|
+      response = http_connect(attributes.to_http_str) do |conn|
+        create_http_post_request(@@PROFILE_URIS[action])
+      end
+      bless_models(Twitter::User.unmarshal(response.body))
+    end
+  end
+end

data/lib/twitter/client/search.rb

@@ -0,0 +1,27 @@
+class Twitter::Client
+
+  @@SEARCH_URIS = {
+    :basic => "/search.json",
+  }
+
+  # Provides access to Twitter's Search API.
+  # 
+  # Example:
+  #  # For keyword search
+  #  iterator = @twitter.search(:q => "coworking")
+  #  while (tweet = iterator.next)
+  #    puts tweet.text
+  #  end
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:received+
+  # * +:sent+
+  def search(options = {})
+#    raise ArgumentError, "Invalid messaging action: #{action}"
+    uri = @@SEARCH_URIS[:basic]
+    response = http_connect(nil, false, :search) {|conn|	create_http_get_request(uri, options) }
+    json = JSON.parse(response.body)
+    bless_models(Twitter::Status.unmarshal(JSON.dump(json["results"])))
+  end
+end

data/lib/twitter/client/status.rb

@@ -0,0 +1,46 @@
+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)
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:get+
+  # * +:post+
+  # * +:delete+
+  def status(action, value = nil)
+    return self.timeline_for(action, value || {}) if :replies == action
+    raise ArgumentError, "Invalid status action: #{action}" unless @@STATUS_URIS.keys.member?(action)
+    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, :source => @@config.source}.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,72 @@
+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',
+    :replies => '/statuses/replies.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
+  # 
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>type</tt> 
+  # is given.  Valid types are:
+  # * +:public+
+  # * +:friends+
+  # * +:friend+
+  # * +:user+
+  # * +:me+
+  def timeline_for(type, options = {}, &block)
+    raise ArgumentError, "Invalid timeline type: #{type}" unless @@TIMELINE_URIS.keys.member?(type)
+    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,65 @@
+class Twitter::Client
+  @@USER_URIS = {
+  	:info => '/users/show',
+  	:friends => '/statuses/friends.json',
+  	:followers => '/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'
+  # 
+  # Where <tt>options</tt> is a +Hash+ of options that can include:
+  # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
+  # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
+  # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
+  #
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:info+
+  # * +:friends+
+  # 
+  # +Note:+ You should not use this method to attempt to retrieve the 
+  # authenticated user's followers.  Please use any of the following 
+  # ways of accessing this list:
+  #  followers = client.my(:followers)
+  # OR
+  #  followers = client.my(:info).followers
+  def user(id, action = :info, options = {})
+    raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
+    id = id.to_i if id.is_a?(Twitter::User)
+    params = options.merge(:id => id)
+    response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], params) }
+    bless_models(Twitter::User.unmarshal(response.body))
+  end
+  
+  # Syntactic sugar for queries relating to authenticated user in Twitter's User API
+  # 
+  # Where <tt>action</tt> is one of the following:
+  # * <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
+  # 
+  # Where <tt>options</tt> is a +Hash+ of options that can include:
+  # * <tt>:page</tt> - optional.  Retrieves the next set of friends.  There are 100 friends per page.  Default: 1.
+  # * <tt>:lite</tt> - optional.  Prevents the inline inclusion of current status.  Default: false.
+  # * <tt>:since</tt> - optional.  Only relevant for <tt>:friends</tt> action.  Narrows the results to just those friends added after the date given as value of this option.  Must be HTTP-formatted date.
+  #
+  # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt> 
+  # is given.  Valid actions are:
+  # * +:info+
+  # * +:friends+
+  # * +:followers+
+  def my(action, options = {})
+    raise ArgumentError, "Invalid user action: #{action}" unless @@USER_URIS.keys.member?(action)
+    params = options.merge(:id => @login)
+    response = http_connect {|conn| create_http_get_request(@@USER_URIS[action], params) }
+    users = Twitter::User.unmarshal(response.body)
+    bless_models(users)
+  end
+end