blythedunham-sms_on_rails 0.1.0

data/lib/sms_on_rails/model_support/phone_number_associations.rb

@@ -0,0 +1,13 @@
+module SmsOnRails
+  module ModelSupport
+    module PhoneNumberAssociations
+      def self.included(base)
+        base.send :has_many,   :outbounds, :class_name => 'SmsOnRails::Outbound',
+               :foreign_key => 'sms_phone_number_id', :dependent => :delete_all
+        base.send :belongs_to, :carrier, :class_name => 'SmsOnRails::PhoneCarrier',
+               :foreign_key => :carrier_id
+      end
+    end
+  end
+end
+

data/lib/sms_on_rails/schema_helper.rb

@@ -0,0 +1,51 @@
+module SmsOnRails
+  class SchemaHelper
+    class << self
+      def create(*files)
+        each_file(*files) {|file, options| file_to_string(file, options) }
+      end
+
+      def drop(*files)
+        each_file(*files) {|file, options| drop_tables(file, options)}
+      end
+
+      def each_file(*files, &block)
+        options = parse_options(files)
+        files.inject('') {|str, f| str << yield(f, options); str }
+      end
+
+      def schema(command, *files)
+        str = "ActiveRecord::Schema.define do\n"
+        str << self.send(command, *files)
+        str << "\nend"
+        str
+      end
+
+      def file_to_string(file, options={})
+        File.read(File.join(File.dirname(__FILE__), "../../db/migrate/#{file}.rb"))
+      end
+
+      def drop_tables(file, options={})
+        str = "\n"
+        data = file_to_string(file)
+        data.scan(/create_table\s+[":]([^\W]*)/) do
+          table_name = $1.dup
+          str << safe_code(str, options) { |code| code << "    drop_table :#{table_name}\n" }
+        end
+        str
+      end
+
+      def safe_code(str, options, &block)
+        str = ''
+        str << "  begin\n  " if options[:safe]
+        yield str
+        str << "  rescue Exception => e\n  end\n" if options[:safe]
+        str
+      end
+
+      def parse_options(files)
+        options = files.last.is_a?(Hash) ? files.pop : {}
+      end
+    end
+  end
+end

data/lib/sms_on_rails/service_providers/base.rb

@@ -0,0 +1,222 @@
+# This is the base class for service providers from which all others inherit
+# All service providers are singletons and can be accessed by their instance
+#
+# To send a message without validation
+#  SmsOnRails::ServiceProviders::<Provider>.instance.send_message '12065551234', 'my message', options
+#
+# To send a message with validation use send_to_phone_number with a string or SmsOnRails::PhoneNumber instance
+#  SmsOnRails::ServiceProviders<Provider>.instance.send_to_phone_number(number, message, options)
+#
+# To send an sms(with validation)
+#  SmsOnRails::ServiceProviders<Provider>.instance.send_sms(sms, options)
+# However, it is preferred to use the locking mechanism to prevent double messages from being sent
+#   sms.deliver!
+#
+module SmsOnRails
+  module ServiceProviders
+    class Base 
+      include Singleton
+
+      #the configuration options for the service provider
+      class_inheritable_hash :config
+      self.config ||= {}
+
+      #special deliver options specific to the service provider
+      class_inheritable_accessor  :delivery_options
+      self.delivery_options ||= {}
+
+      #the default service provider
+      cattr_accessor :default_service_provider
+
+      #a unique id by which each service provider is identified
+      class_inheritable_accessor :provider_id, :instance_writer => false
+
+      #the logger -> ActiveRecord::Base.logger
+      cattr_accessor :logger
+      @@logger ||= ActiveRecord::Base.logger
+
+      
+      def requires_carrier?; false; end
+
+      # Deliver all the sms messages marked with this as its sms service provider
+      def deliver
+        Outbound.deliver(delivery_options.merge(:conditions => ['sms_service_provider_id = ?', self.provider_id]))
+      end
+
+      [:config, :name, :provider_id, :logger, :human_name].each{|method| class_eval  "def #{method}; self.class.#{method}; end"}
+
+
+      # Sends a message to a phone number directly to the provider.
+      # No validations are performed
+      # * +phone_number+ the exact string text to send
+      # * +message+ - the string message to send
+      # * +options+ - additional options to be used by the provider
+      #
+      def send_message(phone_number, message, options={})
+        raise SmsOnRails::SmsError.new("Override send_message in subclass #{self.class}")
+      end
+
+      
+      # Sends a message to a phone number active record object or string
+      # and performs validation on the phone_number
+      #
+      # * +phone_number+ can be either a phone number active record obj or a string text. Strings are converted to phone_number objects
+      # * +message+ - the message to send
+      # * +options+ - additional options to be used by the provider
+      #
+      # ===Options
+      # <tt>:skip_validation</tt> - skips validation and sends the message directly to the
+      # provider
+      def send_to_phone(phone_obj, message, options={})
+
+        if options[:skip_validation]
+          phone_text = phone_obj.is_a?(ActiveRecord::Base) ? format_phone_number(phone_number) : phone_obj
+          return send_message(phone_text, message, options)
+        end
+
+        phone_number = phone_obj.is_a?(ActiveRecord::Base) ? phone_obj :
+                       find_or_create_phone_number(phone_obj, options)
+
+        assert_message_options!(phone_number, message, options)
+        send_message(format_phone_number(phone_number), message, options)
+      end
+
+      # Send an Sms with validation
+      # +sms+ is an sms active record object that responds to phone_number and full_message
+      #
+      # Refer to send_to_phone for more infomation on validation
+      def send_sms(sms, options={})
+        send_to_phone(sms.phone_number, sms.actual_message, options)
+      end
+
+      protected
+
+      #can override in subclass if different finder should be used
+      def find_or_create_phone_number(phone_text, options={})
+        phone = phone_klass.find_and_create_by_number(phone_text)
+        phone.assign_carrier(options[:carrier]) if options[:carrier]
+        phone
+      end
+
+      #override this if the expected format differs in subclass
+      def format_phone_number(phone_number)
+        phone_number.digits
+      end
+
+      # Raise an exception if the white list is being used (only sends to people on this list)
+      # and this phone number is not on the list
+      def check_white_list!(phone_number)
+        if self.class.config[:white_list] && !phone_number.white_list?
+          raise SmsOnRails::SmsError.new("Phone number #{phone_number.human_display} is not in white list")
+        end
+      end
+
+      # Raise an exception if this phone_number is marked as do not send
+      def check_do_not_send!(phone_number)
+        if phone_number.do_not_send?
+          raise SmsOnRails::SmsError.new("Phone number #{phone_number.human_display} do not send is set:#{phone_number.do_not_send}")
+        end
+      end
+
+      # Raise exception if invalid data is entered
+      def assert_message_options!(phone_number, message, options)
+        raise SmsOnRails::SmsError.new("Invalid or undefined phone number: #{phone_number.human_display}") unless phone_number && phone_number.valid?
+        raise SmsOnRails::SmsError.new("No message specified") unless message
+        raise SmsOnRails::SmsError.new("Message is too long. #{message}") if message.length > self.class.max_characters
+        check_white_list!(phone_number)
+        check_do_not_send!(phone_number)
+      end
+
+      # return the appropriate exception class
+      # Return a fatal error if the block returns true and a non fatal if the
+      # block returns false
+      def sms_error_class(&block)#:nodoc
+        if yield
+          SmsOnRails::FatalSmsError
+        else
+          SmsOnRails::SmsError
+        end
+      end
+
+      # The class used for phone numbers
+      # can be overwritten and specified in environment.rb
+      def phone_klass
+        config[:phone_klass]||SmsOnRails::PhoneNumber
+      end
+
+      class << self
+
+         def set_default_service_provider(provider)
+           return if $gems_rake_task
+           provider_instance = get_service_provider(provider)
+           raise SmsOnRails::FatalSmsError.new("Cannot set default provider to #{provider}. Check that support for #{provider} exists.") unless provider_instance
+           self.default_service_provider = provider_instance
+         end
+         
+         def max_characters
+           self.config[:max_characters]||140
+         end
+
+         # Name of service provider (downcase no spaces)
+         def name
+           @name ||= self.to_s.demodulize.underscore
+         end
+
+         # Human name of provider
+         def human_name
+           @human_name ||= self.to_s.demodulize.titleize
+         end
+
+         # Hash map of provider_id to the provider
+         def provider_map
+           @provider_map ||= provider_list.inject({}) do |map, klass|
+             map[klass.provider_id] = klass unless klass.nil?
+             map
+           end
+         end
+
+         #List of all providers available
+         def provider_list
+           @provider_list ||= subclasses.inject([]) do |list, klass_name|
+             klass = klass_name.constantize
+             begin
+               list << klass.instance
+             rescue LoadError => exc
+               logger.error "#{klass} load error: #{exc}"
+             end
+             list
+           end
+         end
+
+         # Locate the service provider by provider id
+         #  Example: SmsOnRails::ServiceProviders::Base.provider_by_id 1
+         def provider_by_id(provider_id)
+           provider_map[provider_id.to_i] if provider_id.to_i > 0
+         end
+
+         # Locate the service provider by name or symbol
+         #  Example: SmsOnRails::ServiceProviders::Base.provider_by_name :dummy
+         def provider_by_name(provider_name)
+           key = provider_name.to_s.downcase
+           provider_list.detect{|p| key == p.name || provider_name == p.human_name}
+         end
+
+         # Locate the service provider object by provider_id, string, symbol, or ServiceProvider object
+         # Defaults to the default service provider
+         #   SmsOnRails::ServiceProviders::Base.get_service_provider :dummy
+         #   SmsOnRails::ServiceProviders::Base.get_service_provider 1
+         #   SmsOnRails::ServiceProviders::Base.get_service_provider SmsOnRails::ServiceProviders::Dummy
+         def get_service_provider(provider)
+           case provider.class.to_s
+            when 'Fixnum'           then provider_by_id(provider)
+            when 'String'           then (provider.to_i > 0 ? provider_by_id(provider) : provider_by_name(provider))
+            when 'Symbol'           then provider_by_name(provider)
+            when 'NilClass'         then nil
+            else
+              provider
+            end
+         end
+      end
+    end
+  end
+end

data/lib/sms_on_rails/service_providers/clickatell.rb

@@ -0,0 +1,52 @@
+module SmsOnRails
+  module ServiceProviders
+    class Clickatell < Base
+      self.provider_id = 1
+
+      FATAL_ERROR_CODES = %w(105 114) unless defined?(FATAL_ERROR_CODES)
+      
+      def initialize
+        begin
+          require 'clickatell'
+        rescue LoadError => exc
+          raise LoadError.new(exc.to_s + " Please make sure the clickatell gem is installed.")
+        end
+        super
+      end
+      
+      def ping
+        result = invoke_clickatell{ api.ping(nil) }
+        result.is_a?(Net::HTTPOK)
+      end
+
+      def authenticate
+        invoke_clickatell{ api }
+      end
+
+      #Send a message without validation
+      # * phone_number - phone number string digits
+      # * message - the message text
+      # * options - anything else
+      def send_message(phone_number, message, options={})
+        unique_id = invoke_clickatell{  api.send_message(phone_number, message) }
+        {:unique_id => unique_id}
+      end
+
+      protected
+
+      #Get the api key
+      def api#:nodoc:
+        @@api ||= ::Clickatell::API.authenticate(config[:api_id], config[:user_name], config[:password])
+      end
+
+      # wrap this method around all clickatell calls
+      # if anything other than a 105 is thrown, reraise FatalSmsError
+      def invoke_clickatell(&block)#:nodoc
+        yield
+        
+      rescue ::Clickatell::API::Error => cae
+        raise sms_error_class{ !(FATAL_ERROR_CODES.include?(cae.code)) }.new("Clickatell Error:#{cae.code}:#{cae.message}", cae.code)
+      end
+    end
+  end
+end

data/lib/sms_on_rails/service_providers/dummy.rb

@@ -0,0 +1,19 @@
+module SmsOnRails
+  module ServiceProviders
+    class Dummy < Base
+
+      self.provider_id = 2
+
+      def ping
+        true
+      end
+
+      def send_message(phone_number, message, options={})
+        response = {:unique_id => "#{$$}:#{Time.now.strftime('%Y%m%d%H%M%SZ')}.#{rand(1000)}"}
+        response
+      end
+      
+    end
+  end
+end
+SmsOnRails::ServiceProviders::Base.default_service_provider ||= SmsOnRails::ServiceProviders::Dummy.instance

data/lib/sms_on_rails/service_providers/email_gateway.rb

@@ -0,0 +1,68 @@
+#Require all the email gateway support files
+Dir.glob(File.dirname(__FILE__) + '/email_gateway_support/*.rb').each {|f| require f }
+
+module SmsOnRails
+  module ServiceProviders
+    class EmailGateway < Base
+        self.provider_id = 3
+
+        def ping; true; end
+
+        def mailer_klass; self.class.mailer_klass; end
+
+        def requires_carrier?; true; end
+
+        # Email Gateway Send message
+        #
+        #   send_message('2065551234@txt.att.net', 'My message')
+        #   send_message('12065551234', 'my message', :carrier => 'Verizon')
+        #   send_message(['12065551234', '4125556667'], 'my message', :carrier => 'Verizon')
+        #
+        # === Params
+        # * +phone_number+ - can be one of the following
+        #    sms_email_address. Example: '2065551234@txt.att.net'
+        #    array of sms_email_addresses: ['2065551234@txt.att.net', '2065552234@txt.att.net']
+        # * +message+ - the text message to send
+        #
+        # ===Options
+        # * <tt>:sender</tt>  - email address of the sender overrides default
+        # * <tt>:bcc</tt>     - email_address or array of email_addresses to blind carbon copy
+        def send_message(phone_text, message, options={})
+          mailer_klass.deliver_sms_through_gateway(phone_text, message, self.class.config.merge(options))
+          {}
+        end
+
+        protected
+
+        #the formate for email is the sms email address
+        def format_phone_number(phone_number)
+          phone_number.sms_email_address
+        end
+
+        # additional check to make sure the sms_email_address is valid
+        def assert_message_options!(phone_number, message, options)
+          super(phone_number, message, options)
+          unless phone_number.carrier || phone_number.sms_email_address
+            raise EmailGatewayInvalidSms.phone_error(phone_number)
+          end
+        end
+
+        # override to append the carrier if specified as part of the phone number
+        # or as a separate option
+        def find_or_create_phone_number(phone_text, options={})
+          phone = phone_klass.find_by_sms_email_address(phone_text)
+          phone ||= super(phone_text, options)
+          phone.assign_carrier(options[:carrier]) if options[:carrier]
+          phone
+        end
+
+        class << self
+          # The mailer class to use that can be specified in the config options for :mailer_klass
+          def mailer_klass#:nodoc:
+            @mailer_klass ||= config[:mailer_klass]||SmsOnRails::ServiceProviders::EmailGatewaySupport::SmsMailer
+          end
+        end
+      end
+
+  end
+end

data/lib/sms_on_rails/service_providers/email_gateway_support/errors.rb

@@ -0,0 +1,20 @@
+module SmsOnRails
+  module ServiceProviders
+    class EmailGatewayInvalidSms < SmsOnRails::SmsError
+      def self.phone_error(phone_number)
+        new(self.phone_message(phone_number))
+      end
+      def self.phone_message(phone_number)
+        msg =  "Invalid phone number #{phone_number.human_display if phone_number}. "
+        msg << "Please specify the digits and the option :carrier, "
+        msg << "or specify the full email address like 2065551234@txt.att.net"
+      end
+    end
+
+    class EmailGatewayInvalidCarrier < EmailGatewayInvalidSms
+      def self.phone_message(phone_number)
+        msg =  "The carrier for #{phone_number.human_display if phone_number} is invalid."
+      end
+    end
+  end
+end