blythedunham-sms_on_rails 0.1.0

data/lib/sms_on_rails/all_models.rb

@@ -0,0 +1,3 @@
+Dir.glob(File.dirname(__FILE__) + "/../../app/models/sms_on_rails/*.rb") {|f| require f;}
+
+

data/lib/sms_on_rails/model_support/draft.rb

@@ -0,0 +1,178 @@
+module SmsOnRails
+  module ModelSupport
+    module Draft
+
+      def self.included(base)#:nodoc
+        base.send :accepts_nested_attributes_for, :outbounds
+        #base.acts_as_deliverable :fatal_exception => SmsOnRails::FatalSmsError
+
+        base.validates_presence_of  :message
+        base.validate :validates_message_length
+
+        base.class_inheritable_accessor  :default_header
+        base.class_inheritable_accessor  :default_footer
+        base.class_inheritable_accessor  :max_message_length
+        
+        base.max_message_length = SmsOnRails::ServiceProviders::Base.max_characters
+
+        base.validates_associated :outbounds
+
+        base.send :include, InstanceMethods
+        base.send :extend,  ClassMethods
+      end
+
+      module ClassMethods
+
+        # Create a new sms draft
+        # +message+ - can either be a string, an attribute hash (nested ok) or and ActiveRecord
+        # +phone_numbers+ - array or single text phone number or phone number . If +message+ is
+        #   a nested attributes (Rails 2.3), +phone_numbers+ and +options+ should be blank
+        #
+        # ===Options
+        # <tt>:send_immediately</tt> - Send all outbounds now
+        # <tt>:draft</tt> - a hash of attributes for the draft object
+        # <tt>:phone_number</tt> - a hash of attributes applied to all +phone_numbers+
+        # <tt>:outbound</tt> - a hash of attributes applied to all generated +Outbound+ instances
+        # <tt>:keep_failed_outbounds</tt> - typically outbound messages are destroyed if they fail during delivery
+        # <tt>:deliver</tt> - options to pass to the deliver method if <tt>:send_immediately</tt> is used
+        #
+        # ===Example
+        # SmsOnRails::Draft.create_sms('my_message', '9995556667')
+        # SmsOnRails::Draft.create_sms('my_message', ['2065556666', '9995556667'])
+        #
+        # SmsOnRails::Draft.create_sms(params[:draft]) # assume nested with :outbound_attributes
+        # SmsOnRails::Draft.create_sms(params[:draft], params[:phone_numbers], :send_immediately => true
+        def create_sms(message, phone_numbers=nil, options={})
+
+          draft = create_draft(message)
+          draft.attributes = options[:draft] if options[:draft]
+          
+          # Update draft with any existing phone numbers
+          draft.outbounds.each {|o| o.assign_existing_phone } if draft.outbounds
+
+          # Generate new phone_numbers
+          draft.create_outbounds_for_phone_numbers(phone_numbers, options) if phone_numbers
+
+          if draft.send(options[:bang] ? :save! : :save) && options[:send_immediately]
+            if !draft.send(options[:bang] ? :deliver! : :deliver, options[:deliver])
+              # this is really crappy but when we are sending multiple messages
+              # locking has to actually create the object.
+              # so if we fail try to delete
+              # this could be terribly slow if there are a lot of outbounds
+              if options[:keep_failed_outbounds]
+                draft.outbounds.each{|o| o.update_attribute(:sms_draft_id, nil ) }
+              else
+                draft.outbounds.each{|o| o.destroy }
+                draft.outbounds = []
+              end
+            end
+          end
+          draft
+        end
+
+        def create_sms!(message, phone_numbers=nil, options={})
+          create_sms(message, phone_numbers, options.reverse_merge(:bang => true, :create => :create!))
+        end
+
+        # Create the draft object
+        # +options+ - A Draft object, a hash of attributes(can be nested) or a String with the draft message
+        def create_draft(options={})
+          if options.is_a?(ActiveRecord::Base)
+            options.dup
+          elsif options.is_a?(Hash)
+            new(options)
+          elsif options.is_a?(String)
+            new(:message => options)
+          end
+        end
+      end
+
+      module InstanceMethods
+
+        def initialize(args={})#:nodoc:
+          super args
+          default_headers_and_footers
+        end
+
+        def save_and_deliver(options={})
+          save and deliver(options)
+        end
+
+        def save_and_deliver!(options={})
+          save! and deliver!(options)
+        end
+
+        # The length of the message
+        # This does not take into consideration substituted params
+        # TODO: adjust max length for substituted params
+        def message_length; complete_message.length; end
+        def max_message_length; self.class.max_message_length; end
+
+        # default the headers and footers
+        def default_headers_and_footers
+          self.header ||= self.class.default_header
+          self.footer ||= self.class.default_footer
+        end
+
+        # The complete message with header and footer
+        def complete_message
+          complete_message = ""
+          complete_message << "#{header}\n" unless header.blank?
+          complete_message << message
+          complete_message << "\n#{footer}" unless footer.blank?
+          complete_message
+        end
+
+
+        # Deliver all the unsent outbound messages
+        # +error+ - set this option to add an error message to the draft object
+        #
+        # This is locked and safe for individual messages
+        # but the draft object itself is not locked down,
+        # so it can be processed by multiple threads
+        def deliver(options={})
+          options||={}
+          deliver_method = options.delete(:bang) ? :deliver! : :deliver
+
+          error_messages = outbounds.inject([]) do |error_messages, o|
+            next(error_messages) if o.delivered?
+            unless o.send(deliver_method, options)
+             error_messages << "Message could not be delivered to: #{o.phone_number.human_display}"
+            end
+            error_messages
+          end
+     
+          self.update_attribute(:status, error_messages.blank? ?  'PROCESSED' : 'FAILED')
+          error_messages.each { |msg| errors.add_to_base(msg) }
+          error_messages.blank?
+        end
+
+        # Deliver all outbound messages safely using optimisitic locking
+        # Progates any exception thrown
+        def deliver!(options={})
+          deliver((options||{}).merge(:bang => true))
+        end
+        
+        # Create Outbound Instances based on +phone_numbers+ and +options+
+        # Refer to SmsOnRails::ModelSupport::Outbound.create_outbounds_from_phone
+        def create_outbounds_for_phone_numbers(phone_numbers, options={})
+          self.outbounds = self.class.reflections[:outbounds].klass.create_outbounds_for_phone_numbers(phone_numbers, options)
+        end
+        
+        # if there is only one outbound message, return the actual (substituted)
+        # message. Otherwise, returns the draft message with substituted strings if any
+        def actual_message
+          self.outbounds.length == 1 ? outbounds.first.actual_message : message
+        end
+
+        protected
+
+        # validates the length of the message including the header and footer
+        def validates_message_length
+          errors.add(:message, "must be less than #{max_message_length} characters") unless message_length < max_message_length
+        end
+
+      end
+    end
+  end
+end

