From f66f787fbe97a4e348929d66b0b6092db092e381 Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Wed, 29 Apr 2015 10:38:51 +0100 Subject: [PATCH 1/9] Adds documentation for the Lookups API --- README.md | 26 +++++++++++++++++- docs/index.rst | 10 +++++++ docs/usage/lookups.rst | 62 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 1 deletion(-) create mode 100644 docs/usage/lookups.rst diff --git a/README.md b/README.md index c40a1e81b..31a9883b7 100644 --- a/README.md +++ b/README.md @@ -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 @@ -191,7 +215,7 @@ implementations: - Ruby 1.9.3 - [JRuby][jruby] - [Rubinius][rubinius] -- +- ## Getting help diff --git a/docs/index.rst b/docs/index.rst index c4784894d..63f4f6fe9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -70,6 +70,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 --------- diff --git a/docs/usage/lookups.rst b/docs/usage/lookups.rst new file mode 100644 index 000000000..702b609b7 --- /dev/null +++ b/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 `_ 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} From ff71332569f2287b9b4096f63cfeeba08cd4b40d Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Wed, 6 May 2015 01:15:38 +0200 Subject: [PATCH 2/9] URI encode phone number lookups --- lib/twilio-ruby/rest/lookups/phone_numbers.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/twilio-ruby/rest/lookups/phone_numbers.rb b/lib/twilio-ruby/rest/lookups/phone_numbers.rb index 5c0dc0faf..c6cf48a03 100644 --- a/lib/twilio-ruby/rest/lookups/phone_numbers.rb +++ b/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 From 4d7d9c21e45db6f2c3910bbed5ba31069f715025 Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Wed, 6 May 2015 01:44:57 +0200 Subject: [PATCH 3/9] Adds specs for URI encoding phone numbers --- spec/rest/lookups/phone_number_spec.rb | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/spec/rest/lookups/phone_number_spec.rb b/spec/rest/lookups/phone_number_spec.rb index 30548eae6..0bdf54123 100644 --- a/spec/rest/lookups/phone_number_spec.rb +++ b/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 From e6ebf5730421a988682aa17e91e175a461e29cf0 Mon Sep 17 00:00:00 2001 From: Dawson Botsford Date: Sun, 31 May 2015 18:40:58 -0700 Subject: [PATCH 4/9] Spelling correction automated from Dawson's Spelling Bee --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9a4aaee2..3c6c9f7e1 100644 --- a/README.md +++ b/README.md @@ -201,7 +201,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/ From d743bed1f0c83a2bfb2cd375ceb21326f8ec9bf9 Mon Sep 17 00:00:00 2001 From: Ben Morris Date: Wed, 10 Jun 2015 15:41:22 -0400 Subject: [PATCH 5/9] Update README.md Bump Gem version to 4.2.0 in Readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9a4aaee2..ad8bea501 100644 --- a/README.md +++ b/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.0' ``` To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install: From a197343143d5c5976ae250eabb76c93007e12b38 Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Thu, 18 Jun 2015 17:57:18 +0100 Subject: [PATCH 6/9] Pass URL parameters through for task router statistics --- .../rest/task_router/statistics.rb | 2 +- spec/rest/task_router/statistics_spec.rb | 37 +++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 spec/rest/task_router/statistics_spec.rb diff --git a/lib/twilio-ruby/rest/task_router/statistics.rb b/lib/twilio-ruby/rest/task_router/statistics.rb index 364e91670..7822fa5e6 100644 --- a/lib/twilio-ruby/rest/task_router/statistics.rb +++ b/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 diff --git a/spec/rest/task_router/statistics_spec.rb b/spec/rest/task_router/statistics_spec.rb new file mode 100644 index 000000000..d22e5ce92 --- /dev/null +++ b/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::Client.new 'someSid', 'someAuthToken' + allow(Net::HTTP::Get).to receive(:new) + .with("/test/harness/Statistics.json?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 From 98d683562bd16f12fe67273e5126ff8778d1e0c7 Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Thu, 18 Jun 2015 18:16:14 +0100 Subject: [PATCH 7/9] Use TaskRouterClient in test for realism --- spec/rest/task_router/statistics_spec.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/rest/task_router/statistics_spec.rb b/spec/rest/task_router/statistics_spec.rb index d22e5ce92..58adff2ee 100644 --- a/spec/rest/task_router/statistics_spec.rb +++ b/spec/rest/task_router/statistics_spec.rb @@ -25,9 +25,9 @@ def initialize(path, client) end it "passes parameters to the HTTP request for statistics" do - client = Twilio::REST::Client.new 'someSid', 'someAuthToken' + client = Twilio::REST::TaskRouterClient.new 'someSid', 'someAuthToken', 'someWorkspaceSid' allow(Net::HTTP::Get).to receive(:new) - .with("/test/harness/Statistics.json?Minutes=15", Twilio::REST::BaseClient::HTTP_HEADERS) + .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( From c7f3ddddff7798bb66626d42897ff6e64481c16d Mon Sep 17 00:00:00 2001 From: Phil Nash Date: Fri, 19 Jun 2015 12:39:12 +0100 Subject: [PATCH 8/9] Bumps version to 4.2.1 --- CHANGES.md | 9 +++++++++ README.md | 2 +- lib/twilio-ruby/version.rb | 2 +- 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 31a766ba9..14acf53f0 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,15 @@ twilio-ruby changelog ===================== +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 ------------- diff --git a/README.md b/README.md index bb65ccf06..cfa04b64f 100644 --- a/README.md +++ b/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.2.0' +gem 'twilio-ruby', '~> 4.2.1' ``` To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install: diff --git a/lib/twilio-ruby/version.rb b/lib/twilio-ruby/version.rb index e78fe9cee..331678f88 100644 --- a/lib/twilio-ruby/version.rb +++ b/lib/twilio-ruby/version.rb @@ -1,3 +1,3 @@ module Twilio - VERSION = '4.2.0' + VERSION = '4.2.1' end From c9b3c1265753e8893f52079660c02016d1cd18f3 Mon Sep 17 00:00:00 2001 From: Mathieu Lajugie Date: Tue, 23 Jun 2015 16:14:34 -0700 Subject: [PATCH 9/9] Update Twilio::REST::ListResource#list doc The `total` special attribute was removed in 4.0.0 but there was still mention of it. --- lib/twilio-ruby/rest/list_resource.rb | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/lib/twilio-ruby/rest/list_resource.rb b/lib/twilio-ruby/rest/list_resource.rb index ece4d15b9..e2d1194a5 100644 --- a/lib/twilio-ruby/rest/list_resource.rb +++ b/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.