twilio 2.9.0 → 3.0.0

data/.gitignore

@@ -2,4 +2,7 @@
 .DS_Store
 coverage
 rdoc
-pkg
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/CHANGELOG.rdoc

@@ -0,0 +1,27 @@
+= Twilio Gem Changelog
+
+== 3.0
+
+* SSL validation (thanks Kyle Humberto)
+* Available phone numbers search support (thanks Mark Turner)
+* Deprecated Twilio::Connection method has been removed, use Twilio.connect(...)
+* LocalPhoneNumber and TollFreeNumber have been removed to reflect API changes
+* New phone numbers are now provisioned via the IncomingPhoneNumber class
+* Several classes improved to avoid adding a stray "?" when no params were set
+* Compatibility with 1.9.2 (and tested on 1.8.7 MRI and REE)
+* Now uses Bundler, Rspec 2, and WebMock
+
+== 2.9
+
+* Compatibility with Twilio's 2010-04-01 API publish
+
+== 2.8
+
+* SMS callback URLs
+* Ability to delete phone numbers
+
+== 2.7
+
+* SMS functionality
+
+For earlier versions, see https://github.com/webficient/twilio/commits/master

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in twilio.gemspec
+gemspec

data/README.rdoc

@@ -4,8 +4,6 @@ The Twilio gem provides two major pieces of functionality: (1) a Ruby wrapper fo
 
 See http://www.twilio.com/docs/index for Twilio's API documentation.
 
-For an overview of the Twilio Gem and a sample use case, check out our cached blog entry: http://webcache.googleusercontent.com/search?q=cache:AejgwBra3fMJ:www.webficient.com/2009/06/22/hello-this-is-your-rails-app-calling-you+site:http://www.webficient.com/2009/06/22/hello-this-is-your-rails-app-calling-you&hl=en&gl=us&strip=1
-
 == Calling the Twilio REST API
 
 First set your credentials by calling the connect method:
@@ -36,14 +34,26 @@ and you can nest multiple verbs inside a block:
 
 == Installation
 
-  sudo gem install twilio -s http://gemcutter.org
+  gem install twilio
   
-If you need to tweak the source code, clone this repository and do a rake build and rake install.
+== Contributing
+
+1. Run 'bundle' from the command line to install dependencies
+2. Write test(s) for your patch
+3. Submit a pull request
+
+Note: don't require 'rubygems' in any file (http://www.rubyinside.com/why-using-require-rubygems-is-wrong-1478.html)
 
 == Copyright
 
-Copyright (c) 2009-2010 Phil Misiowiec, Webficient LLC. See LICENSE for details.
+Copyright (c) 2009-2011 Phil Misiowiec, Webficient LLC. See LICENSE for details.
 
 == Contributors
 
-Kyle Daigle, Yuri Gadow, Jonathan Rudenberg, Jeff Wigal, Alex K Wolfe
+* Kyle Daigle
+* Yuri Gadow
+* Kyle Humberto
+* Jonathan Rudenberg
+* Mark Turner
+* Jeff Wigal
+* Alex K Wolfe

data/Rakefile

@@ -1,49 +1,9 @@
-require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "twilio"
-    gem.summary = %Q{Twilio API Client}
-    gem.description = %Q{Twilio API wrapper}
-    gem.email = "github@webficient.com"
-    gem.homepage = "http://github.com/webficient/twilio"
-    gem.authors = ["Phil Misiowiec", "Jonathan Rudenberg", "Alex K Wolfe", "Kyle Daigle", "Jeff Wigal", "Yuri Gadow"]
-    gem.add_dependency 'builder', '>= 2.1.2'
-    gem.add_dependency 'httparty', '>= 0.4.3'
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
-end
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = 'twilio'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+require 'bundler/setup'
+Bundler::GemHelper.install_tasks
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.verbose = false
-end
-
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
+require 'rake'
+require 'rspec/core/rake_task'
 
+RSpec::Core::RakeTask.new
 
-task :default => :test
+task :default => :spec

data/lib/twilio.rb

@@ -23,16 +23,31 @@
 
 require 'httparty'
 require 'builder'
+
 require 'twilio/twilio_object'
+
 require 'twilio/account'
+require 'twilio/available_phone_numbers'
 require 'twilio/call'
-require 'twilio/sms'
-require 'twilio/connection'
+require 'twilio/conference'
 require 'twilio/incoming_phone_number'
-require 'twilio/local_phone_number'
 require 'twilio/notification'
 require 'twilio/outgoing_caller_id'
 require 'twilio/recording'
-require 'twilio/toll_free_phone_number'
-require 'twilio/conference'
-require 'twilio/verb'
+require 'twilio/sms'
+require 'twilio/verb'
+
+module Twilio  
+  include HTTParty
+  TWILIO_URL = "https://api.twilio.com/2010-04-01/Accounts"
+  SSL_CA_PATH = "/etc/ssl/certs"
+  
+  # The connect method caches your Twilio account id and authentication token
+  # Example:
+  #  Twilio.connect('AC309475e5fede1b49e100272a8640f438', '3a2630a909aadbf60266234756fb15a0')
+  def self.connect(account_sid, auth_token)
+    self.base_uri "#{TWILIO_URL}/#{account_sid}"
+    self.basic_auth account_sid, auth_token
+    self.default_options[:ssl_ca_path] ||= SSL_CA_PATH unless self.default_options[:ssl_ca_file]
+  end  
+end

data/lib/twilio/account.rb

@@ -2,7 +2,7 @@ module Twilio
   # The Account resource represents your Twilio Account. 
   class Account < TwilioObject
     def get
-      Twilio.get('') 
+      Twilio.get('')
     end
     
     def update_name(name)

data/lib/twilio/available_phone_numbers.rb

@@ -0,0 +1,56 @@
+module Twilio
+  # An AvailablePhoneNumbers resources represents the available phone numbers
+  # that Twilio can provide you based on your search criteria. The valid 
+  # query terms are outlined in the search methods.
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio.AvailablePhoneNumbers.search_local(:area_code => 541)
+  class AvailablePhoneNumbers < TwilioObject
+
+    # The Search method handles the searching of both local and toll-free 
+    # numbers. 
+    def search(opts={})
+      iso_country_code = opts[:iso_country_code] || 'US'
+      resource = opts.delete(:resource)
+
+      params = {
+        :AreaCode => opts[:area_code],
+        :InPostalCode => opts[:postal_code],
+        :InRegion => opts[:in_region],
+        :Contains => opts[:contains],
+        :NearLatLong => opts[:near_lat_long],
+        :NearNumber => opts[:near_number],
+        :InLata => opts[:in_lata],
+        :InRateCenter => opts[:in_rate_center],
+        :Distance => opts[:distance]
+      }.reject {|k,v| v == nil} unless opts.empty?
+      
+      Twilio.get("/AvailablePhoneNumbers/#{iso_country_code}/#{resource}", :query => params)
+    end
+
+    # The search_local method searches for numbers in local areas (i.e. state, zip, etc..)
+    # Search Options:
+    #   :area_code
+    #   :postal_code
+    #   :in_region
+    #   :contains
+    #   :near_lat_long
+    #   :near_number
+    #   :in_lata
+    #   :in_rate_center
+    #   :distance
+    def search_local(opts ={})
+      opts = {:resource => 'Local'}.merge(opts)
+      search(opts)
+    end
+
+    # The search_toll_free method searches for available toll-free numbers
+    # Search Options
+    #   :contains
+    def search_toll_free(opts ={})
+      opts = {:resource => 'TollFree'}.merge(opts)
+      search(opts)
+    end
+  end
+end
+

data/lib/twilio/call.rb

@@ -6,12 +6,12 @@ module Twilio
     #  Example:
     #  Twilio.connect('my_twilio_sid', 'my_auth_token')
     #  Twilio::Call.make(CALLER_ID, user_number, 'http://myapp.com/twilio_response_handler')
-    def make(from, to, url, optional = {})
-      Twilio.post("/Calls", :body => {:From => from, :To => to, :Url => url}.merge(optional))
+    def make(from, to, url, opts = {})
+      Twilio.post("/Calls", :body => {:From => from, :To => to, :Url => url}.merge(opts))
     end
 
-    def list(optional = {})
-      Twilio.get("/Calls", :query => optional)  
+    def list(opts = {})
+      Twilio.get("/Calls", :query => (opts.empty? ? nil : opts))  
     end
         
     def get(call_sid)

data/lib/twilio/conference.rb

@@ -4,20 +4,20 @@ module Twilio
     # a Conference Instance Resource is created to represent the conference room
     # and a Participant Instance Resource is created to represent the caller who joined.
   class Conference < TwilioObject
