twilio-rb 0.4 → 1.0beta

data/README.md

@@ -1,7 +1,11 @@
 
 # Twilio.rb
 
-Interact with the Twilio API in a nice Ruby way
+Interact with the Twilio API in a nice Ruby way. 
+
+Twilio.rb is the only library that encapsulates Twilio resources as Ruby objects, has 100% test coverage, and supports the whole API.
+
+It offers an ActiveRecord style API, i.e. one that most Ruby developers are familiar using to manipulate Ruby objects with.
 
 ## Installation
 
@@ -15,6 +19,10 @@ Require the library in your script as
 
 <pre>require 'twilio'</pre>
 
+or using bundler:
+
+<pre>gem 'twilio-rb', '1.0pre', :require => 'twilio'</pre>
+
 ## Configuration
 
 Configuration for this library is encapsulated within `Twilio::Config`. One needs to setup with an Account SID and an Auth Token, e.g.
@@ -27,50 +35,19 @@ end</pre>
 
 Any method that calls the Twilio API will raise `Twilio::ConfigurationError` if either Account SID or Auth Token are not configured.
 
-## The Account object
-
-The Twilio API in its current incarnation supports one Twilio account per Account SID, and so the Twilio::Account object correspondingly is a singleton object.
-
-To access properties of the account the property name should be called as a method on the object itself, e.g.
-
-<pre>Twilio::Account.friendly_name</pre>
-
-The first time a method is invoked on the object an API call is made to retrieve the data. The methods themselves are not defined until they are called, i.e. lazy evaluation. This strategy means that addtional properties added to subsequent versions of the API should not break the library.
-
-To reload the data when needed `Twilio::Account.reload!` will make another API call and update its own internal state.
-
-Predicate methods i.e. those ending in `?` map directly to the status of the account, e.g. `Twilio::Account.suspended?` returns true if Twilio have suspended your account. Again, all of these methods are defined on the fly.
-
-The only account property that can be modified via the REST API is the friendly name, e.g.
-
-<pre>Twilio::Account.friendly_name = "I'm so vain, I had to change my name!"</pre>
-
-This will update the API immediately with a PUT request.
-
-Please refer to the Twilio REST API documentation for an up to date list of properties.
+# Getting started
 
 ## Making a telephone call
 
 The API used to make a telephone call is similar to interacting with an ActiveRecord model object.
 <pre>Twilio::Call.create :to => '+16465551234', :from => '+19175550000', 
                     :url => "http://example.com/call_handler"</pre>
-or
-<pre>call = Twilio::Call.new :to => '+16465551234', :from => '+19175550000', 
-                        :url => "http://example.com/call_handler"
-
-call.save</pre>
 
 The parameter keys should be given as underscored symbols. They will be converted internally to camelized strings prior to an API call being made.
 
 Please see the Twilio REST API documentation for an up to date list of supported parameters. 
 
-## Finding an existing telephone call
-
-To retrieve an earlier created call, there is the `Twilio::Call.find` method, which accepts a call SID, e.g.
-
-<pre>call = Twilio::Call.find 'CAa346467ca321c71dbd5e12f627deb854'</pre>
-
-This returns an instance of `Twilio::Call` if a call with the given SID was found, otherwise nil is returned 
+If the request was successful, an instance of `Twilio::Call` wil be returned
 
 ### Modifying a live telephone call
 
@@ -83,21 +60,26 @@ Once a call has been been created it can be modified with the following methods:
 `Twilio::Call#cancel!` and `Twilio::Call#complete!` will raise `Twilio::InvalidStateError` if the call has not been "saved". 
 `Twilio::Call#url=` will updated its state with the new URL ready for when `Twilio::Call#save` is called.
 
+## Finding an existing telephone call
+
+To retrieve an earlier created call, there is the `Twilio::Call.find` method, which accepts a call SID, e.g.
+
+<pre>call = Twilio::Call.find 'CAa346467ca321c71dbd5e12f627deb854'</pre>
+
+This returns an instance of `Twilio::Call` if a call with the given SID was found, otherwise nil is returned
+
 ## Sending an SMS message
 
 The API used to send an SMS message is similar to interacting with an ActiveRecord model object.
 <pre>Twilio::SMS.create :to => '+16465551234', :from => '+19175550000', 
                    :body => "Hey baby, how was your day? x"</pre>
-or
-<pre>sms = Twilio::SMS.new :to => '+16465551234', :from => '+19175550000', 
-                      :body => "Hey baby, how was your day? x"
-
-sms.save</pre>
 
 The parameter keys should be given as underscored symbols. They will be converted internally to camelized strings prior to an API call being made.
 
 Please see the Twilio REST API documentation for an up to date list of supported parameters.
 
