twilio-ruby 3.11.5 → 4.0.0

data/docs/usage/twiml.rst

@@ -18,7 +18,7 @@ which returns raw TwiML.
     require 'twilio-ruby'
 
     Twilio::TwiML::Response.new do |r|
-        r.Say "Hello"
+      r.Say "Hello"
     end.text
 
 .. code-block:: xml
@@ -35,14 +35,14 @@ All attributes are keyword arguments.
     require 'twilio-ruby'
 
     Twilio::TwiML::Response.new do |r|
-        r.Play "https://api.twilio.com/cowbell.mp3", :loop => 5
+      r.Play "https://api.twilio.com/cowbell.mp3", loop: 5
     end.text
 
 .. code-block:: xml
 
     <?xml version="1.0" encoding="utf-8"?>
     <Response>
-        <Play loop="3">https://api.twilio.com/cowbell.mp3</Play>
+      <Play loop="3">https://api.twilio.com/cowbell.mp3</Play>
     <Response>
 
 Any example of nesting nouns in verbs
@@ -52,10 +52,10 @@ Any example of nesting nouns in verbs
     require 'twilio-ruby'
 
     Twilio::TwiML::Response.new do |r|
-        r.Say "hello"
-        r.Gather :finish_on_key => 4 do |g|
-            g.Say "world"
-        end
+      r.Say "hello"
+      r.Gather finishOnKey: => 4 do |g|
+        g.Say "world"
+      end
     end.text
 
 which returns the following

data/docs/usage/validation.rst

@@ -48,12 +48,11 @@ actually from Twilio.
     signature = "HpS7PBa1Agvt4OtO+wZp75IuQa0=" # will look something like that
 
     if @validator.validate(url, post_vars, signature)
-        puts "Confirmed to have come from Twilio."
+      puts "Confirmed to have come from Twilio."
     else
-        puts "NOT VALID.  It might have been spoofed!"
+      puts "NOT VALID.  It might have been spoofed!"
     end
 
-
 Trailing Slashes
 ==================
 
@@ -69,3 +68,40 @@ https://mycompany.com/twilio and you may have built the hash using
 https://mycompany.com/twilio/. More information can be found in our
 documentation on validating requests.
 
+Rack Middleware
+===============
+
+If you are serving up your site using a Rack based framework, such as Sinatra or
+Rails, you can use the Rack middleware that is included in the gem to protect
+from spoofing attempts.
+
+To use the middleware, you need to set it up with your Twilio Auth Token and a
+set of paths to watch. For example, here is how you would use the middleware in
+a Sinatra application:
+
+.. code-block:: ruby
+
+    require 'sinatra'
+    require 'twilio-ruby'
+
+    auth_token = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+
+    use Rack::TwilioWebhookAuthentication, auth_token, /\/messages/
+
+    post '/messages' do
+      # response with TwiML
+    end
+
+Now, any POST request to /messages in your application that doesn't validate as
+a Twilio request, will automatically respond with a 403 status code and your
+action will not be hit.
+
+If you use subaccounts and need to validate with different auth tokens, you can pass a block to the middleware instead of an auth token. The block will be passed the Account Sid making the call.
+
+.. code-block:: ruby
+
+    use Rack::TwilioWebhookAuthentication, nil, /\/messages/ do |account_sid|
+      # lookup auth_token from account_sid
+    end
+
+Ensure you pass `nil` for the auth_token when passing a block, otherwise the block will not be called.

data/examples/examples.rb

@@ -8,7 +8,7 @@
 ################ ACCOUNTS ################
 
 # shortcut to grab your account object (account_sid is inferred from the client's auth credentials)
-@account = @client.account 
+@account = @client.account
 
 # list your (sub)accounts
 @client.accounts.list
@@ -19,12 +19,16 @@
 puts @account.friendly_name
 
 # update an account's friendly name
-@client.accounts.get(@account_sid).update(:friendly_name => 'A Fabulous Friendly Name')
+@client.accounts.get(@account_sid).update(friendly_name: 'A Fabulous Friendly Name')
 
 ################ CALLS ################
 
 # print a list of calls (all parameters optional)
