txter 2.0.2

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,125 @@
+4info
+=====
+
+Connect to the 4info SMS gateway
+
+If you're using 4info.com as your SMS gateway this gem will give you a painless API for both sending and receiving messages.
+
+Setting Up Your Model
+=====
+
+Include Txter::Contactable into your User class or whatever you're using to represent an entity with a phone number. 
+
+    class User < ActiveRecord::Base
+      include Txter::Contactable
+    end
+
+You can also specify which attributes you'd like to use instead of the defaults
+
+    class User < ActiveRecord::Base
+      include Txter::Contactable
+
+      sms_phone_number_column            :mobile_number
+      sms_blocked_column                 :is_sms_blocked
+      sms_confirmation_code_column       :the_sms_confirmation_code
+      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 '_column' at the end)
+    end
+
+Turning the thing on
+---
+
+Because it can be expensive to send TXTs accidentally, it's required that you manually configure Txter in your app. Put this line in config/environments/production.rb or anything that loads _only_ in your production environment:
+
+    Txter.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:
+
+    Txter.configure do |config|
+      # these two are required:
+      # (replace them with your actual account info)
+      config.client_id = 12345
+      config.client_key = 'ABC123'
+
+      # 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 sms_phone_number_column will be subject to normalized formatting:
+
+    user = User.create :sms_phone_number => '(206) 555-1234'
+    user.sms_phone_number # => 2065551234
+
+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
+====
+
+You can manage the user's SMS state like so:
+
+    @user = User.create(:sms_phone_number => '5552223333')
+    @user.send_sms_confirmation!
+    @user.sms_confirmed? # => false
+
+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 and @user.sms_blocked? will be true.
+You can fix this by calling:
+
+    @user.unblock_sms!
+
+
+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 Txter::Controller into it. Then specify which Ruby class you're using as a contactable user model (likely User)
+
+
+    class SMSController < ApplicationController
+      include Txter::Controller
+
+      sms_contactable User # or whichever class you included Txter::Contactable into
+    end
+
+And hook this up in your routes.rb file like so:
+
+    ActionController::Routing::Routes.draw do |map|
+      map.route '4info', :controller => 'txter', :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

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "txter"
+    gem.summary = %Q{Send and receive SMS messages simply via the Twilio gateway or the 4info.com gateway}
+    gem.description = %Q{Drop-in functionality to let Ruby apps send and receive TXT messages}
+    gem.email = "gitcommit@6brand.com"
+    gem.homepage = "http://github.com/JackDanger/txter"
+    gem.authors = ["Jack Danger Canty"]
+    # gem.add_dependency "hpricot", ">= 0"
+    # gem.add_dependency "haml", ">= 0"
+    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 Txter"
+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
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "inline_styles #{version}"
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+2.0.2

data/init.rb

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

data/lib/4info_templates/confirm.haml

@@ -0,0 +1,6 @@
+!!! XML
+%request{ :clientId => config.client_id, :clientKey => config.client_key, :type => "VALIDATION" }
+  %validation
+    %recipient
+      %type= 5
+      %id= number

data/lib/4info_templates/deliver.haml

@@ -0,0 +1,11 @@
+!!! XML
+%request{ :clientId => config.client_id, :clientKey => config.client_key, :type => "MESSAGE" }
+  %message
+    - if config.short_code
+      %sender
+        %type= 6
+        %id= config.short_code
+    %recipient
+      %type= 5
+      %id= number
+    %text= message.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub("'", "&apos;").gsub('"', "&quot;")

data/lib/4info_templates/unblock.haml

@@ -0,0 +1,6 @@
+!!! XML
+%request{ :clientId => config.client_id, :clientKey => config.client_key, :type => "UNBLOCK" }
+  %unblock
+    %recipient
+      %type= 5
+      %id= number

data/lib/configuration.rb

