definitialize-rubymarks 0.0.1

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2009 Definitalize, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of 
+this software and associated documentation files (the "Software"), to deal in 
+the Software without restriction, including without limitation the rights to 
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 
+the Software, and to permit persons to whom the Software is furnished to do so, 
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all 
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,92 @@
+= RubyMarks
+
+RubyMarks lets you interact with TextMarks (textmarks.com) in Ruby. Here is how to get started and a few of things you can do with RubyMarks.
+
+= Installation
+
+Add the GitHub gem source if you haven't done so already.
+
+  gem sources -a http://gems.github.com
+	
+And then...
+
+  gem install definitialize-rubymarks
+  
+To include RubyMarks in your program:
+
+  require 'rubymarks'
+
+You may also need to <tt>require 'rubygems'</tt> if necessary.
+  
+= Starting RubyMarks
+
+To use RubyMarks, you need your TextMarks *username* (or phone number), *password*, *keyword*, and your *API* *key*. Here we are instantiating the RubyMarks class to a local variable:
+
+  r = RubyMarks.new(
+    :user => 'myusername',
+    :password => 'mypassword',
+    :keyword => 'mykeyword', # The keyword you chose when you signed up for TextMarks
+    :api_key => 'mysite_com_123456'
+  )
+  
+= Inviting people to your group
+
+People need to be subscribed to your group before they can receive text messages. To send an invitation:
+
+  r.send :invite, :to => '2065551414'
+  
+This will send a text message to (206) 555-1414 asking the person to reply "Y" if they want to be subscribed. If they subscribe, you can now send text messages to them.
+
+= Sending a text message
+
+  r.send :message, :to => '2065551414', :message => 'Hi there! TextMarks is pretty cool, huh?'
+  
+This will send the message "Hi there! TextMarks is pretty cool, huh?" to the number supplied to <tt>:to</tt>. You can also supply <tt>:to</tt> with a TextMarks username, if they're registered.
+
+= Sending an alert
+
+An alert is a text message that is sent to all of your subscribers.
+
+  r.send :alert, :message => "Change of plans! We're all now going to meet at the hot dog stand."
+  
+= Retrieving messages
+
+You can use the <tt>messages</tt> method to return an array of the public messages in your group (these include alerts sent out and messages your subscribes may have sent back to your group):
+
+  r.messages
+  => [{"msg"=>"Change of plans! We're all now going to meet at the hot dog stand.", "time"=>1241680837, "nick"=>"group_leader", "id"=>123456,
+  "phone"=>"+12065551414"},
+      {"msg"=>"But I don't like hot dogs.", "time"=>1241638161, "nick"=>"User123", "id"=>867750, "phone"=>"+12065552323"}]
+      
+  r.messages.size
+  => 2
+     
+= Retrieving members
+
+You can use the <tt>members</tt> method to return an array of everyone subscribed to your group:
+
+  r.members
+  => [{"time"=>1241682280, "nick"=>"group_leader", "phone"=>"+12065551414"},
+      {"time"=>1241685492, "nick"=>"User123", "phone"=>"+12065552323"},
+      {"time"=>1241682332, "nick"=>"User456", "phone"=>"+12065557979"}]
+  
+  r.members.size
+  => 3
+  
+  r.members.last['nick']
+  => "User456"
+  
+= See if someone is subscribed
+
+Use the <tt>is_member?</tt> method to check if someone is subscribed to your group. Supply either a 10 digit phone number or a username:
+  
+  r.is_member? '2065552323'
+  => true
+  
+  r.is_member? 'random_dude'
+  => false
+
+= Additional information
+
+* RubyMarks uses TextMark's latest V2 Alpha API. RubyMarks will be updated when the API gets updated (if necessary).
+* Every method (except for <tt>is_member?</tt>) returns the API's response in JSON format.

data/lib/rubymarks.rb

