4info 1.1.1 → 1.2.0

data/4info.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{4info}
-  s.version = "1.1.1"
+  s.version = "1.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jack Danger Canty"]
-  s.date = %q{2010-02-10}
+  s.date = %q{2010-02-11}
   s.description = %q{A complete Ruby API for handling SMS messages via 4info.com}
   s.email = %q{gitcommit@6brand.com}
   s.extra_rdoc_files = [

data/README.markdown

@@ -3,12 +3,12 @@
 
 Connect to the 4info SMS gateway
 
-If you're using 4info.com as your SMS gateway this gem will give you a painless API.
+If you're using 4info.com as your SMS gateway this gem will give you a painless API for both sending and receiving messages.
 
-USAGE
+Setting Up Your Model
 =====
 
-Include FourInfo::Contactable into your User class or whatever you're using to represent an entity with a phone number.
+Include FourInfo::Contactable into your User class or whatever you're using to represent an entity with a phone number. 
 
     class User < ActiveRecord::Base
       include FourInfo::Contactable
@@ -25,25 +25,39 @@ You can also specify which attributes you'd like to use instead of the defaults
       sms_confirmation_attempted_column  :when_was_the_sms_confirmation_attempted
       sms_confirmed_phone_number_column  :the_mobile_number_thats_been_confirmed
 
-      # Defaults to the name on the left (minus the word '_column')
+      # Defaults to the name on the left (minus the '_column' at the end)
     end
 
+
+Confirming Phone Number And Sending Messages
+====
+
 You can manage the user's SMS state like so:
 
     @user = User.create(:sms_phone_number => '5552223333')
-    @user.confirm_sms!
-    # then ask the user for the confirmation code and
-    # compare it to @user.sms_confirmation_code
-    # if they're the same, call
-    @user.sms_confirmed!
-    @user.update_attributes(:sms_confirmed_phone_number => @user.sms_phone_number)
+    @user.send_sms_confirmation!
+
+then ask the user for the confirmation code off their phone and pass it in to sms_confirm_with:
+
+    @user.sms_confirm_with(user_provided_code)
+
+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.")
-    # Then maybe the user will reply with 'BLOCK' by accident
+
+Then maybe the user will reply with 'BLOCK' by accident and @user.sms_blocked? will be true.
+You can fix this by calling:
+
     @user.unblock_sms!
 
 
-There's also a controller module that allows you to super-easily create a controller
-that receives data from 4info.com
+Receiving Messages From 4info.com
+====
+
+You can also receive data posted to you from 4info.com. This is how you'll receive messages and notices that users have been blocked.
+All you need is to create a bare controller and include FourInfo::Controller into it. Then specify which Ruby class you're using as a contactable user model (likely User)
+
 
     class SMSController < ApplicationController
       include FourInfo::Controller
@@ -51,10 +65,24 @@ that receives data from 4info.com
       sms_contactable User # or whichever class you included FourInfo::Contactable into
     end
 
-Now anything posted to the index (or create, if you've hooked this up RESTfully) action
-will automatically work. If a user sends 4info.com a message their user record on your site
-will (if User has a 'receive_sms' method defined) receive the message directly.
+And hook this up in your routes.rb file like so:
+
+    ActionController::Routing::Routes.draw do |map|
+      map.route '4info', :controller => 'four_info', :action => :index
+    end
+
+Now just tell 4info.com to POST messages and block notices to you at:
+
+    http://myrubyapp.com/4info
+
+Now if your users reply to an SMS with 'STOP' your database will be 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_sms_phone_number('5551119999').receive_sms("I love you!")
 
 That's it. Patches welcome, forks celebrated.
 
-Copyright (c) 2010 Jack Danger Canty (http://jåck.com/), released under the MIT license
+Copyright (c) 2010 [Jack Danger Canty](http://jåck.com/), released under the MIT license

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

data/lib/contactable.rb

@@ -13,7 +13,7 @@ module FourInfo
       require 'net/http'
 
       Attributes.each do |attribute|
-        # add a method for setting or retrieving
+        # add a method in the class for setting or retrieving
         # which column should be used for which attribute
         # 
         # :sms_phone_number_column defaults to :sms_phone_number, etc.
@@ -24,34 +24,34 @@ module FourInfo
             @#{attribute}_column
           end
         "
-        # provide a helper method to access the right value
-        # no matter which column it's stored in
+        # provide helper methods to access the right value
+        # no matter which column it's stored in.
         #
         # e.g.: @user.four_info_sms_confirmation_code
         #       == @user.send(User.sms_confirmation_code_column)
         model.class_eval "
-          def four_info_#{attribute}(value = nil)
-            value ?
-              send(self.class.#{attribute}_column.to_s+'=', value) :
-              send(self.class.#{attribute}_column)
+          def four_info_#{attribute}
+            send self.class.#{attribute}_column
           end
           alias_method :four_info_#{attribute}?, :four_info_#{attribute}
-          alias_method :four_info_#{attribute}=, :four_info_#{attribute}
+          def four_info_#{attribute}=(value)
+            send self.class.#{attribute}_column.to_s+'=', value
+          end
         "
       end
     end
 
-    def current_phone_number_confirmed_for_sms?
-      return false if four_info_sms_confirmed_phone_number.blank?
-      four_info_sms_confirmed_phone_number == four_info_sms_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? || four_info_sms_blocked?
-      return false unless current_phone_number_confirmed_for_sms?
+      return false unless sms_confirmed?
 
       # split into pieces that fit as individual messages.
       msg.to_s.scan(/.{1,160}/m).map do |text|
@@ -59,15 +59,18 @@ module FourInfo
       end
     end
 
-    def confirm_sms!
+    # Sends an SMS validation request via xml to the 4info gateway.
+    # If request succeeds the 4info-generated confirmation code is saved
+    # in the contactable record.
+    def send_sms_confirmation!
       return false if four_info_sms_blocked?
-      return true  if current_phone_number_confirmed_for_sms?
+      return true  if sms_confirmed?
       return false if four_info_sms_phone_number.blank?
 
       response = FourInfo::Request.new.confirm(four_info_sms_phone_number)
       if response.success?
-        self.four_info_sms_confirmation_code response.confirmation_code
-        self.four_info_sms_confirmation_attempted Time.now
+        self.four_info_sms_confirmation_code = response.confirmation_code
+        self.four_info_sms_confirmation_attempted = Time.now
         save
       else
         # "Confirmation Failed: #{response['message'].inspect}"
@@ -75,21 +78,37 @@ module FourInfo
       end
     end
 
-    def sms_confirmed!
-      # save the phone number into the 'confirmed phone number' attribute
-      four_info_sms_confirmed_phone_number four_info_sms_phone_number
-    end
-
+    # Sends an unblock request via xml to the 4info gateway.
+    # If request succeeds, changes the contactable record's
+    # sms_blocked_column to false.
     def unblock_sms!
       return false unless four_info_sms_blocked?
 
       response = FourInfo::Request.new.unblock(four_info_sms_phone_number)
       if response.success?
-        four_info_sms_blocked 'false'
+        self.four_info_sms_blocked = 'false'
         save!
       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 four_info_sms_confirmation_code == code
+        # save the phone number into the 'confirmed phone number' attribute
+        self.four_info_sms_confirmed_phone_number = four_info_sms_phone_number
+        save
+      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 four_info_sms_confirmed_phone_number.blank?
+      four_info_sms_confirmed_phone_number == four_info_sms_phone_number
+    end
   end  
 end

data/lib/controller.rb

@@ -47,7 +47,7 @@ module FourInfo
       end
 
       def find_contactable(id)
-        [id, id.sub(/^\+/,''), id.sub(/^\+1/,'')].each do |possible_phone_number|
+        [id, id.sub(/^\+/,''), id.sub(/^\+1/,'')].uniq.compact.each do |possible_phone_number|
           found = @@contactable_class.find(
             :first,
             :conditions => 

data/test/four_info_contactable_test.rb

@@ -60,7 +60,7 @@ class FourInfoContactableTest < ActiveSupport::TestCase
     context "when phone number is blank" do
       setup { @user.sms_phone_number = nil}
       context "confirming phone number" do
-        setup { @user.confirm_sms! }
+        setup { @user.send_sms_confirmation! }
         should_not_change "any attributes" do
           @user.attributes.inspect
         end
@@ -82,7 +82,7 @@ class FourInfoContactableTest < ActiveSupport::TestCase
       context "confirming phone number" do
         setup {
           FourInfo::Request.any_instance.stubs(:perform).returns(ValidationSuccess)
-          @worked = @user.confirm_sms!
+          @worked = @user.send_sms_confirmation!
         }
         should "work" do assert @worked end
         should "save confirmation number in proper attribute" do
@@ -95,15 +95,25 @@ class FourInfoContactableTest < ActiveSupport::TestCase
           @user.four_info_sms_confirmation_code
         end
         should "not have number confirmed yet" do
-          assert !@user.current_phone_number_confirmed_for_sms?
+          assert !@user.sms_confirmed?
         end
-        context "calling sms_confirmed!" do
-          setup { @user.sms_confirmed! }
+        context "calling sms_confirm_with(right_code)" do
+          setup { @user.sms_confirm_with(@user.four_info_sms_confirmation_code) }
           should "save the phone number into the confirmed attribute" do
             assert_equal @user.four_info_sms_confirmed_phone_number,
                          @user.four_info_sms_phone_number
           end
-          should_change "confirmed phone number attribuet" do
+          should_change "confirmed phone number attribute" do
+            @user.four_info_sms_confirmed_phone_number
+          end
+        end
+        context "calling sms_confirm_with(wrong_code)" do
+          setup { @user.sms_confirm_with('wrong_code') }
+          should "not save the phone number into the confirmed attribute" do
+            assert_not_equal @user.four_info_sms_confirmed_phone_number,
+                             @user.four_info_sms_phone_number
+          end
+          should_not_change "confirmed phone number attribute" do
             @user.four_info_sms_confirmed_phone_number
           end
         end
@@ -111,7 +121,7 @@ class FourInfoContactableTest < ActiveSupport::TestCase
       context "confirming phone number when the confirmation fails for some reason" do
         setup {
           FourInfo::Request.any_instance.stubs(:perform).returns(ValidationError)
-          @worked = @user.confirm_sms!
+          @worked = @user.send_sms_confirmation!
         }
         should "not work" do assert !@worked end
         should "not save confirmation number" do
@@ -149,7 +159,7 @@ class FourInfoContactableTest < ActiveSupport::TestCase
     context "when the number is confirmed" do
       setup {
         FourInfo::Request.any_instance.stubs(:perform).returns(SendMsgSuccess)
-        @user.stubs(:current_phone_number_confirmed_for_sms?).returns(true)
+        @user.stubs(:sms_confirmed?).returns(true)
       }
       context "sending a message" do
         setup { @result = @user.send_sms!('message') }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: 4info
 version: !ruby/object:Gem::Version 
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors: 
 - Jack Danger Canty
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-10 00:00:00 -08:00
+date: 2010-02-11 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency