tropo_rest 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+pkg/*
+*.gem
+.bundle
+.yardoc
+doc/*
+*.rbc

data/.rspec

@@ -0,0 +1,3 @@
+--colour
+--format=nested
+--backtrace

data/Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in tropo_rest.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,88 @@
+PATH
+  remote: .
+  specs:
+    tropo_rest (0.0.1)
+      faraday (~> 0.5.3)
+      faraday_middleware (~> 0.3.1)
+      hashie (~> 0.4.0)
+      multi_json (~> 0.0.5)
+      multi_xml (~> 0.2.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.2)
+    archive-tar-minitar (0.5.2)
+    autotest (4.3.2)
+    autotest-fsevent (0.2.4)
+      sys-uname
+    autotest-growl (0.2.9)
+    columnize (0.3.2)
+    crack (0.1.8)
+    diff-lcs (1.1.2)
+    faraday (0.5.3)
+      addressable (~> 2.2.2)
+      multipart-post (~> 1.0.1)
+      rack (>= 1.1.0, < 2)
+    faraday_middleware (0.3.1)
+      faraday (~> 0.5.3)
+    hashie (0.4.0)
+    json (1.4.6)
+    json (1.4.6-java)
+    linecache19 (0.5.11)
+      ruby_core_source (>= 0.1.4)
+    multi_json (0.0.5)
+    multi_xml (0.2.0)
+    multipart-post (1.0.1)
+    nokogiri (1.4.4)
+    nokogiri (1.4.4-java)
+      weakling (>= 0.0.3)
+    rack (1.2.1)
+    rake (0.8.7)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    ruby-debug-base19 (0.11.24)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.4)
+      archive-tar-minitar (>= 0.5.2)
+    sys-uname (0.8.5)
+    weakling (0.0.4-java)
+    webmock (1.6.1)
+      addressable (>= 2.2.2)
+      crack (>= 0.1.7)
+    yard (0.6.4)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  autotest (~> 4.3.2)
+  autotest-fsevent (~> 0.2.4)
+  autotest-growl (~> 0.2.9)
+  bundler (>= 1.0.0)
+  faraday (~> 0.5.3)
+  faraday_middleware (~> 0.3.1)
+  hashie (~> 0.4.0)
+  json (~> 1.4)
+  multi_json (~> 0.0.5)
+  multi_xml (~> 0.2.0)
+  nokogiri (~> 1.4.4)
+  rake (~> 0.8.7)
+  rspec (~> 2.3.0)
+  ruby-debug19
+  tropo_rest!
+  webmock (~> 1.6.1)
+  yard (~> 0.6.4)

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 by Christopher Durtschi
+
+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,104 @@
+TropoRest
+=========
+
+A simple Ruby wrapper for the Tropo REST API
+
+Installation
+------------
+
+    $ gem install tropo_rest
+
+You will also need to install your favorite JSON and XML libraries.
+Acceptable choices are yajl-ruby, json, active_support, or json_pure for JSON,
+and nokogiri, libxml, or rexml for XML.
+
+
+Usage Examples
+--------------
+
+    require 'tropo_rest'
+
+    TropoRest.configure do |config|
+      config.username = 'tropousername'
+      config.password = 'tropopassword'
+    end
+
+    # Gets all of your applications
+    puts TropoRest.applications
+
+    # Gets a specific application by ID
+    puts TropoRest.application(123456)
+
+    # You can also pass in the HREF of the application instead of the ID
+    puts TropoRest.application('https://api.tropo.com/v1/applications/123456')
+
+    # Create an application
+    puts TropoRest.create_application(
+      :name => "new app",
+      :voice_url => "http://website.com",
+      :messaging_url => "http://website2.com",
+      :platform => "scripting",
+      :partition => "staging"
+    ) # returns an object with the "href" of the new application
+
+    # Update an application
+    puts TropoRest.update_application(123456,
+      :name => "newer app",
+      :platform => "webapi",
+      :partition => "production"
+    ) # returns an object with the "href" of the new application
+
+    # Delete an application
+    puts TropoRest.delete_application(123456)
+
+    # Gets all addresses for an application
+    puts TropoRest.addresses(123456)
+
+    # Gets a specific address
+    puts TropoRest.address(12345, "skype", "+99000936209990123456")
+
+    # You can also pass in the HREF of the address
+    puts TropoRest.address("https://api.tropo.com/v1/applications/123456/addresses/skype/+99000936209990123456")
+
+    # Create an address
+    puts TropoRest.create_address(123456,
+      :type => "number",
+      :prefix => "1407"
+    ) # returns an object with the "href" of the new address
+
+    # Delete an address
+    puts TropoRest.delete_address(123456, "skype", "+99000936209990123456")
+
+    # Gets all of the exchanges
+    puts TropoRest.exchanges
+
+    # Creates a session for the given token
+    puts TropoRest.create_session("TOKEN")
+
+    # Sends a signal to a current session.
+    # First parameter is the session ID, second is the signal to send.
+    puts TropoRest.create_signal("9a5c43f30b414d51901c4cfde00f43e8", "exit")
+
+
+Note on Patches/Pull Requests
+-----------------------------
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+
+Credits
+-------
+
+Thanks to [Tropo](https://www.tropo.com/) for creating such an awesome service.
+
+Thanks to the creators of the [twitter](https://github.com/jnunemaker/twitter/) gem, whose lovely code I shamelessly ripped off :)
+
+
+Copyright
+---------
+
+Copyright (c) 2011 Christopher Durtschi. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,35 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  # Put spec opts in a file named .rspec in root
+end
+
+desc "Generate code coverage"
+RSpec::Core::RakeTask.new(:coverage) do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end
+
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['HISTORY.mkd', 'LICENSE.mkd', 'lib/**/*.rb']
+    task.options = [
+      '--protected',
+      '--output-dir', 'doc/yard',
+      '--tag', 'format:Supported formats',
+      '--tag', 'authenticated:Requires Authentication',
+      '--tag', 'rate_limited:Rate Limited',
+      '--markup', 'markdown',
+    ]
+  end
+end

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/lib/faraday/request/serialize_json.rb