-    def list(optional = {})
-      Twilio.get("/Conferences", :query => optional)  
+    def list(opts = {})
+      Twilio.get("/Conferences", :query => (opts.empty? ? nil : opts))
     end
     
     def get(conference_sid)
-      Twilio.get("/Conferences/#{conference_sid}")  
+      Twilio.get("/Conferences/#{conference_sid}")
     end
     
-    def participants(conference_sid, optional = {})
-      Twilio.get("/Conferences/#{conference_sid}/Participants", :query => optional) 
+    def participants(conference_sid, opts = {})
+      Twilio.get("/Conferences/#{conference_sid}/Participants", :query => (opts.empty? ? nil : opts))
     end
     
     def participant(conference_sid, call_sid)
-      Twilio.get("/Conferences/#{conference_sid}/Participants/#{call_sid}") 
+      Twilio.get("/Conferences/#{conference_sid}/Participants/#{call_sid}")
     end
     
     def mute_participant(conference_sid, call_sid)

data/lib/twilio/incoming_phone_number.rb

@@ -5,12 +5,26 @@ module Twilio
   #   Twilio.connect('my_twilio_sid', 'my_auth_token')
   #   Twilio::IncomingPhoneNumber.list
   class IncomingPhoneNumber < TwilioObject
-    def list(optional = {})
-      Twilio.get("/IncomingPhoneNumbers", :query => optional) 
+    def list(opts = {})
+      Twilio.get("/IncomingPhoneNumbers", :query => (opts.empty? ? nil : opts)) 
     end
     
     def get(incoming_sid)
       Twilio.get("/IncomingPhoneNumbers/#{incoming_sid}") 
     end
+    
+    # Creates a phone number in Twilio. You must first find an existing number using
+    # the AvailablePhoneNumber class before creating one here.
+    #
+    # Required: you must either set PhoneNumber or AreaCode as a required option
+    # For additional options, see http://www.twilio.com/docs/api/rest/incoming-phone-numbers
+    def create(opts)
+      raise "You must set either :PhoneNumber or :AreaCode" if !opts.include?(:AreaCode) && !opts.include?(:PhoneNumber)
+      Twilio.post("/IncomingPhoneNumbers", :body => opts)
+    end
+    
+    def delete(incoming_sid)
+      Twilio.delete("/IncomingPhoneNumbers/#{incoming_sid}")
+    end
   end
 end

data/lib/twilio/notification.rb

@@ -5,8 +5,8 @@ module Twilio
   #   Twilio.connect('my_twilio_sid', 'my_auth_token')
   #   Twilio::Notification.list
   class Notification < TwilioObject
-    def list(optional = {})
-      Twilio.get('/Notifications', :query => optional)
+    def list(opts = {})
+      Twilio.get('/Notifications', :query => (opts.empty? ? nil : opts))
     end
     
     def get(notification_sid)

data/lib/twilio/outgoing_caller_id.rb

@@ -5,16 +5,17 @@ module Twilio
   #   Twilio.connect('my_twilio_sid', 'my_auth_token')
   #   Twilio::OutgoingCallerId.list
   class OutgoingCallerId < TwilioObject
-    def create(phone_number, friendly_name = phone_number, call_delay = 0)
+    def create(phone_number, friendly_name = phone_number, call_delay = 0, extension = nil)
       Twilio.post("/OutgoingCallerIds", :body => {
         :PhoneNumber => phone_number, 
         :FriendlyName => friendly_name, 
-        :CallDelay => call_delay 
+        :CallDelay => call_delay,
+        :Extension => extension
       })
     end
 
-    def list(optional = {})
-      Twilio.get("/OutgoingCallerIds", :query => optional) 
+    def list(opts = {})
+      Twilio.get("/OutgoingCallerIds", :query => (opts.empty? ? nil : opts)) 
     end
         
     def get(callerid_sid)

data/lib/twilio/recording.rb

@@ -5,8 +5,8 @@ module Twilio
   #   Twilio.connect('my_twilio_sid', 'my_auth_token')
   #   Twilio::Recording.list
   class Recording < TwilioObject    
-    def list(optional = {})
-      Twilio.get("/Recordings", :query => optional)  
+    def list(opts = {})
+      Twilio.get("/Recordings", :query => (opts.empty? ? nil : opts))  
     end
     
     def get(recording_sid)