-@account.calls.list({:page => 0, :page_size => 1000, :start_time => '2010-09-01'}).each do |call|
+@account.calls.list(
+  page: 0,
+  page_size: 1000,
+  start_time: '2010-09-01'
+).each do |call|
   puts call.sid
 end
 
@@ -34,18 +38,23 @@ end
 end
 
 # make a new outgoing call. returns a call object just like calls.get
-@call = @account.calls.create({:from => '+14159341234', :to => '+18004567890', :url => 'http://example.com/call-handler'})
+@call = @account.calls.create(
+  from: '+14159341234',
+  to: '+18004567890',
+  url: 'http://example.com/call-handler'
+)
 
 # cancel the call if not already in progress
-@account.calls.get(@call.sid).update({:status => 'canceled'})
+@account.calls.get(@call.sid).update(status: 'canceled')
 # or equivalently
-@call.update({:status => 'canceled'})
+@call.update(status: 'canceled')
 # or simply
 @call.cancel
 
 # redirect and then terminate a call
-@account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:url => 'http://example.com/call-redirect'})
-@account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:status => 'completed'})
+@call = @account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662')
+@call.update(url: 'http://example.com/call-redirect')
+@call.update(status: 'completed')
 # or, use the aliases...
 @call.redirect_to('http://example.com/call-redirect')
 @call.hangup
@@ -53,7 +62,7 @@ end
 ################ SMS MESSAGES ################
 
 # print a list of messages
-@account.messages.list({:date_sent => '2010-09-01'}).each do |message|
+@account.messages.list(date_sent: '2010-09-01').each do |message|
   puts message.body
 end
 
@@ -61,10 +70,18 @@ end
 puts @account.messages.get('SMXXXXXXXX').body
 
 # send an sms
-@account.messages.create(:from => '+14159341234', :to => '+16105557069', :body => 'Hey there!')
+@account.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  body: 'Hey there!'
+)
 
 # send an mms
-@account.messages.create(:from => '+14159341234', :to => '+16105557069', :media_urls => 'http://example.com/media.png')
+@account.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  media_urls: 'http://example.com/media.png'
+)
 
 ################ PHONE NUMBERS ################
 
@@ -72,22 +89,28 @@ puts @account.messages.get('SMXXXXXXXX').body
 @account.available_phone_numbers.list
 
 # print some available numbers
-@numbers = @account.available_phone_numbers.get('US').local.list({:contains => 'AWESOME'})
-@numbers.each {|num| puts num.phone_number}
+@numbers = @account.available_phone_numbers.get('US').local.list(
+  contains: 'AWESOME'
+)
+@numbers.each { |num| puts num.phone_number }
 
 # buy the first one
-@account.incoming_phone_numbers.create(:phone_number => @numbers[0].phone_number)
+@account.incoming_phone_numbers.create(phone_number: @numbers[0].phone_number)
 
 # update an existing phone number's voice url
-@account.incoming_phone_numbers.get('PNdba508c5616a7f5e141789f44f022cc3').update({:voice_url => 'http://example.com/voice'})
+number = @account.incoming_phone_numbers.get('PNdba508c5616a7f5e141789f44f022cc3')
+number.update(voice_url: 'http://example.com/voice')
 
 # decommission an existing phone number
-numbers = @account.incoming_phone_numbers.list(:friendly_name => 'A Fabulous Friendly Name') 
+numbers = @account.incoming_phone_numbers.list(
+  friendly_name: 'A Fabulous Friendly Name'
+)
 numbers[0].delete
 ################ CONFERENCES  ################
 
 # get a particular conference's participants object and stash it
-@participants = @account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39').participants
+conference = @account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39')
+@participants = conference.participants
 
 # list participants
 @participants.list.each do |p|
@@ -95,17 +118,18 @@ numbers[0].delete
 end
 
 # update a conference participant
-@participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:muted => 'true'})
+@participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').update(muted: 'true')
 # or an easier way
 @participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').mute
 
 # and, since we're lazy loading, this would only incur one http request
-@account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39').participants.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:muted => 'true'})
+@account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39').participants
+  .get('CA386025c9bf5d6052a1d1ea42b4d16662').update(muted: 'true')
 
 ################ QUEUES ###################
 
 # create a new queue
