ringcentral 0.1.0

data/.document

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

data/.gitignore

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

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Todd Eichel
+
+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,178 @@
+[ringcentral](http://github.com/tfe/ringcentral/)
+========
+
+A Ruby library for interacting with the RingCentral [RingOut API](https://service.ringcentral.com/ringoutapi/) and (coming soon) [FaxOut API](https://service.ringcentral.com/faxoutapi/).
+
+Currently it is a very thin wrapper around the native RingCentral HTTP API. Eventually I would like to document and abstract away as many of the idiosyncrasies of the native API as possible.
+
+All four RingOut commands are supported (see "Usage" below).
+
+
+Installation
+------------
+
+Install the gem:
+
+    sudo gem install ringcentral
+
+And if you're using Rails (not required), add it to your environment.rb configuration as a gem dependency:
+
+    config.gem 'ringcentral'
+
+I highly recommend requiring a specific version (with the `:version` argument to `config.gem`) from your app, because this gem is young and the API *will* change.
+
+
+
+Usage
+-----
+
+### RingOut
+
+When calling `list` and `call`, you will always need to supply the RingCentral account credentials as the first three arguments to the methods:
+
+* **Username**: your main RingCentral account phone number
+* **Password**: password for an individual user on your RingCentral account
+* **Extension**: extension number for an individual user on your RingCentral account
+
+For `status` and `cancel`, no credentials are required by RingCentral, just a session ID returned by the `call` method.
+
+*Errata*
+
+* RingCentral returns a "Call Completed" response for every session ID that's not attached to a call currently in progress.
+* The "WS" parameter is returned when placing a call and is accepted as a parameter to the `status` and `cancel` methods, but as far as I can tell it doesn't do anything. RingCentral support didn't know either.
+
+
+#### List
+
+    RingCentral::Phone.list(username, password, extension)
+
+Gets a hash of the numbers associated with the provided RingCentral credentials (output formatted for readability). Example:
+
+    >> RingCentral::Phone.list('8889363711', '1234', '101')
+    => {
+         "Home" => "6505553711",
+         "Mobile" => "6505551233",
+         "Business" => "6505551550"
+       }
+
+
+
+#### Call
+
+    RingCentral::Phone.call(username, password, extension, to, from, caller_id, prompt = 1)
+
+Place a RingOut call to the `to` number, from the `from` number, and with the specified `caller_id`. Set `prompt` to `0` to avoid the "Press 1 to connect this call" prompt (default is to leave the prompt on).
+
+The response is a session ID (which you can use to get call status or cancel the call later) and a "WS" field (see "Errata" above).
+
+    >> RingCentral::Phone.call('8889363711', '1234', '101', '6505551230', '6505551231', '8889363711')
+    => {
+         :session_id => "20",
+         :ws => ".62"
+       }
+
+
+#### Status
+
+    RingCentral::Phone.status(session_id, ws = nil)
+
+Check the status of the RingOut call with a given `session_id` in progress (or completed). The `ws` parameter appears to be unused, so it defaults to `nil`.
+
+The response is a hash of status information: for the call as a whole, and the status for each of the numbers (callback, the originating number; and destination, the number being called). Possible values for the status are as follows:
+
+* **Success**: picked up, line open (gets set for the callback number before the destination)
+* **In Progress**: ringing (or waiting to be rung if it's the destination number)
+* **Busy**: appears in the "general call status" field after call has completed
+* **No Answer**
+* **Rejected**: party hung up, line closed
+* **Generic Error**
+* **Finished**: other party hung up, line closed
+* **International calls disabled**
+* **Destination number prohibited**
+
+In general, this is how I've observed call statuses to proceed over the course of the RingOut procedure:
+
+When the call is initiated, the callback number is called. All statuses are "In Progress."
+
+    >> RingCentral::Phone.status(3)
+    => {
+         :general     => "In Progress",
+         :callback    => "In Progress",
+         :destination => "In Progress"
+       }
+
+When the call to the callback number is picked up, that status goes to "Success." It will remain this way during the time it takes for the operator to respond to the call connection prompt, if you did not skip it.
+
+    >> RingCentral::Phone.status(3)
+    => {
+         :general     => "In Progress",
+         :callback    => "Success",
+         :destination => "In Progress"
+       }
+
+When the destination number is picked up, all statuses go to "Success." They will remain this way while the call is in progress.
+
+    >> RingCentral::Phone.status(3)
+    => {
+         :general     => "Success",
+         :callback    => "Success",
+         :destination => "Success"
+       }
+
+When both calls (to the callback and the destination numbers) have completed, the final statuses are "Call Completed." They will remain this way for a couple seconds.
+
+    >> RingCentral::Phone.status(3)
+    => {
+         :general     => "Call Completed",
+         :callback    => "Call Completed",
+         :destination => "Call Completed"
+       }
+
+Edge cases: I haven't experimented with many cases, but as an example this is the status returned when the callback number rejects the call.
+
+    >> RingCentral::Phone.status(6)
+    => {
+         :general     => "Busy",
+         :callback    => "Rejected",
+         :destination => "Generic Error"
+       }
+
+
+#### Cancel
+
+    RingCentral::Phone.cancel(session_id, ws = nil)
+
+Cancel a RingOut call with a given `session_id`. It seems like you can only cancel while one of the numbers is still ringing, or perhaps only when the callback number is being rung. You cannot cancel a call that has been picked up and is running.
+
+The response is simply the session ID in a hash. The same response is given no matter what the result of the API call was. Essentially this method could be considered to make a "best effort" attempt to cancel your call, but don't rely on it.
+
+    >> RingCentral::Phone.cancel(242323)
+    => { :session_id => "242323" }
+
+
+### FaxOut
+
+To be implemented.
+
+
+Todo
+----
+
+* Be able to supply RingCentral account credentials once, up-front, rather than supplying with each API call.
+* Wrap up the call, status, and cancel into a Call object which maintains its state.
+* Set Call command arguments using response from the List command, perhaps so a user could do `call(:from => :mobile)`
+* Determine how accepting the RingCentral APIs are of formatted or malformed input.
+* Implement the FaxOut API.
+* Write tests.
+
+
+Contact
+-------
+
+Problems, comments, and pull requests all welcome. [Find me on GitHub.](http://github.com/tfe/)
+
+
+Copyright
+-------
+
+Copyright © 2010 [Todd Eichel](http://toddeichel.com/) for [Fooala, Inc.](http://opensource.fooala.com/).

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "ringcentral"
+    gem.summary = %Q{A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.}
+    gem.description = %Q{A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.}
+    gem.email = "todd@toddeichel.com"
+    gem.homepage = "http://github.com/tfe/ringcentral"
+    gem.authors = ["Todd Eichel"]
+    gem.add_development_dependency "thoughtbot-shoulda", ">= 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 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "ringcentral #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/ringcentral.rb

@@ -0,0 +1,136 @@
+require 'rest_client'
+
+module RingCentral
+  
+  URL = 'https://service.ringcentral.com'
+  
+  class Fax
+    
+    PATH = 'faxapi.asp'
+    URL = [RingCentral::URL, PATH].join('/')
+    
+  end
+  
+  class Phone
+    
+    PATH = 'ringout.asp'
+    URL = [RingCentral::URL, PATH].join('/')
+    SuccessResponse = 'OK'
+    
+    STATUS_CODES = {
+      0 => 'Success',          # picked up, line open (gets set for the callback number before the destination)
+      1 => 'In Progress',      # ringing (or waiting to be rung if it's the destination number)
+      2 => 'Busy',             # appears in the "general call status" field after call has completed
+      3 => 'No Answer',
+      4 => 'Rejected',         # party hung up, line closed
+      5 => 'Generic Error',
+      6 => 'Finished',         # other party hung up, line closed
+      7 => 'International calls disabled',
+      8 => 'Destination number prohibited'
+    }
+    
+    
+    def self.list(username, password, extension)
+      
+      params = { :cmd => :list }
+      response = RestClient.post(URL, params.merge(RingCentral.credentials_hash(username, password, extension)))
+      body = response.body
+      
+      if body[0..1] == SuccessResponse # sucessful responses start with "OK "
+        data = body[3..-1]
+        return Hash[*data.split(';')].invert
+      else
+        raise "RingCentral response: #{body}"
+      end
+    end
+    
+    
+    def self.call(username, password, extension, to, from, caller_id, prompt = 1)
+      
+      params = {
+        :cmd => :call,
+        :to => to,
+        :from => from,
+        :clid => caller_id,
+        :prompt => prompt
+      }
+      response = RestClient.post(URL, params.merge(RingCentral.credentials_hash(username, password, extension)))
+      body = response.body
+      
+      if body[0..1] == SuccessResponse # sucessful responses start with "OK "
+        session_id, ws = body[3..-1].split(' ')
+        return { :session_id => session_id, :ws => ws }
+      else
+        raise "RingCentral response: #{body}"
+      end
+    end
+    
+    
+    # Notes:
+    #  - WS param doesn't seem to do anything or even be required
+    #  - API always gives the "completed call" response regardless of whether the session ID is valid
+    #  - while call is running (and for a few seconds after it is disconnected), status string with both callback 
+    #    and destination number are given, with statuses for both; after that, only the session ID is given
+    def self.status(session_id, ws = nil)
+      
+      params = {
+        :cmd => :status,
+        :sessionid => session_id,
+        :ws => ws
+      }
+      response = RestClient.post(URL, params)
+      body = response.body
+      
+      if body[0..1] == SuccessResponse # sucessful responses start with "OK "
+        session_id, statuses = body[3..-1].split(' ')
+        if statuses
+          statuses = statuses.split(';')
+          return {
+            :general     => STATUS_CODES[statuses[0].to_i],
+            :destination => STATUS_CODES[statuses[2].to_i],
+            :callback    => STATUS_CODES[statuses[4].to_i]
+          }
+        else
+          return {
+            :general     => "Call Completed",
+            :destination => "Call Completed",
+            :callback    => "Call Completed"
+          }
+        end
+      else
+        raise "RingCentral response: #{body}"
+      end
+    end
+    
+    
+    def self.cancel(session_id, ws = nil)
+      
+      params = {
+        :cmd => :cancel,
+        :sessionid => session_id,
+        :ws => ws
+      }
+      response = RestClient.post(URL, params)
+      body = response.body
+      
+      if body[0..1] == SuccessResponse # sucessful responses start with "OK "
+        session_id = body[3..-1]
+        return { :session_id => session_id }
+      else
+        raise "RingCentral response: #{body}"
+      end
+    end
+  end
+  
+  
+  private
+  
+  def self.credentials_hash(username, password, extension = nil)
+    {
+      :username => username,
+      :password => password,
+      :ext => extension
+    }
+  end
+  
+end

data/rails/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), *%w[.. lib ringcentral])

data/ringcentral.gemspec

@@ -0,0 +1,55 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{ringcentral}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Todd Eichel"]
+  s.date = %q{2010-07-31}
+  s.description = %q{A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.}
+  s.email = %q{todd@toddeichel.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.md"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "VERSION",
+     "lib/ringcentral.rb",
+     "rails/init.rb",
+     "ringcentral.gemspec",
+     "test/helper.rb",
+     "test/test_ringcentral.rb"
+  ]
+  s.homepage = %q{http://github.com/tfe/ringcentral}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.}
+  s.test_files = [
+    "test/helper.rb",
+     "test/test_ringcentral.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    else
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+  end
+end
+

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'ringcentral'
+
+class Test::Unit::TestCase
+end

data/test/test_ringcentral.rb

@@ -0,0 +1,7 @@
+require 'helper'
+
+class TestRingcentral < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification 
+name: ringcentral
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Todd Eichel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-31 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: thoughtbot-shoulda
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id001
+description: A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.
+email: todd@toddeichel.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.md
+- Rakefile
+- VERSION
+- lib/ringcentral.rb
+- rails/init.rb
+- ringcentral.gemspec
+- test/helper.rb
+- test/test_ringcentral.rb
+has_rdoc: true
+homepage: http://github.com/tfe/ringcentral
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A Ruby library for interacting with the RingCentral RingOut API and (coming soon) FaxOut API.
+test_files: 
+- test/helper.rb
+- test/test_ringcentral.rb