data/lib/sms_on_rails/model_support/outbound.rb

@@ -0,0 +1,136 @@
+module SmsOnRails
+  module ModelSupport
+    module Outbound
+
+      mattr_accessor :default_options
+      self.default_options = {}
+      
+      def self.included(base)
+
+        base.has_a_sms_service_provider
+
+        base.acts_as_deliverable :fatal_exception => SmsOnRails::FatalSmsError,
+                                 :error => 'Unable to send message.'
+
+
+        base.acts_as_substitutable :draft_message,
+                            :phone_number_digits  => :phone_number_digits,
+                            :phone_number  => Proc.new{|record| record.phone_number.human_display },
+                            :sender_name   => :sender_name
+
+        base.send :alias_method, :full_message,      :substituted_draft_message
+        base.send :alias_method, :send_immediately,  :deliver
+        base.send :alias_method, :send_immediately!, :deliver!
+
+        base.send :cattr_accessor, :default_options
+
+        base.send :accepts_nested_attributes_for, :phone_number
+        
+        base.send :include, InstanceMethods
+        base.send :extend,  ClassMethods
+      end
+
+      module ClassMethods
+        def send_immediately(message, phone_number, options={})
+          create_sms(message, phone_number, options.merge(:send_immediately => true))
+        end
+
+        def send_immediately!(message, phone_number, options={})
+          create_sms!(message, phone_number, options.merge(:send_immediately => true))
+        end
+
+        def create_sms(message, number, options={})
+          draft = reflections[:draft].klass.create_sms(message, number, options.reverse_merge(:keep_failed_outbounds => true))
+          number.is_a?(Array) ? draft.outbounds : draft.outbounds.first
+        end
+
+        def create_sms!(message, number, options={})
+          draft = reflections[:draft].klass.create_sms!(message, number, options)
+          number.is_a?(Array) ? draft.outbounds : draft.outbounds.first
+        end
+
+        def create_outbounds_for_phone_numbers(phone_numbers, options={})
+          smses = reflections[:phone_number].klass.find_and_create_all_by_numbers(phone_numbers, (options[:find]||{}).reverse_merge(:create => :new)).inject([]) do |smses, phone|
+            phone.attributes = options[:phone_number] if options[:phone_number]
+            phone.carrier = options[:carrier] if options[:carrier]
+            sms = self.new(options[:sms]||{})
+            sms.phone_number = phone
+            sms.service_provider = options[:service_provider] if options[:service_provider]
+            smses << sms
+            smses
+          end
+          smses
+        end
+
+        #Create the object find the existing phone if already stored
+        def create_with_phone(attributes, draft=nil)
+          outbound = new(attributes)
+          transaction {
+            outbound.assign_existing_phone
+            outbound.draft = draft
+            outbound.save
+          }
+          outbound
+        end
+
+      end #ClassMethods
+
+      module InstanceMethods
+
+        def phone_number_digits
+          self['phone_number_digits']||(phone_number ? phone_number.number : nil)
+        end
+
+        def phone_number_digits=(digits)
+          self.phone_number ||= SmsOnRails::PhoneNumber.new
+          self.phone_number.number = digits
+          assign_existing_phone
+          self.phone_number.number
+        end
+
+        def assign_phone_number(phone)
+          self.phone_number = SmsOnRails::PhoneNumber.find_and_create_by_number(phone)
+        end
+
+        def assign_existing_phone; assign_phone_number(self.phone_number); end
+
+        # The actual (not substituted draft message
+        # Substituted message can be obtained with +substituted_draft_message+
+        def draft_message; draft.complete_message if draft; end
+
+        def actual_message
+          read_attribute(:actual_message) || draft_message
+        end
+        
+        #only save the actual message if it differs from the draft message
+        def actual_message=(msg)
+          write_attribute(:actual_message, msg) unless substituted_draft_message == draft_message
+        end
+        
+        #Todo
+        def sender_name; ''; end
+
+        protected
+
+        # deliver_message is the actual call to the service provider to send the message
+        # this method is called during deliver in the acts_as_deliverable
+        def deliver_message(options)
+          self.sms_service_provider||= default_service_provider
+
+          # set the actual message if it differs; not a before_save to reduce the
+          # overhead of checking for all commits
+          self.actual_message = substituted_draft_message
+
+          result = (self.sms_service_provider).send_sms(self)
+          self.unique_id = result[:unique_id] if result.is_a?(Hash)
+       
+          result
+        end
+
+        def log_delivery_error(exc)
+          logger.error "SMS Delivery Error: #{self.phone_number.human_display if self.phone_number}: #{exc}"
+        end
+      end
+    end
+  end
+end

