nuntium_api 0.13 → 0.14

data/lib/nuntium/exception.rb

@@ -0,0 +1,10 @@
+class Nuntium
+  class Exception < ::StandardError
+    attr_accessor :properties
+
+    def initialize(msg, properties = {})
+      super msg
+      @properties = properties
+    end
+  end
+end

data/lib/nuntium.rb

@@ -6,150 +6,256 @@
 #
 # === Example
 #
-#   api = Nuntium.new 'service_url', 'account_name', 'application_name', 'application_password'
+#   require 'rubygems'
+#   require 'nuntium'
+#
+#   api = Nuntium.new "service_url", "account_name", "application_name", "application_password"
+#
+#   # Get all countries
+#   countries = api.countries
+#
+#   # Get all carriers that belong to a specific country
+#   carriers = api.carriers 'ar'
+#
+#   # Get all channels
+#   channels = api.channels
+#
+#   # Create a channel
+#   api.create_channel {
+#     :name => "my_channel",
+#     :kind => "clickatell",
+#     :protocol => "sms",
+#     :direction =>"bidirectional",
+#     :enabled => true,
+#     :priority => 10,
+#     :configuration => {:password => "secret"}
+#   }
+#
+#   message = {
+#     :from => "sms://1234",
+#     :to => "sms://5678",
+#     :subject => "Hi",
+#     :body => "Hello Nuntium!",
+#   }
+#
+#   # Send an Application Originated message.
+#   # The response is of type HTTParty::Response
+#   response = api.send_ao message
+#
+#   # Can also send many messages at once
+#   messages = [{:to => "sms://1", :body => 'One'}, {:to => "sms://2", :body => 'Two'}]
+#   response = api.send_ao messages
+#
+#   # Simulate sending and get a list of candidate channels
+#   api.get_candidate_channels_for_ao message
+
 require 'rubygems'
-require 'httparty'
+require 'net/http'
 require 'json'
+require 'rest_client'
+require 'cgi'
+require File.expand_path('../nuntium/exception', __FILE__)
 
 # 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
     @account = account
     @application = application
-    @auth = {:username => "#{account}/#{application}", :password => password}
+    @options = {
+      :user => "#{account}/#{application}",
+      :password => password,
+      :headers => {:content_type => 'application/json'},
+    }
   end
 
-  # Gets the list of countries known to Nuntium.
+  # Gets the list of countries known to Nuntium as an array of hashes.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def countries
-    self.class.get "#{@url}/api/countries.json"
+    get_json "/api/countries.json"
   end
 
-  # Gets a country given its iso2 or iso3 code, or nil if a country with that iso does not exist.
+  # Gets a country as a hash given its iso2 or iso3 code, or nil if a country with that iso does not exist.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def country(iso)
-    c = self.class.get "#{@url}/api/countries/#{iso}.json"
-    return nil if c.class <= String
-    c
+    get_json "/api/countries/#{iso}.json"
   end
 
-  # Gets the list of carriers known to Nuntium that belong to a country, given its
-  # iso2 or iso3 code. Gets all carriers if no country is specified.
+  # Gets the list of carriers known to Nuntium that belong to a country as an array of hashes, given its
+  # iso2 or iso3 code. Gets all carriers as an array of hashes if no country is specified.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def carriers(country_id = nil)
     if country_id
-      self.class.get "#{@url}/api/carriers.json", :query => {:country_id => country_id}
+      get_json "/api/carriers.json?country_id=#{country_id}"
     else
-      self.class.get "#{@url}/api/carriers.json"
+      get_json "/api/carriers.json"
     end
   end
 
-  # Gets a carrier given its guid, or nil if a carrier with that guid does not exist.
+  # Gets a carrier as a hash given its guid, or nil if a carrier with that guid does not exist.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def carrier(guid)
-    c = self.class.get "#{@url}/api/carriers/#{guid}.json"
-    return nil if c.class <= String
-    c
+    get_json "/api/carriers/#{guid}.json"
   end
 
   # Returns the list of channels belonging to the application or that don't
-  # belong to any application.
+  # belong to any application, as an array of hashes.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def channels
-    chans = self.class.get "#{@url}/api/channels.json", :basic_auth => @auth
-    return nil if chans.class <= String
-    chans.each do |channel|
-      read_configuration channel
+    get "/api/channels.json" do |response, error|
+      raise Nuntium::Exception.new error.message if error
+
+      channels = JSON.parse response.body
+      channels.each { |channel| read_configuration channel }
+      channels
     end
   end
 