@@ -0,0 +1,41 @@
+module Txter
+  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
+    end
+
+    def configure(&block)
+      @@configuration = Configuration.new(&block)
+    end
+  end
+
+  class Configuration
+
+    attr_accessor :client_id
+    attr_accessor :client_key
+    attr_accessor :gateway
+    attr_accessor :short_code
+    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,150 @@
+module Txter
+  module Contactable
+
+    Attributes = [  :sms_phone_number,
+                    :sms_blocked,
+                    :sms_confirmation_code,
+                    :sms_confirmation_attempted,
+                    :sms_confirmed_phone_number ]
+
+    def self.included(model)
+      gem 'haml'
+      require 'haml'
+      require 'net/http'
+
+      Attributes.each do |attribute|
+        # 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.
+        model.instance_eval "
+          def #{attribute}_column(value = nil)
+            @#{attribute}_column ||= :#{attribute}
+            @#{attribute}_column = value if value
+            @#{attribute}_column
+          end
+        "
+        # provide helper methods to access the right value
+        # no matter which column it's stored in.
+        #
+        # e.g.: @user.txter_sms_confirmation_code
+        #       == @user.send(User.sms_confirmation_code_column)
+        model.class_eval "
+          def txter_#{attribute}
+            send self.class.#{attribute}_column
+          end
+          alias_method :txter_#{attribute}?, :txter_#{attribute}
+          def txter_#{attribute}=(value)
+            send self.class.#{attribute}_column.to_s+'=', value
+          end
+        "
+      end
+
+      # normalize the phone number before it's saved in the database
+      # (only for model classes using callbacks a la ActiveRecord,
+      #  other folks will have to do this by hand)
+      if model.respond_to?(:before_save)
+        model.before_save :normalize_sms_phone_number
+        model.class_eval do
+          def normalize_sms_phone_number
+            self.txter_sms_phone_number = Txter.numerize(txter_sms_phone_number)
+          end
+        end
+      end
+    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? || txter_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 Txter.deliver(text, txter_sms_phone_number).success?
+          text.size
+        else
+          false
+        end
+      end
+    end
+
+    # Sends an SMS validation request through the gateway
+    def send_sms_confirmation!
+      return false if txter_sms_blocked?
+      return true  if sms_confirmed?
+      return false if txter_sms_phone_number.blank?
+
+      confirmation_code = Txter.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 :
+                   Txter).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 = Txter.deliver(message, txter_sms_phone_number)
+
+      if response.success?
+        update_txter_sms_confirmation confirmation_code
+      else
+        false
+      end
+    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 txter_sms_blocked?
+
+      response = Txter.unblock(txter_sms_phone_number)
+      if response.success?
+        self.txter_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 txter_sms_confirmation_code.to_s.downcase == code.downcase
+        # save the phone number into the 'confirmed phone number' attribute
+        self.txter_sms_confirmed_phone_number = txter_sms_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 txter_sms_confirmed_phone_number.blank?
+      txter_sms_confirmed_phone_number == txter_sms_phone_number
+    end
+
+    protected
+
+      def update_txter_sms_confirmation(new_code)
+        self.txter_sms_confirmation_code = new_code
+        self.txter_sms_confirmation_attempted = Time.now.utc
+        self.txter_sms_confirmed_phone_number = nil
+        save
+      end
+  end  
+end

data/lib/controller.rb

@@ -0,0 +1,62 @@
+module Txter
+  module Controller
+
+    def self.included(controller)
+      controller.instance_eval do
+        # the user should specify which class gets contacted
+        def sms_contactable(klass)
+          @@contactable_class = klass
+        end
+      end
+    end
+
+    # the likely default
+    def index
+      recieve_xml
+    end
+
+    # in case this is hooked up as a RESTful route
+    def create
+      recieve_xml
+    end
+
+    protected
+
+      def recieve_xml
+
+        unless defined?(@@contactable_class)
+          raise RuntimeError, "Please define your user class in the Txter controller via the 'sms_contactable' method"
+        end
+
+        request = params[:request]
+        render :text => 'unknown format', :status => 500 and return unless request
+        case request['type']
+        when 'BLOCK'
+          @contactable = find_contactable(request[:block][:recipient][:id])
+          @contactable.txter_sms_blocked = true
+          @contactable.save!
+        when 'MESSAGE'
+          @contactable = find_contactable(request[:message][:sender][:id])
+          if @contactable.respond_to?(:receive_sms)
+            @contactable.receive_sms(request[:message][:text])
+          else
+            warn "An SMS message was received but #{@@contactable_class.name.inspect} doesn't have a receive_sms method!"
+          end
+        end
+        render :text => 'OK', :status => 200
+      end
+
+      def find_contactable(id)
+        [id, id.sub(/^\+/,''), id.sub(/^\+1/,'')].uniq.compact.each do |possible_phone_number|
+          found = @@contactable_class.find(
+            :first,
+            :conditions => 
+              { @@contactable_class.sms_phone_number_column => possible_phone_number }
+          )
+          return found if found
+        end
+      # rescue => error
+      #   render :text => error.inspect
+      end
+  end
+end