Merge branch 'master' of github.com:twilio/twilio-ruby

CHANGES.md

@@ -11,6 +11,15 @@ Release August 11, 2015
   - Worker
   - TaskQueue
 
+Version 4.2.1
+-------------
+
+Release June 19, 2015
+
+- Allow passing URL parameters through when getting statistics for TaskRouter objects
+- URI encode phone number lookups
+- Adds documentation for lookups
+
 Version 4.2.0
 -------------
 

README.md

@@ -11,7 +11,7 @@ A module for using the Twilio REST API and generating valid [TwiML](http://www.t
 To install using [Bundler][bundler] grab the latest stable version:
 
 ```ruby
-gem 'twilio-ruby', '~> 4.1.0'
+gem 'twilio-ruby', '~> 4.2.1'
 ```
 
 To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:
@@ -147,6 +147,30 @@ capability.allow_client_incoming 'andrew'
 There is a slightly more detailed document in the [Capability][capability]
 section of the wiki.
 
+## Lookup Phone Number information
+
+You can look up details on phone numbers with the Lookups API.
+
+```ruby
+require 'twilio-ruby'
+
+# put your own credentials here
+account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
+
+# set up a client to talk to the Twilio REST API
+@lookups_client = Twilio::REST::LookupsClient.new account_sid, auth_token
+
+# lookup a number
+number = @lookups_client.phone_numbers.get('+14159341234')
+
+# investigate the number
+number.national_format
+# => "(415) 934-1234"
+number.country_code
+# => "US"
+```
+
 ## Getting Started With TwiML
 
 TwiML support is based on the [Builder][builder] library. You can construct a
@@ -201,7 +225,7 @@ If you've instead found a bug in the library or would like new features added, g
 ## More Information
 
 There are more detailed examples in the included [examples][examples]
-directory. Also for thoose upgrading, the [upgrade guide][upgrade] is available in the [twilio-ruby github wiki][wiki].
+directory. Also for those upgrading, the [upgrade guide][upgrade] is available in the [twilio-ruby github wiki][wiki].
 
 [capability]: https://github.com/twilio/twilio-ruby/wiki/Capability
 [builder]: http://builder.rubyforge.org/

docs/index.rst

@@ -71,6 +71,16 @@ state.
     usage/taskrouter-tokens
 
 
+Lookups
+-------
+
+Query the Lookups API to get information about phone numbers and their carriers.
+
+.. toctree::
+    :maxdepth: 1
+
+    usage/lookups
+
 TwiML
 ---------
 

docs/usage/lookups.rst

@@ -0,0 +1,62 @@
+===========
+Lookups API
+===========
+
+Lookups allows you to systematically ascertain information about phone numbers. With Lookups, you can identify local-friendly number formats, reduce the likelihood of undelivered messages and protect yourself from fraud.
+
+For more information see the `Lookups API <https://www.twilio.com/docs/api/rest/lookups>`_ documentation.
+
+Looking up details on a phone number
+------------------------------------
+
+You can look up a phone number with a :class:`Twilio::REST::LookupsClient`. You instantiate the client as you would with any other :class:`Twilio::REST` client
+
+.. code-block:: ruby
+
+    require "twilio-ruby"
+
+    # Find these values at twilio.com/user/account
+    account_sid = "AC123123"
+    auth_token = "secret"
+
+    @lookups_client = Twilio::REST::LookupsClient.new account_sid, auth_token
+
+You can then use the client to lookup a phone number.
+
+.. code-block:: ruby
+
+    response = @lookups_client.phone_numbers.get("+12316851234")
+    response.country_code
+    # => "US"
+    response.phone_number
+    # => "+12316851234"
+    response.national_format
+    # => "(231) 685-1234"
+    response.url
+    # => "https://lookups.twilio.com/v1/PhoneNumbers/+12316851234"
+
+Invalid Phone Numbers
+---------------------
+
+The Lookups API is a REST API that returns data on phone number resources. If you try to lookup a phone number that doesn't exist the API will raise a 404 :class:`Twilio::REST::RequestError`. You should handle this within your code.
+
+.. code-block:: ruby
+
+    response = @lookups_client.phone_numbers.get("+15558675309")
+    begin
+      puts response.phone_number
+    rescue Twilio::REST::RequestError => e
+      raise e unless e.code == 20404 # ensure this is a 404 error
+      puts "Invalid number"
+    end
+
+Carrier Information
+-------------------
+
+The Lookups API can be used to find out more information about the carrier for the phone number. Just pass the type "carrier" to the request.
+
+.. code-block:: ruby
+
+    response = @lookups_client.phone_numbers.get("+12316851234", type: "carrier")
+    response.carrier
+    # => {"mobile_country_code"=>nil, "mobile_network_code"=>nil, "name"=>"Charter Fiberlink, LLC", "type"=>"landline", "error_code"=>nil}

lib/twilio-ruby/rest/list_resource.rb

@@ -35,11 +35,10 @@ def inspect # :nodoc:
 
       ##
       # 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.
+      # array includes two special methods +previous_page+ and +next_page+
+      # which will return the previous or next page or resources. By default
+      # Twilio will only return 50 resources, and the maximum number of
+      # resources you can request (using the :page_size param) is 1000.
       #
       # The optional +params+ hash allows you to filter the list returned. The
       # filters for each list resource type are defined by Twilio.

lib/twilio-ruby/rest/lookups/phone_numbers.rb

@@ -6,7 +6,7 @@ class PhoneNumbers < Twilio::REST::NextGenListResource;
         include Twilio::REST::Utils
 
         def get(number, query={})
-          full_path = "#{@path}/#{number}"
+          full_path = "#{@path}/#{URI.encode(number)}"
           full_path << "?#{url_encode(twilify(query))}" if !query.empty?
           @instance_class.new full_path, @client
         end

lib/twilio-ruby/rest/task_router/statistics.rb

@@ -4,7 +4,7 @@ module TaskRouter
       module Statistics
         def statistics(args={})
           path = "#{@path}/Statistics"
-          response = @client.get(path, args, true)
+          response = @client.get(path, args)
           statistics_class.new(path, @client, response)
         end
 

spec/rest/lookups/phone_number_spec.rb

@@ -5,4 +5,24 @@
     client = Twilio::REST::LookupsClient.new 'otherSid', 'otherToken'
     expect(client).to respond_to(:phone_numbers)
   end
+
+  it 'gets phone numbers without special encoding' do
+    number = '+13123131434'
+    client = Twilio::REST::LookupsClient.new 'otherSid', 'otherToken'
+    expect(client).to receive(:get).once
+      .with('/v1/PhoneNumbers/+13123131434')
+      .and_return({ phone_number: number })
+    phone_number = client.phone_numbers.get('+13123131434').phone_number
+    expect(phone_number).to be(number)
+  end
+
+  it 'URI encodes phone number path parameters' do
+    number = '+13123131434'
+    client = Twilio::REST::LookupsClient.new 'otherSid', 'otherToken'
+    expect(client).to receive(:get).once
+      .with('/v1/PhoneNumbers/+1%20312%20313%201434')
+      .and_return({ phone_number: number })
+    phone_number = client.phone_numbers.get('+1 312 313 1434').phone_number
+    expect(phone_number).to be(number)
+  end
 end

spec/rest/task_router/statistics_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+class Twilio::REST::TaskRouter::StatisticsTestHarnessStatistics
+  def initialize(*args)
+  end
+end
+
+class StatisticsTestHarness
+  include Twilio::REST::TaskRouter::Statistics
+
+  def initialize(path, client)
+    @path = path
+    @client = client
+  end
+end
+
+describe Twilio::REST::TaskRouter::Statistics do
+  it "creates a new statistics object based on the class" do
+    client = double("Client")
+    allow(client).to receive(:get)
+    harness = StatisticsTestHarness.new("/test/harness", client)
+    expect(harness.statistics).to(
+      be_an_instance_of(Twilio::REST::TaskRouter::StatisticsTestHarnessStatistics)
+    )
+  end
+
+  it "passes parameters to the HTTP request for statistics" do
+    client = Twilio::REST::TaskRouterClient.new 'someSid', 'someAuthToken', 'someWorkspaceSid'
+    allow(Net::HTTP::Get).to receive(:new)
+      .with("/test/harness/Statistics?Minutes=15", Twilio::REST::BaseClient::HTTP_HEADERS)
+      .and_call_original
+    harness = StatisticsTestHarness.new("/test/harness", client)
+    expect(harness.statistics(minutes: 15)).to(
+      be_an_instance_of(Twilio::REST::TaskRouter::StatisticsTestHarnessStatistics)
+    )
+  end
+end