data/lib/twilio/sms.rb

@@ -10,8 +10,8 @@ module Twilio
       Twilio.post("/SMS/Messages", :body => {:From => from, :To => to, :Body => body}.merge(callback))
     end
 
-    def list(optional = {})
-      Twilio.get("/SMS/Messages", :query => optional)
+    def list(opts = {})
+      Twilio.get("/SMS/Messages", :query => (opts.empty? ? nil : opts))
     end
 
     def get(sms_message_sid)

data/lib/twilio/twilio_object.rb

@@ -1,16 +1,19 @@
 module Twilio
-  class TwilioObject  #:nodoc: all    
-    attr_reader :connection
-    
-    def initialize(connection = nil)
-      @connection = connection
+  class TwilioObject  #:nodoc: all        
+    def initialize
     end
     
     class << self
       def method_missing(method_id, *args) #:nodoc:
         o = self.new
         o.send(method_id, *args)
+      rescue HTTParty::UnsupportedURIScheme
+        raise "You must set Twilio.connect before calling #{self.inspect}##{method_id}"
       end
     end
+    
+    def connected?
+      self.class.base_uri
+    end
   end
 end

data/lib/twilio/version.rb

@@ -0,0 +1,3 @@
+module Twilio
+  VERSION = "3.0.0"
+end

data/spec/fixtures/xml/account.xml

@@ -0,0 +1,23 @@
+<TwilioResponse>
+  <Account>
+    <Sid>mysid</Sid>
+    <FriendlyName>Do you like my friendly name?</FriendlyName>
+    <Status>active</Status>
+    <DateCreated>Wed, 04 Aug 2010 21:37:41 +0000</DateCreated>
+    <DateUpdated>Fri, 06 Aug 2010 01:15:02 +0000</DateUpdated>
+    <AuthToken>mytoken</AuthToken>
+    <Uri>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d</Uri>
+    <SubresourceUris>
+      <AvailablePhoneNumbers>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/AvailablePhoneNumbers</AvailablePhoneNumbers>
+      <Calls>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Calls</Calls>
+      <Conferences>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Conferences</Conferences>
+      <IncomingPhoneNumbers>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/IncomingPhoneNumbers</IncomingPhoneNumbers>
+      <Notifications>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Notifications</Notifications>
+      <OutgoingCallerIds>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/OutgoingCallerIds</OutgoingCallerIds>
+      <Recordings>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Recordings</Recordings>
+      <Sandbox>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Sandbox</Sandbox>
+      <SMSMessages>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/SMS/Messages</SMSMessages>
+      <Transcriptions>/2010-04-01/Accounts/ACba8bc05eacf94afdae398e642c9cc32d/Transcriptions</Transcriptions>
+    </SubresourceUris>
+  </Account>
+</TwilioResponse>

data/spec/fixtures/xml/available_phone_numbers_local.xml

@@ -0,0 +1,26 @@
+TwilioResponse>
+    <AvailablePhoneNumbers uri="/2010-04-01/Accounts/ACde6f1e11047ebd6fe7a55f120be3a900/AvailablePhoneNumbers/US/Local?AreaCode=510">
+        <AvailablePhoneNumber>
+            <FriendlyName>(510) 564-7903</FriendlyName>
+            <PhoneNumber>+15105647903</PhoneNumber>
+            <Lata>722</Lata>
+            <RateCenter>OKLD TRNID</RateCenter>
+            <Latitude>37.780000</Latitude>
+            <Longitude>-122.380000</Longitude>
+            <Region>CA</Region>
+            <PostalCode>94703</PostalCode>
+            <IsoCountry>US</IsoCountry>
+        </AvailablePhoneNumber>
+        <AvailablePhoneNumber>
+            <FriendlyName>(510) 488-4379</FriendlyName>
+            <PhoneNumber>+15104884379</PhoneNumber>
+            <Lata>722</Lata>
+            <RateCenter>OKLD FRTVL</RateCenter>
+            <Latitude>37.780000</Latitude>
+            <Longitude>-122.380000</Longitude>
+            <Region>CA</Region>
+            <PostalCode>94602</PostalCode>
+            <IsoCountry>US</IsoCountry>
+        </AvailablePhoneNumber>
+    </AvailablePhoneNumbers>
+</TwilioResponse>