@@ -0,0 +1,17 @@
+module Faraday
+  class Request::SerializeJson < Faraday::Middleware
+    begin
+      require 'multi_json'
+    rescue LoadError, NameError => error
+      self.load_error = error
+    end
+
+    def call(env)
+      env[:request_headers]['Content-Type'] = 'application/json'
+      if env[:body] && !env[:body].respond_to?(:to_str)
+        env[:body] = ::MultiJson.encode(env[:body])
+      end
+      @app.call env
+    end
+  end
+end

data/lib/faraday/response/raise_http_errors.rb

@@ -0,0 +1,52 @@
+module Faraday
+  class Response::RaiseHttpErrors < Response::Middleware
+    def self.register_on_complete(env)
+      env[:response].on_complete do |response|
+        case response[:status].to_i
+        when 400
+          raise TropoRest::BadRequest, error_message(response)
+        when 401
+          raise TropoRest::NotAuthorized, error_message(response)
+        when 403
+          raise TropoRest::AccessDenied, error_message(response)
+        when 404
+          raise TropoRest::NotFound, error_message(response)
+        when 405
+          raise TropoRest::MethodNotAllowed, error_message(response)
+        when 415
+          raise TropoRest::UnsupportedMediaType, error_message(response)
+        when 500
+          raise TropoRest::InternalServerError, error_message(response)
+        when 503
+          raise TropoRest::ServiceUnavailable, error_message(response)
+        end
+      end
+    end
+
+    def initialize(app)
+      super
+      @parser = nil
+    end
+
+    private
+
+    def self.error_message(response)
+      "#{response[:method].to_s.upcase} #{response[:url].to_s}: #{response[:status]}#{error_body(response[:body])}"
+    end
+
+    def self.error_body(body)
+      if body.nil?
+        nil
+      elsif body['error']
+        ": #{body['error']}"
+      elsif body['errors']
+        first = body['errors'].to_a.first
+        if first.kind_of? Hash
+          ": #{first['message'].chomp}"
+        else
+          ": #{first.chomp}"
+        end
+      end
+    end
+  end
+end

data/lib/faraday/response/resource.rb

