tropo-webapi-ruby 0.1.5

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,24 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+doc
+
+## PROJECT::SPECIFIC
+
+*.gem

data/HISTORY.rdoc

@@ -0,0 +1,5 @@
+= Tropo Release History
+
+== Version 0.1.0
+
+- Alpha release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010 Voxeo, Corporation
+
+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.rdoc

@@ -0,0 +1,192 @@
+= Tropo Web API Ruby Library
+
+A Ruby library for interaction with the Tropo Web API using JSON.
+
+== Tropo Web API Overview
+
+The Tropo Remote API provides a RESTful JSON API for controlling realtime communications applications from
+your own web servers.
+
+== Requirements
+
+* Ruby v1.8.6+ or JRuby v1.4.0+
+* RubyGems
+
+== Installation
+
+  $ sudo gem install tropo-webapi-ruby
+
+Optional, if you would like to use with Sinatra:
+
+  $ sudo gem install sinatra
+
+== Generate Documentation
+
+=== Developer
+
+  $ gemserver
+
+=== Project Developer
+
+  $ sudo gem install yardoc
+
+From within the project:
+
+  $ yardoc
+
+== Usage
+
+  require 'rubygems'
+  require 'tropo-webapi-ruby'
+
+  # Will return the properly formatted JSON to pass to Tropo
+  response = Tropo::Generator.ask({ :say => 'Hello world!' })
+
+  # Will return a Ruby Hash, with some transformations, from the JSON string received from Tropo
+  response = Tropo::Generator.parse(json_string)
+
+  # Will provide instance variables that will allow you to easily reference session type
+  tropo = Tropo::Generator.new
+  response = tropo.parse(json_string)
+  p 'Hey, this is a voice session!' if tropo.voice_session
+  p 'Hey, this is a text messaging session!' if tropo.text_session
+
+== Examples
+
+=== Sinatra
+
+Using the great RESTful Web Services framework Sinatra for Ruby.
+
+==== Hello World
+
+  require 'rubygems'
+  require 'sinatra'
+  require 'tropo-webapi-ruby'
+
+  post '/helloworld.json' do
+    Tropo::Generator.say 'Hello World!'
+  end
+
+  post '/helloworld_block.json' do
+    tropo = Tropo::Generator.new do
+      say 'Hello World!'
+    end
+    tropo.response
+  end
+
+  post '/helloworld_twice.json' do
+    tropo = Tropo::Generator.new
+    tropo.say 'Hello World!'
+    tropo.say 'Hello again.'
+    tropo.response
+  end
+
+==== Getting Session Information
+
+  # Produces a Ruby hash:
+  #
+  # { :session => 
+  #   { :timestamp    => Tue Jan 19 18:27:46 -0500 2010, 
+  #     :user_type    =>"HUMAN", 
+  #     :initial_text => nil,
+  #     :account_id   =>"0", 
+  #     :headers      => [{ "value" => "70", "key"=>"Max-Forwards" }, 
+  #                       { "value" => "385", "key"=>"Content-Length" }, 
+  #                       { "value" => "<sip:127.0.0.1:49152>", "key"=>"Contact" }, 
+  #                       { "value" => "replaces", "key"=>"Supported" }, 
+  #                       { "value" => "<sip:sample.json@localhost:5555>", "key"=>"To" }, 
+  #                       { "value" => "1 INVITE", "key"=>"CSeq" }, 
+  #                       { "value" => "SJphone-M/1.65.382f (SJ Labs)", "key"=>"User-Agent" }, 
+  #                       { "value" => "SIP/2.0/UDP 127.0.0.1:49152;branch=z9000000a9;rport=49152", "key"=>"Via" }, 
+  #                       { "value" => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", "key"=>"Call-ID" }, 
+  #                       { "value" => "application/sdp", "key"=>"Content-Type" }, 
+  #                       { "value" => "unknown <sip:127.0.0.1:49152>;tag=750b1b1648e9c876", "key"=>"From" }],
+  #     :id            => "3FA7C70A1DD211B286B7A583D7B46DDD0xac106207", 
+  #     :to            => { :network => "PSTN", 
+  #                         :channel => "VOICE", 
+  #                         :name    => "unknown", 
+  #                         :id      => "sample.json"}, 
+  #     :from          => { :network => "PSTN", 
+  #                         :channel => "VOICE", 
+  #                         :name    => "unknown", 
+  #                         :id      => "unknown"}}}
+  #
+  post '/start_session.json' do
+    tropo_session = Tropo::Generator.parse request.env["rack.input"].read
+    p tropo_session
+  end
+
+==== Asking for input and receiving the response, or catching a hangup
+
+  post '/ask.json' do
+    tropo = Tropo::Generator.new do
+              on :event => 'hangup', :next => '/hangup.json'
+              on :event => 'continue', :next => '/answer.json'
+              ask({ :name    => 'account_number', 
+                    :bargein => 'true', 
+                    :timeout => 30,
+                    :require => 'true' }) do
+                      say     :value => 'Please say your account number'
+                      choices :value => '[5 DIGITS]'
+                    end
+              end
+    tropo.response
+  end
+
+  # Produces a Ruby hash, if the user gives a response before hanging up:
+  #
+  # { :result => 
+  #   { :actions          => { :attempts       => 1, 
+  #                            :disposition    => "SUCCESS", 
+  #                            :interpretation => "12345", 
+  #                            :confidence     => 100, 
+  #                            :name           => "account_number", 
+  #                            :utterance      => "1 2 3 4 5" }, 
+  #     :session_duration => 3, 
+  #     :error            => nil, 
+  #     :sequence         => 1, 
+  #     :session_id       => "5325C262-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", 
+  #     :state            => "ANSWERED", 
+  #     :complete         => true } }
+  #
+  post '/answer.json' do
+    tropo_event = Tropo::Generator.parse request.env["rack.input"].read
+    p tropo_event
+  end
+
+  # Produces a Ruby hash, if the user hangs up before giving a reponse
+  # { :result => 
+  #   { :actions          => {}, 
+  #     :session_duration => 1, 
+  #     :error            => nil, 
+  #     :sequence         => 1, 
+  #     :session_id       => "812BEF50-1DD2-11B2-8F5B-C16F64C1D62E@127.0.0.1", 
+  #     :state            => "DISCONNECTED", 
+  #     :complete         => true } }
+  #
+  post '/hangup.json' do
+    tropo_event = Tropo::Generator.parse request.env["rack.input"].read
+    p tropo_event
+  end
+
+==== Redirect a call before answering
+
+  # A redirect method
+  post '/redirect.json' do
+    Tropo::Generator.redirect({ :to => 'sip:1234', :from => '4155551212' })
+  end
+
+==== Reject a call before answering
+
+  # A reject method
+  post '/reject.json' do
+    Tropo::Generator.reject
+  end
+
+=== Additional Examples
+
+May be found by checking out the project from Github, and then looking in $PROJECT_HOME/examples and $PROJECT_HOME/spec/tropo-webapi-ruby_spec.rb.
+
+== Copyright
+
+Copyright (c) 2010 Voxeo, Corporation. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "tropo-webapi-ruby"
+    gem.summary = "Tropo Web API Ruby Gem"
+    gem.description = "Ruby library for interacting with the Tropo Web API via REST & JSON"
+    gem.email = "jsgoecke@voxeo.com"
+    gem.homepage = "http://tropo.com"
+    gem.authors = ["Jason Goecke"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.files.include %w(lib/tropo-webapi-ruby.rb lib/tropo-webapi-ruby/tropo-webapi-ruby.rb lib/tropo-webapi-ruby/tropo-webapi-ruby-helpers.rb LICENSE VERSION README.markdown)
+    gem.add_dependency('json', '>= 1.2.0')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "tropo #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# require 'yardoc'
+# YARD::Rake::YardocTask.new do |t|
+#   t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+#   t.options = ['--any', '--extra', '--opts'] # optional
+# end

data/VERSION

@@ -0,0 +1 @@
+0.1.5

data/examples/sinatra_server.rb

@@ -0,0 +1,193 @@
+require 'rubygems'
+require 'sinatra'
+require '../lib/tropo-webapi-ruby'
+
+enable :sessions
+
+post '/index.json' do
+  tropo = Tropo::Generator.new do
+            on :event => 'continue', :next => '/the_answer.json'
+            ask({ :name    => 'account_number', 
+                  :bargein => 'true', 
+                  :timeout => 30,
+                  :require => 'true' }) do
+                    say     :value => 'Please enter your account number'
+                    choices :value => '[5 DIGITS]'
+                  end
+          end
+  tropo.response
+end
+
+post '/the_answer.json' do
+  Tropo::Generator.hangup
+end
+
+post '/helloworld.json' do
+  json_session = request.env["rack.input"].read
+  p json_session
+  tropo_session = Tropo::Generator.parse json_session
+  Tropo::Generator.say :value => 'Hello World!'
+end
+
+# ===
+# Ask answer example
+post '/ask.json' do
+  tropo = Tropo::Generator.new do
+            on :event => 'hangup', :next => '/hangup.json'
+            on :event => 'continue', :next => '/answer.json'
+            ask({ :name    => 'account_number', 
+                  :bargein => 'true', 
+                  :timeout => 30,
+                  :require => 'true' }) do
+                    say     :value => 'Please say your account number'
+                    choices :value => '[5 DIGITS]'
+                  end
+          end
+  tropo.response
+end
+
+post '/answer.json' do
+  tropo_event = Tropo::Generator.parse request.env["rack.input"].read
+  p tropo_event
+end
+
+post '/hangup.json' do
+  tropo_event = Tropo::Generator.parse request.env["rack.input"].read
+  p tropo_event
+end
+# ===
+post '/say_goodbye.json' do
+  Tropo::Generator.say :value => 'Thank you. Goodbye.'
+end
+
+post '/start.json' do
+  tropo_session = Tropo::Generator.parse request.env["rack.input"].read
+  session[:callid] = tropo_session[:session][:id]
+  tropo = Tropo::Generator.new do
+    say :value => 'Hello World!'
+    on  :event => 'hangup', :next => '/hangup.json'
+  end
+  tropo.response
+end
+
+post '/disconnect.json' do
+  tropo = Tropo::Generator.hangup
+  p tropo
+  tropo
+end
+
+post '/hangup.json' do
+  p 'Received a hangup response!'
+  json_string = request.env["rack.input"].read
+  tropo_session = Tropo::Generator.parse json_string
+  p tropo_session
+end
+
+post '/conference.json' do
+  tropo = Tropo::Generator.conference({ :name       => 'foo', 
+                                        :id         => '1234', 
+                                        :mute       => false,
+                                        :send_tones => false,
+                                        :exit_tone  => '#' }) do
+                                          on(:event => 'join') { say :value => 'Welcome to the conference' }
+                                          on(:event => 'leave') { say :value => 'Someone has left the conference' }
+                                        end
+  tropo
+end
+
+post '/result.json' do
+  tropo_result = Tropo::Generator.parse request.env["rack.input"].read
+  p tropo_result
+end
+
+post '/nomatch.json' do
+  Tropo::Generator.say :value => 'Something went terribly wrong!'
+end
+
+post '/redirect.json' do
+  response = Tropo::Generator.redirect(:to => 'sip:9991427589@sip.tropo.com')
+  p response
+  response
+end
+
+post '/reject.json' do
+  response = Tropo::Generator.reject
+  p response
+  response
+end
+
+post '/total_recording.json' do
+  tropo = Tropo::Generator.new do
+    start_recording :name => 'ladeda', :url => 'http://postthis/mofo'
+    say :value => 'I am now recording!'
+    stop_recording
+  end
+  p tropo.response
+  tropo.response
+end
+
+post '/record.json' do
+  response = Tropo::Generator.record({ :name       => 'foo', 
+                                       :url        => 'http://sendme.com/tropo', 
+                                       :beep       => true,
+                                       :send_tones => false,
+                                       :exit_tone  => '#' }) do
+                                         say     :value => 'Please say your account number'
+                                         choices :value => '[5 DIGITS]'
+                                       end
+  p response
+  response
+end
+
+post '/session_scope.json' do
+  session = Hash.new
+  session[:foo] = 'bar'
+  tropo = Tropo::Generator.new(session) do
+    p session
+    say 'Do we now see the session?'
+  end
+  tropo.response
+end
+
+post '/transfer_request.json' do
+  tropo = Tropo::Generator.new do
+    say 'Hello, about to transfer you'
+    transfer :to => 'sip:9991427589@sip.tropo.com'
+    say 'I like rocks!'*10
+  end
+  p tropo.response
+  tropo.response
+end
+
+post '/ons.json' do
+  tropo = Tropo::Generator.new
+  p tropo.on :event => 'hangup', :next => '/hangup.json'
+  p tropo.on :event => 'continue', :next => '/next_resource.json'
+  tropo.say 'That was a boat load of ons...'
+  tropo.response
+end
+
+post '/on_with_block.json' do
+  tropo = Tropo::Generator.new
+  p tropo.on :event => 'hangup', :next => '/hangup.json'
+  p tropo.on :event => 'continue', :next => '/next_resource.json' do
+      say 'About to send you to the next menu.'
+    end
+  tropo.say 'That was a boat load of ons...'
+  tropo.response
+end
+
+post '/test_json.json' do
+  t = Tropo::Generator.new
+  t.on :event => 'error', :next => '/error.json' # For fatal programming errors. Log some details so we can fix it
+  t.on :event => 'hangup', :next => '/hangup.json' # When a user hangs or call is done. We will want to log some details.
+  t.on :event => 'continue', :next => '/next.json'
+  t.say "Hello"
+  t.start_recording(:name => 'recording', :url => "http://heroku-voip.marksilver.net/post_audio_to_s3?filename=foo.wav&unique_id=bar")
+  # [From this point, until stop_recording(), we will record what the caller *and* the IVR say]
+  t.say "You are now on the record."
+  # Prompt the user to incriminate themselve on-the-record
+  t.say "Go ahead, sing-along."
+  t.say "http://denalidomain.com/music/keepers/HappyHappyBirthdaytoYou-Disney.mp3"
+  t.response
+end