-@queue = @account.queues.create(:friendly_name => 'MyQueue', :max_size => 50)
+@queue = @account.queues.create(friendly_name: 'MyQueue', max_size: 50)
 
 # get a list of queues for this account
 @queues = @account.queues.list

data/examples/print-call-log.rb

@@ -13,7 +13,7 @@ auth_token = '62ea81de3a5b414154eb263595357c69'
 # set up a client
 client = Twilio::REST::Client.new(account_sid, auth_token)
 
-calls = client.account.calls.list
+calls = client.calls.list
 
 begin
   calls.each do |call|

data/lib/rack/twilio_webhook_authentication.rb

@@ -0,0 +1,47 @@
+module Rack
+  # Middleware that authenticates webhooks from Twilio using the request
+  # validator.
+  #
+  # The middleware takes an auth token with which to set up the request
+  # validator and any number of paths. When a path matches the incoming request
+  # path, the request will be checked for authentication.
+  #
+  # Example:
+  #
+  # require 'rack'
+  # use Rack::TwilioWebhookAuthentication, ENV['AUTH_TOKEN'], /\/messages/
+  #
+  # The above appends this middleware to the stack, using an auth token saved in
+  # the ENV and only against paths that match /\/messages/. If the request
+  # validates then it gets passed on to the action as normal. If the request
+  # doesn't validate then the middleware responds immediately with a 403 status.
+
+  class TwilioWebhookAuthentication
+    def initialize(app, auth_token, *paths, &auth_token_lookup)
+      @app = app
+      @auth_token = auth_token
+      define_singleton_method(:get_auth_token, auth_token_lookup) if block_given?
+      @path_regex = Regexp.union(paths)
+    end
+
+    def call(env)
+      return @app.call(env) unless env["PATH_INFO"].match(@path_regex)
+      request = Rack::Request.new(env)
+      original_url = request.url
+      params = request.post? ? request.POST : {}
+      auth_token = @auth_token || get_auth_token(params['AccountSid'])
+      validator = Twilio::Util::RequestValidator.new(auth_token)
+      signature = env['HTTP_X_TWILIO_SIGNATURE'] || ""
+      if validator.validate(original_url, params, signature)
+        @app.call(env)
+      else
+        [
+          403,
+          {'Content-Type' => 'text/plain'},
+          ["Twilio Request Validation Failed."]
+        ]
+      end
+    end
+  end
+
+end

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

@@ -8,7 +8,8 @@ module Twilio
         resource :sandbox, :available_phone_numbers, :incoming_phone_numbers,
           :calls, :outgoing_caller_ids, :conferences, :sms, :recordings,
           :transcriptions, :notifications, :applications, :connect_apps,
-          :authorized_connect_apps, :queues, :usage, :messages, :media, :sip
+          :authorized_connect_apps, :queues, :usage, :messages, :media, :sip,
+          :tokens, :addresses
       end
     end
   end

data/lib/twilio-ruby/rest/addresses/dependent_phone_numbers.rb

@@ -0,0 +1,6 @@
+module Twilio
+  module REST
+    class DependentPhoneNumbers < ListResource; end
+    class DependentPhoneNumber < InstanceResource; end
+  end
+end

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

