hoiio 1.0.0

data/lib/hoiio-ruby/api/number.rb

@@ -0,0 +1,84 @@
+#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
+  class Number < Request
+    # Manage Number API Request
+    # Hoiio provides dedicated virtual phone numbers to developers for your IVR applications.
+    # This service enables your IVR application to receive incoming calls and allows you to create customer hotlines,
+    # call filtering services etc using our IVR API.
+    #
+    # The Number API will allow developers to have full control over how they assign their Hoiio Numbers to their IVR applications.
+
+    # Creates a new instance of Number
+    # @param client a shared object used to cache authentication data
+    def initialize(client)
+      super client
+    end
+
+    # Call Get Countries API
+    # URL: http://developer.hoiio.com/docs/number_countries.html
+    # Return a list of countries for which there are Hoiio Numbers available for subscription.
+    def get_countries(params={})
+      api_post '/number/get_countries', params
+    end
+
+    # Call Get Choices API
+    # URL: http://developer.hoiio.com/docs/number_select.html
+    # Return a list of available Hoiio Numbers for subscription in a given country.
+    def get_choices(params={})
+      api_post '/number/get_choices', params, [:country]
+    end
+
+    # Call Get Rates API
+    # URL: http://developer.hoiio.com/docs/number_rates.html
+    # Retrieve the billable rate that will be charged for subscribing to a Hoiio Number via the number/subscribe API.
+    def get_rates(params={})
+      api_post '/number/get_rates', params, [:country]
+    end
+
+    # Call Subscribe API
+    # URL: http://developer.hoiio.com/docs/number_subscribe.html
+    # Subscribe for a new Hoiio Number or extend an existing subscription of a Hoiio Number.
+    # Hoiio Numbers can be used in IVR apps to receive incoming calls from your users.
+    def subscribe(params={})
+      api_post '/number/subscribe', params, [:number, :duration]
+    end
+
+    # Call Update Forwarding API
+    # URL: http://developer.hoiio.com/docs/number_configure.html
+    # Configure the URL that the incoming call notification and incoming SMS notification
+    # for your Hoiio Number will be sent to.
+    def update_forwarding(params={})
+      api_post '/number/update_forwarding', params, [:number]
+    end
+
+    # Call Get Active API
+    # URL: http://developer.hoiio.com/docs/number_status.html
+    # Retrieve the list of Hoiio Numbers that is assigned to your application and their current configuration
+    def get_active(params={})
+      api_post '/number/get_active', params
+    end
+
+  end
+end

data/lib/hoiio-ruby/api/sms.rb

@@ -0,0 +1,81 @@
+#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
+  class SMS < Request
+    # Manage SMS API Request
+    # SMS is one of the most popular forms of mobile communications. Chatting between friends,
+    # 2-factor authentication by your bank's online portal, receiving alerts from your stock market applications
+    # and SMS marketing are just some of the more popular uses of SMS.
+    #
+    # The SMS API component of Hoiio API allows developers to send/receive SMS to/from more than 200 countries
+    # around the world at a very competitive rate.
+
+    # Creates a new instance of SMS
+    # @param client a shared object used to cache authentication data
+    def initialize(client)
+      super client
+    end
+
+    # Call Send API
+    # URL: http://developer.hoiio.com/docs/sms_send.html
+    # Send SMS to mobile numbers in over 200 countries
+    def send(params={}, bulk_send = false)
+      if bulk_send
+        api_post '/sms/bulk_send', params, [:dest, :msg]
+      else
+        api_post '/sms/send', params, [:dest, :msg]
+      end
+    end
+
+    # Call Bulk_Send API
+    # URL: http://developer.hoiio.com/docs/sms_bulk_send.html
+    # Send SMS in bulk (up to 1000 messages) to any mobile numbers in more than 200 countries
+    def bulk_send(params={})
+      self.send params, true
+    end
+
+    # Call Get History API
+    # URL: http://developer.hoiio.com/docs/sms_history.html
+    # Retrieve the history of SMS sent or received by this application.
+    def get_history(params={})
+      api_post '/sms/get_history', params
+    end
+
+    # Call Get Rate API
+    # URL: http://developer.hoiio.com/docs/sms_rate.html
+    # Retrieve the billable rate that will be charged for each multipart SMS message made or
+    # receive via the sms/send API and sms/receive API respectively.
+    def get_rate(params={})
+      api_post '/sms/get_rate', params, [:dest, :incoming], true
+    end
+
+    # Call Query Status API
+    # URL: http://developer.hoiio.com/docs/sms_status.html
+    # Query the current status of a SMS sent previously via sms/send API.
+    def query_status(params={})
+      api_post '/sms/query_status', params, [:txn_ref]
+    end
+
+  end
+end