data/lib/sms_on_rails/model_support/phone_carrier.rb

@@ -0,0 +1,77 @@
+module SmsOnRails
+  module ModelSupport
+    module PhoneCarrier
+      def self.included(base)
+        base.send :validates_presence_of, :name
+        base.send :include, InstanceMethods
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+
+        # Returns the email address for sms
+        #
+        # * +phone+ - phone number digits or an SmsOnRails::PhoneCarrier
+        # * +carrier+ - the name, instance, or id of a carrier
+        #
+        #  SmsOnRails::PhoneCarrier.sms_email_address('12065551111', 1) => '2065551111@att.txt.net'
+        def sms_email_address(phone, carrier)
+          phone_carrier = carrier_by_value(carrier)
+          raise SmsOnRails::SmsError("Invalid carrier: #{carrier}") unless phone_carrier
+          phone_carrier.sms_email_address(phone)
+        end
+
+        # Retrurns the SmsOnRails::PhoneCarrier object
+        # +carrier+ can be
+        # * symbol name of the object (ex :verizon)
+        # * text name (Ex. 'Verizon')
+        # * SmsOnRails::PhoneCarrier instance returns self
+        # * the id number
+        def carrier_by_value(carrier)
+          phone_carrier = case carrier.class.to_s
+            when 'Symbol', 'String'   then find_by_name(carrier)
+            when "#{self.class.to_s}" then carrier
+            when 'Fixnum'             then find_by_id(carrier)
+            else nil
+          end
+        end
+
+        # Return the number text and carrier obj from an email string
+        # carrier_from_sms_email '12065551234@txt.att.net ' => [12065551234, <SmsOnRails::PhoneCarrier>]
+        def carrier_from_sms_email(address)
+
+          number = address
+          carrier = nil
+
+          if address.match(/^\s*(\d+)@(\S+)\s*$/)
+            number = match[1]
+            carrier_name = match[2]
+            carrier = find_by_email_domain(match[2]) if match[2]
+          end
+          
+          [number, carrier]
+        end
+      end
+      module InstanceMethods
+
+        # Returns the email address for sms
+        #
+        # * +phone+ - phone number digits or an SmsOnRails::PhoneNumber
+        # * +options+ - empty space now
+        #
+        #  att_carrier.sms_email_address('12065551111') => '2065551111@att.txt.net'
+        #
+        def sms_email_address(phone, options={})
+          email = (phone.is_a?(ActiveRecord::Base) ? phone.digits : phone).dup
+          email.gsub!(/^1/, '')
+          email << '@'
+          email << self.email_domain
+          email
+        end
+
+        # Return the carriers name when stringified
+        def to_s; name; end
+      end
+    end
+  end
+end