+If the request was successful, an instance of `Twilio::SMS` wil be returned
+
 ## Finding an existing telephone SMS message
 
 To retrieve an earlier created SMS message, there is the `Twilio::SMS.find` method, which accepts a SMS message SID, e.g.
@@ -106,7 +88,7 @@ To retrieve an earlier created SMS message, there is the `Twilio::SMS.find` meth
 
 This returns an instance of `Twilio::SMS` if a SMS message with the given SID was found, otherwise nil is returned
 
-## Building TwiML documents
+# Building TwiML documents
 
 A TwiML document is an XML document. The best way to build XML in Ruby is with Builder, and so it follows that we should use builder for TwiML. `Twilio::TwiML.build` behaves like builder except element names are capitalised for you and attributes are camelized for you as well. This is so you may continue to write beautiful code.
 
@@ -143,3 +125,190 @@ Therefore emits the following TwiML document:
 </pre>
 
 This specialised behaviour only affects `Twilio::TwiML.build` and does not affect Builder in general.
+
+# Rails 3 integration
+
+Twilio.rb has Rails integration out of the box. It adds a new mime type :voice and a template handler for TwiML views.
+So now your Rails app can respond_to :voice. Insane!
+
+<pre>
+class FooController &lt; ApplicationController
+  responds_to :html, :voice
+
+  def index
+   ...
+  end
+end
+</pre>
+
+coupled with the following view file `app/views/foo/index.voice`
+
+<pre>
+res.say 'Damn this library is so ill dude!'
+</pre>
+
+It's now easier than ever to integrate Twilio in your Rails app cleanly and easily.
+
+# Basics
+
+Each super-resource, e.g. Calls, OutgoingCallerIds, etc has a Ruby object in the Twilio namespace representing it, Twilio::Call, Twilio::OutgoingCallerId, etc.
+
+## Summary
+
+Resources that can be created via the API, using the HTTP POST verb can be done so in the library using the `.create` class method, e.g.
+
+<pre>Twilio::Call.create :to => '+16465551234', :from => '+19175550000', 
+                    :url => "http://example.com/call_handler"</pre>
+
+Resources that can be removed via the API, using the HTTP DELETE verb can be done so in the library using the `#destroy` instance method, e.g.
+
+<pre>
+# Delete all log entries
+Twilio::Notification.all.each &:destroy
+</pre>
+
+Object representations instantiated by the library respond to all methods that match attributes on its corresponding resource. The method names are those of the parameters in snake case (underscored), i.e. as they are returned in the JSON representation. 
+
+The Twilio API documentation itself is the canonical reference for which resources have what properties, and which of those can be updated by the API. Please refer to the Twilio REST API documentation for thos information.
+
+## Accessing resource instances
+
+Resource instances can be accessed ad hoc passsing the resource sid to the `.find` class method on the resource class, e.g.
+
+<pre>call = Twilio::Call.find 'CAe1644a7eed5088b159577c5802d8be38'</pre>
+
+This will return an instance of the resource class, in this case `Twilio::Call`, with the attributes of the resource. These attributes are accessed using dynamically defined getter methods, where the method name is the attribute name underscored, i.e. as they are returned in a JSON response from the API. 
+
+Sometimes these method name might collide with native Ruby methods, one such example is the `method` parameter colliding with `Object#method`. Native Ruby methods are never overridden by the library as they are lazily defined using `method_missing`. To access these otherwise unreachable attributes, there is another syntax for accessing resource attributes:
+
+
+<pre>
+call = Twilio::Call.find 'CAe1644a7eed5088b159577c5802d8be38'
+call[:method] # With a symbol or 
+call['method'] # or with a string. Access is indifferent.
+</pre>
+
+## Querying list resources
+
+List resources can be accessed ad hoc by calling the `.all` class method on the resource class, e.g.
+
+<pre>calls = Twilio::Call.all</pre>
+
+This will return a collection of objects, each a representation of the corresponding resource.
+
+### Using filter parameters to refine a query
+
+The `.all` class method will ask Twilio for all resource instances on that list resource, this can easily result in a useless response if there are numerous resource instances on a given resource. The `.all` class method accepts a hash of options for parameters to filter the response, e.g.
+
+<pre>Twilio::Call.all :to => '+19175550000', :status => 'complete'</pre>
+
+Twilio does some fancy stuff to implement date ranges, consider the API request:
+
+<pre>GET /2010-04-01/Accounts/AC5ef87.../Calls?StartTime&gt;=2009-07-06&EndTime&lt;=2009-07-10</pre>
+
+This will return all calls started after midnight July 06th 2009 and completed before July 10th 2009. Any call started and ended within that time range matches those criteria and will be returned. To make the same reqest using this library:
+
+<pre>
+require 'date'
+start_date, end_date = Date.parse('2009-07-06'),  Date.parse('2009-07-10')
+
+Twilio::Call.all :started_after => start_date, :ended_before => end_date
+</pre>
+
+All option parameters pertaining to dates accept a string or any object that returns a RFC 2822 date when `#to_s` is called on it, e.g. an instance of `Date`. If a date parameter is not a rnage but absolute, one can of course use the normal option, e.g.
+
+<pre>Twilio::Call.all :start_time => start_date</pre>
+
+The key names for these Date filters are inconsistent across resources, in the library they are:
+
+<pre>
+Twilio::SMS.all :created_before => date, :created_after => date, :sent_before => date, :sent_after # :"created_#{when}" and :"sent_#{when}" are synonomous
+Twilio::Notification.all :created_before => date, :created_after => date
+Twilio::Call.all :started_before => date, :started_after => date, :ended_before => date, :ended_after => date
+</pre>
+
+### Pagination
+
+The Twilio API paginates API responses and by default it will return 30 objects in one response, this can be overridden to return up to a maximum of 1000 per response using the `:page_size` option, If more than 1000 resources instances exist, the `:page` option is available, e.g.
+
+<pre>Twilio::Call.all :started_after => start_date, :ended_before => end_date, :page_size => 1000, :page => 7</pre>
+
+To determine how many resources exist, the `.count` class method exists, which accepts the same options as `.all` in order to constrain the query e.g.
+
+<pre>Twilio::Call.count :started_after => start_date, :ended_before => end_date</pre>
+
+It returns an integer corresponding to how many resource instances exist with those conditions.
+
+## Updating resource attributes
+
+Certain resources have attributes that can be updated with the REST API. Instances of those resources can be updated using either a setter method with a name that corresponds to the attribute, or by using the `#update_attributes`.
+
+<pre>
+call = Twilio::Call.all(:status => 'in-progress').first
+
+call.url = 'http://example.com/in_ur_apiz_hijackin_ur_callz.xml'
+call.update_attributes :url => 'http://example.com/in_ur_apiz_hijackin_ur_callz.xml'
+</pre>
+
+These are both equivalent, i.e. they immediately make an API request and update the state of the object with the API response. The first one in fact uses the second one internally and is just a shortcut. Use the second when there is more than one attribute to be updated in the same HTTP request.
+
+## Manipulating conference participants
+
+The participants list resource is a subresource of a conference resource instance:
+
+<pre>conference = Twilio::Conference.find 'CFbbe46ff1274e283f7e3ac1df0072ab39'</pre>
+
+Conference participants are accessed via the `#particpants` instance method, e.g.
+
+<pre>participants = conference.participants</pre>
+
+The muted state can be toggled using the `#mute!` instance method, e.g. toggle the mute state off all participants:
+
+<pre>participants.each &:mute!</pre>
+
+Participants can be removed from the conference using the '#destroy instance method'
+
+# Singleton resources
+
+The Twilio API in its current incarnation has two singleton (scoped per account) resources, correspondingly there are the Twilio::Account, and Twilio::Sandbox singleton objects.
+
+To access properties of a singleton object the property name should be called as a method on the object itself, e.g.
+
+<pre>Twilio::Account.friendly_name</pre>
+
+The first time a method is invoked on the object an API call is made to retrieve the data. The methods themselves are not defined until they are called, i.e. lazy evaluation. This strategy means that addtional properties added to subsequent versions of the API should not break the library.
+
+To reload the data when needed `Twilio::Account.reload!` will make another API call and update its own internal state.
+
+The account has a predicate method i.e.  ending in `?`, it maps directly to the status of the account, e.g. `Twilio::Account.suspended?` returns true if Twilio have suspended your account. Again, this is defined on the fly.
+
+The only account property that can be modified via the REST API is the friendly name, e.g.
+
+<pre>Twilio::Account.friendly_name = "I'm so vain, I had to change my name!"</pre>
+<pre>Twilio::Account.update_attributes :friendly_name => "I'm so vain, I had to change my name!"</pre>
+
+This will update the API immediately with a POST request.
+
+Twilio::Sandbox supports more options. Please refer to the Twilio REST API documentation for an up to date list of properties.
+
+# Searching for and purchasing available phone numbers
+
+The Twilio API allows a user to search for available phone numbers in Twilio's inventory. e.g. to find a number in the 917 area code containing '7777':
+
+<pre>Twilio::AvailablePhoneNumber.all :area_code => '917', :contains => '7777'</pre>
+
+A collection of Twilio::AvailablePhoneNumber objects will be returned. e.g. To purchase the first one:
+
+<pre>numbers = Twilio::AvailablePhoneNumber.all :area_code => '917', :contains => '7777'
+numbers.first.purchase! :voice_url => 'http://example.com/twiml.xml'</pre>
+
+Which is a shortcut for:
+
+<pre>numbers = Twilio::AvailablePhoneNumber.all :area_code => '917', :contains => '7777'
+Twilio::IncomingPhoneNumber.create :phone_number => numbers.first.phone_number, :voice_url => 'http://example.com/twiml.xml'</pre>
+
+# Recordings
+
+A recording resource instance has an extra instance method: `#mp3` this returns a publicly accessible URL for the MP3 representation of the resource instance. 
+
+

