lib/twitter/client/messaging.rb

   1 class Twitter::Client
   2
   3   @@MESSAGING_URIS = {
   4     :received => '/direct_messages.json',
   5     :sent => '/direct_messages/sent.json',
   6     :post => '/direct_messages/new.json',
   7     :delete => '/direct_messages/destroy',
   8   }
   9
  10   # Provides access to Twitter's Messaging API for received and
  11   # sent direct messages.
  12   #
  13   # Example:
  14   #  received_messages = @twitter.messages(:received)
  15   #
  16   # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt>
  17   # is given.  Valid actions are:
  18   # * +:received+
  19   # * +:sent+
  20   def messages(action, options = nil)
  21     # method scoped method
  22     def uri_suffix(opts); opts && opts[:page] ? "?page=#{opts[:page]}" : ""; end
  23     raise ArgumentError, "Invalid messaging action: #{action}" unless [:sent, :received].member?(action)
  24     uri = @@MESSAGING_URIS[action] + uri_suffix(options)
  25     response = http_connect {|conn|     create_http_get_request(uri) }
  26     bless_models(Twitter::Message.unmarshal(response.body))
  27   end
  28
  29   # Provides access to Twitter's Messaging API for sending and deleting
  30   # direct messages to other users.
  31   #
  32   # <tt>action</tt> can be:
  33   # * <tt>:post</tt> - to send a new direct message, <tt>value</tt>, to <tt>user</tt> given.
  34   # * <tt>:delete</tt> - to delete direct message with message ID <tt>value</tt>.
  35   #
  36   # <tt>value</tt> should be:
  37   # * <tt>String</tt> when action is <tt>:post</tt>.  Will be the message text sent to given <tt>user</tt>.
  38   # * <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
  39   #
  40   # <tt>user</tt> should be:
  41   # * <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.
  42   # * totally ignore when <tt>action</tt> is <tt>:delete</tt>.  It has no purpose in this use case scenario.
  43   #
  44   # Examples:
  45   # The example below sends the message text 'Are you coming over at 6pm for the BBQ tonight?' to user with screen name 'myfriendslogin'...
  46   #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 'myfriendslogin')
  47   # The example below sends the same message text as above to user with unique integer ID of 1234567890...
  48   # the example below sends the same message text as above to user represented by <tt>user</tt> object instance of <tt>Twitter::User</tt>...
  49   #  @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', user)
  50   #  message = @twitter.message(:post, 'Are you coming over at 6pm for the BBQ tonight?', 1234567890)
  51   # the example below delete's the message send directly above to user with unique ID 1234567890...
  52   #  @twitter.message(:delete, message)
  53   # Or the following can also be done...
  54   #  @twitter.message(:delete, message.id)
  55   #
  56   # In both scenarios (<tt>action</tt> is <tt>:post</tt> or
  57   # <tt>:delete</tt>) a blessed <tt>Twitter::Message</tt> object is
  58   # returned that represents the newly posted or newly deleted message.
  59   #
  60   # An <tt>ArgumentError</tt> will be raised if an invalid <tt>action</tt>
  61   # is given.  Valid actions are:
  62   # * +:post+
  63   # * +:delete+
  64   #
  65   # An <tt>ArgumentError</tt> is also raised when no user argument is
  66   # supplied when <tt>action</tt> is +:post+.
  67   def message(action, value, user = nil)
  68     raise ArgumentError, "Invalid messaging action: #{action}" unless [:post, :delete].member?(action)
  69     raise ArgumentError, "User argument must be supplied for :post case" if action.eql?(:post) and user.nil?
  70     uri = @@MESSAGING_URIS[action]
  71     user = user.to_i if user and user.is_a?(Twitter::User)
  72     case action
  73     when :post
  74       response = http_connect({:text => value, :user => user, :source => @@config.source}.to_http_str) {|conn| create_http_post_request(uri) }
  75     when :delete
  76       response = http_connect {|conn| create_http_delete_request(uri, :id => value.to_i) }
  77     end
  78     message = Twitter::Message.unmarshal(response.body)
  79     bless_model(message)
  80   end
  81 end