-  # Returns a chnanel given its name, or nil if the channel doesn't exist
+  # Returns a channel given its name. Raises when the channel does not exist.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def channel(name)
-    response = self.class.get "#{@url}/api/channels/#{name}.json", :basic_auth => @auth
-    return_channel response
+    get_channels "/api/channels/#{name}.json"
   end
 
   # Creates a channel.
+  #
   #   create_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
+  #
+  # Raises Nuntium::Exception if something goes wrong. You can access specific errors on properties via the properties
+  # accessor of the exception.
   def create_channel(channel)
     write_configuration channel
-    response = self.class.post "#{@url}/api/channels.json", :basic_auth => @auth, :body => channel.to_json
-    return_channel response
+    post "/api/channels.json", channel.to_json do |response, error|
+      handle_channel_error error if error
+
+      channel = JSON.parse response
+      read_configuration channel
+      channel
+    end
   end
 
   # Updates a channel.
+  #
   #   update_channel :name => 'foo', :kind => 'qst_server', :protocol => 'sms', :configuration => {:password => 'bar'}
+  #
+  # Raises Nuntium::Exception if something goes wrong. You can access specific errors on properties via the properties
+  # accessor of the exception.
   def update_channel(channel)
     write_configuration channel
-    response = self.class.put "#{@url}/api/channels/#{channel['name'] || channel[:name]}.json", :basic_auth => @auth, :body => channel.to_json
-    return_channel response
+    channel_name = channel['name'] || channel[:name]
+
+    put "/api/channels/#{channel_name}.json", channel.to_json do |response, error|
+      handle_channel_error error if error
+
+      channel = JSON.parse response.body
+      read_configuration channel
+      channel
+    end
   end
 
   # Deletes a chnanel given its name.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def delete_channel(name)
-    self.class.delete "#{@url}/api/channels/#{name}", :basic_auth => @auth
+    delete "/api/channels/#{name}" do |response, error|
+      raise Nuntium::Exception.new error.message if error
+
+      response
+    end
   end
 
-  # Returns the list of candidate channels when simulating routing the given
-  # AO message.
+  # Returns the list of candidate channels when simulating routing the given AO message.
+  #
   #   candidate_channels_for_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   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
-    chans.each do |channel|
-      read_configuration channel
-    end
+    get_channels "/api/candidate/channels.json?#{to_query message}"
   end
 
   # Sends one or many AO messages.
   # Returns an enhanced HTTParty::Response instance with id, guid and token readers that matches those x-headers
   # returned by Nuntium.
+  #
   # To send a token, just include it in the message as :token => 'my_token'
+  #
   #   send_ao :from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'
   #   send_ao [{:from => 'sms://1', :to => 'sms://2', :subject => 'hello', :body => 'hi!'}, {...}]
+  #
+  # Returns a hash with :id, :guid and :token keys if a single message was sent, otherwise
+  # returns a hash with a :token key.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def send_ao(messages)
-    response = if messages.is_a? Array
-      self.class.post "#{@url}/#{@account}/#{@application}/send_ao.json", :basic_auth => @auth, :body => messages.to_json
+    if messages.is_a? Array
+      post "/#{@account}/#{@application}/send_ao.json", messages.to_json do |response, error|
+        raise Nuntium::Exception.new error.message if error
+
+        {:token => response.headers[:x_nuntium_token]}
+      end
     else
-      self.class.post "#{@url}/#{@account}/#{@application}/send_ao", :basic_auth => @auth, :body => messages
+      get "/#{@account}/#{@application}/send_ao?#{to_query messages}" do |response, error|
+        raise Nuntium::Exception.new error.message if error
+
+        {
+          :id => response.headers[:x_nuntium_id],
+          :guid => response.headers[:x_nuntium_guid],
+          :token => response.headers[:x_nuntium_token],
+        }
+      end
     end
-    def response.id; headers['x-nuntium-id']; end
-    def response.token; headers['x-nuntium-token']; end
-    def response.guid; headers['x-nuntium-guid']; end
-    response
   end
 
   # Gets AO messages that have the given token. The response is an array of hashes with the messages' attributes.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def get_ao(token)
-    self.class.get "#{@url}/#{@account}/#{@application}/get_ao.json?token=#{token}", :basic_auth => @auth
+    get_json "/#{@account}/#{@application}/get_ao.json?token=#{token}"
   end
 
   # Gets the custom attributes specified for a given address. Returns a hash with the attributes
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def get_custom_attributes(address)
-    attrs = self.class.get "#{@url}/api/custom_attributes?address=#{address}", :basic_auth => @auth
-    return nil unless attrs.is_a? Hash
-    attrs
+    get_json "/api/custom_attributes?address=#{address}"
   end
 
