twilio-ruby 3.2.0 → 3.3.0

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

@@ -8,28 +8,88 @@ module Twilio
         @instance_class = Twilio::REST.const_get @resource_name.chop
         @uri, @client = uri, client
       end
-    
-      # Grab a list of this kind of resource and return it as an array.
+
+      def inspect # :nodoc:
+        "<#{self.class} @uri=#{@uri}>"
+      end
+
+      ##
+      # Grab a list of this kind of resource and return it as an array. The
+      # array includes a special attribute named +total+ which will return the
+      # total number of items in the list on Twilio's server. This may differ
+      # from the +size+ and +length+ attributes of the returned array since
+      # by default Twilio will only return 50 resources, and the maximum number
+      # of resources you can request is 1000.
+      #
+      # The optional +params+ hash allows you to filter the list returned. The
+      # filters for each list resource type are defined by Twilio
       def list(params = {})
         raise "Can't get a resource list without a REST Client" unless @client
         response = @client.get @uri, params
         resources = response[detwilify(@resource_name)]
-        resources.map do |resource|
-          @instance_class.new "#{@uri}/#{resource['sid']}", @client, resource
+        resource_list = resources.map do |resource|
+          @instance_class.new "#{@uri}/#{resource[instance_sid_key]}", @client,
+            resource
         end
+        # set the +total+ property on the array
+        resource_list.instance_eval {
+          eigenclass = class << self; self; end
+          eigenclass.send :define_method, :total, &lambda {response['total']}
+        }
+        # update the list's internal total if we just fetched the whole list
+        @total = response['total'] if params.empty?
+        resource_list
       end
 
-      # Return an empty instance resource object with the proper URI.
+      ##
+      # Ask Twilio for the total number of items in the list and cache it.
+      # Calling this method makes an HTTP GET request to <tt>@uri</tt> with a
+      # page size parameter of 1 to minimize data over the wire while still
+      # obtaining the total. Don't use this or #total if you are planning to
+      # call #list anyway, since the array returned from #list will have a
+      # +total+ attribute as well.
+      def total!
+        raise "Can't get a resource total without a REST Client" unless @client
+        response = @client.get @uri, :page_size => 1
+        @total = response['total']
+      end
+
+      ##
+      # Return the cached total number of items in the list, or fetch and cache.
+      def total
+        @total ||= total!
+      end
+
+      ##
+      # Return an empty instance resource object with the proper URI. Note that
+      # this will never raise a Twilio::REST::RequestError on 404 since no HTTP
+      # request is made. The HTTP request is made when attempting to access an
+      # attribute of the returned instance resource object, such as
+      # its #date_created or #voice_url attributes.
       def get(sid)
         @instance_class.new "#{@uri}/#{sid}", @client
       end
-    
-      # Return a newly created resource.
+      alias :find :get # for the ActiveRecord lovers
+
+      ##
+      # Return a newly created resource. Some +params+ may be required. Consult
+      # the Twilio REST API documentation related to the kind of resource you
+      # are attempting to create for details. Calling this method makes an HTTP
+      # POST request to <tt>@uri</tt> with the given params
       def create(params = {})
         raise "Can't create a resource without a REST Client" unless @client
         response = @client.post @uri, params
         @instance_class.new "#{@uri}/#{response['sid']}", @client, response
       end
+
+      private
+
+      ##
+      # Return the JSON key containing the sid of each instance. Overridden for
+      # conference participants and perhaps other resources.
+      def instance_sid_key
+        'sid'
+      end
     end
   end
 end

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

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

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

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

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

@@ -1,12 +1,12 @@
 module Twilio
   module REST
-    class Recording < InstanceResource
+    class Recordings < ListResource; end
 
+    class Recording < InstanceResource
       def initialize(uri, client, params={})
         super uri, client, params
         resource :transcriptions
       end
-
     end
   end
 end

data/lib/twilio-ruby/rest/sms/messages.rb

@@ -7,5 +7,7 @@ module Twilio
         @resource_name = 'sms_messages'
       end
     end
+
+    class Message < InstanceResource; end
   end
 end

data/lib/twilio-ruby/rest/sms/short_codes.rb

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

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

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

data/lib/twilio-ruby/version.rb

@@ -0,0 +1,3 @@
+module Twilio
+  VERSION = '3.3.0'
+end

data/lib/twilio-ruby.rb

@@ -1,52 +1,37 @@
-TWILIO_RUBY_ROOT = File.expand_path(File.dirname(__FILE__))
-
 require 'net/http'
 require 'net/https'
 require 'builder'
-require 'json'
+require 'multi_json'
 require 'cgi'
 require 'openssl'
 require 'base64'
 require 'jwt'
 
-
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/util"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/util/request_validator"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/util/capability"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/errors"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/utils"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/list_resource"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/instance_resource"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sandbox/sandbox"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/accounts/account"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/accounts/accounts"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/calls/call"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/calls/calls"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sms/sms"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sms/message"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sms/messages"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sms/short_code"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/sms/short_codes"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/applications/application"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/applications/applications"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/outgoing_caller_ids/outgoing_caller_id"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/outgoing_caller_ids/outgoing_caller_ids"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/incoming_phone_numbers/incoming_phone_number"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/incoming_phone_numbers/incoming_phone_numbers"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/available_phone_numbers/available_phone_number"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/available_phone_numbers/available_phone_numbers"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/available_phone_numbers/country"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/available_phone_numbers/local"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/available_phone_numbers/toll_free"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/conferences/conference"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/conferences/conferences"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/conferences/participant"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/conferences/participants"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/recordings/recording"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/recordings/recordings"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/transcriptions/transcription"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/transcriptions/transcriptions"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/notifications/notification"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/notifications/notifications"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/rest/client"
-require "#{TWILIO_RUBY_ROOT}/twilio-ruby/twiml/response"
+require 'twilio-ruby/version'
+require 'twilio-ruby/util'
+require 'twilio-ruby/util/request_validator'
+require 'twilio-ruby/util/capability'
+require 'twilio-ruby/twiml/response'
+require 'twilio-ruby/rest/errors'
+require 'twilio-ruby/rest/utils'
+require 'twilio-ruby/rest/list_resource'
+require 'twilio-ruby/rest/instance_resource'
+require 'twilio-ruby/rest/sandbox'
+require 'twilio-ruby/rest/accounts'
+require 'twilio-ruby/rest/calls'
+require 'twilio-ruby/rest/sms'
+require 'twilio-ruby/rest/sms/messages'
+require 'twilio-ruby/rest/sms/short_codes'
+require 'twilio-ruby/rest/applications'
+require 'twilio-ruby/rest/outgoing_caller_ids'
+require 'twilio-ruby/rest/incoming_phone_numbers'
+require 'twilio-ruby/rest/available_phone_numbers'
+require 'twilio-ruby/rest/available_phone_numbers/country'
+require 'twilio-ruby/rest/available_phone_numbers/local'
+require 'twilio-ruby/rest/available_phone_numbers/toll_free'
+require 'twilio-ruby/rest/conferences'
+require 'twilio-ruby/rest/conferences/participants'
+require 'twilio-ruby/rest/recordings'
+require 'twilio-ruby/rest/transcriptions'
+require 'twilio-ruby/rest/notifications'
+require 'twilio-ruby/rest/client'

data/test/twilio_spec.rb

@@ -1,6 +1,7 @@
-require 'rubygems'
+$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
 require 'twilio-ruby'
 require 'fakeweb'
+require 'rack'
 
 describe Twilio::REST::Client do
   before :all do
@@ -21,14 +22,14 @@ describe Twilio::REST::Client do
   end
   
   it 'should set up the proper http ssl connection when a different domain is given' do
-    twilio = Twilio::REST::Client.new('someSid', 'someToken', 'api.faketwilio.com')
+    twilio = Twilio::REST::Client.new('someSid', 'someToken', :host => 'api.faketwilio.com')
     twilio.instance_variable_get('@connection').address.should == 'api.faketwilio.com'
     twilio.instance_variable_get('@connection').port.should == 443
     twilio.instance_variable_get('@connection').use_ssl?.should == true
   end
 
   it 'should set up the proper http ssl connection when a proxy_host is given' do
-    twilio = Twilio::REST::Client.new('someSid', 'someToken', 'api.faketwilio.com', 'localhost')
+    twilio = Twilio::REST::Client.new('someSid', 'someToken', :host => 'api.faketwilio.com', :proxy_addr => 'localhost')
     twilio.instance_variable_get('@connection').proxy?.should == true
     twilio.instance_variable_get('@connection').proxy_address.should == 'localhost'
     twilio.instance_variable_get('@connection').proxy_port.should == 80
@@ -38,7 +39,7 @@ describe Twilio::REST::Client do
   end
 
   it 'should set up the proper http ssl connection when a proxy_host and proxy_port are given' do
-    twilio = Twilio::REST::Client.new('someSid', 'someToken', 'api.faketwilio.com', 'localhost', 13128)
+    twilio = Twilio::REST::Client.new('someSid', 'someToken', :host => 'api.faketwilio.com', :proxy_addr => 'localhost', :proxy_port => 13128)
     twilio.instance_variable_get('@connection').proxy?.should == true
     twilio.instance_variable_get('@connection').proxy_address.should == 'localhost'
     twilio.instance_variable_get('@connection').proxy_port.should == 13128
@@ -208,3 +209,139 @@ describe Twilio::Util::RequestValidator do
     validator.validate(url, params, signature).should == true
   end
 end
+
+describe Twilio::Util::Capability do
+  before :each do
+    @capability = Twilio::Util::Capability.new 'myAccountSid', 'myAuthToken'
+  end
+
+  def queries(q)
+    q.scan(/scope:client:(incoming|outgoing)\?(\S+)/).map{|(type, query)| [type, Rack::Utils.parse_query(query)]}
+  end
+
+  it 'should return a valid jwt when #generate is called' do
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    decoded['scope'].should_not be_nil
+    decoded['iss'].should_not be_nil
+    decoded['exp'].should_not be_nil
+  end
+
+  it 'should properly set the iss key in the payload' do
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    decoded['iss'].should == 'myAccountSid'
+  end
+
+  it 'should properly set the exp key based on the default hour ttl' do
+    seconds = Time.now.to_i
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    decoded['exp'].should == seconds + 3600
+  end
+
+  it 'should properly set the exp key based on the ttl passed to #generate' do
+    ttl = rand 10000
+    seconds = Time.now.to_i
+    token = @capability.generate ttl
+    decoded = JWT.decode token, 'myAuthToken'
+    decoded['exp'].should == seconds + ttl
+  end
+
+  it 'should generate a proper incoming client scope string' do
+    @capability.allow_client_incoming 'andrew'
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [['incoming', {'clientName' => 'andrew'}]]
+  end
+
+  it 'should generate multiple proper incoming client scope strings' do
+    @capability.allow_client_incoming 'andrew'
+    @capability.allow_client_incoming 'bridget'
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [
+      ['incoming', {'clientName' => 'andrew'}],
+      ['incoming', {'clientName' => 'bridget'}]
+    ]
+  end
+
+  it 'should generate a proper outgoing client scope string' do
+    @capability.allow_client_outgoing 'myAppSid'
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [['outgoing', {'appSid' => 'myAppSid'}]]
+  end
+
+  it 'should generate a proper outgoing client scope string with parameters' do
+    app_params_hash = {'key' => 'a value', :foo => 'bar/baz'}
+    @capability.allow_client_outgoing 'myAppSid', app_params_hash
+    app_params = @capability.instance_eval {url_encode(app_params_hash)}
+    params_hash = {'appSid' => 'myAppSid', 'appParams' => app_params}
+    params = @capability.instance_eval {url_encode(params_hash)}
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [['outgoing', params_hash]]
+  end
+
+  it 'should generate a proper outgoing client scope string based on the ' +
+    'client name when calling #allow_client_incoming first' do
+    @capability.allow_client_incoming 'andrew'
+    @capability.allow_client_outgoing 'myAppSid'
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [
+      ['incoming', {'clientName' => 'andrew'}],
+      ['outgoing', {'clientName' => 'andrew', 'appSid' => 'myAppSid'}]
+    ]
+  end
+
+  it 'should generate a proper outgoing client scope string based on the ' +
+    'client name when calling #allow_client_incoming second' do
+    @capability.allow_client_outgoing 'myAppSid'
+    @capability.allow_client_incoming 'andrew'
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    queries(decoded['scope']).should == [["incoming", {"clientName"=>"andrew"}], ["outgoing", {"clientName"=>"andrew", "appSid"=>"myAppSid"}]]
+  end
+
+  it 'should generate a proper outgoing client scope string with parameters ' +
+    'and a client name when calling #allow_client_incoming first' do
+    @capability.allow_client_incoming 'andrew'
+    app_params_hash = {'key' => 'a value', :foo => 'bar/baz'}
+    @capability.allow_client_outgoing 'myAppSid', app_params_hash
+    app_params = @capability.instance_eval {url_encode(app_params_hash)}
+    params_hash = {'appSid' => 'myAppSid', 'appParams' => app_params, 'clientName' => 'andrew'}
+    params = @capability.instance_eval {url_encode(params_hash)}
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    scopes = queries(decoded['scope'])
+    scopes.shift.should == ["incoming", {"clientName"=>"andrew"}]
+    scope = scopes.shift
+    scope.first.should == 'outgoing'
+    Rack::Utils.parse_query(scope.last['appParams']).should == {'key' => 'a value', 'foo' => 'bar/baz'}
+    scope.last["clientName"].should == "andrew"
+    scope.last["appSid"].should == "myAppSid"
+    scopes.should be_empty
+  end
+
+  it 'should generate a proper outgoing client scope string with parameters ' +
+    'and a client name when calling #allow_client_incoming second' do
+    app_params_hash = {'key' => 'a value', :foo => 'bar/baz'}
+    @capability.allow_client_outgoing 'myAppSid', app_params_hash
+    @capability.allow_client_incoming 'andrew'
+    app_params = @capability.instance_eval {url_encode(app_params_hash)}
+    params_hash = {'appSid' => 'myAppSid', 'appParams' => app_params, 'clientName' => 'andrew'}
+    params = @capability.instance_eval {url_encode(params_hash)}
+    token = @capability.generate
+    decoded = JWT.decode token, 'myAuthToken'
+    scopes = queries(decoded['scope'])
+    scopes.shift.should == ["incoming", {"clientName"=>"andrew"}]
+    scope = scopes.shift
+    scope.first.should == 'outgoing'
+    Rack::Utils.parse_query(scope.last['appParams']).should == {'key' => 'a value', 'foo' => 'bar/baz'}
+    scope.last["clientName"].should == "andrew"
+    scope.last["appSid"].should == "myAppSid"
+    scopes.should be_empty
+  end
+end

data/twilio-ruby.gemspec

@@ -1,15 +1,29 @@
+require 'lib/twilio-ruby/version'
+
 Gem::Specification.new do |s|
-  s.name = "twilio-ruby"
-  s.version = "3.2.0"
-  s.author = "Andrew Benton"
-  s.email = "andrew@twilio.com"
-  s.description = "A simple library for communicating with the Twilio REST API, building TwiML, and generating Twilio Client Capability Tokens"
-  s.summary = "A simple library for communicating with the Twilio REST API, building TwiML, and generating Twilio Client Capability Tokens"
-  s.homepage = "http://github.com/twilio/twilio-ruby"
+  s.name = 'twilio-ruby'
+  s.version = Twilio::VERSION
+  s.author = 'Andrew Benton'
+  s.email = 'andrew@twilio.com'
+
+  s.description = 'A simple library for communicating with the Twilio REST API, building TwiML, and generating Twilio Client Capability Tokens'
+  s.summary = 'A simple library for communicating with the Twilio REST API, building TwiML, and generating Twilio Client Capability Tokens'
+  s.homepage = 'http://github.com/twilio/twilio-ruby'
+
   s.platform = Gem::Platform::RUBY
-  s.files = Dir['lib/**/*.rb'] + Dir['test/**/*.rb'] + ['examples.rb', 'Rakefile', 'LICENSE', 'README.md', 'twilio-ruby.gemspec']
+  s.require_paths = %w[lib]
+  s.files = `git ls-files`.split("\n")
   s.test_files = Dir['test/**/*.rb']
-  s.add_dependency("json", ">= 1.2.0")
-  s.add_dependency("builder", ">= 2.1.2")
-  s.add_dependency("jwt", ">= 0.1.2")
+
+  s.add_dependency('multi_json', '>= 1.0.3')
+  s.add_dependency('builder', '>= 2.1.2')
+  s.add_dependency('jwt', '>= 0.1.2')
+
+  s.add_development_dependency 'rake',    '~> 0.9.0'
+  s.add_development_dependency 'rspec',   '~> 2.6.0'
+  s.add_development_dependency 'fakeweb', '~> 1.3.0'
+  s.add_development_dependency 'rack',    '~> 1.3.0'
+
+  s.extra_rdoc_files = ['README.md', 'README.rdoc', 'examples.rb', 'LICENSE']
+  s.rdoc_options = ['--line-numbers', '--inline-source', '--title', 'twilio-ruby', '--main', 'README.md']
 end