hoiio 1.0.0

data/lib/hoiio-ruby/util/request_util.rb

@@ -0,0 +1,65 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+module Hoiio
+  module RequestUtil
+
+    # Utility methods
+
+    # Check if any required parameter is missing in params hash
+    #
+    # @param required_param_names array of names of required parameters that need to be checked
+    # @param params hash of params that will be used to check the presence of each required_param_name
+    #
+    # @return Hoiio::InputError if a required param is missing
+    def check_nil_or_empty(required_param_names=[], params)
+      required_param_names.each { |p|
+        if params[p].nil? || params[p].empty?
+          raise Hoiio::RequestError.new "Param " << p << " is missing"
+        end
+      }
+    end
+
+    # Check that only 1 required parameter is needed for specific API calls
+    #
+    # @param required_param_names array of names of required parameters that need to be checked
+    # @param params hash of params that will be used to check the presence of each required_param_name
+    #
+    # @return Hoiio::InputError if a required param is missing or if all required params are present
+    def check_for_mutual_exclusivity(required_param_names=[], params)
+      i = 0
+      required_param_names.each { |p|
+        if !params[p].nil? && !params[p].empty?
+          i += 1
+        end
+      }
+
+      if i == 0
+        raise Hoiio::RequestError.new "All required params are missing"
+      elsif i > 1
+        raise Hoiio::RequestError.new "More than 1 required, mutually exclusive param are present."
+      end
+    end
+
+  end
+end

data/lib/hoiio-ruby/util/response_util.rb

@@ -0,0 +1,59 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+module Hoiio
+  module ResponseUtil
+
+    # Process response returned by Hoiio API
+    # @param response response of Hoiio API
+    # @return response parsed as a Hash
+    #
+    # @raise ServerError if status is not present
+    # @raise ResponseError if status is not success_ok
+    def process_response(response)
+      response = create_hash response
+      if response['status'].nil?
+        raise Hoiio::ServerError
+      elsif STATUS_SUCCESS != response['status']
+        raise Hoiio::ResponseError.new response['status'], response['status']
+      end
+      response
+    end
+
+    private
+
+    # Create a Hash from a JSON response
+    # @param response response of Hoiio API
+    # @return response parsed as a Hash
+    def create_hash(response)
+      begin
+        JSON.parse response
+      rescue JSON::ParserError
+        response
+      rescue StandardError
+        response
+      end
+    end
+
+  end
+end

data/lib/hoiio-ruby/version/version.rb

@@ -0,0 +1,26 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+module Hoiio
+  VERSION = '1.0.0'
+end

data/spec/fax_spec.rb

@@ -0,0 +1,65 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+require 'spec_helper'
+
+FAX_SEND_RESPONSE = {:status => SUCCESS, :txn_ref => "test-1"}
+FAX_GET_HISTORY_RESPONSE = {:status => SUCCESS, :entries_count => "1"}
+FAX_GET_RATE_RESPONSE = {:status => SUCCESS, :rate => "0.03", :currency => "SGD"}
+FAX_QUERY_STATUS_RESPONSE = {:status => SUCCESS, :fax_status => "answered", :currency => "USD"}
+
+FakeWeb.register_uri :post, construct_fakeweb_uri("/fax/send"), :body => FAX_SEND_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/fax/get_history"), :body => FAX_GET_HISTORY_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/fax/get_rate"), :body => FAX_GET_RATE_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/fax/query_status"), :body => FAX_QUERY_STATUS_RESPONSE.to_json
+
+
+describe Hoiio::Fax do
+
+  it 'should send a fax and return txn ref' do
+    response = CLIENT.fax.send({:dest => TEST_PHONE, :file => "test"})
+    check_status response
+    check_txn_ref response
+  end
+
+  it 'should return history' do
+    response = CLIENT.fax.get_history
+    check_status response
+    response['entries_count'].should == "1"
+  end
+
+  it 'should return fax rate' do
+    response = CLIENT.fax.get_rate({:dest => "+1231231"})
+    check_status response
+    response["currency"].should == "SGD"
+    response["rate"].should == "0.03"
+  end
+
+  it 'should query fax status' do
+    response = CLIENT.fax.query_status({:txn_ref => "test"})
+    check_status response
+    response["currency"].should == "USD"
+    response["fax_status"].should == "answered"
+  end
+
+end