data/lib/hoiio-ruby/api/user.rb

@@ -0,0 +1,50 @@
+#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
+  class User < Request
+    # Manage User API Request
+    # The User API will allow developers to check their credit balances and other account information.
+
+    # Creates a new instance of User
+    # @param client a shared object used to cache authentication data
+    def initialize(client)
+      super client
+    end
+
+    # Call Get Balance API
+    # URL: http://developer.hoiio.com/docs/account_credit.html
+    # Retrieve the current credit balance of an account.
+    def get_balance
+      api_post '/user/get_balance'
+    end
+
+    # Call Get Info API
+    # URL: http://developer.hoiio.com/docs/account_info.html
+    # Retrieve the general information of your account.
+    def get_info
+      api_post '/user/get_info'
+    end
+
+  end
+end

data/lib/hoiio-ruby/api/voice.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.
+
+module Hoiio
+  class Voice < Request
+    # Manage Voice API Request
+    # The Voice API component of Hoiio API provides developers access to telephony services in
+    # more than 200 countries around the world. You will be able to initiate phone calls to any mobile phones,
+    # land lines or create call conferences just by making an API request to our servers.
+    # You can connect 2 phones using the Call API, or connect multiple phones using the Conference API.
+
+    # Creates a new instance of Voice
+    # @param client a shared object used to cache authentication data
+    def initialize(client)
+      super client
+    end
+
+    # Call Voice/Call API
+    # URL: http://developer.hoiio.com/docs/voice_call.html
+    # Dial out to 2 destination number and connect them together in a phone conversation
+    def call(params={})
+      api_post '/voice/call', params, [:dest2]
+    end
+
+    # Call Conference API
+    # URL: http://developer.hoiio.com/docs/voice_conference.html
+    # Call a list of destination numbers and place them in a conference call
+    def conference(params={})
+      api_post '/voice/conference', params, [:dest]
+    end
+
+    # Call Hangup API
+    # URL: http://developer.hoiio.com/docs/voice_hangup.html
+    # Hangup a call that is currently in progress.
+    # You can call this API at any point in time when a call is in progress to hang up the call.
+    def hangup(params={})
+      api_post '/voice/hangup', params, [:txn_ref]
+    end
+
+    # Call Get History API
+    # URL: http://developer.hoiio.com/docs/voice_callhistory.html
+    # Retrieve the history of calls, including current ongoing calls.
+    def get_history(params={})
+      api_post '/voice/get_history', params
+    end
+
+    # Call Get Rate API
+    # URL: http://developer.hoiio.com/docs/voice_rate.html
+    # Retrieve the billable rate that will be charged for calls made via the voice/call API.
+    def get_rate(params={})
+      api_post '/voice/get_rate', params, [:dest1, :dest2]
+    end
+
+    # Call Query Status API
+    # URL: http://developer.hoiio.com/docs/voice_status.html
+    # Query the current status of a call.
+    def query_status(params={})
+      api_post '/voice/query_status', params, [:txn_ref]
+    end
+
+  end
+end

data/lib/hoiio-ruby/client.rb

