hoiio 1.0.0

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Steve Van
+
+MIT License
+
+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.md

@@ -0,0 +1,78 @@
+# Hoiio
+
+This is Ruby SDK for [Hoiio API][homepage]
+
+Hoiio API is set of telephony API that integrate telephony services - phone calls, conference, IVR (Interactive Voice Responses), Fax and SMS - into your services and website easily.
+
+Read the documentation at http://hoiio.readthedocs.org/
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hoiio'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hoiio
+
+## Getting Started With Hoiio Ruby Gem
+
+
+### Setup
+
+``` ruby
+require 'hoiio'
+
+# Hoiio Application Credentials
+app_id = ''
+access_token = ''
+
+# set up a client to talk to the Twilio REST API
+@client = Hoiio::Client.new app_id, access_token
+```
+
+### Usage
+
+After a @client object has been created, app_id and access_token are cached and used for subsequent API calls.
+Normally, app_id won't change, but you can modify the client's access_token by reassigning it to a new one.
+
+All API's URI specified in [Hoiio Developer's website][documentation] are included in this SDK and can be accessed
+conveniently.
+
+For example, @client.sms will make all SMS APIs with the same name available, i.e: @client.sms.send will call /sms/send,
+ @client.sms.query_status will fire a request to /sms/query_status (as specified [here][sms_query_status]).
+
+### Send an SMS
+
+``` ruby
+# send an SMS using Hoiio
+@client.sms.send(
+  :dest => '+6591234567',
+  :msg => 'Hello Steve',
+  :notify_url => 'http://dev.example.com/sms/notify'
+)
+```
+
+### Make a call
+
+``` ruby
+# call a destination number using Hoiio
+@client.voice.call(
+  :dest2 => '+6591234567',
+  :caller_id => 'private'
+)
+```
+
+## API References
+
+Visit [our API site][documentation] to learn more about our powerful communication API.
+
+
+[homepage]:http://developer.hoiio.com/
+[documentation]:http://developer.hoiio.com/docs/index.html
+[sms_query_status]:http://developer.hoiio.com/docs/sms_status.html

data/lib/hoiio-ruby.rb

@@ -0,0 +1,44 @@
+#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 'httparty'
+require 'json'
+require 'cgi'
+
+require 'hoiio-ruby/version/version' unless defined?(Hoiio::VERSION)
+require 'hoiio-ruby/errors'
+require 'hoiio-ruby/util/request_util'
+require 'hoiio-ruby/util/response_util'
+require 'hoiio-ruby/request'
+require 'hoiio-ruby/client'
+require 'hoiio-ruby/api/user'
+require 'hoiio-ruby/api/sms'
+require 'hoiio-ruby/api/voice'
+require 'hoiio-ruby/api/fax'
+require 'hoiio-ruby/api/ivr'
+require 'hoiio-ruby/api/ivr/start'
+require 'hoiio-ruby/api/ivr/middle'
+require 'hoiio-ruby/api/ivr/end'
+require 'hoiio-ruby/api/number'
+
+STATUS_SUCCESS = "success_ok"

data/lib/hoiio-ruby/api/fax.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
+  class Fax < Request
+    # Manage the Fax API Request
+    # Fax API provides developers access to faxing capabilities by using our simple API.
+    # Developers can use the Fax API to send, and also to receive fax via Hoiio virtual numbers.
+    # Charges for fax is similar to our Voice API - by per minute usage.
+    # This should not come as a surprise since fax is delivered over phone lines.
+    # Note that Fax is only supported in Singapore
+
+    # Creates a new instance of Fax
+    # @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/fax_send.html
+    # Send a fax file to a fax number
+    # Fax is only supported in Singapore at the moment
+    def send(params={})
+      api_post '/fax/send', params, [:dest, :file]
+    end
+
+    # Call Get History API
+    # URL: http://developer.hoiio.com/docs/fax_history.html
+    # Retrieve the history of faxes sent by this application, including current ongoing faxes
+    def get_history(params={})
+      api_post '/fax/get_history', params
+    end
+
+    # Call Get Rate API
+    # URL: http://developer.hoiio.com/docs/fax_rate.html
+    # Retrieves the billable rate that will be charged for fax sent or received via the fax/send API
+    # and fax/receive API respectively
+    def get_rate(params={})
+      api_post '/fax/get_rate', params, [:dest, :incoming], true
+    end
+
+    # Call Query Status API
+    # URL: http://developer.hoiio.com/docs/fax_status.html
+    # Query the current status of a fax made previously via fax/send API
+    def query_status(params={})
+      api_post '/fax/query_status', params, [:txn_ref]
+    end
+
+  end
+end

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

