twilio_contactable 0.7.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,144 @@
+Twilo Contactable
+=====
+
+Twilo makes voice and SMS interactions easy. But if you want to be able to seamlessly validate your user's phone numbers for
+both voice and text there's a lot of work you'll have to do in your Rails app. Unless you use this gem.
+
+Why bother?
+=====
+
+Unless you're programming Ruby like it's PHP you don't enjoy passing strings around and writing all procedural code. This gem lets you
+ask for a phone number from your users, confirm their ownership of it via SMS or Voice or both, and keep track of whether the number is
+still validated when they edit it.
+
+
+Setting Up Your Model
+=====
+
+Include Twilio::Contactable into your User class or whatever you're using to represent an entity with a phone number. 
+
+    class User < ActiveRecord::Base
+      twilio_contactable
+    end
+
+You can also specify which attributes you'd like to use instead of the defaults
+
+    class User < ActiveRecord::Base
+      twilio_contactable do |config|
+        config.phone_number_column                  :mobile_number
+        config.formatted_phone_number_column        :formatted_mobile_number
+        config.sms_blocked_column                   :should_we_not_txt_this_user
+        config.sms_confirmation_code_column         :the_sms_confirmation_code
+        config.sms_confirmation_attempted_column    :when_was_the_sms_confirmation_attempted
+        config.sms_confirmed_phone_number_column    :the_mobile_number_thats_been_confirmed_for_sms
+        config.voice_blocked_column                 :should_we_not_call_this_user
+        config.voice_confirmation_code_column       :the_voice_confirmation_code
+        config.voice_confirmation_attempted_column  :when_was_the_voice_confirmation_attempted
+        config.voice_confirmed_phone_number_column  :the_mobile_number_thats_been_confirmed_for_voice
+
+      # Defaults to the name on the left (minus the '_column' at the end)
+      # e.g., the sms_blocked_column is 'sms_blocked'
+      #
+      # You don't need all those columns, omit any that you're sure you won't want.
+    end
+
+Turning the thing on
+---
+
+Because it can be expensive to send TXTs or make calls accidentally, it's required that you manually configure TwilioContactable in your app. Put this line in config/environments/production.rb or anything that loads _only_ in your production environment:
+
+    TwilioContactable.mode = :live
+
+Skipping this step (or adding any other value) will prevent TXTs from actually being sent.
+
+You'll also want to configure your setup with your client_id and client_key. Put this in the same file as above or in a separate initializer if you wish:
+
+    TwilioContactable.configure do |config|
+      # these three are required:
+      # (replace them with your actual account info)
+      config.client_id = 12345
+      config.client_key = 'ABC123'
+      config.website_address = 'http://myrubyapp.com' # <- Twilio.com needs to be able to find this
+
+      # the rest are optional:
+      config.short_code     = 00001 # if you have a custom short code
+      config.proxy_address  = 'my.proxy.com'
+      config.proxy_port     = '80'
+      config.proxy_username = 'user'
+      config.proxy_password = 'password'
+    end
+
+Phone number formatting
+---
+
+Whatever is stored in the phone_number_column will be subject to normalized formatting:
+
+    user = User.create :phone_number => '(206) 555-1234'
+    user.phone_number # => (206) 555-1234
+    user.formatted_phone_number # => 12065551234 (defaults to US country code)
+
+If you want to preserve the format of the number exactly as the user entered it you'll want
+to save that in a different attribute.
+
+
+Confirming Phone Number And Sending Messages
+====
+
+When your users first hand you their number it will be unconfirmed:
+
+    @user = User.create(:phone_number => '555-222-3333')
+    @user.send_sms_confirmation! # fires off a TXT to the user with a generated confirmation code
+    @user.sms_confirmed?         # => false, because we've only started the process
+
+then ask the user for the confirmation code off their phone and pass it in to sms_confirm_with:
+
+    @user.sms_confirm_with('123XYZ')
+
+If the code is right then the user's current phone number will be automatically marked as confirmed. You can check this at any time with:
+
+    @user.sms_confirmed? # => true
+    @user.send_sms!("Hi! This is a text message.")
+
+If the code is wrong then the user's current phone number will stay unconfirmed.
+
+    @user.sms_confirmed? # => false
+    @user.send_sms!("Hi! This is a text message.") # sends nothing
+
+
+Receiving TXTs and Voice calls
+====
+
+You can also receive data posted to you from Twilio. This is how you'll receive messages, txts and notices that users have been blocked.
+All you need is to create a bare controller and include TwilioContactable::Controller into it. Then specify which Ruby class you're using as a contactable user model (likely User)
+
+
+    class SMSController < ApplicationController
+      include TwilioContactable::Controller
+
+      sms_contactable User # or whichever class you included TwilioContactable::Contactable into
+    end
+
+And hook this up in your routes.rb file like so:
+
+    ActionController::Routing::Routes.draw do |map|
+      map.route 'twilio', :controller => 'twilio_contactable', :action => :index
+    end
+
+Now just tell Twilio to POST messages and block notices to you at:
+
+    http://myrubyapp.com/twilio
+
+Now if your users reply to an SMS with 'STOP' or 'BLOCK' your database will be automatically updated to reflect this.
+
+Incoming messages from a user will automatically be sent to that user's record:
+
+   # If "I love you!" is sent to you from a user with
+   # the phone number "555-111-9999"
+   # then the following will be executed:
+   User.find_by_phone_number('5551119999').receive_sms("I love you!")
+
+It's up to you to implement the 'receive_sms' method on User.
+
+That's it. Patches welcome, forks celebrated.
+
+Copyright (c) 2010 [Jack Danger Canty](http://jåck.com/), released under the MIT license

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "twilio_contactable"
+    gem.summary = %Q{Help authorize the users of your Rails apps to confirm and use their phone numbers}
+    gem.description = %Q{Does all the hard work with letting you confirm your user's phone numbers for Voice or TXT over the Twilio API}
+    gem.email = "gitcommit@6brand.com"
+    gem.homepage = "http://github.com/JackDanger/twilio_contactable"
+    gem.authors = ["Jack Danger Canty"]
+    gem.add_dependency "twiliolib", ">= 2.0.5"
+    gem.add_development_dependency "shoulda", ">= 0"
+    gem.add_development_dependency "mocha", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+desc "Test Twilio Contactable"
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+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
+
+task :test => :check_dependencies
+
+task :default => :test

data/VERSION

@@ -0,0 +1 @@
+0.7.1

data/init.rb

@@ -0,0 +1,3 @@
+# Include hook code here
+
+require 'twilio_contactable'

data/lib/configuration.rb

@@ -0,0 +1,41 @@
+module TwilioContactable
+  class << self
+    def mode
+      @@mode ||= :test
+    end
+
+    def mode=(new_mode)
+      @@mode = new_mode
+    end
+
+    def configured?
+      return false unless configuration
+      configuration.client_id && configuration.client_key
+    end
+
+    def configuration
+      @@configuration ||= Configuration.new
+    end
+
+    def configure(&block)
+      @@configuration = Configuration.new(&block)
+    end
+  end
+
+  class Configuration
+
+    attr_accessor :client_id
+    attr_accessor :client_key
+    attr_accessor :short_code
+    attr_accessor :website_address
+    attr_accessor :default_from_phone_number
+    attr_accessor :proxy_address
+    attr_accessor :proxy_port
+    attr_accessor :proxy_username
+    attr_accessor :proxy_password
+
+    def initialize
+      yield self
+    end
+  end
+end

data/lib/contactable.rb

@@ -0,0 +1,204 @@
+module TwilioContactable
+  module Contactable
+
+    Attributes = [
+      :phone_number,
+      :formatted_phone_number,
+      :sms_blocked,
+      :sms_confirmation_code,
+      :sms_confirmation_attempted,
+      :sms_confirmed_phone_number,
+      :voice_blocked,
+      :voice_confirmation_code,
+      :voice_confirmation_attempted,
+      :voice_confirmed_phone_number
+    ]
+
+    class Configuration
+      Attributes.each do |attr|
+        attr_accessor "#{attr}_column"
+      end
+      # the following is set when a controller includes TwilioContactable
+      # and calls twilio_contactable with this model as an argument
+      attr_accessor :controller
+
+      def initialize
+
+        yield self if block_given?
+
+        Attributes.each do |attr|
+          # set the defaults if the user hasn't specified anything
+          if send("#{attr}_column").blank?
+            send("#{attr}_column=", attr)
+          end
+        end
+      end
+    end
+
+    def self.included(model)
+
+      # set up the configuration, available within the class object
+      # via this same 'twilio_contactable' method
+      model.instance_eval do
+        def twilio_contactable(&block)
+          @@twilio_contactable = Configuration.new(&block) if block
+          @@twilio_contactable ||= Configuration.new
+        end
+      end
+
+      # normalize the phone number before it's saved in the database
+      # (only for model classes using callbacks a la ActiveModel,
+      #  other folks will have to do this by hand)
+      if model.respond_to?(:before_save)
+        model.before_save :format_phone_number
+        model.class_eval do
+          def format_phone_number
+            self._TC_formatted_phone_number =
+              TwilioContactable.internationalize(_TC_phone_number)
+          end
+        end
+      end
+    end
+
+    # Set up a bridge to access the data for a specific instance
+    # by referring to the column values in the configuration.
+    def twilio_contactable
+      self.class.twilio_contactable
+    end
+    Attributes.each do |attr|
+      eval %Q{
+        def _TC_#{attr}
+          read_attribute self.class.twilio_contactable.#{attr}_column
+        end
+        def _TC_#{attr}=(value)
+          write_attribute  self.class.twilio_contactable.#{attr}_column, value
+        end
+      }
+    end
+
+
+
+    # Sends an SMS validation request through the gateway
+    def send_sms_confirmation!
+      return false if _TC_sms_blocked
+      return true  if sms_confirmed?
+      return false if _TC_phone_number.blank?
+
+      confirmation_code = TwilioContactable.generate_confirmation_code
+
+      # Use this class' confirmation_message method if it
+      # exists, otherwise use the generic message
+      message = (self.class.respond_to?(:confirmation_message) ?
+                   self.class :
+                   TwilioContactable).confirmation_message(confirmation_code)
+
+      if message.to_s.size > 160
+        raise ArgumentError, "SMS Confirmation Message is too long. Limit it to 160 characters of unescaped text."
+      end
+
+      response = TwilioContactable::Gateway.deliver(message, _TC_phone_number)
+
+      if response.success?
+        update_twilio_contactable_sms_confirmation confirmation_code
+      else
+        false
+      end
+    end
+
+    # Begins a phone call to the user where they'll need to type
+    # their confirmation code
+    def send_voice_confirmation!
+      return false if _TC_voice_blocked
+      return true  if voice_confirmed?
+      return false if _TC_phone_number.blank?
+
+      confirmation_code = TwilioContactable.generate_confirmation_code
+
+      response = TwilioContactable::Gateway.initiate_voice_call(self, _TC_phone_number)
+
+      if response.success?
+        update_twilio_contactable_voice_confirmation confirmation_code
+      else
+        false
+      end
+    end
+
+    # Compares user-provided code with the stored confirmation
+    # code. If they match then the current phone number is set
+    # as confirmed by the user.
+    def sms_confirm_with(code)
+      if _TC_sms_confirmation_code.to_s.downcase == code.downcase
+        # save the phone number into the 'confirmed phone number' attribute
+        self._TC_sms_confirmed_phone_number = _TC_phone_number
+        save
+      else
+        false
+      end
+    end
+
+    # Returns true if the current phone number has been confirmed by
+    # the user for recieving TXT messages.
+    def sms_confirmed?
+      return false if _TC_sms_confirmed_phone_number.blank?
+      self._TC_sms_confirmed_phone_number == _TC_phone_number
+    end
+
+    # Compares user-provided code with the stored confirmation
+    # code. If they match then the current phone number is set
+    # as confirmed by the user.
+    def voice_confirm_with(code)
+      if _TC_voice_confirmation_code.to_s.downcase == code.downcase
+        # save the phone number into the 'confirmed phone number' attribute
+        self._TC_voice_confirmed_phone_number = _TC_phone_number
+        save
+      else
+        false
+      end
+    end
+
+    # Returns true if the current phone number has been confirmed by
+    # the user by receiving a phone call
+    def voice_confirmed?
+      return false if _TC_voice_confirmed_phone_number.blank?
+      self._TC_voice_confirmed_phone_number == _TC_phone_number
+    end
+
+    # Sends one or more TXT messages to the contactable record's
+    # mobile number (if the number has been confirmed).
+    # Any messages longer than 160 characters will need to be accompanied
+    # by a second argument <tt>true</tt> to clarify that sending
+    # multiple messages is intentional.
+    def send_sms!(msg, allow_multiple = false)
+      if msg.to_s.size > 160 && !allow_multiple
+        raise ArgumentError, "SMS Message is too long. Either specify that you want multiple messages or shorten the string."
+      end
+      return false if msg.to_s.strip.blank? || _TC_sms_blocked
+      return false unless sms_confirmed?
+
+      # split into pieces that fit as individual messages.
+      msg.to_s.scan(/.{1,160}/m).map do |text|
+        if TwilioContactable::Gateway.deliver_sms(text, _TC_phone_number).success?
+          text.size
+        else
+          false
+        end
+      end
+    end
+
+    protected
+
+      def update_twilio_contactable_sms_confirmation(new_code)
+        self._TC_sms_confirmation_code = new_code
+        self._TC_sms_confirmation_attempted = Time.now.utc
+        self._TC_sms_confirmed_phone_number = nil
+        save
+      end
+
+      def update_twilio_contactable_voice_confirmation(new_code)
+        self._TC_voice_confirmation_code = new_code
+        self._TC_voice_confirmation_attempted = Time.now.utc
+        self._TC_voice_confirmed_phone_number = nil
+        save
+      end
+  end  
+end