data/spec/ivr_spec.rb

@@ -0,0 +1,82 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+require 'spec_helper'
+
+IVR_START_DIAL_RESPONSE = {:status => SUCCESS, :txn_ref => "test-1", :session => "S-1"}
+IVR_MIDDLE_PLAY_RESPONSE = {:status => SUCCESS}
+IVR_MIDDLE_GATHER_RESPONSE = {:status => SUCCESS}
+IVR_MIDDLE_RECORD_RESPONSE = {:status => SUCCESS}
+IVR_MIDDLE_MONITOR_RESPONSE = {:status => SUCCESS}
+IVR_END_TRANSFER_RESPONSE = {:status => SUCCESS, :room => "R-1"}
+IVR_END_HANGUP_RESPONSE = {:status => SUCCESS, :room => "R-1"}
+
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/start/dial"), :body => IVR_START_DIAL_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/middle/play"), :body => IVR_MIDDLE_PLAY_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/middle/gather"), :body => IVR_MIDDLE_GATHER_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/middle/record"), :body => IVR_MIDDLE_RECORD_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/middle/monitor"), :body => IVR_MIDDLE_MONITOR_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/end/transfer"), :body => IVR_END_TRANSFER_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/ivr/end/hangup"), :body => IVR_END_HANGUP_RESPONSE.to_json
+
+describe Hoiio::IVR do
+
+  it 'should make a dial-out to a destination number' do
+    response = CLIENT.ivr.start.dial({:dest => TEST_PHONE})
+    check_status response
+    check_txn_ref response
+    response["session"].should == "S-1"
+  end
+
+  it 'should want to play a voice message' do
+    response = CLIENT.ivr.middle.play({:session => "S-1"})
+    check_status response
+  end
+
+  it 'should get user input via the telephone keypad' do
+    response = CLIENT.ivr.middle.gather({:session => "S-1", :notify_url => "http://dev.example.com/hoiio/record"})
+    check_status response
+  end
+
+  it 'should record voice messages from the user over the phone' do
+    response = CLIENT.ivr.middle.gather({:session => "S-1", :notify_url => "http://dev.example.com/hoiio/record"})
+    check_status response
+  end
+
+  it 'should record the call conversation, including any voice messages' do
+    response = CLIENT.ivr.middle.monitor({:session => "S-1", :notify_url => "http://dev.example.com/hoiio/record"})
+    check_status response
+  end
+
+  it 'should transfer the call to destination number' do
+    response = CLIENT.ivr.end.transfer({:session => "S-1", :dest => "+6591112222"})
+    check_status response
+    response["room"].should == "R-1"
+  end
+
+  it 'should hang up a specific call' do
+    response = CLIENT.ivr.end.hangup({:session => "S-1"})
+    check_status response
+  end
+
+end

data/spec/number_spec.rb

