twilio-ruby 3.11.5 → 5.0.0

data/Makefile

@@ -1,13 +1,25 @@
+.PHONY: test lint-changed lint
+
+CHANGED_RUBY_FILES = $(shell git status --porcelain | grep ".rb" | awk -F ' ' '{print $2}' | tr '\n' ' ')
+
 install:
-	gem build twilio-ruby.gemspec
-	gem install twilio-ruby-*.gem
+	bundle install; bundle exec rake install
 
 test-install:
 	bundle install
 
-test:
+test: lint
 	bundle exec rake spec
 
+docs:
+	yard doc
+
+lint:
+	rubocop --cache true --parallel
+
 authors:
 	echo "Authors\n=======\n\nA huge thanks to all of our contributors:\n\n" > AUTHORS.md
 	git log --raw | grep "^Author: " | cut -d ' ' -f2- | cut -d '<' -f1 | sed 's/^/- /' | sort | uniq >> AUTHORS.md
+
+gem:
+	bundle exec rake build | sed -e 's/.*pkg/pkg/g' | sed -e "s/\.$$//g" | xargs gem push

data/README.md

@@ -1,18 +1,23 @@
-[![Build Status](https://travis-ci.org/twilio/twilio-ruby.png?branch=master)](https://travis-ci.org/twilio/twilio-ruby)
-[![Gem Version](https://badge.fury.io/rb/twilio-ruby.png)](http://badge.fury.io/rb/twilio-ruby)
-
 # twilio-ruby
 
-A module for using the Twilio REST API and generating valid
-[TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup Language").
-[Click here to read the full documentation.][documentation]
+[![Build Status](http://img.shields.io/travis/twilio/twilio-ruby.svg)][travis]
+[![Gem Version](http://img.shields.io/gem/v/twilio-ruby.svg)][gem]
+[![Code Quality](http://img.shields.io/codeclimate/github/twilio/twilio-ruby.svg)][codeclimate]
+
+A module for using the Twilio REST API and generating valid [TwiML](http://www.twilio.com/docs/api/twiml/ "TwiML - Twilio Markup Language"). [Click here to read the full documentation.][documentation]
+
+## Installation
+
+To install using [Bundler][bundler] grab the latest stable version:
 
-## Install
+```ruby
+gem 'twilio-ruby', '~> 5.0.0.rc26'
+```
 
-Via rubygems.org:
+To manually install `twilio-ruby` via [Rubygems][rubygems] simply gem install:
 
 ```bash
-gem install twilio-ruby
+gem install twilio-ruby -v 5.0.0.rc26
 ```
 
 To build and install the development branch yourself from the latest source:
@@ -23,12 +28,20 @@ cd twilio-ruby
 make install
 ```
 
-## Getting Started With REST
+### Migration from 4.x
+[Upgrade Guide][upgrade]
+
+## Documentation
+[Here][documentation]
+
+## Feedback
+During the Release Candidate period of this library, please leave all feedback and issues in the [Github Issues][issues] for `twilio-ruby`.
+
+## Getting Started
 
 ### Setup Work
 
-``` ruby
-require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+```ruby
 require 'twilio-ruby'
 
 # put your own credentials here
@@ -37,71 +50,42 @@ auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 
 # set up a client to talk to the Twilio REST API
 @client = Twilio::REST::Client.new account_sid, auth_token
-```
 
-### Send an SMS
+# alternatively, you can preconfigure the client like so
+Twilio.configure do |config|
+  config.account_sid = account_sid
+  config.auth_token = auth_token
+end
 
-``` ruby
-@client.account.messages.create(
-  :from => '+14159341234',
-  :to => '+16105557069',
-  :body => 'Hey there!'
-)
+# and then you can create a new client without parameters
+@client = Twilio::REST::Client.new
 ```
 
-### Send an MMS
+### Make a Call
 
-``` ruby
-@client.account.messages.create(
-  :from => '+14159341234',
-  :to => '+16105557069',
-  :body => 'Hey there!',
-  :media_url => 'http://example.com/smileyface.jpg',
+```ruby
+@client.api.account.calls.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  url: 'http://example.com'
 )
 ```
 
-### Do Some Stuff With Calls
+### Send an SMS
 
-``` ruby
-# make a new outgoing call
-@call = @client.account.calls.create(
-  :from => '+14159341234',
-  :to => '+18004567890',
-  :url => 'http://example.com/call-handler',
+```ruby
+@client.api.account.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  body: 'Hey there!'
 )
-
-# hangup a ringing call, but don't touch it if it's connected
-@call.cancel
-
-# if you have the call sid, you can fetch a call object via:
-@call = @client.account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662')
-
-# redirect an in-progress call
-@call.redirect_to('http://example.com/call-redirect')
-
-# hangup a call, no matter whether it is ringing or connected
-@call.hangup
 ```
 
-### List Calls after a certain time
-
-``` ruby
-# list calls made or received on or after May 13, 2013
-@client.account.calls.list("start_time>" => "2013-05-13") # Notice we omit the "=" in the "start_time>=" parameter because it is automatically added
-```
-
-### Buy a Phone Number
-
-``` ruby
-# print some available numbers
-@numbers = @client.account.available_phone_numbers.get('US').local.list(
-  :contains => 'AWESOME'
-)
-@numbers.each {|num| puts num.phone_number}
+### Customizing your HTTP Client
+twilio-ruby uses [Faraday][faraday] to make HTTP requests. You can tell Twilio::REST::Client to use any of the Faraday adapters like so:
 
-# buy the first one
-@number = @numbers[0].phone_number
-@client.account.incoming_phone_numbers.create(:phone_number => @number)
+```ruby
+@client.http_client.adapter = :typhoeus
 ```
 
 ## Getting Started With Client Capability Tokens
@@ -109,25 +93,27 @@ auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 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
+```ruby
 require 'twilio-ruby'
 
 # put your own account credentials here:
-account_sid = 'AC043dcf9844e13758bc3a36a84c29761'
-auth_token = '62ea81de3a5b413254eb263595357c69'
+account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 
 # set up
-capability = Twilio::Util::Capability.new account_sid, auth_token
+capability = Twilio::JWT::ClientCapability.new account_sid, auth_token
+
 
 # allow outgoing calls to an application
-capability.allow_client_outgoing 'AP89a0180a1a4ddf1da954efca349b7a20'
+outgoingScope = Twilio::JWT::ClientCapability::OutgoingClientScope.new 'AP11111111111111111111111111111111'
+capability.add_scope(outgoingScope)
 
 # allow incoming calls to 'andrew'
-capability.allow_client_incoming 'andrew'
+incomingScope = Twilio::JWT::ClientCapability::IncomingClientScope.new 'tom'
+capability.add_scope(incomingScope)
 
 # generate the token string
-@token = capability.generate
+@token = capability.to_s
 ```
 
 There is a slightly more detailed document in the [Capability][capability]
@@ -135,28 +121,26 @@ section of the wiki.
 
 ## Getting Started With TwiML
 
-TwiML support is based on the [builder][builder] library. You can construct a
+TwiML support is based on the [Builder][builder] library. You can construct a
 TwiML response like this:
 
-``` ruby
-require 'rubygems' # not necessary with ruby 1.9 but included for completeness
+```ruby
 require 'twilio-ruby'
 
-# build up a response
-response = Twilio::TwiML::Response.new do |r|
-  r.Say 'hello there', :voice => 'alice'
-  r.Dial :callerId => '+14159992222' do |d|
-    d.Client 'jenny'
+response = Twilio::TwiML::VoiceResponse.new do |r|
+  r.say('hello there', voice: 'alice')
+  r.dial(caller_id: '+14159992222') do |d|
+    d.client 'jenny'
   end
 end
 
 # print the result
-puts response.text
+puts response.to_s
 ```
 
 This will print the following (except for the whitespace):
 
-```
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Response>
   <Say voice="alice">hello there</Say>
@@ -166,16 +150,27 @@ This will print the following (except for the whitespace):
 </Response>
 ```
 
-## More Information
-
-There are more detailed examples in the included [examples][examples]
-directory.
-
-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/
-[examples]:https://github.com/twilio/twilio-ruby/blob/master/examples
-[documentation]:http://twilio-ruby.readthedocs.org/en/latest
-[upgrade]:https://github.com/twilio/twilio-ruby/wiki/UpgradeGuide
-[wiki]:https://github.com/twilio/twilio-ruby/wiki
+## Supported Ruby Versions
+
+This library supports and is [tested against][travis] the following Ruby
+implementations:
+
+- Ruby 2.4.0
+- Ruby 2.3.0
+- Ruby 2.2.0
+- Ruby 2.1.0
+- Ruby 2.0.0
+
+[capability]: https://github.com/twilio/twilio-ruby/wiki/Capability
+[builder]: http://builder.rubyforge.org/
+[examples]: https://github.com/twilio/twilio-ruby/blob/master/examples
+[documentation]: http://twilio.github.io/twilio-ruby
+[wiki]: https://github.com/twilio/twilio-ruby/wiki
+[bundler]: http://bundler.io
+[rubygems]: http://rubygems.org
+[gem]: https://rubygems.org/gems/twilio
+[travis]: http://travis-ci.org/twilio/twilio-ruby
+[codeclimate]: https://codeclimate.com/github/twilio/twilio-ruby
+[upgrade]: https://github.com/twilio/twilio-ruby/wiki/Ruby-Version-5.x-Upgrade-Guide
+[issues]: https://github.com/twilio/twilio-ruby/issues
+[faraday]: https://github.com/lostisland/faraday

data/Rakefile

@@ -1,12 +1,64 @@
-require 'rubygems'
-require 'rubygems/package_task'
+require 'bundler'
+Bundler.setup
+Bundler::GemHelper.install_tasks
+
 require 'rspec/core/rake_task'
+desc 'Run all specs'
+RSpec::Core::RakeTask.new(:spec)
 
-spec = eval(File.read('twilio-ruby.gemspec'))
+task default: :spec
+task test: :spec
 
-Gem::PackageTask.new(spec) do |p|
-  p.gem_spec = spec
+task :authors do
+  `make authors`
 end
 
-RSpec::Core::RakeTask.new
-task :default => :spec
+task :deploy, [:version] => [:spec, :authors] do |t, args|
+  current_version = Twilio::VERSION
+
+  if args.version.nil?
+    version = Twilio::VERSION
+    version_parts = version.split('.')
+    increment = version_parts.pop
+    increment_prefix = increment.split(/\d/)[0]
+
+    increment = increment[increment_prefix.length..-1] if increment_prefix
+
+    increment = increment.to_i + 1
+    increment = "#{increment_prefix}#{increment}" if increment_prefix
+
+    version = [*version_parts, increment].join('.')
+  else
+    version = args.version
+  end
+
+  puts("Deploying #{version}")
+
+  # Update version.rb
+  version_file = <<SRC
+module Twilio
+  VERSION = '#{version}'
+end
+SRC
+  File.write('lib/twilio-ruby/version.rb', version_file)
+
+  # Update README.md
+  current_readme = File.read('README.md')
+  new_readme = current_readme.gsub(Regexp.new(current_version.gsub('.', '\.')), version)
+  File.write('README.md', new_readme)
+
+  # Make a git commit
+  `git commit -am "Bumping to version #{version}"`
+
+  # Do the gem deployment
+  `make gem`
+
+  # Push the branch back up
+  `git push`
+
+  # Tag the branch
+  `git tag #{version}`
+
+  # Push the tags
+  `git push --tags`
+end

data/VERSIONS.md

@@ -0,0 +1,64 @@
+# Versioning Strategy
+
+`twilio-ruby` uses a modified version of [Semantic Versioning][semver] for all 
+changes to the helper library.  It is strongly encouraged that you pin at least 
+the major version and potentially the minor version to avoid pulling in breaking 
+changes.
+
+Semantic Versions take the form of `MAJOR`.`MINOR`.`PATCH`
+
+When bugs are fixed in the library in a backwards compatible way, the `PATCH` 
+level will be incremented by one.  When new features are added to the library 
+in a backwards compatible way, the `PATCH` level will be incremented by one.
+`PATCH` changes should _not_ break your code and are generally safe for upgrade.
+
+When a new large feature set comes online or a small breaking change is 
+introduced, the `MINOR` version will be incremented by one and the `PATCH` 
+version reset to zero. `MINOR` changes _may_ require some amount of manual code
+change for upgrade. These backwards-incompatible changes will generally be limited 
+to a small number of function signature changes.
+
+The `MAJOR` version is used to indicate the family of technology represented by 
+the helper library.  It increased from `4.x.x` to `5.x.x` when Twilio moved to 
+auto generation of helper libraries.  Breaking changes that requires extensive 
+reworking of code (like the `4.x.x` to `5.x.x` upgrade) will case the `MAJOR` 
+version to be incremented by one, the `MINOR` and `PATCH` versions will be reset 
+to zero.  Twilio understands that this can be very disruptive, we will only 
+introduce this type of breaking change when absolutely necessary. New `MAJOR` 
+versions will be communicated in advance with `Release Candidates` and a 
+schedule.
+
+## Supported Versions
+
+`twilio-ruby` follows an evergreen model of support.  New features and 
+functionality will only be added to the current version.  The current version - 
+1 will continue to be supported with bugfixes and security updates, but no new 
+features.
+
+## Edge Features (alpha Branch)
+
+Twilio frequently rolls out new features in public and private beta periods.
+Twilio strives to ship early and often and bake customer feedback back into our 
+products.  To support that mission, the `twilio-ruby` helper library has an 
+`Edge` version based of the `alpha` branch.  This version is identified with an
+`alpha` metadata tag on the version number.
+
+The way the `Edge` artifact is created is by playing the `Edge` features on top
+of our stable artifact.  The `Edge` artifact will always have the same version 
+number as the stable artifact it was created from, but with an `alpha` suffix.
+
+For example, `5.0.0-alpha-1` is the `5.0.0` branch with `Edge` features included.
+If there is a change to one of the `Edge` features we may regenerate the `Edge`
+artifact and release a new `5.0.0-alpha-2`, new `Edge` artifacts simply increment
+the number after the `alpha` suffix.  All `Edge` features are considered 
+unstable and a backwards incompatible change in an `Edge` feature will not cause
+any version change so you should take care when upgrading from one `alpha` 
+version to another.  
+
+Once an `Edge` feature has matured it will be considered `Mainline` and included
+in the stable artifact, with a `MAJOR` or `MINOR` version bump.
+
+To use an `Edge` artifact in your Ruby project you will have to make sure that 
+you pin the artifact with `alpha` stability in your `pom.xml`.
+
+[semver]: http://semver.org/

data/examples/examples.rb

@@ -1,124 +1,137 @@
-# examples version 3
+# examples version
 
-@account_sid = 'AC043dcf9844e04758bc3a36a84c29761'
-@auth_token = '62ea81de3a5b414154eb263595357c69'
+@account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+@auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 # set up a client
 @client = Twilio::REST::Client.new(@account_sid, @auth_token)
 
 ################ ACCOUNTS ################
 
 # shortcut to grab your account object (account_sid is inferred from the client's auth credentials)
-@account = @client.account 
+@account = @client.api.account
 
 # list your (sub)accounts
-@client.accounts.list
+@accounts = @client.api.accounts.each do |account|
+  puts(account)
+end
 
 # grab an account instance resource if you know the sid
-@account = @client.accounts.get(@account_sid)
-# http round trip happens here
-puts @account.friendly_name
+@account = @client.api.accounts(account_sid).fetch
+puts(@account.friendly_name)
 
 # update an account's friendly name
-@client.accounts.get(@account_sid).update(:friendly_name => 'A Fabulous Friendly Name')
+@client.api.accounts(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|
+@client.calls.list(limit: 10, start_time: '2010-09-01').each do |call|
   puts call.sid
 end
 
 # get a particular call and list its recording urls
-@account.calls.get('CAXXXXXXX').recordings.list.each do |r|
+@client.calls('CAXXXXXXX').recordings.each do |r|
   puts r.wav
 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 = @client.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'})
-# or equivalently
-@call.update({:status => 'canceled'})
-# or simply
-@call.cancel
+@client.calls(@call.sid).update(status: 'canceled')
 
 # redirect and then terminate a call
-@account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:url => 'http://example.com/call-redirect'})
-@account.calls.get('CA386025c9bf5d6052a1d1ea42b4d16662').update({:status => 'completed'})
-# or, use the aliases...
-@call.redirect_to('http://example.com/call-redirect')
-@call.hangup
+@call = client.calls('CAXXXXXXX')
+@call.update(url: 'http://example.com/call-redirect')
+@call.update(status: 'completed')
 
 ################ SMS MESSAGES ################
 
-# print a list of messages
-@account.messages.list({:date_sent => '2010-09-01'}).each do |message|
-  puts message.body
+@client.messages.list(date_sent: '2010-09-01').each do |message|
+  puts message.date_created
 end
 
 # print a particular sms message
-puts @account.messages.get('SMXXXXXXXX').body
+puts @client.messages('SMXXXXXXXX').fetch.body
 
 # send an sms
-@account.messages.create(:from => '+14159341234', :to => '+16105557069', :body => 'Hey there!')
+@client.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')
+@client.messages.create(
+  from: '+14159341234',
+  to: '+16105557069',
+  media_urls: 'http://example.com/media.png'
+)
 
 ################ PHONE NUMBERS ################
 
 # get a list of supported country codes
-@account.available_phone_numbers.list
+@client.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}
+@client.available_phone_numbers('US').local.list.each do |num|
+  puts num
+end
+
+@numbers = @client.available_phone_numbers('US').local.list(area_code: '908')
+@numbers.each { |num| puts num.phone_number }
 
 # buy the first one
-@account.incoming_phone_numbers.create(:phone_number => @numbers[0].phone_number)
+@client.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'})
+@client.incoming_phone_numbers('PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').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[0].delete
+numbers = @client.incoming_phone_numbers.list(friendly_name: 'A Fabulous Friendly Name')
+number = numbers[0].sid
+@client.incoming_phone_numbers(number).delete
+
 ################ CONFERENCES  ################
 
 # get a particular conference's participants object and stash it
-@participants = @account.conferences.get('CFbbe46ff1274e283f7e3ac1df0072ab39').participants
+conference = @client.conferences('CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').fetch
+@participants = conference.participants
 
 # list participants
-@participants.list.each do |p|
+@participants.each do |p|
   puts p.sid
 end
 
 # update a conference participant
-@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'})
+@client
+  .conferences('CFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
+  .participants('CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
+  .update(muted: 'true')
 
 ################ QUEUES ###################
 
 # create a new queue
-@queue = @account.queues.create(:friendly_name => 'MyQueue', :max_size => 50)
+@queue = @client.queues.create(friendly_name: 'MyQueue', max_size: 50)
 
 # get a list of queues for this account
-@queues = @account.queues.list
+@queues = @client.queues.list
 
 # get a particular queue and its members
-@queue = @account.queues.get("QQb6765b0458714964970a73dcaf55efd1")
+@queue = @client.queues('QQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx').fetch
 @members = @queue.members
 
-#list members
+# list members
 @members.list.each do |m|
   puts m.wait_time
 end
 
 # dequeue a particular user and run twiml at a specific url
-@member = @members.get('CA386025c9bf5d6052a1d1ea42b4d16662')
-@member.dequeue('http://myapp.com/deque')
+@client
+  .queues('QQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
+  .members('CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
+  .update(url: 'http://myapp.com/deque', method: 'POST')

data/examples/{print-call-log.rb → print_call_log.rb}

@@ -1,4 +1,3 @@
-require 'rubygems'
 require 'twilio-ruby'
 
 # print a list of all phone calls, what phone number each was to/from, and how
@@ -7,18 +6,19 @@ require 'twilio-ruby'
 # put your Twilio credentials here. you can find your AccountSid and AuthToken
 # at the top of your account dashboard page located at:
 #   https://www.twilio.com/user/account
-account_sid = 'AC043dcf9844e04758bc3a36a84c29761'
-auth_token = '62ea81de3a5b414154eb263595357c69'
+account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
 
 # set up a client
 client = Twilio::REST::Client.new(account_sid, auth_token)
 
-calls = client.account.calls.list
+calls = client.calls.page
 
-begin
+loop do
   calls.each do |call|
     price = call.price || '0.00' # since apparently prices can be nil...
-    puts call.sid + "\t" + call.from + "\t" + call.to + "\t" + price
+    puts call.sid + "\t" + call.from + "\t" + call.to + "\t" + price.to_s
   end
   calls = calls.next_page
-end while not calls.empty?
+  break if calls.nil?
+end