+  # Sets custom attributes of a given address.
+  #
+  # Raises Nuntium::Exception if something goes wrong.
   def set_custom_attributes(address, attributes)
-    self.class.post "#{@url}/api/custom_attributes?address=#{address}", :basic_auth => @auth, :body => attributes
+    post "/api/custom_attributes?address=#{address}", attributes.to_json do |response, error|
+      raise Nuntium::Exception.new error.message if error
+
+      nil
+    end
   end
 
   private
 
   def write_configuration(channel)
+    return unless channel[:configuration] || channel['configuration']
+
     configuration = []
-    channel[:configuration].each do |name, value|
+    (channel[:configuration] || channel['configuration']).each do |name, value|
       configuration << {:name => name, :value => value}
     end
-    channel[:configuration] = configuration
+    if channel[:configuration]
+      channel[:configuration] = configuration
+    else
+      channel['configuration'] = configuration
+    end
   end
 
   def read_configuration(channel)
-    configuration = {}
-    (channel['configuration'] || channel[:configuration]).each do |hash|
-      configuration[hash['name'] || hash[:name]] = hash['value'] || hash[:value]
-    end
-    channel['configuration'] = configuration
+    channel['configuration'] = Hash[channel['configuration'].map { |e| [e['name'], e['value']] }]
   end
 
   def return_channel(response)
@@ -164,4 +270,83 @@ class Nuntium
     end
   end
 
+  def get(path)
+    resource = RestClient::Resource.new @url, @options
+    resource = resource[path].get
+    yield resource, nil
+  rescue RestClient::Exception => ex
+    yield nil, ex
+  rescue Errno::ECONNREFUSED => ex
+    yield nil, ex
+  end
+
+  def get_json(path)
+    get(path) do |response, error|
+      raise Nuntium::Exception.new error.message if error
+
+      JSON.parse response.body
+    end
+  end
+
+  def get_channels(path)
+    get(path) do |response, error|
+      raise Nuntium::Exception.new error.message if error
+
+      channels = JSON.parse response.body
+      channels.each { |channel| read_configuration channel }
+      channels
+    end
+  end
+
+  def post(path, data)
+    resource = RestClient::Resource.new @url, @options
+    resource = resource[path].post(data)
+    yield resource, nil
+  rescue RestClient::Exception => ex
+    yield nil, ex
+  rescue Errno::ECONNREFUSED => ex
+    yield nil, ex
+  end
+
+  def put(path, data)
+    resource = RestClient::Resource.new @url, @options
+    resource = resource[path].put(data)
+    yield resource, nil
+  rescue RestClient::Exception => ex
+    yield nil, ex
+  rescue Errno::ECONNREFUSED => ex
+    yield nil, ex
+  end
+
+  def delete(path, data)
+    resource = RestClient::Resource.new @url, @options
+    resource = resource[path].delete
+    yield resource, nil
+  rescue RestClient::Exception => ex
+    yield nil, ex
+  rescue Errno::ECONNREFUSED => ex
+    yield nil, ex
+  end
+
+  def handle_channel_error(error)
+    if error.is_a? RestClient::BadRequest
+      response = JSON.parse error.response.body
+      raise Nuntium::Exception.new response['summary'], Hash[response['properties'].map {|e| [e.keys[0], e.values[0]]}]
+    else
+      raise Nuntium::Exception.new error.message
+    end
+  end
+
+  def to_query(hash)
+    query = ''
+    first = true
+    hash.each do |key, value|
+      query << '&' unless first
+      query << key.to_s
+      query << '='
+      query << CGI.escape(value.to_s)
+      first = false
+    end
+    query
+  end
 end

metadata

@@ -1,12 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: nuntium_api
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 13
-  version: "0.13"
+  - 14
+  version: "0.14"
 platform: ruby
 authors: 
 - InsTEDD
@@ -14,10 +14,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-02 00:00:00 Z
+date: 2011-09-22 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: httparty
+  name: rest-client
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
@@ -55,6 +55,7 @@ extra_rdoc_files: []
 files: 
 - lib/nuntium_api.rb
 - lib/nuntium.rb
+- lib/nuntium/exception.rb
 homepage: http://code.google.com/p/nuntium-api-ruby
 licenses: []