@@ -0,0 +1,137 @@
+require 'httparty'
+
+class RubyMarks
+  include HTTParty
+  base_uri 'alpha.api2.textmarks.com'
+  format :json
+
+  # When instantiating RubyMarks, you need to supply your TextMarks username, password, keyword, and API key (all required).
+  #   r = RubyMarks.new(
+  #     :user => 'myusername',
+  #     :password => 'mypassword',
+  #     :keyword => 'mykeyword', # The keyword you chose when you signed up for TextMarks
+  #     :api_key => 'mysite_com_123456'
+  #   )
+  def initialize(options = {})    
+    if [:user, :password, :keyword, :api_key].any? { |o| options[o].nil? }
+      raise ArgumentError, "Missing required argument(s). Requires :user, :password, :keyword, :api_key"
+    end
+
+    valid_api_key = self.class.get('/Test/test_api_key/', :query => { :api_key => options[:api_key] })['head']['rescode'] == 0
+    valid_user_info = self.class.get('/Test/test_auth_user/', :query => { :auth_user => options[:user], :auth_pass => options[:password] })['head']['rescode'] == 0
+    keyword_status = self.class.get('/Anybody/keyword_status/', :query => { :keyword => options[:keyword] })
+
+    if valid_api_key
+      if valid_user_info
+        if keyword_status['body']['available']
+          raise "Keyword '#{options[:keyword]}' hasn't been registered."
+        else
+          if keyword_status['body']['public_config']['manager']['nick'] == options[:user]
+            self.class.default_params :auth_user => options[:user], :auth_pass => options[:password], :tm => options[:keyword], :api_key => options[:api_key]
+          else
+            raise "Keyword doesn't belong to user '#{options[:user]}'"
+          end
+        end
+      else
+        raise "Invalid username or password."
+      end
+    else
+      raise "Invalid API key."
+    end
+  end
+
+  # Allows you to send invitations, messages, and alerts.
+  # To invite someone to your group:
+  #   r.send :invite, :to => '2065551414'
+  # To send a regular message:
+  #   r.send :message, :to =>'2065551414', :message => 'Hi there!'
+  # To send an alert (message that is sent to all of your subscribers):
+  #   r.send :alert, :message => 'Important! A new episode of 30 Rock is on!'
+  def send(action, options = {})
+    raise ArgumentError, "Invalid messaging action: #{action}" unless [:invite, :message, :alert].member? action
+
+    case action
+      when :invite then send_invite(options)
+      when :message then send_message(options)
+      when :alert then send_alert(options)
+    end
+  end
+
+  # Returns an array of everyone subscribed to your group. (Can only return up to 100 members)
+  #   r.members
+  #   => [{"time"=>1241682280, "nick"=>"group_leader", "phone"=>"+12065551414"},
+  #       {"time"=>1241685492, "nick"=>"User123", "phone"=>"+12065552323"},
+  #       {"time"=>1241682332, "nick"=>"User456", "phone"=>"+12065557979"}]
+  # 
+  #   r.members.size
+  #   => 3
+  # 
+  #   r.members.last['nick']
+  #   => "User456"
+  def members
+    self.class.get('/GroupLeader/members/', :query => { :count => 100 })['body']['members']
+  end
+
+  # Check if someone is subscribed to your group. Supply either a 10 digit phone number or a username.
+  #   r.is_member? 'User123'
+  #   => true
+  # 
+  #   r.is_member? '2065552323'
+  #   => true
+  # 
+  #   r.is_member? 'random_dude'
+  #   => false
+  def is_member?(user)
+    self.class.get('/GroupLeader/has_member/', :query => { :user => user })['body']['member'] if user
+  end
+
+  # Deletes (unsubscribes) a member from your group. Supply either a 10 digit phone number or a username.
+  #   r.delete_member '2065552323'
+  #
+  #   r.delete_member 'User123'
+  def delete_member(user)
+    self.class.post('/GroupLeader/kick_member/', :query => { :user => user })
+  end
+
+  # Returns an array of the public messages in your group (these include alerts sent out and messages your subscribes may have sent back to your group). (JSON format)
+  #   r.messages
+  #   => [{"msg"=>"Change of plans! We're all now going to meet at the hot dog stand.", "time"=>1241680837, "nick"=>"group_leader", "id"=>123456, "phone"=>"+12065551414"},
+  #       {"msg"=>"But I don't like hot dogs.", "time"=>1241638161, "nick"=>"User123", "id"=>867750, "phone"=>"+12065552323"}]
+  #
+  #   r.messages.size
+  #   => 2
+  #     
+  #   for message in r.messages
+  #     p "#{message['nick']} said '#{message['msg']}'"
+  #   end
+  #   => "group_leader said 'Change of plans! We're all now going to meet at the hot dog stand.'"
+  #      "User123 said 'But I don't like hot dogs.'"
+  def messages
+    self.class.get('/GroupLeader/messages/')['body']['messages']
+  end
+
+  # Deletes a message that is in your group.
+  #   r.delete_message '123456' # Delete message with the id of 123456
+  #
+  #   r.delete_message r.messages.first['id'] # Delete the first message in the group
+  def delete_message(message_id)
+    self.class.post('/GroupLeader/delete_message/', :query => { :msg_id => message_id })
+  end
+
+  protected
+
+  def send_invite(options)
+    raise ArgumentError, "Missing required argument(s). Requires :to" if options[:to].nil?
+    self.class.post('/Anybody/invite_to_group/', :query => { :user => options[:to] })
+  end
+
+  def send_message(options)
+    raise ArgumentError, "Missing required argument(s). Requires :message, :to" if options[:message].nil? or options[:to].nil?
+    self.class.post('/GroupLeader/send_one_message/', :query => { :msg => options[:message], :to => options[:to] })
+  end
+
+  def send_alert(options)
+    raise ArgumentError, "Missing required argument(s). Requires :message" if options[:message].nil?
+    self.class.post('/GroupLeader/broadcast_message/', :query => { :msg => options[:message] })
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification 
+name: definitialize-rubymarks
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Andrew Schaper
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-01 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.3
+    version: 
+description: RubyMarks lets you interact with TextMarks (textmarks.com) in Ruby.
+email: andrew@soshiku.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.rdoc
+- lib/rubymarks.rb
+has_rdoc: true
+homepage: http://definitialize.com/rubymarks
+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: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: RubyMarks lets you interact with TextMarks (textmarks.com) in Ruby.
+test_files: []
+