@@ -0,0 +1,26 @@
+module Faraday
+  class Response::Resource < Response::Middleware
+    class << self
+      attr_accessor :resource
+    end
+
+    def self.register_on_complete(env)
+      env[:response].on_complete do |response|
+        if resource
+          response_body = response[:body]
+          if response_body.is_a?(Hash)
+            response[:body] = resource.new(response_body)
+          elsif response_body.is_a?(Array)
+            response[:body] = response_body.map{|item| item.is_a?(Hash) ? resource.new(item) : item}
+          end
+        end
+      end
+    end
+
+    def initialize(app, resource=nil)
+      super app
+      self.class.resource = resource
+      @parser = nil
+    end
+  end
+end

data/lib/hashie/twash.rb

@@ -0,0 +1,61 @@
+require 'hashie/dash'
+
+module Hashie
+  # A Twash is a two-way Trash. You can get back to the original keys using #to_hash
+  class Twash < Hashie::Dash
+
+    # Defines a property on the Twash. Options are as follows:
+    #
+    # * <tt>:default</tt> - Specify a default value for this property, to be
+    # returned before a value is set on the property in a new Dash.
+    # * <tt>:from</tt> - Specify the original key name that will be write only.
+    def self.property(property_name, options = {})
+      super
+
+      if options[:from]
+        translations[options[:from].to_sym] = property_name.to_sym
+        class_eval <<-RUBY
+          def #{options[:from]}=(val)
+            self[:#{property_name}] = val
+          end
+        RUBY
+      end
+    end
+
+    # Set a value on the Twash in a Hash-like way. Only works
+    # on pre-existing properties.
+    def []=(property, value)
+      if self.class.translations.keys.include? property.to_sym
+        send("#{property}=", value)
+      elsif property_exists? property
+        super
+      end
+    end
+
+    def to_hash
+      out = super
+      self.class.translations.each do |from, to|
+        to_s = to.to_s
+        if out.keys.include?(to_s)
+          out[from.to_s] = out.delete(to_s)
+        end
+      end
+      out
+    end
+
+    private
+
+    def self.translations
+      @translations ||= {}
+    end
+
+    # Raises an NoMethodError if the property doesn't exist
+    #
+    def property_exists?(property)
+      unless self.class.property?(property.to_sym)
+        raise NoMethodError, "The property '#{property}' is not defined for this Trash."
+      end
+      true
+    end
+  end
+end

data/lib/tropo_rest/client/address.rb

@@ -0,0 +1,76 @@
+module TropoRest
+  class Client
+    module Address
+
+      SINGULAR_PATH = "applications/%d/addresses/%s/%s".freeze
+      PLURAL_PATH   = "applications/%d/addresses".freeze
+      RESOURCE      = TropoRest::Resource::Address
+
+      # Returns the addresses for the specified application
+      #
+      # @param application_id [String, Integer] The ID of the application.
+      # @return [Array] The addresses.
+      # @raise [TropoRest::NotFound] Error raised when ID does not identify an active application.
+      # @see https://www.tropo.com/docs/rest/prov_view_app_addresses.htm
+      def addresses(application_id)
+        path = get_path(PLURAL_PATH, application_id)
+        get(path, RESOURCE)
+      end
+
+      # Returns the specified address
+      #
+      # @overload address(application_id, type, identifier)
+      #   @param application_id [String, Integer] The ID of the application.
+      #   @param type [String] The type of address (aim, gtalk, jabber, msn, skype, number, token, yahoo)
+      #   @param identifier [String] The address, number, or username
+      # @overload address(href)
+      #   @param href [String] The HREF of the address
+      # @return [TropoRest::Resource::Address] The address.
+      # @raise [TropoRest::NotFound] Error raised when address not found.
+      def address(*args)
+        path = get_path(SINGULAR_PATH, *args)
+        get(path, RESOURCE)
+      end
+
+      # Creates a new address for the specified application
+      #
+      # @param application_id_or_href [String, Integer] The ID or HREF of the application.
+      # @param params [Hash] The attributes of the address to be created.
+      # @option params [String] :type The type of address to create (aim, gtalk, jabber, msn, number, token, yahoo). Required.
+      # @option params [String] :prefix The country and area code for a number
+      # @option params [String] :number A complete phone number already assigned to an existing application
+      # @option params [String] :channel Either "voice" or "messaging", used when creating a token
+      # @option params [String] :username An IM username. Required when adding an IM account
+      # @option params [String] :password An IM password. Required when adding an IM account
+      # @return [Hashie::Mash] An object containing the "href" of the new application
+      # @raise [TropoRest::BadRequest] Error raised when invalid parameters are supplied.
+      # @see https://www.tropo.com/docs/rest/prov_add_number.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_toll_free.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_international.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_specific_num.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_im.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_token.htm
+      def create_address(application_id_or_href, params={})
+        path = get_path(PLURAL_PATH, application_id_or_href)
+        post(path, RESOURCE.new(params))
+      end
+
+      # Removes an address from an application
+      #
+      # @overload delete_address(application_id, type, identifier)
+      #   @param application_id [String, Integer] The ID of the application.
+      #   @param type [String] The type of address (aim, gtalk, jabber, msn, skype, number, token, yahoo)
+      #   @param identifier [String] The address, number, or username
+      # @overload delete_address(href)
+      #   @param href [String] The HREF of the address to be deleted.
+      # @return [Hashie::Mash] An object with a "message" attribute indicating success.
+      # @raise [TropoRest::NotFound] Error raised when address not found.
+      # @see https://www.tropo.com/docs/rest/prov_delete_address.htm
+      def delete_address(*args)
+        path = get_path(SINGULAR_PATH, *args)
+        delete(path)
+      end
+
+    end
+  end
+end

data/lib/tropo_rest/client/application.rb

@@ -0,0 +1,72 @@
+module TropoRest
+  class Client
+    module Application
+
+      SINGULAR_PATH = "applications/%d".freeze
+      PLURAL_PATH   = "applications".freeze
+      RESOURCE      = TropoRest::Resource::Application
+
+      # Returns the authenticated user's applications
+      #
+      # @return [Array] The applications.
+      # @see https://www.tropo.com/docs/rest/prov_view_apps.htm
+      def applications
+        get(PLURAL_PATH, RESOURCE)
+      end
+
+      # Returns the application specified by an ID
+      #
+      # @param id_or_href [String, Integer] The ID or HREF of the application.
+      # @return [TropoRest::Resource::Application] The application.
+      # @raise [TropoRest::NotFound] Error raised when ID does not identify an active application.
+      def application(id_or_href)
+        path = get_path(SINGULAR_PATH, id_or_href)
+        get(path, RESOURCE)
+      end
+
+      # Creates a new application
+      #
+      # @param params [Hash] The attributes of the application to be created.
+      # @option params [String] :name The name of the application. Required.
+      # @option params [String] :platform Either "scripting" or "webapi". Required.
+      # @option params [String] :partition Either "staging" or "production". Defaults to "staging" if not specified.
+      # @option params [String] :voice_url The voice endpoint of the application. Optional.
+      # @option params [String] :messaging_url The messaging endpoint of the application. Optional.
+      # @return [Hashie::Mash] An object containing the "href" of the new application
+      # @raise [TropoRest::BadRequest] Error raised when invalid parameters are supplied.
+      # @see https://www.tropo.com/docs/rest/prov_new_app.htm
+      def create_application(params={})
+        post(PLURAL_PATH, RESOURCE.new(params))
+      end
+
+      # Permanently destroys the application specified by an ID
+      #
+      # @param id_or_href [String, Integer] The ID or HREF of the application to be deleted.
+      # @return [Hashie::Mash] An object with a "message" attribute indicating success.
+      # @raise [TropoRest::NotFound] Error raised when ID does not identify an active application.
+      def delete_application(id_or_href)
+        path = get_path(SINGULAR_PATH, id_or_href)
+        delete(path)
+      end
+
+      # Updates an application
+      #
+      # @param id_or_href [String, Integer] The ID or HREF of the application to be updated.
+      # @param params [Hash] The attributes to be updated. of the application.
+      # @option params [String] :name The name of the application. Required.
+      # @option params [String] :platform Either "scripting" or "webapi". Required.
+      # @option params [String] :partition Either "staging" or "production". Defaults to "staging" if not specified.
+      # @option params [String] :voice_url The voice endpoint of the application. Optional.
+      # @option params [String] :messaging_url The messaging endpoint of the application. Optional.
+      # @return [Hashie::Mash] An object containing the "href" of the new application
+      # @raise [TropoRest::NotFound] Error raised when ID does not identify an active application.
+      # @see https://www.tropo.com/docs/rest/prov_update_name.htm
+      # @see https://www.tropo.com/docs/rest/prov_add_urls.htm
+      def update_application(id_or_href, params={})
+        path = get_path(SINGULAR_PATH, id_or_href)
+        put(path, RESOURCE.new(params))
+      end
+
+    end
+  end
+end

data/lib/tropo_rest/client/exchange.rb

@@ -0,0 +1,18 @@
+module TropoRest
+  class Client
+    module Exchange
+
+      PLURAL_PATH = "exchanges".freeze
+      RESOURCE    = TropoRest::Resource::Exchange
+
+      # Returns the exchanges available for the authenticated user
+      #
+      # @return [Array] The exchanges.
+      # @see https://www.tropo.com/docs/rest/prov_view_exchanges.htm
+      def exchanges
+        get(PLURAL_PATH, RESOURCE)
+      end
+
+    end
+  end
+end

data/lib/tropo_rest/client/session.rb

@@ -0,0 +1,20 @@
+module TropoRest
+  class Client
+    module Session
+
+      PLURAL_PATH = "sessions".freeze
+
+      # Creates a session for the given token
+      #
+      # @param token [String] The token of the application.
+      # @param params [Hash] The parameters to pass to the session.
+      # @return [Hashie::Mash] The session object.
+      # @see https://www.tropo.com/docs/rest/starting_session.htm
+      def create_session(token, params={})
+        params.merge! 'action' => 'create', 'token' => token
+        get(PLURAL_PATH, params)
+      end
+
+    end
+  end
+end

data/lib/tropo_rest/client/signal.rb

@@ -0,0 +1,26 @@
+module TropoRest
+  class Client
+    module Signal
+
+      PLURAL_PATH = "sessions/%s/signals".freeze
+
+      # Sends a signal for the given session ID
+      #
+      # @param session_id [String] The 16-byte GUID session ID.
+      # @param signal [String] The signal to send to the session.
+      # @return [Hashie::Mash] The signal object. Will have a field "status" with one of these values: "QUEUED", "NOTFOUND", "FAILED"
+      # @see https://www.tropo.com/docs/rest/interrupting_code_one_signal.htm
+      # @see https://www.tropo.com/docs/rest/interrupting_code_multiple.htm
+      # @see https://www.tropo.com/docs/rest/unnamed_signals.htm
+      # @see https://www.tropo.com/docs/rest/redirecting_app_based_on_signal.htm
+      # @see https://www.tropo.com/docs/rest/event_queuing.htm
+      # @see https://www.tropo.com/docs/rest/starting_session.htm
+      # @see https://www.tropo.com/docs/rest/parameters.htm
+      def create_signal(session_id, signal)
+        path = get_path(PLURAL_PATH, session_id)
+        post(path, {"signal" => signal})
+      end
+
+    end
+  end
+end

data/lib/tropo_rest/client.rb

@@ -0,0 +1,27 @@
+module TropoRest
+  class Client
+    attr_accessor *Configuration::VALID_OPTIONS_KEYS
+
+    include Connection
+    include Request
+
+    require 'tropo_rest/client/application'
+    require 'tropo_rest/client/exchange'
+    require 'tropo_rest/client/address'
+    require 'tropo_rest/client/session'
+    require 'tropo_rest/client/signal'
+
+    include TropoRest::Client::Application
+    include TropoRest::Client::Exchange
+    include TropoRest::Client::Address
+    include TropoRest::Client::Session
+    include TropoRest::Client::Signal
+
+    def initialize(options={})
+      options = TropoRest.options.merge(options)
+      Configuration::VALID_OPTIONS_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+  end
+end