@@ -0,0 +1,12 @@
+module Twilio
+  module REST
+    class Addresses < ListResource; end
+
+    class Address < InstanceResource
+      def initialize(path, client, params={})
+        super path, client, params
+        resource :dependent_phone_numbers
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+module Twilio
+  module REST
+    class BaseClient
+      include Twilio::Util
+      include Twilio::REST::Utils
+
+      HTTP_HEADERS = {
+          'Accept' => 'application/json',
+          'Accept-Charset' => 'utf-8',
+          'User-Agent' => "twilio-ruby/#{Twilio::VERSION}" \
+                        " (#{RUBY_ENGINE}/#{RUBY_PLATFORM}" \
+                        " #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL})"
+      }
+
+      ##
+      # Override the default host for a REST Client (api.twilio.com)
+      def self.host(host=nil)
+        return @host unless host
+        @host = host
+      end
+
+      attr_reader :account_sid, :last_request, :last_response
+
+      def initialize(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        options[:host] ||= self.class.host
+        @config = Twilio::Util::ClientConfig.new options
+
+        @account_sid = args[0] || Twilio.account_sid
+        @auth_token = args[1] || Twilio.auth_token
+        if @account_sid.nil? || @auth_token.nil?
+          raise ArgumentError, 'Account SID and auth token are required'
+        end
+
+        set_up_connection
+        set_up_subresources
+      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 |path, *args|
+          params = twilify(args[0])
+          params = {} if params.empty?
+          # build the full path unless already given
+          path = build_full_path(path, params, method) unless args[1]
+          request = method_class.new(path, HTTP_HEADERS)
+          request.basic_auth(@account_sid, @auth_token)
+          request.form_data = params if [:post, :put].include?(method)
+          connect_and_send(request)
+        end
+      end
+
+      protected
+
+      ##
+      # Builds up full request path
+      # Needs implementation in child classes
+      def build_full_path(path, params, method)
+        raise NotImplementedError
+      end
+
+      ##
+      # 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 # :doc:
+        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
+        set_up_ssl
+        @connection.open_timeout = @config.timeout
+        @connection.read_timeout = @config.timeout
+      end
+
+      ##
+      # Set up the ssl properties of the <tt>@connection</tt> Net::HTTP object.
+      # This is a private method documented for completeness.
+      def set_up_ssl # :doc:
+        @connection.use_ssl = @config.use_ssl
+        if @config.ssl_verify_peer
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          @connection.ca_file = @config.ssl_ca_file
+        else
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+      end
+
+      ##
+      # Set up sub resources attributes.
+      def set_up_subresources # :doc:
+        # To be overridden
+      end
+
+      ##
+      # 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
+        retries_left = @config.retry_limit
+        begin
+          response = @connection.request request
+          @last_response = response
+          if response.kind_of? Net::HTTPServerError
+            raise Twilio::REST::ServerError
+          end
+        rescue Exception
+          raise if request.class == Net::HTTP::Post
+          if retries_left > 0 then retries_left -= 1; retry else raise end
+        end
+        if response.body and !response.body.empty?
+          object = MultiJson.load response.body
+        end
+        if response.kind_of? Net::HTTPClientError
+          raise Twilio::REST::RequestError.new object['message'], object['code']
+        end
+        object
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Twilio
+  module REST
+    class Feedback < ListResource;
+
+      ##
+      # Get this feedback object.
+      #
+      # Overridden because GETS to /Feedback
+      # returns an instance, not a list.
+      def get(params={}, full_path=false)
+        raise "Can't fetch feedback without a REST Client" unless @client
+        response = @client.get @path, params, full_path
+        path = full_path ? @path.split('.')[0] : @path
+        @instance_class.new path, @client, response
+      end
+
+      ##
+      # Creates a new Feedback object.
+      def create(params={})
+        raise "Can't create feedback without a REST Client" unless @client
+        response = @client.post @path, params
+        @instance_class.new @path, @client, response
+      end
+    end
+
+    class FeedbackInstance < InstanceResource; end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Twilio
+  module REST
+    class FeedbackSummary < ListResource
+      def initialize(path, client)
+        @path, @client = path, client
+        @instance_class = Twilio::REST::FeedbackSummaryInstance
+        @list_key, @instance_id_key = 'feedback_summary', 'sid'
+      end
+    end
+
+    class FeedbackSummaryInstance < InstanceResource; end
+  end
+end

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

@@ -1,27 +1,32 @@
 module Twilio
   module REST
     class Calls < ListResource
+      def initialize(path, client)
+        super
+        resource :feedback_summary
+      end
+
       def make(from, to, url)
-        create :from => from, :to => to, :url => url
+        create from: from, to: to, url: url
       end
     end
 
     class Call < InstanceResource
       def initialize(path, client, params={})
         super path, client, params
-        resource :recordings, :notifications
+        resource :recordings, :notifications, :feedback
       end
 
       def redirect_to(url)
-        update :url => url
+        update url: url
       end
 
       def cancel
-        update :status => 'canceled'
+        update status: 'canceled'
       end
 
       def hangup
-        update :status => 'completed'
+        update status: 'completed'
       end
     end
   end