@@ -0,0 +1,80 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+require 'spec_helper'
+
+NUMBER_GET_COUNTRIES_RESPONSE = {:status => SUCCESS, :entries_count => "10"}
+NUMBER_GET_CHOICES_RESPONSE = {:status => SUCCESS, :total_entries_count => "30"}
+NUMBER_GET_RATES_RESPONSE = {:status => SUCCESS, :currency => "SGD", :entries_count => "50"}
+NUMBER_SUBSCRIBE_RESPONSE = {:status => SUCCESS, :debit => "9.99", :currency => "SGD"}
+NUMBER_UPDATE_FORWARDING_RESPONSE = {:status => SUCCESS}
+NUMBER_GET_ACTIVE_RESPONSE = {:status => SUCCESS, :entries_count => "3"}
+
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/get_countries"), :body => NUMBER_GET_COUNTRIES_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/get_choices"), :body => NUMBER_GET_CHOICES_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/get_rates"), :body => NUMBER_GET_RATES_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/subscribe"), :body => NUMBER_SUBSCRIBE_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/update_forwarding"), :body => NUMBER_UPDATE_FORWARDING_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/number/get_active"), :body => NUMBER_GET_ACTIVE_RESPONSE.to_json
+
+
+describe Hoiio::Number do
+
+  it 'should get a list of countries for Hoiio Numbers' do
+    response = CLIENT.number.get_countries
+    check_status response
+    response['entries_count'].should == "10"
+  end
+
+  it 'should get a list of available Hoiio Numbers for subscription in a given country' do
+    response = CLIENT.number.get_choices({:country => "SG"})
+    check_status response
+    response['total_entries_count'].should == "30"
+  end
+
+  it 'should retrieve the billable rate that will be charged for subscribing to a Hoiio Number' do
+    response = CLIENT.number.get_rates({:country => "SG"})
+    check_status response
+    response['entries_count'].should == "50"
+    response['currency'].should == "SGD"
+  end
+
+  it 'should subscribe for a new Hoiio Number or extend an existing subscription of a Hoiio Number' do
+    response = CLIENT.number.subscribe({:number => "+6581111111", :duration => "1"})
+    check_status response
+    response['debit'].should == "9.99"
+    response['currency'].should == "SGD"
+  end
+
+  it 'should configure the URL that the incoming call notification and incoming SMS notification for Hoiio Number' do
+    response = CLIENT.number.update_forwarding({:number => "+6581111111"})
+    check_status response
+  end
+
+  it 'should retrieve the list of Hoiio Numbers and their current configurations' do
+    response = CLIENT.number.get_active({:number => "+6581111111"})
+    check_status response
+    response['entries_count'].should == "3"
+  end
+
+end

data/spec/sms_spec.rb

@@ -0,0 +1,73 @@
+#Copyright (C) 2012 Hoiio Pte Ltd (http://www.hoiio.com)
+#
+#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.
+
+require 'spec_helper'
+
+SMS_SEND_RESPONSE = {:status => SUCCESS, :txn_ref => "test-1"}
+SMS_BULK_SEND_RESPONSE = {:status => SUCCESS, :bulk_txn_ref => "test-2"}
+SMS_GET_HISTORY_RESPONSE = {:status => SUCCESS, :entries_count => "1"}
+SMS_GET_RATE_RESPONSE = {:status => SUCCESS, :rate => "0.03", :currency => "SGD"}
+SMS_QUERY_STATUS_RESPONSE = {:status => SUCCESS, :sms_status => "delivered", :currency => "USD"}
+
+FakeWeb.register_uri :post, construct_fakeweb_uri("/sms/send"), :body => SMS_SEND_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/sms/bulk_send"), :body => SMS_BULK_SEND_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/sms/get_history"), :body => SMS_GET_HISTORY_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/sms/get_rate"), :body => SMS_GET_RATE_RESPONSE.to_json
+FakeWeb.register_uri :post, construct_fakeweb_uri("/sms/query_status"), :body => SMS_QUERY_STATUS_RESPONSE.to_json
+
+
+describe Hoiio::SMS do
+
+  it 'should send an SMS and return txn ref' do
+    response = CLIENT.sms.send({:dest => TEST_PHONE, :msg => "test"})
+    check_status response
+    check_txn_ref response
+  end
+
+  it 'should send multiple SMSes and return txn ref' do
+    response = CLIENT.sms.bulk_send({:dest => "+651234567,+6512352138", :msg => "test"})
+    check_status response
+    response['bulk_txn_ref'].should_not be_nil
+  end
+
+  it 'should return history' do
+    response = CLIENT.sms.get_history
+    check_status response
+    response['entries_count'].should == "1"
+  end
+
+  it 'should return SMS rate' do
+    response = CLIENT.sms.get_rate({:dest => "+1231231"})
+    check_status response
+    response['currency'].should == "SGD"
+    response['rate'].should == "0.03"
+  end
+
+  it 'should query SMS status' do
+    response = CLIENT.sms.query_status({:txn_ref => "test"})
+    check_status response
+    response['currency'].should == "USD"
+    response['sms_status'].should == "delivered"
+  end
+
+end