data/lib/sms_on_rails/model_support/phone_number.rb

@@ -0,0 +1,248 @@
+module SmsOnRails
+  module ModelSupport
+    module PhoneNumber
+      def self.included(base)
+        base.send :include,InstanceMethods
+        base.send :extend, ClassMethods
+        base.send :validates_format_of, :phone_number_digits, :with => /^\d{5,30}$/, :message => 'must be a number and have at least 5 digits'
+        base.before_save {|record| record.number = record.digits}
+        base.send :validates_presence_of, :number
+        base.send :attr_reader, :original_number
+        base.class_inheritable_accessor :valid_finder_create_options
+        base.valid_finder_create_options = %w(create keep_duplicates skip_sort)
+      end
+    end
+
+    module ClassMethods
+
+      # adds a sanitize search for numbers for the options
+      # used for finders
+      # Use with find for other ActiveRecord objects
+      #   Outbound.find :all, add_number_search([1,2,3], :conditions => 'outbounds.send_priority == 1')
+      def add_number_search(numbers, options={}, merge_options={})
+        number_digits = [numbers].flatten
+        number_digits.collect!{|n| digits(n) } unless merge_options[:skip_sanitize]
+        number_conditions = ['number in (?)', number_digits.uniq.compact]
+        options[:conditions] = merge_conditions(options[:conditions]||{}, number_conditions)
+        options
+      end
+
+      # Find all numbers (sanitized) that match a list of String +numbers+
+      def find_all_by_numbers(numbers, options={}, merge_options={})
+        return [] unless numbers.dup.delete_if{|x| x.blank? }.any?
+        find(:all, add_number_search(numbers, options, merge_options))
+      end
+
+      # Find a single number
+      def find_by_number(number, options={})
+        find_all_by_numbers([number], options).first;
+      end
+
+
+
+      # Find all numbers and create if it doesn't already exist
+      # +number_list+ - a list of numbers (String, ActiveRecord or attribute hash)
+      # +options+ - additional create options and normal finder options like <tt>:conditions</tt>
+      # === Additional Options
+      # <tt>:create</tt> - <tt>:new</tt>(Default), <tt>:create</tt>, or <tt>:create!</tt>
+      # If the number does not exist, create it with this method. Using <tt>:new</tt> means none of the objects are saved
+      # <tt>:keep_duplicates<tt> - When set to true, duplicates in the list are returned
+      # <tt>:skip_sort</tt> - Default is to sort the list to be in the same order as +number_list+.
+      # Set to false to skip sorting (perf boost). Instance creation or attribute update does not occur
+      # when <tt>skip_sort</tt> is false.
+      def find_and_create_all_by_numbers(number_list, options={})
+        create_options, finder_options = seperate_find_and_create_options(options)
+
+        # Collect a list of digits and a list of attributes
+        attribute_list = []
+        number_digits = [number_list].flatten.inject([]) do |list, n|
+          attribute_list << (new_attributes = value_to_hash(n))
+          digit = digits(new_attributes[:number]||new_attributes['number'])
+          digit = new_attributes[:number]||new_attributes['number'] if digit.blank?
+          list << digit
+          list
+        end
+
+        
+        found_numbers = find_all_by_numbers(number_digits, finder_options, :skip_sanitize => true)
+        # sort the list based on the order of the original input
+        # not found values have nil
+        if create_options[:skip_sort]
+          found_numbers
+        else
+          sorted_numbers = sort_by_numbers(found_numbers, number_digits, create_options)
+          transaction { update_attributes_on_list(sorted_numbers, attribute_list, create_options) }
+        end
+      end
+
+      # Find a number and create if it does not exist
+      # +options+ include those specified in find_all_and_create_by_number
+      def find_and_create_by_number(number, options={})
+        find_and_create_all_by_numbers(number, options.reverse_merge(:create => :new)).first
+      end
+
+
+      # Return the phone number with specified carrier if the phone number is an sms email address
+      def find_by_sms_email_address(address, options={})
+        number, carrier = reflections[:carrier].klass.carrier_from_sms_email(address)
+
+        if number
+          phone = find_by_number(number, options)||new(:number => number)
+          phone.carrier = carrier if carrier
+          phone
+        else
+          nil
+        end
+
+      end
+
+      # The digits (numbers) only of the phone number
+      # Digits are how phone numbers are stored in the database
+      # The following all return +12065555555+
+      #  SmsOnRails::digits(12065555555')
+      #  SmsOnRails::digits(206.555.5555')
+      #  SmsOnRails::digits(1206-555  5555')
+      def digits(text)
+        return text.digits if text.is_a?(self)
+        number = text.to_s.gsub(/\D/,'')
+        number = "1#{number}" if number.length == 10
+        number
+      end
+
+      # The human display pretty phone number
+      # (206) 555-5555
+      def human_display(number)
+        base_number = digits(number)
+        if base_number.length == 11 && base_number.first == '1'
+          "(#{base_number[1..3]}) #{base_number[4..6]}-#{base_number[7..10]}"
+        elsif base_number.length > 0
+          "+#{base_number}"
+        else
+          nil
+        end
+      end
+
+      protected
+            # Return create_options hash and finder options hash from all options
+      def seperate_find_and_create_options(options={})#:nodoc:
+
+        seperated_options = (options||{}).inject([{}, {}]) {|map, (k,v)|
+          if valid_finder_create_options.include?(k.to_s)
+            map.first[k.to_sym] = v
+          else
+            map.last[k.to_sym]  = v
+          end
+          map
+        }
+        seperated_options.first[:create] = :new if seperated_options.first[:create].is_a?(TrueClass)
+        seperated_options
+      end
+
+     # Convert a PhoneNumber, hash map or string number
+      # into an attribute hash
+      def value_to_hash(digits)#:nodoc:
+        attributes = if digits.is_a?(ActiveRecord::Base)
+          digits.attributes
+        elsif digits.is_a?(Hash)
+          digits.dup
+        elsif digits
+          {:number => digits}
+        end
+        attributes
+      end
+
+            # Return a sorted list of PhoneNumber instances
+      # Will create new records for missing records if attribute_list is specified
+      # +unsorted_list+ - unsorted list of PhoneNumbers
+      # +sorted_digits+ - sorted list of digits (Strings)
+      # +attribute_list+ - optional list of attributes in sorted order
+      # +creation_method+ - :create, :new, or :create!
+      def sort_by_numbers(unsorted_list, sorted_digits, options={})
+
+        unsorted_map = unsorted_list.inject({}) {|map, v| map[v.number] = v; map }
+
+        # First sort the list in the order of the sorted digits
+        # leaving nils for empty spaces
+        sorted_list = if sorted_digits.length > 1
+          sorted = [nil] * sorted_digits.length
+          sorted_digits.each_with_index{|n, idx|
+            sorted[idx] = unsorted_map[n]
+            unsorted_map[n] = :used unless options[:keep_duplicates]
+          }
+          
+          sorted.delete_if{|x| x == :used } unless options[:keep_duplicates]
+          sorted
+        else
+          unsorted_list.any? ?  unsorted_list.dup : [nil]
+        end
+        sorted_list
+      end
+
+      # create new records for any records not found
+      # update the attributes of the found records
+      # save if :create
+      def update_attributes_on_list(sorted_list, attribute_list, options={})
+      
+        unless attribute_list.blank?
+          0.upto(sorted_list.length - 1) {|idx|
+            if sorted_list[idx]
+              if (attr = attribute_list[idx].delete_if{|x, y| x.to_s == 'number'}).any?
+                sorted_list[idx].attributes = attr
+                sorted_list[idx].save  if options[:create]
+                sorted_list[idx].save! if options[:create!]
+              end
+            elsif options[:create]
+              sorted_list[idx] = self.send(options[:create], attribute_list[idx])
+            end
+          }
+        end
+        sorted_list
+      end
+
+    end
+
+    module InstanceMethods
+      # The human display pretty phone number
+      # (206) 555-5555
+      def human_display
+        self.class.human_display(self.number)
+      end
+
+      def number=(value)
+        @original_number = value unless value.blank?
+        @digits = self.class.digits(value)
+        write_attribute :number, @digits
+      end
+
+      def number
+        n = read_attribute :number
+        n.blank? ? original_number : n
+      end
+
+      def digits
+        @digits||=self.class.digits(self.number)
+      end
+
+      # return the sms email address from the carrier
+      def sms_email_address
+        carrier.sms_email_address(self) if carrier
+      end
+
+      #Assign the carrier to the phone number if it exists
+      #+carrier+ - can be a ActiveRecord object, a name of the carrier, or carrier id
+      def assign_carrier(carrier)
+        specified_carrier = self.class.reflections[:carrier].klass.carrier_by_value(carrier)
+        self.carrier = specified_carrier if specified_carrier
+      end
+      
+      alias_method  :phone_number_digits, :digits
+
+      # Returns true if the number is marked as do not send (not blank)
+      # Values could be abuse, bounce, opt-out, etc
+      def do_not_send?
+        !self.do_not_send.blank?
+      end
+      
+    end
+  end
+end