telapi 1.0.0

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.DS_Store
+.bundle
+.config
+.rspec
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+bin
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in telapi-ruby.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Phil Misiowiec
+
+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,162 @@
+# Telapi::Ruby
+
+See www.telapi.com to signup for TelAPI.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'telapi'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install telapi
+
+## Authentication and Configuration
+
+Every API request requires a valid *account_sid* and *auth_token*. By default these are set to *nil*, so your application
+should set them in its configuration (e.g. Ruby on Rails initializer).
+
+For example:
+
+    Telapi.config do |config|
+      config.account_sid = 'abc123'
+      config.auth_token  = 'xyz567'
+    end
+
+You can also set individual settings directly:
+
+    Telapi.config.ssl_ca_path = '/some/path'
+
+Inspecting the current configuration returns a hash:
+
+    p Telapi.config # (or Telapi.config.inspect)
+    #=> {:base_uri=>"https://api.telapi.com/2011-07-01/", :ssl_ca_path=>"/some/path", :account_sid=>'abc123', :auth_token=>'xyz567'}
+
+## Design
+
+Minimal code is needed to retrieve objects and perform operations. There's no need to instantiate a client object -- work directly with the desired classes.
+
+Most classes provide identically named class and instance methods for ultimate flexibility. For example, to hang up an existing call, you can call either of the following:
+
+    call = Telapi::Call.get('123abc')
+    call.hangup
+
+    # avoids an additional network request
+    Telapi::Call.hangup('123abc')
+
+Individual objects are wrapped into a Resource instance, which exposes all of the attributes documented in the [TelAPI documentation](http://www.telapi.com/docs/) as accessors and avoids the need to deal with direct JSON responses in your application code. A convenient *attributes* method allows you to dump out the object's values.
+
+    Telapi::Account.get.attributes
+    # => { ...hash of keys and values... }
+
+Methods that return collections wrap Resource objects in a Resource Collection instance, which behaves similar to an Array, but also includes meta info about totals, page size, current page, etc.
+
+## Documentation
+
+Detailed documentation can be found at [RubyDoc](http://rubydoc.info/gems/telapi/) and [the official TelAPI documentation site](http://www.telapi.com/docs/).
+
+## Usage Examples - REST API
+
+Refer to the documentation for more examples.
+
+### Get account details
+
+    acct = Telapi::Account.get
+    acct.friendly_name    # => "My Account"
+    acct.account_balance  # => "25.000"
+
+### Get available numbers
+
+    numbers = Telapi::AvailablePhoneNumber.list('US', :AreaCode => '805')
+    numbers.each { |n| puts n.phone_number }
+    # => +18052585701
+    #    +18052585702
+
+### Get list of calls
+
+    Telapi::Call.list # => returns ResouceCollection of Telapi::Call objects
+
+### Make a call
+
+    Telapi::Call.make('12223334444', '13334445555', 'http://mycallback...')
+
+### Record a call
+
+    call = Telapi::Call.get('123abc')
+    call.record
+
+    # or invoke the class method to avoid an additional network request
+    Telapi::Call.record('123abc')
+
+### Send an SMS message
+
+    Telapi::Message.create('12223334444', '13334445555', 'Hey you')
+
+### Transcribe audio
+
+    Telapi::Transcription.transcribe_audio('http://some-audio-url')
+
+### Caller ID
+
+    Telapi::CallerId.lookup('12223334444')
+
+## Usage Examples - Inbound XML
+
+### Say
+
+    ix = Telapi::InboundXml.new do
+      Say('Hello.', :loop => 3, :voice => 'man')
+      Say('Hello, my name is Jane.', :voice => 'woman')
+      Say('Now I will not stop talking.', :loop => 0)
+    end
+
+    ix.response
+
+    # results in the following XML:
+    # <?xml version="1.0"?>
+    # <Response>
+    #   <Say loop="3" voice="man">Hello.</Say>
+    #   <Say voice="woman">Hello, my name is Jane.</Say>
+    #   <Say loop="0">Now I will not stop talking.</Say>
+    # </Response>
+
+### Play
+
+    Telapi::InboundXml.new { Play('http://example.com/hello.mp3', :loop => 3) }
+
+### Gather
+
+    Telapi::InboundXml.new do
+      Gather(:action      => 'http://example.com/example-callback-url/say?example=simple.xml',
+             :method      => 'GET',
+             :numDigits   => '4',
+             :finishOnKey => '#') {
+        Say 'Please enter your 4 digit pin.'
+      }
+    end
+
+### SMS Response
+
+    Telapi::InboundXml.new do
+      Sms(
+        'Test message sent from TelAPI!',
+        :action => 'http://liveoutput.com/telapi-test-sms-action',
+        :method => 'POST',
+        :from => '1112223333',
+        :to => '3334445555',
+        :statusCallback => 'http://liveoutput.com/telapi-test-status-callback'
+      )
+    end
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/telapi.rb

@@ -0,0 +1,24 @@
+require 'telapi/version'
+
+require 'telapi/error'
+require 'telapi/configuration'
+require 'telapi/network'
+
+require 'telapi/resource'
+require 'telapi/resource_collection'
+
+require 'telapi/account'
+require 'telapi/application'
+require 'telapi/available_phone_number'
+require 'telapi/call'
+require 'telapi/caller_id'
+require 'telapi/carrier'
+require 'telapi/conference'
+require 'telapi/fraud'
+require 'telapi/incoming_phone_number'
+require 'telapi/message'
+require 'telapi/notification'
+require 'telapi/recording'
+require 'telapi/transcription'
+
+require 'telapi/inbound_xml'

data/lib/telapi/account.rb

@@ -0,0 +1,14 @@
+module Telapi
+  # Wraps TelAPI Account functionality
+  class Account < Resource
+    class << self
+
+      # Gets current Telapi account as a Telapi::Account object
+      # See http://www.telapi.com/docs/api/rest/accounts/view/
+      def get
+        Account.new(Network.get)
+      end
+
+    end
+  end
+end

data/lib/telapi/application.rb

@@ -0,0 +1,88 @@
+module Telapi
+  # Wraps TelAPI Application functionality
+  class Application < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Application objects
+      # See http://www.telapi.com/docs/api/rest/applications/list/
+      #
+      # Optional params is a hash containing:
+      # +FriendlyName+:: string
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Applications'], optional_params)
+        ResourceCollection.new(response, 'applications', self)
+      end
+
+      # Returns a Telapi::Application object given its id
+      # See http://www.telapi.com/docs/api/rest/applications/view/
+      def get(id)
+        response = Network.get(['Applications', id])
+        Application.new(response)
+      end
+
+      # Creates an application, returning a Telapi::Application object
+      # See http://www.telapi.com/docs/api/rest/applications/create/
+      #
+      # Required params:
+      # +name+:: string
+      #
+      # Optional params is a hash containing:
+      # +VoiceUrl+:: valid URL
+      # +VoiceMethod+:: (POST) or GET
+      # +VoiceFallbackUrl+:: valid URL
+      # +VoiceFallbackMethod+:: (POST) or GET
+      # +VoiceCallerIdLookup+:: true or (false)
+      # +SmsUrl+:: valid URL
+      # +SmsMethod+:: (POST) or GET
+      # +SmsFallbackUrl+:: valid URL
+      # +SmsFallbackMethod+:: (POST) or GET
+      # +HeartbeatUrl+:: valid URL
+      # +HeartbeatMethod+:: (POST) or GET
+      # +StatusCallback+:: valid URL
+      # +StatusCallbackMethod+:: (POST) or GET
+      def create(name, optional_params = {})
+        opts = { :FriendlyName => name }.merge(optional_params)
+        response = Network.post(['Applications'], opts)
+        Application.new(response)
+      end
+
+      # Updates an application, returning a Telapi::Application object
+      # See http://www.telapi.com/docs/api/rest/applications/update/
+      #
+      # Required params:
+      # +id+:: application id
+      #
+      # Optional params is a hash supporting same options under ::create
+      # in addition to:
+      # +FriendlyName+:: string
+      def update(id, optional_params = {})
+        response = Network.post(['Applications', id], optional_params)
+        Application.new(response)
+      end
+
+      # Deletes an application, returning a Telapi::Application object
+      # See http://www.telapi.com/docs/api/rest/applications/delete/
+      #
+      # Required params:
+      # +id+:: application id
+      def delete(id)
+        response = Network.delete(['Applications', id])
+        Application.new(response)
+      end
+
+    end
+
+    # See ::update
+    def update(optional_params = {})
+      self.class.update(self.sid, optional_params)
+    end
+
+    # See ::delete
+    def delete(optional_params = {})
+      self.class.delete(self.sid)
+    end
+
+  end
+end

data/lib/telapi/available_phone_number.rb

@@ -0,0 +1,24 @@
+module Telapi
+  # Wraps TelAPI Available Phone Number functionality
+  class AvailablePhoneNumber < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::AvailablePhoneNumber objects
+      # See http://www.telapi.com/docs/api/rest/available-phone-numbers/list/
+      #
+      # Required params:
+      # +country_code_iso+:: country code (ISO), see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # Optional params is a hash containing:
+      # +AreaCode+:: valid area code, e.g. 415
+      # +Contains+:: 0-9, lower and upper case letters of the alphabet (Aa-Zz), or *
+      # +InRegion+:: valid region (state or province) abbreviation
+      # +InPostalCode+:: valid postal code
+      def list(country_code_iso, optional_params = {})
+        response = Network.get(['AvailablePhoneNumbers', country_code_iso, 'Local'], optional_params)
+        ResourceCollection.new(response, 'available_phone_numbers', self)
+      end
+
+    end
+  end
+end

data/lib/telapi/call.rb

@@ -0,0 +1,214 @@
+module Telapi
+  # Wraps TelAPI Call functionality
+  class Call < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Call objects
+      # See http://www.telapi.com/docs/api/rest/calls/list/
+      #
+      # Optional params is a hash containing:
+      # +To+:: phone number, e.g. 7325551234
+      # +From+:: phone number, e.g. 7325551234
+      # +Status+:: ringing, in-progress, queued, busy, no-answer, or failed
+      # +StartTime+:: date in the following format: YYYY-MM-DD
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Calls'], optional_params)
+        ResourceCollection.new(response, 'calls', self)
+      end
+
+      # Returns a Telapi::Call object given its id
+      # See http://www.telapi.com/docs/api/rest/calls/view/
+      def get(id)
+        response = Network.get(['Calls', id])
+        Call.new(response)
+      end
+
+      # Creates a call, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/make/
+      #
+      # Required params:
+      # +to+:: phone number, e.g. 7325551234
+      # +from+:: phone number, e.g. 7325551234
+      # +url+:: valid url
+      #
+      # Optional params is a hash containing:
+      # +ForwardedFrom+:: phone number, e.g. 7325551234
+      # +Method+:: (POST) or GET
+      # +FallbackUrl+:: valid URL
+      # +FallbackMethod+:: (POST) or GET
+      # +StatusCallback+:: valid URL
+      # +StatusCallbackMethod+:: (POST) or GET
+      # +SendDigits+:: 0-9, #, or *
+      # +Timeout+:: integer greater than or equal to 0 (default: 60)
+      # +HideCallerId+:: true or (false)
+      def make(to, from, url, optional_params = {})
+        opts = { :To => to, :From => from, :Url => url }.merge(optional_params)
+        response = Network.post(['Calls'], opts)
+        Call.new(response)
+      end
+
+      # Interrupts a call, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/interrupt/
+      #
+      # Required params:
+      # +id+:: call id
+      # +url+:: valid url
+      # +method+:: (POST) or GET
+      # +status+:: canceled or (completed)
+      def interrupt(id, url, method = 'POST', status = 'completed')
+        opts = { :Url => url, :Method => method, :Status => status }
+        response = Network.post(['Calls', id], opts)
+        Call.new(response)
+      end
+
+      # Hangs up a call, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/hangup/
+      #
+      # Required params:
+      # +id+:: call id
+      # +status+:: completed
+      def hangup(id, status = 'completed')
+        opts = { :Status => status }
+        response = Network.post(['Calls', id], opts)
+        Call.new(response)
+      end
+
+      # Sends touch tones during call, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/send-digits/
+      #
+      # Required params:
+      # +id+:: call id
+      # +play_dtmf+:: 0-9, W, or w
+      # +play_dtmf_leg+:: aleg or bleg
+      def send_digits(id, play_dtmf, play_dtmf_leg = 'aleg')
+        opts = { :PlayDtmf => play_dtmf, :PlayDtmfLeg => play_dtmf_leg }
+        response = Network.post(['Calls', id], opts)
+        Call.new(response)
+      end
+
+      # Play audio file during call, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/play-audio/
+      #
+      # Required params:
+      # +id+:: call id
+      # +sound_url+:: valid URL
+      #
+      # Optional params is a hash containing:
+      # +Length+:: integer greater than or equal to 0
+      # +Legs+:: aleg, bleg, or (both)
+      # +Loop+:: true or (false)
+      # +Mix+::  true or (false)
+      def play_audio(id, sound_url, optional_params = {})
+        opts = { :Sounds => sound_url }.merge(optional_params)
+        response = Network.post(['Calls', id, 'Play'], opts)
+        Call.new(response)
+      end
+
+      # Change caller's voice via speed and pitch of audio, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/voice-effects/
+      #
+      # Required params:
+      # +id+:: call id
+      #
+      # Optional params is a hash containing:
+      # +AudioDirection+:: in or (out)
+      # +Pitch+:: value between -1 and 1, including 0
+      # +PitchSemiTones+:: value between -14 and 14, including 0
+      # +PitchOctaves+:: value between -1 and 1, including 0
+      # +Rate+:: value between -1 and 1, including 0
+      def voice_effect(id, optional_params = {})
+        response = Network.post(['Calls', id, 'Effect'], optional_params)
+        Call.new(response)
+      end
+
+      # Initiate or end a call recording, returning a Telapi::Call object
+      # See http://www.telapi.com/docs/api/rest/calls/record/
+      #
+      # Required params:
+      # +id+:: call id
+      # +record+:: (true) or false
+      #
+      # Optional params is a hash containing:
+      # +TimeLimit+:: integer greater than or equal to 0
+      # +CallbackUrl+:: valid URL
+      def record(id, record = true, optional_params = {})
+        opts = { :Record => record }.merge(optional_params)
+        response = Network.post(['Calls', id, 'Recordings'], opts)
+        Call.new(response)
+      end
+
+      # Returns a resource collection containing Telapi::Recording objects
+      # See http://www.telapi.com/docs/api/rest/recordings/list/
+      #
+      # Required params:
+      # +id+:: call id
+      #
+      # Optional params is a hash containing:
+      # +DateCreated+:: date in the following format: YYYY-MM-DD
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def recordings(id, optional_params = {})
+        response = Network.get(['Calls', id, 'Recordings'], optional_params)
+        ResourceCollection.new(response, 'recordings', Recording)
+      end
+
+      # Returns a resource collection containing Telapi::Notification objects
+      # See http://www.telapi.com/docs/api/rest/notifications/list/
+      #
+      # Required params:
+      # +id+:: call id
+      #
+      # Optional params is a hash containing:
+      # +Log+:: 0 (error), 1 (warning), or 2 (info)
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def notifications(id, optional_params = {})
+        response = Network.get(['Calls', id, 'Notifications'], optional_params)
+        ResourceCollection.new(response, 'notifications', Notification)
+      end
+    end
+
+    # See ::interrupt
+    def interrupt(url, method = 'POST', status = 'completed')
+      self.class.interrupt(self.sid, url, method, status)
+    end
+
+    # See ::hangup
+    def hangup(status = 'completed')
+      self.class.hangup(self.sid, status)
+    end
+
+    # See ::send_digits
+    def send_digits(play_dtmf, play_dtmf_leg = 'aleg')
+      self.class.send_digits(self.sid, play_dtmf, play_dtmf_leg)
+    end
+
+    # See ::play_audio
+    def play_audio(sound_url, optional_params = {})
+      self.class.play_audio(self.sid, sound_url, optional_params)
+    end
+
+    # See ::voice_effect
+    def voice_effect(optional_params = {})
+      self.class.voice_effect(self.sid, optional_params)
+    end
+
+    # See ::record
+    def record(record = true, optional_params = {})
+      self.class.record(self.sid, record, optional_params)
+    end
+
+    # See ::recordings
+    def recordings(optional_params = {})
+      self.class.recordings(self.sid, optional_params)
+    end
+
+    # See ::notifications
+    def notifications(optional_params = {})
+      self.class.notifications(self.sid, optional_params)
+    end
+
+  end
+end