nuntium_api 0.7 → 0.8

data/lib/nuntium.rb

@@ -1,10 +1,20 @@
+# Provides access to the Nuntium Public API.
+#
+# === Install
+#
+#   gem install nuntium_api
+#
+# === Example
+#
+#   api = Nuntium.new 'service_url', 'account_name', 'application_name', 'application_password'
 require 'rubygems'
 require 'httparty'
+require 'json'
 
 # Provides access to the Nuntium Public API.
 class Nuntium
   include HTTParty
-  
+
   # Creates an application-authenticated Nuntium api access.
   def initialize(url, account, application, password)
     @url = url
@@ -12,21 +22,21 @@ class Nuntium
     @application = application
     @auth = {:username => "#{account}/#{application}", :password => password}
   end
-  
+
   # Gets the list of countries known to Nuntium.
   def countries
     self.class.get "#{@url}/api/countries.json"
   end
-  
+
   # Gets a country given its iso2 or iso3 code, or nil if a country with that iso does not exist.
   def country(iso)
     c = self.class.get "#{@url}/api/countries/#{iso}.json"
     return nil if c.class <= String
     c
   end
-  
+
   # Gets the list of carriers known to Nuntium that belong to a country, given its
-  # iso2 or iso3 code.
+  # iso2 or iso3 code. Gets all carriers if no country is specified.
   def carriers(country_id = nil)
     if country_id
       self.class.get "#{@url}/api/carriers.json", :query => {:country_id => country_id}
@@ -34,14 +44,14 @@ class Nuntium
       self.class.get "#{@url}/api/carriers.json"
     end
   end
-  
+
   # Gets a carrier given its guid, or nil if a carrier with that guid does not exist.
   def carrier(guid)
     c = self.class.get "#{@url}/api/carriers/#{guid}.json"
     return nil if c.class <= String
     c
   end
-  
+
   # Returns the list of channels belonging to the application or that don't
   # belong to any application.
   def channels
@@ -51,7 +61,7 @@ class Nuntium
       read_configuration channel
     end
   end
-  
+
   # Returns a chnanel given its name, or nil if the channel doesn't exist
   def channel(name)
     channel = self.class.get "#{@url}/api/channels/#{name}.json", :basic_auth => @auth
@@ -59,35 +69,29 @@ class Nuntium
     read_configuration channel
     channel
   end
-  
+
   # Creates a channel.
-  # Example:
-  #   create_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms',
-  #     :configuration => {:password => 'bar'}
+  #   create_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
   def create_channel(channel)
     write_configuration channel
-    self.class.post "#{@url}/api/channels.json", :basic_auth => @auth, :body => channel
+    self.class.post "#{@url}/api/channels.json", :basic_auth => @auth, :body => channel.to_json
   end
-  
-  # Creates a channel.
-  # Example:
-  #   update_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms',
-  #     :configuration => {:password => 'bar'}
+
+  # Updates a channel.
+  #   update_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
   def update_channel(channel)
     write_configuration channel
-    self.class.put "#{@url}/api/channels/#{channel['name']}.json", :basic_auth => @auth, :body => channel
+    self.class.put "#{@url}/api/channels/#{channel['name']}.json", :basic_auth => @auth, :body => channel.to_json
   end
-  
+
   # Deletes a chnanel given its name.
   def delete_channel(name)
     self.class.delete "#{@url}/api/channels/#{name}", :basic_auth => @auth
   end
-  
+
   # Returns the list of candidate channels when simulating routing the given
   # AO message.
-  # Example:
-  #   candidate_channels_for_ao :from => 'sms://1', :to => 'sms://2', 
-  #     :subject => 'hello', :body => 'hi!'
+  #   candidate_channels_for_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
   def candidate_channels_for_ao(message)
     chans = self.class.get "#{@url}/api/candidate/channels.json", :basic_auth => @auth, :body => message
     return nil if chans.class <= String
@@ -95,30 +99,31 @@ class Nuntium
       read_configuration channel
     end
   end
-  
-  # Sends an AO message.
-  # Example:
+
+  # Sends one or many AO messages. Returns an HTTParty::Response instance.
   #   send_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
-  def send_ao(message)
-    self.class.post "#{@url}/#{@account}/#{@application}/send_ao", :basic_auth => @auth, :body => message
+  #   send_ao [{:from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'}, {...}]
+  def send_ao(messages)
+    body = messages.is_a?(Array) ? messages.to_json : messages
+    self.class.post "#{@url}/#{@account}/#{@application}/send_ao.json", :basic_auth => @auth, :body => body
   end
-  
-  private 
-  
+
+  private
+
   def write_configuration(channel)
     configuration = []
     channel[:configuration].each do |name, value|
-      configuration << {:name => name, :value => value} 
+      configuration << {:name => name, :value => value}
     end
     channel[:configuration] = configuration
-  end 
-  
+  end
+
   def read_configuration(channel)
     configuration = {}
     channel['configuration'].each do |hash|
-      configuration[hash['name']] = hash['value'] 
+      configuration[hash['name']] = hash['value']
     end
     channel['configuration'] = configuration
   end
-  
+
 end

metadata

@@ -1,12 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: nuntium_api
 version: !ruby/object:Gem::Version 
-  hash: 5
-  prerelease: false
-  segments: 
-  - 0
-  - 7
-  version: "0.7"
+  version: "0.8"
 platform: ruby
 authors: 
 - InsTEDD
@@ -14,23 +9,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-08 00:00:00 +07:00
+date: 2010-06-08 00:00:00 +08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: httparty
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
         version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: json
   type: :runtime
-  version_requirements: *id001
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
 description: Access the Nuntium API in ruby. Nuntium is an open source and free platform -developed by InSTEDD- that allows applications to send and receive all type of messages. Examples of messages are sms, emails and twitter direct messages.
 email: aborenszweig@manas.com.ar
 executables: []
@@ -51,27 +52,21 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
+  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
       version: "0"
+  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: Access the Nuntium API in ruby