@@ -0,0 +1,71 @@
+#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
+
+  #
+  # Hoiio::Client class caches basic authentication parameters
+  # After being instantiated, a Hoiio::Client object's data will be shared among
+  # all request object, which is subclass of Hoiio::Request
+  #
+  # #How to instantiated a client object:
+  #
+  #   @client = Hoiio::Client.new app_id, access_token
+  #
+
+  class Client
+
+    # @attr_reader app_id your Hoiio application's app_id. Please keep this securely
+    attr_reader :app_id
+
+    # @attr_reader all api request objects
+    attr_reader :user, :sms, :fax, :number, :ivr, :voice
+
+    # @attr_accessor access_token used to stored access_token of a user.
+    # At any point in time, you can reset the access_token by calling @client.access_token = "new token"
+    # and it will be available to all subsequent calls to Hoiio API
+    attr_accessor :access_token
+
+    # Create an instance of Hoiio:Client
+    # @param app_id application id of your Hoiio application
+    # @param access_token access_token of your Hoiio application
+    def initialize(app_id, access_token)
+      @app_id, @access_token = app_id.strip, access_token.strip
+      set_up_resources
+    end
+
+    private
+
+    # Set up sub resources to be used to call Hoiio API
+    # This method passes the @client object to the initialize block of all API request.
+    def set_up_resources
+      @user = Hoiio::User.new self
+      @sms = Hoiio::SMS.new self
+      @voice = Hoiio::Voice.new self
+      @fax = Hoiio::Fax.new self
+      @number = Hoiio::Number.new self
+      @ivr = Hoiio::IVR.new self
+    end
+
+  end
+end

data/lib/hoiio-ruby/errors.rb

@@ -0,0 +1,47 @@
+#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
+
+  class ServerError < StandardError
+  end
+
+  class RequestError < StandardError
+    attr_reader :code
+
+    def initialize(message, code=nil)
+      super message
+      @code = code
+    end
+  end
+
+  class ResponseError < StandardError
+    attr_reader :code
+
+    def initialize(message, code=nil)
+      super message
+      @code = code
+    end
+  end
+
+end

data/lib/hoiio-ruby/request.rb

@@ -0,0 +1,79 @@
+#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
+  class Request
+
+    # A wrapper class to all API request object
+    # This class uses HTTParty to initiate requests to Hoiio API
+    # and process the response before passing to its subclass
+
+    # HTTParty is used to fire requests
+    include HTTParty
+    base_uri "https://secure.hoiio.com/open"
+
+    include RequestUtil
+    include ResponseUtil
+
+    # Create an instance of Request object using Hoiio::Client object
+    # Inside @client object, app_id and access_token are stored to make API request
+    def initialize(client)
+      @client = client
+    end
+
+    # Send a request to Hoiio API
+    # @param path path of the request
+    # @param params all params (required and optional) to pass along the request
+    # @param required_param_names array of names of all the required params that need to be passed along the request
+    # @param mutually_exclusive mark whether to check for mutual exclusivity of required params
+    # (meaning only 1 required param can be present)
+    #
+    # @return response from Hoiio API after being processed
+    # @raise ServerError if response's HTTP status is not 200 OK.
+    def api_post(path, params={}, required_param_names=[], mutually_exclusive=false)
+
+      if mutually_exclusive
+        check_for_mutual_exclusivity(required_param_names, params)
+      elsif !required_param_names.nil? && !required_param_names.empty?
+        check_nil_or_empty(required_param_names, params)
+      end
+
+      options = Hash.new()
+      options[:body] = params
+
+      options.merge!({:body => {:app_id => @client.app_id, :access_token => @client.access_token}}){
+        |key, oldval, newval| oldval.merge!(newval)
+      }
+
+      response = self.class.post path, options
+      case response.code
+        when 200
+          process_response response
+        else
+          raise Hoiio::ServerError
+      end
+    end
+
+  end
+
+end