@@ -0,0 +1,52 @@
+#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 IVR < Request
+
+    # Hoiio's IVR API allows developers to easily create IVR menus like the above using RESTful APIs.
+    # This can be achieved without the need for technical telecommunication knowledge.
+    # Coupled with our Hoiio Numbers and Text-to-Speech (TTS) technology, you can get started instantly without hassle.
+
+    # @attr_reader 3 blocks of Hoiio IVR
+    attr_reader :start, :middle, :end
+
+    # Creates a new instance of Fax
+    # @param client a shared object used to cache authentication data
+    def initialize(client)
+      super client
+      @client = client
+      set_up
+    end
+
+    private
+
+    # Set up the sub resources using shared @client object
+    def set_up
+      @start = Hoiio::IVRBlock::Start.new @client
+      @middle = Hoiio::IVRBlock::Middle.new @client
+      @end = Hoiio::IVRBlock::End.new @client
+    end
+
+  end
+end

data/lib/hoiio-ruby/api/ivr/end.rb

@@ -0,0 +1,55 @@
+#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 IVRBlock
+    class End < Request
+
+      # Manage the End block of Hoiio IVR Blocks
+      # See here for details: http://developer.hoiio.com/docs/ivr.html
+
+      # Creates a new instance of End IVR Block.
+      # @param client a shared object used to cache authentication data
+      def initialize(client)
+        super client
+      end
+
+      # Call the Transfer API
+      # URL: http://developer.hoiio.com/docs/ivr_transfer.html
+      # Transfer a call to another destination number anywhere in the world or a voice conference room                                                                                                                                                                                                                                                                                                                               The Transfer block will first play the message then transfer the call. If the transfer failed, you can follow up with one of the Middle or End blocks. If the transfer succeeds, you will get a notification after the transferred call has ended.
+      def transfer(params={})
+        api_post '/ivr/end/transfer', params, [:session, :dest]
+      end
+
+      # Call the Hangup API
+      # URL: http://developer.hoiio.com/docs/ivr_hangup.html
+      # To hang up the current call, you can use the Hangup block. Upon receiving this action, the current call will be hang up.
+      # The Hangup block will first play the message, hang up the call then send a notification to your notify_url.
+      # You cannot use any other block after using the Hangup block.
+      def hangup(params={})
+        api_post '/ivr/end/hangup', params, [:session]
+      end
+
+    end
+  end
+end

data/lib/hoiio-ruby/api/ivr/middle.rb

@@ -0,0 +1,70 @@
+#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 IVRBlock
+    class Middle < Request
+
+      # Manage the End block of Hoiio IVR Blocks
+      # See here for details: http://developer.hoiio.com/docs/ivr.html
+
+      # Creates a new instance of Middle IVR Block.
+      # @param client a shared object used to cache authentication data
+      def initialize(client)
+        super client
+      end
+
+      # Call the Play API
+      # URL: http://developer.hoiio.com/docs/ivr_play.html
+      # You can use the Play block if you want to play a voice message. Our Text-to-Speech service will
+      # automatically generate the voice recording for the message you indicated in your API request.
+      # The Play block will first play the message then send a notification to your notify_url.
+      # You cannot use this block after you have used any of the End blocks (Transfer, Hangup).
+      def play(params={})
+        api_post '/ivr/middle/play', params, [:session]
+      end
+
+      # Call the Gather API
+      # URL: http://developer.hoiio.com/docs/ivr_gather.html
+      # Get user input via the telephone's keypad in IVR calls
+      def gather(params={})
+        api_post '/ivr/middle/gather', params, [:session, :notify_url]
+      end
+
+      # Call the Record API
+      # URL: http://developer.hoiio.com/docs/ivr_record.html
+      # Record voice messages from the user over the phone
+      def record(params={})
+        api_post '/ivr/middle/record', params, [:session, :notify_url]
+      end
+
+      # Call the Monitor API
+      # URL: http://developer.hoiio.com/docs/ivr_monitor.html
+      # Record the call conversation, including any voice messages
+      def monitor(params={})
+        api_post '/ivr/middle/monitor', params, [:session, :notify_url]
+      end
+
+    end
+  end
+end

data/lib/hoiio-ruby/api/ivr/start.rb

@@ -0,0 +1,46 @@
+#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 IVRBlock
+    class Start < Request
+
+      # Manage the Start block of Hoiio IVR Blocks
+      # See here for details: http://developer.hoiio.com/docs/ivr.html
+
+      # Creates a new instance of Start IVR Block.
+      # @param client a shared object used to cache authentication data
+      def initialize(client)
+        super client
+      end
+
+      # Call the Gather API
+      # URL: http://developer.hoiio.com/docs/ivr_dial.html
+      # Make a dial-out to a destination number
+      def dial(params={})
+        api_post '/ivr/start/dial', params, [:dest]
+      end
+
+    end
+  end
+end