twilio-ruby 3.2.0 → 3.3.0

data/.gitignore

@@ -0,0 +1,5 @@
+*~
+.*
+pkg/*
+doc/*
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/README.md

@@ -16,20 +16,82 @@ $ rake gem
 $ gem install pkg/twilio-ruby-{version}
 ```
 
-## Some Code To Get You Started
+## Get Started With Client Capability Tokens
+
+If you just need to generate a Capability Token for use with Twilio Client, you
+can do this:
+
+``` ruby
+require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+require 'twilio-ruby'
+
+# put your own account credentials here:
+account_sid = 'AC043dcf9844e13758bc3a36a84c29761'
+auth_token = '62ea81de3a5b413254eb263595357c69'
+
+# set up
+capability = Twilio::Util::Capability.new account_sid, auth_token
+
+# allow outgoing calls to an application
+capability.allow_client_outgoing 'AP89a0180a1a4ddf1da954efca349b7a20'
+
+# allow incoming calls to 'andrew'
+capability.allow_client_incoming 'andrew'
+
+# generate the token string
+@token = capability.generate
+```
+
+There is a slightly more detailed document in the
+[Capability](twilio-ruby/wiki/Capability) section of the wiki.
+
+## Getting Started with TwiML
+
+TwiML support is based on the [builder][1] library. You can construct a TwiML
+response like this:
+
+``` ruby
+require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+require 'twilio-ruby'
+
+# build up a response
+response = Twilio::TwiML::Response.new do |r|
+  r.Say 'hello there', :voice => 'woman'
+  r.Dial :callerId => '+14159992222' do |d|
+    d.Client 'jenny'
+  end
+end
+
+# print the result
+puts response.text
+```
+
+This will print the following (except for the whitespace):
+
+```
+<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say voice="woman">hello there</Say>
+  <Dial callerId="+14159992222">
+    <Client>jenny</Client>
+  </Dial>
+</Response>
+```
+
+## Getting Started with REST
 
 ### Setup Work
 
 ``` ruby
-require 'rubygems' # not necessary with ruby 1.9.2 but included for completeness
+require 'rubygems' # not necessary with ruby 1.9 but included for completeness
 require 'twilio-ruby'
 
 # put your own credentials here
-@account_sid = 'AC043dcf9844e04758bc3a36a84c29761'
-@auth_token = '62ea81de3a5b414154eb263595357c69'
+account_sid = 'AC043dcf9844e04758bc3a36a84c29761'
+auth_token = '62ea81de3a5b414154eb263595357c69'
 
 # set up a client to talk to the Twilio REST API
-@client = Twilio::REST::Client.new(@account_sid, @auth_token)
+@client = Twilio::REST::Client.new account_sid, auth_token
 ```
 
 ### Send an SMS
@@ -84,4 +146,6 @@ require 'twilio-ruby'
 
 There are more detailed examples in the included [examples.rb](twilio-ruby/blob/master/examples.rb).
 
-Full [API documentation](twilio-ruby/wiki/Documentation), as well as an [upgrade guide](twilio-ruby/wiki/UpgradeGuide) for users of the old twiliolib gem, is available in the [twilio-ruby github wiki](twilio-ruby/wiki).
+Full [API documentation](twilio-ruby/wiki/Documentation), as well as an [upgrade guide](twilio-ruby/wiki/UpgradeGuide) for users of the old twiliolib gem, is available in the [twilio-ruby github wiki](twilio-ruby/wiki).
+
+[1]:http://builder.rubyforge.org/

data/lib/twilio-ruby/rest/{accounts/account.rb → accounts.rb}

@@ -1,5 +1,7 @@
 module Twilio
   module REST
+    class Accounts < ListResource; end
+
     class Account < InstanceResource
       def initialize(uri, client, params={})
         super uri, client, params

data/lib/twilio-ruby/rest/{applications/application.rb → applications.rb}

@@ -1,5 +1,6 @@
 module Twilio
   module REST
+    class Applications < ListResource; end
     class Application < InstanceResource; end
   end
 end

data/lib/twilio-ruby/rest/{available_phone_numbers/available_phone_numbers.rb → available_phone_numbers.rb}

@@ -7,5 +7,7 @@ module Twilio
         @uri, @client = uri, client
       end
     end
+
+    class AvailablePhoneNumber < InstanceResource; end
   end
 end

data/lib/twilio-ruby/rest/{calls/call.rb → calls.rb}

@@ -1,5 +1,11 @@
 module Twilio
   module REST
+    class Calls < ListResource
+      def make(from, to, url)
+        create :from => from, :to => to, :url => url
+      end
+    end
+
     class Call < InstanceResource
       def initialize(uri, client, params={})
         super uri, client, params

data/lib/twilio-ruby/rest/client.rb

@@ -1,26 +1,118 @@
 module Twilio
   module REST
+    ##
+    # The Twilio::REST::Client class caches authentication parameters and
+    # exposes methods to make HTTP requests to Twilio's REST API. However, you
+    # should never really need to call these methods yourself since you can
+    # work with the more pleasant wrapper objects like Twilio::REST::Call.
+    #
+    # Instantiate a client like so:
+    #
+    #   @client = Twilio::REST::Client.new account_sid, auth_token
+    #
+    # There are a few options you can use to configure the way your client will
+    # communicate with Twilio. See #new for a list and descriptions.
+    #
+    # Once you have a client object you can use it to do fun things. Every
+    # client object exposes two wrapper objects which you can use as entry
+    # points into Twilio: +account+ and +accounts+.
+    #
+    # ==== @client.account
+    #
+    # Most of the time you'll want to start with the +account+ attribute. This
+    # object is an instance of Twilio::REST::Account that wraps the account
+    # referenced by the +account_sid+ you used when instantiating the client.
+    #
+    # An instance of Twilio::REST::Account exposes objects wrapping all of the
+    # account-level Twilio resources as properties. So
+    #
+    #   @client.account.calls
+    #
+    # represents an account's call list.
+    #
+    # ==== @client.accounts
+    #
+    # If you are doing anything related to subaccounts you'll want to start
+    # here. This object is an instance of Twilio::REST::Accounts that wraps
+    # the list of accounts belonging to the master account referenced by
+    # the +account_sid+ used to instantiate the client.
+    #
+    # This class inherits from Twilio::REST::ListResource, so you can use
+    # methods like ListResource#list to return a (possibly filtered) list of
+    # accounts and ListResource#create to create a new account. Use
+    # ListResource#get to grab a particular account once you know its sid.
     class Client
-
       include Twilio::Util
       include Twilio::REST::Utils
 
       HTTP_HEADERS = {
         'Accept' => 'application/json',
-        'User-Agent' => 'twilio-ruby/3.2.0',
+        'User-Agent' => "twilio-ruby/#{Twilio::VERSION}",
       }
 
-      attr_reader :account_sid, :account, :accounts
+      attr_reader :account_sid, :account, :accounts, :last_request,
+        :last_response
 
-      def initialize(account_sid, auth_token, domain = 'api.twilio.com',
-                     proxy_host = nil, proxy_port = nil)
-        @account_sid = account_sid
-        @auth_token = auth_token
-        set_up_connection_to domain, proxy_host, proxy_port
+      ##
+      # Instantiate a new HTTP client to talk to Twilio. The parameters
+      # +account_sid+ and +auth_token+ are required and used to generate the
+      # HTTP basic auth header in each request. The +options+ parameter is a
+      # hash of connection configuration options. the following keys are
+      # supported:
+      #
+      # === <tt>:host => 'api.twilio.com'</tt>
+      #
+      # The domain to which you'd like the client to make HTTP requests. Useful
+      # for testing. Defaults to 'api.twilio.com'.
+      #
+      # === <tt>:port => 443</tt>
+      #
+      # The port on which to connect to the above domain. Defaults to 443 and
+      # should be left that way except in testing environments.
+      #
+      # === <tt>:use_ssl => true</tt>
+      #
+      # Declare whether ssl should be used for connections to the above domain.
+      # Defaults to true and should be left alone except when testing.
+      #
+      # === <tt>:ssl_verify_peer => true</tt>
+      #
+      # Declare whether to verify the host's ssl cert when setting up the
+      # connection to the above domain. Defaults to true, but can be turned off
+      # to avoid insecure connection warnings in environments without the proper
+      # cert validation chain.
+      #
+      # === <tt>:proxy_addr => 'proxy.host.domain'</tt>
+      #
+      # The domain of a proxy through which you'd like the client to make HTTP
+      # requests. Defaults to nil.
+      #
+      # === <tt>:proxy_port => 3128</tt>
+      #
+      # The port on which to connect to the above proxy. Defaults to nil.
+      #
+      # === <tt>:proxy_user => 'username'</tt>
+      #
+      # The user name to use for authentication with the proxy. Defaults to nil.
+      #
+      # === <tt>:proxy_pass => 'password'</tt>
+      #
+      # The password to use for authentication with the proxy. Defaults to nil.
+      def initialize(account_sid, auth_token, options = {})
+        @account_sid, @auth_token = account_sid.strip, auth_token.strip
+        set_up_connection_from options
         set_up_subresources
       end
 
-      # Define some helper methods for sending HTTP requests
+      def inspect # :nodoc:
+        "<Twilio::REST::Client @account_sid=#{@account_sid}>"
+      end
+
+      ##
+      # Define #get, #put, #post and #delete helper methods for sending HTTP
+      # requests to Twilio. You shouldn't need to use these methods directly,
+      # but they can be useful for debugging. Each method returns a hash
+      # obtained from parsing the JSON object in the response body.
       [:get, :put, :post, :delete].each do |method|
         method_class = Net::HTTP.const_get method.to_s.capitalize
         define_method method do |uri, *args|
@@ -34,13 +126,21 @@ module Twilio
         end
       end
 
-      # Mimic the old (deprecated) interface
-      def request(uri, method = 'POST', params = {})
+      ##
+      # Mimic the old (deprecated) interface. Make an HTTP request to Twilio
+      # using the given +method+ and +uri+. If the +method+ is <tt>'GET'</tt>
+      # then +params+ are appended to the +uri+ as urlencoded query parameters.
+      # If the +method+ is <tt>'POST'</tt> or <tt>'PUT'</tt> then +params+ are
+      # passed as an application/x-www-form-urlencoded string in the request
+      # body.
+      #
+      # Returns the raw Net::HTTP::Response object.
+      def request(uri, method = 'POST', params = {}) # :nodoc:
         raise ArgumentError, 'Invalid path parameter' if uri.empty?
 
         uri = "/#{uri}" unless uri.start_with? '/'
 
-        case method
+        case method.upcase
         when 'GET'
           uri << "?#{url_encode(params)}" if params
           req = Net::HTTP::Get.new uri
@@ -57,33 +157,47 @@ module Twilio
         end
 
         req.basic_auth @account_sid, @auth_token
-        @connection.request req
+        @last_request = req
+        @last_response = @connection.request req
       end
 
       private
 
-      def set_up_connection_to(domain, proxy_host = nil, proxy_port = nil)
-        connection_class = Net::HTTP::Proxy proxy_host, proxy_port
-        @connection = connection_class.new domain, 443
-        @connection.use_ssl = true
-        # Don't check the server cert. Ideally this is configurable in case an
-        # app wants to verify that it's actually talking to the real Twilio.
-        # But cert validation is usually a nightmare, so we skip it for now.
-        @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      ##
+      # Set up and cache a Net::HTTP object to use when making requests. This is
+      # a private method documented for completeness.
+      def set_up_connection_from(options = {}) # :doc:
+        config = {:host => 'api.twilio.com', :port => 443, :use_ssl => true,
+          :ssl_verify_peer => true}.merge! options
+        connection_class = Net::HTTP::Proxy config[:proxy_addr],
+          config[:proxy_port], config[:proxy_user], config[:proxy_pass]
+        @connection = connection_class.new config[:host], config[:port]
+        @connection.use_ssl = config[:use_ssl]
+        unless config[:ssl_verify_peer]
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
       end
 
-      def set_up_subresources
+      ##
+      # Set up +account+ and +accounts+ attributes.
+      def set_up_subresources # :doc:
         accounts_uri = '/2010-04-01/Accounts'
         account_uri = "#{accounts_uri}/#{@account_sid}"
-        # Set up a special handle to grab the account.
         @account = Twilio::REST::Account.new account_uri, self
-        # Set up the accounts subresource.
         @accounts = Twilio::REST::Accounts.new accounts_uri, self
       end
 
-      def connect_and_send(request)
+      ##
+      # Send an HTTP request using the cached <tt>@connection</tt> object and
+      # return the JSON response body parsed into a hash. Also save the raw
+      # Net::HTTP::Request and Net::HTTP::Response objects as
+      # <tt>@last_request</tt> and <tt>@last_response</tt> to allow for
+      # inspection later.
+      def connect_and_send(request) # :doc:
+        @last_request = request
         response = @connection.request request
-        object = JSON.parse response.body if response.body
+        @last_response = response
+        object = MultiJson.decode response.body if response.body
         if response.kind_of? Net::HTTPClientError
           raise Twilio::REST::RequestError, object['message']
         elsif response.kind_of? Net::HTTPServerError
@@ -91,7 +205,6 @@ module Twilio
         end
         object
       end
-
     end
   end
 end

data/lib/twilio-ruby/rest/conferences/participants.rb

@@ -1,5 +1,22 @@
 module Twilio
   module REST
-    class Participants < ListResource; end
+    class Participants < ListResource
+      private
+      def instance_sid_key
+        'call_sid'
+      end
+    end
+
+    class Participant < InstanceResource
+      def mute
+        update :muted => 'true'
+      end
+
+      def unmute
+        update :muted => 'false'
+      end
+
+      alias :kick :delete
+    end
   end
 end

data/lib/twilio-ruby/rest/{conferences/conference.rb → conferences.rb}

@@ -1,5 +1,7 @@
 module Twilio
   module REST
+    class Conferences < ListResource; end
+
     class Conference < InstanceResource
       def initialize(uri, client, params={})
         super uri, client, params

data/lib/twilio-ruby/rest/{incoming_phone_numbers/incoming_phone_numbers.rb → incoming_phone_numbers.rb}

@@ -5,5 +5,7 @@ module Twilio
         create :phone_number => phone_number
       end
     end
+
+    class IncomingPhoneNumber < InstanceResource; end
   end
 end

data/lib/twilio-ruby/rest/instance_resource.rb

@@ -1,13 +1,41 @@
 module Twilio
   module REST
+    ##
+    # A class to wrap an instance resource (like a call or application) within
+    # the Twilio API. All other instance resource classes within this library
+    # inherit from this class. You shouldn't need to instantiate this class
+    # directly. But reviewing the available methods is informative since they
+    # are rarely overridden in the inheriting class.
     class InstanceResource
       include Utils
 
+      ##
+      # Instantiate a new instance resource object. You must pass the +uri+ of
+      # the instance (e.g. /2010-04-01/Accounts/AC123/Calls/CA456) as well as a
+      # +client+ object that responds to #get #post and #delete. This client
+      # is meant to be an instance of Twilio::REST::Client but could just as
+      # well be a mock object if you want to test the interface. The optional
+      # +params+ hash will be converted into attributes on the instantiated
+      # object.
       def initialize(uri, client, params = {})
         @uri, @client = uri, client
         set_up_properties_from params
       end
 
+      def inspect # :nodoc:
+        "<#{self.class} @uri=#{@uri}>"
+      end
+
+      ##
+      # Update the properties of this instance resource using the key/value
+      # pairs in +params+. This makes an HTTP POST request to <tt>@uri</tt>
+      # to handle the update. For example, to update the +VoiceUrl+ of a Twilio
+      # Application you could write:
+      #
+      #   @app.update :voice_url => 'http://my.other.app.com/handle_voice'
+      #
+      # After returning, the object will contain the most recent state of the
+      # instance resource, including the newly updated properties.
       def update(params = {})
         raise "Can't update a resource without a REST Client" unless @client
         response = @client.post @uri, params
@@ -15,18 +43,29 @@ module Twilio
         self
       end
 
+      ##
+      # Refresh the attributes of this instance resource object by fetching it
+      # from Twilio. Calling this makes an HTTP GET request to <tt>@uri</tt>.
       def refresh
         raise "Can't refresh a resource without a REST Client" unless @client
         @updated = false
         response = @client.get @uri
         set_up_properties_from response
+        self
       end
 
+      ##
+      # Delete an instance resource from Twilio. This operation isn't always
+      # supported. For instance, you can't delete an SMS. Calling this method
+      # makes an HTTP DELETE request to <tt>@uri</tt>.
       def delete
         raise "Can't delete a resource without a REST Client" unless @client
         @client.delete @uri
       end
 
+      ##
+      # Lazily load attributes of the instance resource by waiting to fetch it
+      # until an attempt is made to access an unknown attribute.
       def method_missing(method, *args)
         super if @updated
         response = @client.get @uri