twilio 1.4.0 → 2.3.0

data/README.rdoc

@@ -1,23 +1,38 @@
-= twilio
+= Twilio Gem
 
-This wrapper defines each of the interfaces currently supported by Twilio REST API.
+The Twilio gem provides two major pieces of functionality: (1) a Ruby wrapper for the Twilio REST API and (2) response handlers based on the Twilio Markup XML (TwiML).
 
-Sample Usage:
+See http://www.twilio.com/docs/index for Twilio's API documentation.
 
-First create a connection object:
+For an overview of the Twilio Gem and a sample use case, check out http://www.webficient.com/2009/06/22/hello-this-is-your-rails-app-calling-you.
 
-  c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')
-  
-Now instantiate other objects by passing in the connection:
+== Calling the Twilio REST API
+
+First set your credentials by calling the connect method:
 
-  a = Twilio::Account.new(c)
-  a.update_name('sparky')
+  Twilio.connect('my_twilio_sid', 'my_auth_token')
+  
+Now call any of the Twilio classes:
+  
+  Twilio::Call.make('1234567890', '9876543210', 'http://mysite.com/connected_call')
+  Twilio::Recording.list
   
-  call = Twilio::Call.new(c)
-  call.make('1234567890', '9876543210', 'http://mysite.com/connected_call')
+== Responding to Twilio
+
+When Twilio calls your application URL, your response must use the Twilio Markup XML (http://www.twilio.com/docs/api_reference/TwiML/). The Twilio gem makes this very easy 
+by providing a Twilio Verb class. 
+
+For example, in a Ruby on Rails application, you could do the following inside a controller class:
+
+  Twilio::Verb.dial('415-123-4567')
   
-  recording = Twilio::Recording.new(c)
-  recording.list
+and you can nest multiple verbs inside a block:
+
+  verb = Twilio::Verb.new { |v|
+    v.say("The time is #{Time.now}")
+    v.hangup
+  }
+  verb.response
 
 == Copyright
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 4
 :patch: 0
-:major: 1
+:major: 2
+:minor: 3

data/lib/twilio/account.rb

@@ -2,11 +2,11 @@ module Twilio
   # The Account resource represents your Twilio Account. 
   class Account < TwilioObject
     def get
-      self.connection.class.get('')
+      Twilio.get('') 
     end
     
     def update_name(name)
-      self.connection.class.put('', :body => {:FriendlyName => name})
+      Twilio.put('', :body => {:FriendlyName => name}) 
     end
   end
 end

data/lib/twilio/call.rb

@@ -4,31 +4,30 @@ module Twilio
     # initiates the call, either via the REST API, or during a call via the Dial Verb. 
   class Call < TwilioObject
     #  Example:
-    #  c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')
-    #  call = Twilio::Call.new(c)
-    #  response = call.make(CALLER_ID, user_number, 'http://myapp.com/twilio_response_handler')
+    #  Twilio.connect('my_twilio_sid', 'my_auth_token')
+    #  Twilio::Call.make(CALLER_ID, user_number, 'http://myapp.com/twilio_response_handler')
     def make(caller, called, url, optional = {})
-      self.connection.class.post("/Calls", :body => {:Caller => caller, :Called => called, :Url => url}.merge(optional))
+      Twilio.post("/Calls", :body => {:Caller => caller, :Called => called, :Url => url}.merge(optional))
     end
 
     def list(optional = {})
-      self.connection.class.get("/Calls", :query => optional)  
+      Twilio.get("/Calls", :query => optional)  
     end
         
     def get(call_sid)
-      self.connection.class.get("/Calls/#{call_sid}")  
+      Twilio.get("/Calls/#{call_sid}")
     end
     
     def segments(call_sid, call_segment_sid = nil)
-      self.connection.class.get("/Calls/#{call_sid}/Segments#{ '/' + call_segment_sid if call_segment_sid }")
+      Twilio.get("/Calls/#{call_sid}/Segments#{ '/' + call_segment_sid if call_segment_sid }")
     end
     
     def recordings(call_sid)
-      self.connection.class.get("/Calls/#{call_sid}/Recordings")
+      Twilio.get("/Calls/#{call_sid}/Recordings")
     end
     
     def notifications(call_sid)
-      self.connection.class.get("/Calls/#{call_sid}/Notifications")
+      Twilio.get("/Calls/#{call_sid}/Notifications")
     end
   end
 end

data/lib/twilio/connection.rb

@@ -1,10 +1,16 @@
 module Twilio
-  # The Connection class caches the Twilio API base path and authentication credentials.
-  # It is passed into the constructor of other TwilioObject's, avoiding the need to 
-  # explicitly set credentials with each API call.
-  #
-  #  Example:
-  #  c = Twilio::Connection.new('my_twilio_sid', 'my_auth_token')
+  include HTTParty
+  TWILIO_URL = "https://api.twilio.com/2008-08-01/Accounts"
+    
+  # 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
+  end
+  
+  # DEPRECATED - use Twilio.connect
   class Connection
     include HTTParty
     TWILIO_URL = "https://api.twilio.com/2008-08-01/Accounts"
@@ -14,4 +20,5 @@ module Twilio
       self.class.basic_auth account_sid, auth_token     
     end
   end
+  
 end

data/lib/twilio/incoming_phone_number.rb

@@ -1,13 +1,16 @@
 module Twilio
   # An IncomingPhoneNumber resource represents a phone number given to you by 
   # Twilio to receive incoming phone calls. 
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio::IncomingPhoneNumber.list
   class IncomingPhoneNumber < TwilioObject
     def list(optional = {})
-      self.connection.class.get("/IncomingPhoneNumbers", :query => optional) 
+      Twilio.get("/IncomingPhoneNumbers", :query => optional) 
     end
     
     def get(incoming_sid)
-      self.connection.class.get("/IncomingPhoneNumbers/#{incoming_sid}") 
+      Twilio.get("/IncomingPhoneNumbers/#{incoming_sid}") 
     end
   end
 end

data/lib/twilio/local_phone_number.rb

@@ -1,9 +1,12 @@
 module Twilio
   # This sub-resource represents only Local phone numbers, or in other words, not toll-free numbers. 
-  # Also allows you to request a new local phone number be added to your account. 
+  # Also allows you to request a new local phone number be added to your account.
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio::LocalPhoneNumber.list
   class LocalPhoneNumber < TwilioObject
     def create(url, area_code = nil, method = 'POST', friendly_name = nil)
-      self.connection.class.post("/IncomingPhoneNumbers/Local", :body => {
+      Twilio.post("/IncomingPhoneNumbers/Local", :body => {
         :Url => url, 
         :AreaCode => area_code, 
         :Method => method,
@@ -12,7 +15,7 @@ module Twilio
     end
     
     def list
-      self.connection.class.get("/IncomingPhoneNumbers/Local")
+      Twilio.get("/IncomingPhoneNumbers/Local")
     end
   end
 end

data/lib/twilio/notification.rb

@@ -1,17 +1,20 @@
 module Twilio
   # A Notification represenents a log entry made by Twilio in the course of handling 
   # your calls or using the REST API.
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio::Notification.list
   class Notification < TwilioObject
     def list(optional = {})
-      self.connection.class.get('/Notifications', :query => optional)
+      Twilio.get('/Notifications', :query => optional)
     end
     
     def get(notification_sid)
-      self.connection.class.get("/Notifications/#{notification_sid}")
+      Twilio.get("/Notifications/#{notification_sid}")
     end
     
     def delete(notification_sid)
-      self.connection.class.delete("/Notifications/#{notification_sid}")
+      Twilio.delete("/Notifications/#{notification_sid}")
     end
   end
 end

data/lib/twilio/outgoing_caller_id.rb

@@ -1,9 +1,12 @@
 module Twilio
   # An OutgoingCallerId resource represents an outgoing Caller ID that you have 
-  # registered with Twilio for use when making an outgoing call or using the Dial Verb. 
+  # registered with Twilio for use when making an outgoing call or using the Dial Verb.
+  # Example:
+  #   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)
-      self.connection.class.post("/OutgoingCallerIds", :body => {
+      Twilio.post("/OutgoingCallerIds", :body => {
         :PhoneNumber => phone_number, 
         :FriendlyName => friendly_name, 
         :CallDelay => call_delay 
@@ -11,19 +14,19 @@ module Twilio
     end
 
     def list(optional = {})
-      self.connection.class.get("/OutgoingCallerIds", :query => optional) 
+      Twilio.get("/OutgoingCallerIds", :query => optional) 
     end
         
     def get(callerid_sid)
-      self.connection.class.get("/OutgoingCallerIds/#{callerid_sid}") 
+      Twilio.get("/OutgoingCallerIds/#{callerid_sid}") 
     end
     
     def update_name(callerid_sid, name)
-      self.connection.class.put("/OutgoingCallerIds/#{callerid_sid}", :body => {:FriendlyName => name})
+      Twilio.put("/OutgoingCallerIds/#{callerid_sid}", :body => {:FriendlyName => name})
     end
     
     def delete(callerid_sid)
-      self.connection.class.delete("/OutgoingCallerIds/#{callerid_sid}")
+      Twilio.delete("/OutgoingCallerIds/#{callerid_sid}")
     end
   end
 end

data/lib/twilio/recording.rb

@@ -1,21 +1,24 @@
 module Twilio
   # Recordings are generated when you use the Record Verb. Those recordings are 
   # hosted on Twilio's REST API for you to access. 
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio::Recording.list
   class Recording < TwilioObject    
     def list(optional = {})
-      self.connection.class.get("/Recordings", :query => optional)  
+      Twilio.get("/Recordings", :query => optional)  
     end
     
     def get(recording_sid)
-      self.connection.class.get("/Recordings/#{recording_sid}")  
+      Twilio.get("/Recordings/#{recording_sid}")  
     end
     
     def delete(recording_sid)
-      self.connection.class.delete("/Recordings/#{recording_sid}")
+      Twilio.delete("/Recordings/#{recording_sid}")
     end
     
     def transcriptions(recording_sid, transcription_sid = nil)
-      self.connection.class.get("/Recordings/#{recording_sid}/Transcriptions#{ '/' + transcription_sid if transcription_sid }") 
+      Twilio.get("/Recordings/#{recording_sid}/Transcriptions#{ '/' + transcription_sid if transcription_sid }") 
     end
   end
 end

data/lib/twilio/toll_free_phone_number.rb

@@ -1,9 +1,12 @@
 module Twilio
   # This sub-resource represents only Toll Free phone numbers, or in other words, not local numbers. 
   # Also allows you to request a new toll free phone number be added to your account. 
+  # Example:
+  #   Twilio.connect('my_twilio_sid', 'my_auth_token')
+  #   Twilio::TollFreePhoneNumber.list
   class TollFreePhoneNumber < TwilioObject
     def create(url, area_code = nil, method = 'POST', friendly_name = nil)
-      self.connection.class.post("/IncomingPhoneNumbers/TollFree", :body => {
+      Twilio.post("/IncomingPhoneNumbers/TollFree", :body => {
         :Url => url, 
         :AreaCode => area_code, 
         :Method => method,
@@ -12,7 +15,7 @@ module Twilio
     end
     
     def list
-      self.connection.class.get("/IncomingPhoneNumbers/TollFree")
+      Twilio.get("/IncomingPhoneNumbers/TollFree")
     end
   end
 end

data/lib/twilio/twilio_object.rb

@@ -1,11 +1,16 @@
 module Twilio
-  class TwilioObject  #:nodoc: all
-    include HTTParty
-    
+  class TwilioObject  #:nodoc: all    
     attr_reader :connection
     
-    def initialize(connection)
+    def initialize(connection = nil)
       @connection = connection
     end
+    
+    class << self
+      def method_missing(method_id, *args) #:nodoc:
+        o = self.new
+        o.send(method_id, *args)
+      end
+    end
   end
 end