data/lib/railtie.rb

@@ -0,0 +1,22 @@
+module Twilio
+  class Railtie < Rails::Railtie
+    initializer 'twilio.initialize' do |app|
+      module ActionView
+        class Template
+          module Handlers
+            class TwiML < ::ActionView::Template::Handler
+              include ::ActionView::Template::Handlers::Compilable
+
+              def compile(template)
+                %<Twilio::TwiML.build { |res| #{template.source} }>
+              end
+            end
+          end
+        end
+      end
+
+      ::ActionView::Template.register_template_handler(:voice, ActionView::Template::Handlers::TwiML)
+      ::Mime::Type.register_alias 'text/xml', :voice
+    end
+  end
+end

data/lib/twilio/account.rb

@@ -1,20 +1,25 @@
 module Twilio
   module Account
     include Twilio::Resource
-    @attributes = {}
+    @attributes = {}.with_indifferent_access
 
     def attributes
       @attributes.empty? ? reload! : @attributes
     end
 
     def reload!
-      handle_response get "/Accounts/#{Twilio::ACCOUNT_SID}.json"
+      handle_response get path
     end
 
     def friendly_name=(name)
-      handle_response put "/Accounts/#{Twilio::ACCOUNT_SID}.json", :body => { :friendly_name => name }
+      update_attributes :friendly_name => name
+    end
+
+    private
+    def path
+      "/Accounts/#{Twilio::ACCOUNT_SID}.json"
     end
 
     extend self
   end
-end
+end

data/lib/twilio/available_phone_number.rb

@@ -0,0 +1,26 @@
+module Twilio
+  class AvailablePhoneNumber
+    include Twilio::Resource 
+    extend  Twilio::Finder
+
+    class << self
+      def all(opts={})
+        opts                     = Hash[opts.map { |k,v| [k.to_s.camelize, v]}]
+        country_code             = opts['IsoCountryCode'] ? opts.delete('IsoCountryCode') : 'US'
+        number_type              = opts.delete('TollFree') ? 'TollFree' : 'Local'
+        params                   = { :query => opts } if opts.any?
+
+        handle_response get "/Accounts/#{Twilio::ACCOUNT_SID}/AvailablePhoneNumbers/#{country_code}/#{number_type}.json", params 
+      end
+
+      private :new
+      undef_method :count
+
+    end
+
+    # Shortcut for creating a new incoming phone number. Delegates to Twilio::IncomingPhoneNumber.create accepting the same options as that method does.
+    def purchase!(opts={})
+      Twilio::IncomingPhoneNumber.create opts.update :phone_number => phone_number
+    end
+  end
+end

data/lib/twilio/call.rb

@@ -1,62 +1,49 @@
 module Twilio
   class Call
     include Twilio::Resource
+    include Twilio::Persistable
+    extend Twilio::Finder
+
+    class << self
+      alias old_create create
+      def create(attrs={})
+        attrs = attrs.with_indifferent_access
+        attrs.each { |k,v| v.upcase! if k.to_s =~ /method$/ }
+        attrs[:send_digits] = CGI.escape(attrs[:send_digits]) if attrs[:send_digits]
+        attrs['if_machine'].try :capitalize
+        old_create attrs
+      end
 
-    def initialize(attrs ={})  #:nodoc:
-      @attributes = Hash[attrs.map { |k,v| [k.to_s.camelize, v.to_s] }]
-      normalize_http_verbs!
-      escape_send_digits! if attributes.include? 'SendDigits'
-      normalize_if_machine_parameter!
-    end
-
-    # Dials the call
-    def save
-      handle_response self.class.post "/Accounts/#{Twilio::ACCOUNT_SID}/Calls.json", :body => attributes
+      private
+      def prepare_dates(opts)
+        opts.map do |k,v|
+          if [:started_before, :started_after, :ended_before, :ended_after].include? k
+            k = k.to_s
+            # Fancy schmancy-ness to handle Twilio <= URI operator for dates
+            comparator = k =~ /before$/ ? '<=' : '>='
+            delineator = k =~ /started/ ? 'Start' : 'End' 
+            delineator << "Time" << comparator << v.to_s
+          else
+            "#{k.to_s.camelize}=#{v}"
+          end
+        end
+      end
     end
 
-    # Cancels a call if its state is 'queued' or 'ringing'    
+    # Cancels a call if its state is 'queued' or 'ringing'
     def cancel!
-      state_guard { modify_call 'Status' => 'cancelled' }
+      update_attributes :status => 'cancelled'
     end
-    
+
     def complete!
-      state_guard { modify_call 'Status' => 'completed' }
+      update_attributes :status => 'completed'
     end
-    
+
     # Update Handler URL
     def url=(url)
       # If this attribute exists it is assumed the API call to create a call has been made, so we need to tell Twilio.
-      modify_call "url" => url if self[:status]
+      update_attributes :url => url if self[:status]
       self[:url] = url
     end
-
-    private
-
-    def normalize_http_verbs! #:nodoc:
-      # Twilio accepts a HTTP method for use with various callbacks. The API documentation
-      # indicates that the HTTP verbs are to be passed as upcase.
-      attributes.each { |k,v| v.upcase! if k =~ /Method$/ }
-    end
-
-    def escape_send_digits! #:nodoc:
-      # A pound, i.e. "#" has special meaning in a URL so it must be escaped
-      attributes.update 'SendDigits' => CGI.escape(attributes['SendDigits'])
-    end
-
-    def normalize_if_machine_parameter! #:nodoc:
-      attributes['IfMachine'].capitalize! if attributes['IfMachine']
-    end
-
-    def state_guard(&blk)
-      if self[:status] # If this attribute exists it is assumed the API call to create a call has been made, and the object is in the correct state to make request.
-        blk.call
-      else
-        raise Twilio::InvalidStateError.new 'Call is in invalid state to perform this action.'
-      end
-    end
-
-    def modify_call(params)
-      handle_response self.class.post "/Accounts/#{Twilio::ACCOUNT_SID}/Calls/#{self[:sid]}.json", :body => params
-    end
   end
-end
+end

data/lib/twilio/conference.rb

@@ -0,0 +1,18 @@
+module Twilio
+  class Conference
+    include Twilio::Resource
+    extend Twilio::Finder
+
+    def participants
+      res = self.class.get "/Accounts/#{Twilio::ACCOUNT_SID}/Conferences/#{sid}/Participants.json"
+      if (400..599).include? res.code
+        raise Twilio::APIError.new "Error ##{res.parsed_response['code']}: #{res.parsed_response['message']}"
+      else
+        res.parsed_response['participants'].map do |p|
+          p['api_version'] = p['api_version'].to_s # api_version parsed as a date by http_party
+          Twilio::Participant.new p
+        end
+      end
+    end
+  end
+end

data/lib/twilio/deletable.rb

@@ -0,0 +1,7 @@
+module Twilio
+  module Deletable
+    def destroy
+      state_guard { freeze && true if self.class.delete path }
+    end
+  end
+end

data/lib/twilio/finder.rb

@@ -0,0 +1,60 @@
+module Twilio
+  module Finder
+    def find(id)
+      res  = get "/Accounts/#{Twilio::ACCOUNT_SID}/#{resource_fragment}/#{id}.json"
+      hash = res.parsed_response
+      if (200..299).include? res.code
+        hash['api_version'] = hash['api_version'].to_s # api_version parsed as a date by http_party
+        new hash 
+      end
+    end
+
+    def count(opts={})
+      opts   = prepare_dates opts
+      params = "?#{URI.encode(opts.join '&')}" unless opts.empty?
+
+      get("/Accounts/#{Twilio::ACCOUNT_SID}/#{resource_fragment}.json#{params}").parsed_response['total']
+    end
+
+    def all(opts={})
+      opts   = prepare_dates opts
+      params = "?#{URI.encode(opts.join '&')}" unless opts.empty?
+      
+      handle_response get "/Accounts/#{Twilio::ACCOUNT_SID}/#{resource_fragment}.json#{params}"
+    end
+
+    private
+
+    def resource_fragment # :nodoc:
+      # All Twilio resources follow a convention, except SMS :(
+      klass_name = name.demodulize
+      resource   = klass_name == 'SMS' ? "#{klass_name}/Messages" : klass_name.pluralize
+    end
+
+    def prepare_dates(opts) # :nodoc:
+      opts.map do |k,v|
+        if [:updated_before, :created_before, :updated_after, :created_after].include? k
+          k = k.to_s
+          # Fancy schmancy-ness to handle Twilio <= URI operator for dates
+          comparator = k =~ /before$/ ? '<=' : '>='
+          "Date" << k.gsub(/\_\w+$/, '').capitalize << comparator << v.to_s
+        else
+          "#{k.to_s.camelize}=#{v}"
+        end
+      end
+    end
+
+    def handle_response(res) # :nodoc:
+      if (400..599).include? res.code
+        raise Twilio::APIError.new "Error ##{res.parsed_response['code']}: #{res.parsed_response['message']}"
+      else
+        key = name.demodulize == 'SMS' ? 'sms_messages' : name.demodulize.underscore.pluralize
+        res.parsed_response[key].map do |p|
+          p['api_version'] = p['api_version'].to_s # api_version parsed as a date by http_party
+          new p
+        end
+      end
+    end
+
+  end
+end

data/lib/twilio/incoming_phone_number.rb

@@ -0,0 +1,14 @@
+module Twilio
+  class IncomingPhoneNumber
+    extend Twilio::Finder
+    include Twilio::Resource
+    include Twilio::Persistable
+    include Twilio::Deletable
+
+    %w<friendly_name api_version voice_url voice_method voice_fallback_url voice_fallback_method status_callback status_callback_method sms_url sms_method sms_fallback_url sms_fallback_method voice_caller_id_lookup>.each do |meth|
+      define_method "#{meth}=" do |arg|
+        update_attributes meth => arg 
+      end
+    end
+  end
+end

data/lib/twilio/notification.rb

@@ -0,0 +1,23 @@
+module Twilio
+  class Notification
+    include Twilio::Resource
+    include Twilio::Deletable
+    extend Twilio::Finder
+
+    class << self
+      private
+      def prepare_dates(opts)
+        opts.map do |k,v|
+          if [:created_before, :created_after].include? k
+            k = k.to_s
+            # Fancy schmancy-ness to handle Twilio <= URI operator for dates
+            comparator = k =~ /before$/ ? '<=' : '>='
+            "MessageDate" << comparator << v.to_s
+          else
+            "#{k.to_s.camelize}=#{v}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twilio/outgoing_caller_id.rb

@@ -0,0 +1,12 @@
+module Twilio
+  class OutgoingCallerId
+    include Twilio::Resource
+    include Twilio::Deletable
+    include Twilio::Persistable
+    extend Twilio::Finder
+
+    def friendly_name=(value)
+      update_attributes :friendly_name => value
+    end
+  end
+end

data/lib/twilio/participant.rb

@@ -0,0 +1,24 @@
+module Twilio
+  class Participant
+    include Twilio::Resource
+    include Twilio::Deletable
+
+    alias kick! destroy
+
+    def mute!
+      state_guard do
+        update_attributes muted? ? { :muted => false } : { :muted => true }
+      end
+    end
+
+    def muted?
+      muted
+    end
+
+    private
+
+    def path
+      "/Accounts/#{Twilio::ACCOUNT_SID}/Conferences/#{conference_sid}/Participants/#{call_sid}.json"
+    end
+  end
+end

data/lib/twilio/persistable.rb

@@ -0,0 +1,24 @@
+module Twilio
+  module Persistable
+
+    def self.included(base)
+      base.class_eval do
+        class << base
+          def create(attrs={})
+            # All Twilio resources follow a convention, except SMS :(
+            resource = name.demodulize
+            resource = name == 'Twilio::SMS' ? "SMS/Messages" : resource + 's'
+            res = post "/Accounts/#{Twilio::ACCOUNT_SID}/#{resource}.json", :body => Hash[attrs.map { |k,v| [k.to_s.camelize, v]}]
+            if (400..599).include? res.code
+              raise Twilio::APIError.new "Error ##{res.parsed_response['code']}: #{res.parsed_response['message']}"
+            else
+              res.parsed_response['api_version'] = res.parsed_response['api_version'].to_s
+              new res.parsed_response
+            end
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/twilio/recording.rb

@@ -0,0 +1,11 @@
+module Twilio
+  class Recording
+    include Twilio::Resource
+    include Twilio::Deletable
+    extend Twilio::Finder
+
+    def mp3
+      API_ENDPOINT + path.gsub(/\.json$/, '.mp3')
+    end
+  end
+end

data/lib/twilio/resource.rb

@@ -1,28 +1,49 @@
 require 'active_support/core_ext/string' # Chill! we only use the bits of AS we need!
+require 'active_support/core_ext/hash'
 
 module Twilio
   module Resource
-    # Convenience for accessing attributes. Attributes can be accessed either using the
-    # preferred symbol style, e.g. :if_machine or using the Twilio stringified attribute
-    # style, e.g. 'IfMachine'
-    # Kind of like ActiveSupport::HashWithIndifferentAccess on crack.
+    def initialize(attrs ={})  #:nodoc:
+      @attributes = attrs.with_indifferent_access
+    end
+
     def [](key)
-      accessor = key.is_a?(Symbol) ? key.to_s.camelize : key
-      attributes[accessor]
+      attributes[key]
+    end
+
+    def []=(key,value) # :nodoc:
+      attributes[key] = value
     end
 
-    def []=(key,value)
-      accessor = key.is_a?(Symbol) ? key.to_s.camelize : key
-      attributes[accessor] = value
+    def update_attributes(attrs={})
+      state_guard do
+        handle_response klass.post path, :body => Hash[attrs.map { |k,v| [k.to_s.camelize, v]}]
+      end
     end
 
     private
+    def klass
+      self.class == Module ? self : self.class
+    end
+
+    def state_guard
+      if frozen?
+        raise RuntimeError, "#{self.class.name.demodulize} has already been destroyed"
+      else
+        yield
+      end
+    end
+
+    def path # :nodoc:
+      "/Accounts/#{Twilio::ACCOUNT_SID}/#{klass.name.demodulize.pluralize}/#{self[:sid]}.json"
+    end
 
     def handle_response(res) # :nodoc:
-      if res.code.to_s =~ /^(4|5)\d\d/
+      if (400..599).include? res.code
         raise Twilio::APIError.new "Error ##{res.parsed_response['code']}: #{res.parsed_response['message']}"
       else
-        @attributes.update Hash[res.parsed_response.map { |k,v| [k.camelize, v] }] # params are camelized in requests, yet underscored in the repsonse. inconsistency FTW!
+        res.parsed_response['api_version'] = res.parsed_response['api_version'].to_s
+        @attributes.update(res.parsed_response)
       end
     end
 
@@ -31,10 +52,10 @@ module Twilio
       if meth =~ /\=$/
         add_attr_writer meth
         send meth, args.first
-      elsif meth =~ /^#{meth}\?/i
+      elsif meth =~ /^#{meth}\?$/i
         add_predicate meth
         send meth
-      elsif self[id]
+      elsif attributes.keys.include? meth 
         add_attr_reader meth
         send meth
       else
@@ -44,7 +65,7 @@ module Twilio
 
     def add_predicate(attribute)
       metaclass.class_eval do
-        define_method(attribute) { self[:status] =~ /^#{attribute.gsub '?', ''}/i ? true : false }
+        define_method(attribute) { self['status'] =~ /^#{attribute.gsub '?', ''}/i ? true : false }
       end
     end
 
@@ -56,7 +77,7 @@ module Twilio
 
     def add_attr_reader(attribute) #:nodoc
       metaclass.class_eval do
-        define_method(attribute) { self[attribute.to_sym] } unless respond_to? attribute
+        define_method(attribute) { self[attribute] }  unless respond_to? attribute
       end
     end
 
@@ -73,20 +94,6 @@ module Twilio
       end
 
       class << base
-        if instance_of? Class # Don't want this mixed into singleton objects e.g. Twilio::Account
-          def find(id)
-            # All Twilio resources follow a convention, except SMS :(
-            klass_name = name.demodulize
-            resource = klass_name == 'SMS' ? "#{klass_name}/Messages" : klass_name.pluralize
-            res = get "/Accounts/#{Twilio::ACCOUNT_SID}/#{resource}/#{id}.json"
-            new Hash[res.parsed_response.map { |k,v| [k.camelize, v] }] if (200..299).include? res.code
-          end
-
-          def create(attrs={})
-            new(attrs).tap { |c| c.save }
-          end 
-        end
-
         # decorate http methods with authentication
         %w<post get put delete>.each do |meth| 
           define_method(meth) do |*args| # splatted args necessary hack since <= 1.8.7 does not support optional block args 

data/lib/twilio/sandbox.rb

@@ -0,0 +1,26 @@
+module Twilio
+  module Sandbox
+    include Twilio::Resource
+    @attributes = {}.with_indifferent_access
+
+    def attributes
+      @attributes.empty? ? reload! : @attributes
+    end
+
+    def reload!
+      handle_response get path
+    end
+
+    %w<voice_url voice_method sms_url sms_method>.each do |meth|
+      define_method "#{meth}=" do |arg|
+        update_attributes meth => arg 
+      end
+    end
+
+    private
+    def path
+      "/Accounts/#{Twilio::ACCOUNT_SID}/Sandbox.json"
+    end
+    extend self
+  end
+end

data/lib/twilio/sms.rb

@@ -1,14 +1,23 @@
 module Twilio
   class SMS
     include Twilio::Resource
+    include Twilio::Persistable
+    extend  Twilio::Finder
 
-    def initialize(attrs ={})  #:nodoc:
-      @attributes = Hash[attrs.map { |k,v| [k.to_s.camelize, v.to_s] }]
-    end
-
-    # Sends the SMS message
-    def save
-      handle_response self.class.post "/Accounts/#{Twilio::ACCOUNT_SID}/SMS/Messages.json", :body => attributes
+    class << self
+      private
+      def prepare_dates(opts)
+        opts.map do |k,v|
+          if [:created_before, :created_after, :sent_before, :sent_after].include? k
+            k = k.to_s
+            # Fancy schmancy-ness to handle Twilio <= URI operator for dates
+            comparator = k =~ /before$/ ? '<=' : '>=' 
+            "DateSent" << comparator << v.to_s
+          else
+            "#{k.to_s.camelize}=#{v}"
+          end
+        end
+      end
     end
   end
-end
+end

data/lib/twilio/transcription.rb

@@ -0,0 +1,6 @@
+module Twilio
+  class Transcription
+    include Twilio::Resource
+    extend Twilio::Finder
+  end
+end

data/lib/twilio.rb

@@ -1,5 +1,5 @@
 %w<rubygems active_support cgi yajl yajl/json_gem httparty builder>.each  { |lib| require lib }
-require File.join(File.dirname(__FILE__), 'twilio', 'resource.rb')
+%w<resource finder persistable deletable>.each { |lib| require File.join(File.dirname(__FILE__), 'twilio', "#{lib}.rb") }
 
 module Twilio
   API_ENDPOINT        = 'https://api.twilio.com/2010-04-01'
@@ -9,10 +9,15 @@ module Twilio
 
   class << self
     def const_missing(const_name)
-      raise Twilio::ConfigurationError.new "Cannot complete request. Please set #{const_name.to_s.downcase} with Twilio::Config.setup first!"
+      if [:ACCOUNT_SID, :AUTH_TOKEN].include? const_name
+        raise Twilio::ConfigurationError.new "Cannot complete request. Please set #{const_name.to_s.downcase} with Twilio::Config.setup first!"
+      else
+        super
+      end
     end
   end
 end
 
 Dir[File.join(File.dirname(__FILE__), 'twilio', '*.rb')].each { |lib| require lib }
 
+require File.join(File.dirname(__FILE__), 'railtie.rb') if Object.const_defined?(:Rails) && Rails.version =~ /^3/

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification 
 name: twilio-rb
 version: !ruby/object:Gem::Version 
-  prerelease: false
+  prerelease: true
   segments: 
-  - 0
-  - 4
-  version: "0.4"
+  - 1
+  - 0beta
+  version: 1.0beta
 platform: ruby
 authors: 
 - Stevie Graham
@@ -13,7 +13,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-13 00:00:00 +00:00
+date: 2010-12-26 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -106,6 +106,21 @@ dependencies:
         version: 2.2.0
   type: :development
   version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 9
+        - 10
+        version: 0.9.10
+  type: :development
+  version_requirements: *id007
 description: A nice Ruby wrapper for the Twilio REST API
 email: sjtgraham@mac.com
 executables: []
@@ -116,11 +131,24 @@ extra_rdoc_files: []
 
 files: 
 - README.md
+- lib/railtie.rb
 - lib/twilio/account.rb
+- lib/twilio/available_phone_number.rb
 - lib/twilio/call.rb
+- lib/twilio/conference.rb
 - lib/twilio/config.rb
+- lib/twilio/deletable.rb
+- lib/twilio/finder.rb
+- lib/twilio/incoming_phone_number.rb
+- lib/twilio/notification.rb
+- lib/twilio/outgoing_caller_id.rb
+- lib/twilio/participant.rb
+- lib/twilio/persistable.rb
+- lib/twilio/recording.rb
 - lib/twilio/resource.rb
+- lib/twilio/sandbox.rb
 - lib/twilio/sms.rb
+- lib/twilio/transcription.rb
 - lib/twilio/twiml.rb
 - lib/twilio.rb
 has_rdoc: false
@@ -145,11 +173,13 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: