acts_as_subscription 0.0.1

data/lib/acts_as_subscription/backend.rb

@@ -0,0 +1,168 @@
+require 'acts_as_subscription/error'
+
+module ActsAsSubscription
+  module Subscription
+    
+    # Provides a consistent interface to the various recurring billing services.
+    # 
+    # There are three ways to initialize the backend :
+    # 1. Pass the parameters to the _acts_as_subscription_ method inside the model :
+    # 
+    #     class Subscription < ActiveRecord::Base
+    #       acts_as_subscription :backend      => :cheddar_getter,
+    #                            :user         => 'my_user',
+    #                            :password     => 'my_pass',
+    #                            :product_code => 'my_product'
+    #     end
+    #
+    # 2. Set the params in rails via <tt>config/initializers/acts_as_subscription.rb</tt> :
+    #
+    #     ActsAsSubscription::Subscription::Backend.config = {
+    #       :backend      => :cheddar_getter,
+    #       :user         => 'my_user',
+    #       :password     => 'my_pass',
+    #       :product_code => 'my_product'
+    #     }
+    #
+    # 3. Add a <tt>config/subscription.yml</tt> file to your rails project :
+    #
+    #     development:
+    #       backend:      'cheddar_getter'
+    #       user:         'my_user'
+    #       password:     'my_pass'
+    #       product_code: 'my_product'
+
+    module Backend
+      
+      # Stores the backend configuration data.
+      mattr_accessor :config
+      
+      # Stores an instance of the backend for a particular recurring billing service.
+      mattr_accessor :instance
+      
+      # Sets the configuration hash for the backend.
+      # 
+      # _args_ should be a hash containing the subscription backend account and product information :
+      # * <tt>backend</tt> : Name of the recurring billing service being used. Current choices are 
+      #   <tt>:chargify</tt>, <tt>:cheddar_getter</tt> and <tt>:recurly</tt>.
+      # * <tt>user</tt> : Username used to log into the billling service API.
+      # * <tt>password</tt> : Password used to log into the billling service API.
+      # * <tt>product_code</tt> : Code of your product on the backend service.
+      #
+      # If the backend configuration has already been set, _args_ will be merged with the current settings.
+      def self.config=(*args)
+        args = args.extract_options!
+        
+        if @@config
+          @@config = self.config.merge(args)
+        else
+          @@config = args
+        end
+      end
+      
+      # Validates the configuration options, and creates an instance of the requested <tt>:backend</tt>.
+      #
+      # _args_ should be a hash containing the subscription backend account and product information.
+      def self.initialize(*args)
+        # Don't do anything if the backend has already been loaded.
+        return if self.instance
+        
+        self.read_yaml_options
+        self.config = *args        
+        self.validate_options!
+        
+        # Make sure the backend is a valid class.
+        begin
+          require "acts_as_subscription/backend/#{self.config[:backend]}_client"
+          class_name    = "#{self.config[:backend].to_s}_client".camelize
+          klass         = ActsAsSubscription::Subscription::Backend.const_get(class_name)
+          self.instance = klass.new(self.config[:user], self.config[:password], self.config[:product_code])
+        rescue LoadError
+          raise ActsAsSubscription::Subscription::Error::BackendError.new("Backend '#{self.config[:backend]}' could not be found") 
+        rescue NameError
+          raise ActsAsSubscription::Subscription::Error::BackendError.new("Backend '#{self.config[:backend]}' does not appear to implement class '#{class_name}'") 
+        end
+      end
+      
+      # Creates a customer on the backend subscription service, using the settings from the given
+      # <tt>subscription</tt> instance.
+      #
+      # <tt>subscription</tt> should be a subclass of <tt>ActiveRecord::Base</tt> that implements
+      # <tt>acts_as_subscription</tt> :
+      #
+      #   class Subscription < ActiveRecord::Base
+      #     acts_as_subscription
+      #   end
+      #
+      # Returns true if the operation was successful, otherwise an error message.
+      def self.create_subscription(subscription)
+        self.instance.create_subscription(subscription)
+      end
+      
+      # Updates a customer on the backend subscription service, using the settings from the given
+      # <tt>subscription</tt> instance.
+      #
+      # <tt>subscription</tt> should be a subclass of <tt>ActiveRecord::Base</tt> that implements
+      # <tt>acts_as_subscription</tt> :
+      #
+      #   class Subscription < ActiveRecord::Base
+      #     acts_as_subscription
+      #   end
+      #
+      # Returns true if the update was successful, otherwise an error message.
+      def self.update_subscription(subscription)
+        self.instance.update_subscription(subscription)
+      end
+      
+      # Cancels the customer with the given <tt>customer_code</tt> on the backend subscription service.
+      #
+      # Returns true if the cancellation was successful, otherwise an error message.
+      def self.cancel_subscription!(customer_code)
+        self.instance.cancel_subscription!(customer_code)
+      end
+    
+      # Returns a list of subscription plans registered with the backend subscription service.
+      def self.plans
+        self.instance.plans
+      end
+      
+      
+      protected
+      
+      # Tries to read configuration options from the subscription.yml configuration file.
+      def self.read_yaml_options
+        # Try to get initial config from a YAML file if possible.
+        if Rails.root
+          config_path = File.join(Rails.root, 'config/subscription.yml')
+          if FileTest.exists?(config_path)
+            config = YAML::load(ERB.new(IO.read(config_path)).result)[Rails.env]
+            # Convert string keys to symbols.
+            config = config.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
+            self.config = config
+          end
+        end
+      end
+      
+      # Validates the configuration options, and makes sure all required parameters are present.
+      def self.validate_options!
+        unless self.config[:backend]
+          raise ActsAsSubscription::Subscription::Error::ArgumentError.new(':backend parameter must be provided') 
+        end
+        
+        unless self.config[:product_code]
+          raise ActsAsSubscription::Subscription::Error::ArgumentError.new(':product_code parameter must be provided') 
+        end
+        
+        unless self.config[:user]
+          raise ActsAsSubscription::Subscription::Error::ArgumentError.new(':user parameter must be provided') 
+        end
+        
+        unless self.config[:password]
+          raise ActsAsSubscription::Subscription::Error::ArgumentError.new(':password parameter must be provided') 
+        end
+        
+      end
+    end
+    
+  end
+end

data/lib/acts_as_subscription/error.rb

@@ -0,0 +1,15 @@
+module ActsAsSubscription
+  module Subscription
+    module Error # :nodoc:
+    
+      # Raised when invalid arguments are passed.
+      class ArgumentError < Exception
+      end
+  
+      # Raised if there is a problem with the backend configuration.
+      class BackendError < Exception
+      end
+  
+    end
+  end
+end

data/lib/acts_as_subscription/railtie.rb

@@ -0,0 +1,13 @@
+require 'rails'
+require 'acts_as_subscription'
+
+module ActsAsSubscription
+  class Railtie < Rails::Railtie # :nodoc:
+    initializer :'acts_as_subscription.hook' do
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.send(:include, ActsAsSubscription::Subscription)
+        ActiveRecord::Base.send(:include, ActsAsSubscription::SubscriptionPlan)
+      end
+    end
+  end
+end

data/lib/acts_as_subscription/subscription.rb

@@ -0,0 +1,258 @@
+require 'acts_as_subscription/backend'
+
+module ActsAsSubscription
+  module Subscription # :nodoc:
+    extend ActiveSupport::Concern
+    
+    # Class methods for an ActsAsSubscription::Subscription instance.
+    #
+    # Handles validation of all subscription-related information, such as :
+    #
+    # * customer_code 
+    # * email 
+    # * first_name 
+    # * last_name 
+    # * zip_code 
+    # * cc_expiration_month 
+    # * cc_expiration_year
+    # * cc_verification_value
+    # * cc_number
+    #
+    # These class methods should be included in ActiveRecord::Base to provide
+    # subscription validation support.
+    module ClassMethods
+      
+      # Main entry point - any subclass of ActiveRecord::Base can include the
+      # _acts_as_subscription_ method to activate subscription functionality.
+      # 
+      # _args_ should be a hash containing the subscription backend account and product information :
+      # * <tt>backend</tt> : Name of the recurring billing service being used. Current choices are 
+      #   <tt>:chargify</tt>, <tt>:cheddar_getter</tt> and <tt>:recurly</tt>.
+      # * <tt>user</tt> : Username used to log into the billling service API.
+      # * <tt>password</tt> : Password used to log into the billling service API.
+      # * <tt>product_code</tt> : Code of your product on the backend service.
+      # 
+      # There are three ways to initialize the backend :
+      # 1. Pass the parameters to the _acts_as_subscription_ method from within a model :
+      # 
+      #     class Subscription < ActiveRecord::Base
+      #       acts_as_subscription :backend      => :cheddar_getter,
+      #                            :user         => 'my_user',
+      #                            :password     => 'my_pass',
+      #                            :product_code => 'my_product'
+      #     end
+      #
+      # 2. Set the params directly via the Backend module :
+      #     ActsAsSubscription::Subscription::Backend.config = {
+      #       :backend      => :cheddar_getter,
+      #       :user         => 'my_user',
+      #       :password     => 'my_pass',
+      #       :product_code => 'my_product'
+      #     }
+      #
+      # 3. Add a <tt>config/subscription.yml</tt> file to your rails project :
+      #
+      #     development:
+      #       backend:      'cheddar_getter'
+      #       user:         'my_user'
+      #       password:     'my_pass'
+      #       product_code: 'my_product'
+      def acts_as_subscription(*args)
+        
+        ActsAsSubscription::Subscription::Backend.config = *args
+        ActsAsSubscription::Subscription::Backend.initialize
+        
+        validates :customer_code,
+          :presence => true
+        
+        validates :email,
+          :presence => true
+        
+        validates :first_name,
+          :presence => true
+
+        validates :last_name,
+          :presence => true
+
+        validates :plan_code,
+          :presence => true
+
+        validates :zip_code,
+          :presence => true,
+          :if       => :require_zip_code?
+    
+        validates :cc_expiration_month,
+          :presence => true,
+          :unless   => :is_free_plan? 
+    
+        validates :cc_expiration_year,
+          :presence => true,
+          :unless   => :is_free_plan? 
+    
+        validates :cc_verification_value,
+          :presence => true,
+          :if       => :require_verification_value? 
+    
+        validates :cc_number,
+          :presence => true,
+          :unless   => :is_free_plan? 
+  
+        validates_associated :credit_card,
+          :unless => :is_free_plan? 
+
+        before_validation :update_credit_card
+          
+        before_validation :assign_customer_code,    
+          :on => :create
+    
+        validate :validate_credit_card
+        
+        attr_accessible :cc_expiration_month,
+                        :cc_expiration_year,
+                        :cc_number,
+                        :cc_verification_value,
+                        :customer_code,
+                        :email,
+                        :first_name,
+                        :last_name,
+                        :plan_code,
+                        :zip_code
+        
+        # Removed this for the time being, since we often want to perform this before_save
+        # on a different model (such as User), if the forms are nested. Having before_save
+        # on both models causes quite a few problems. This before_save must be specified 
+        # by hand in the implementing model.
+        #before_save :backend_save
+        
+        self.send(:include, ActsAsSubscription::Subscription::SubscriptionInstanceMethods)
+        
+      end
+    end
+    
+    # Instance methods for an ActsAsSubscription::Subscription instance, which use ActiveMerchant 
+    # to validate credit card information.
+    #
+    # These instance methods should be included in ActiveRecord::Base to provide
+    # subscription validation support.
+    module SubscriptionInstanceMethods
+      
+      # Used as an interface to ActiveMerchant for credit card validation.
+      attr_reader   :credit_card
+      
+      # Allows entry of a complete credit card number, even though we only store the last 4 
+      # digits internally.
+      attr_accessor :cc_number
+      
+      # Returns true if the current plan is free, false otherwise.
+      def is_free_plan?
+        # If no plan-code is given, assume this is a paid plan to be on the safe side.
+        return false unless self.plan_code
+        
+        return (self.plan_code =~ /free/i) != nil
+      end
+      
+      # Instantiates an instance of ActiveMerchant::Billing::CreditCard if one hasn't already
+      # been created.
+      def credit_card
+        self[:credit_card] ||= instantiate_credit_card
+      end
+      
+      def backend_save
+        p "+++++++++++++++++++++++ saving +++++++++++++++++++++++"
+        if self.new_record?
+          result = ActsAsSubscription::Subscription::Backend.instance.create_subscription(self)
+        else
+          result = ActsAsSubscription::Subscription::Backend.instance.update_subscription(self)
+        end
+        
+        # No way of knowing what fields the errors are for for some backends - just add a top-level error.
+        unless result == true
+          self.errors.add :base, result
+          return false
+        end
+        
+        return true
+      end
+      
+      # This can be overridden in the implementing model, to turn off zip-code validation.
+      def require_zip_code?
+        return self.is_free_plan? == false
+      end
+      
+      # This can be overridden in the implementing model, to turn off verification-value validation.
+      def require_verification_value?
+        return self.is_free_plan? == false
+      end
+
+      protected
+      
+      # Assigns a unique UUID for the customer.
+      def assign_customer_code
+        self.customer_code ||= UUIDTools::UUID.random_create.to_s
+      end
+      
+      # Updates the ActiveMerchant::Billing::CreditCard instance with the information
+      # provided by the user, prior to validation.
+      def update_credit_card
+        self.credit_card.first_name         = self.first_name
+        self.credit_card.last_name          = self.last_name
+        self.credit_card.month              = self.cc_expiration_month
+        self.credit_card.year               = self.cc_expiration_year
+        self.credit_card.verification_value = self.cc_verification_value
+        self.credit_card.number             = self.cc_number
+        self.cc_last_digits                 = self.credit_card.last_digits
+      end
+      
+      # Creates an instance of ActiveMerchant::Billing::CreditCard, and adds a couple
+      # of utility methods to make it compatible with ActiveRecord.
+      def instantiate_credit_card(attributes = {})
+        ActiveMerchant::Billing::CreditCard.require_verification_value = require_verification_value?
+
+        credit_card = ActiveMerchant::Billing::CreditCard.new(attributes)
+
+        def credit_card.new_record?
+          true
+        end
+
+        def credit_card.persisted?
+          false
+        end
+
+        credit_card
+      end
+      
+      # Returns true if the credit card information provided is valid, or false otherwise.
+      def validate_credit_card
+        return if is_free_plan?
+        
+        unless credit_card.valid?
+          credit_card.errors.each do |field, messages|
+            messages.each do |message|
+              # Only add the error if one doesn't already exist - don't need to report
+              # 'credit card is invalid' etc if it is already blank.
+              errors.add("cc_#{field}".to_sym, message) unless errors["cc_#{field}".to_sym].length > 0
+            end
+          end
+        end
+      end
+      
+    end
+    
+  end
+end
+
+
+
+# Need to monkey-patch this since validation complains and errors that it is returning nil.
+module ActionView # :nodoc:
+  module Helpers # :nodoc:
+    module ActiveModelInstanceTag # :nodoc:
+      def error_message
+        # Original :
+        # object.errors[@method_name]
+        # Patched :
+        object.errors[@method_name] || []
+      end
+    end
+  end
+end

data/lib/acts_as_subscription/subscription_plan.rb

@@ -0,0 +1,93 @@
+require 'acts_as_subscription/backend'
+
+module ActsAsSubscription
+  module SubscriptionPlan # :nodoc:
+    extend ActiveSupport::Concern
+    
+    # Class methods for an ActsAsSubscription::SubscriptionPlan instance.
+    #
+    # Handles validation of all subscription_plan-related information, such as :
+    #
+    # * code 
+    # * name
+    # * description
+    # * price
+    #
+    # These class methods should be included in ActiveRecord::Base to provide
+    # subscription_plan validation support.
+    module ClassMethods
+      
+      # Main entry point - any subclass of ActiveRecord::Base can include the
+      # _acts_as_subscription_plan_ method to activate subscription_plan 
+      # functionality.
+      def acts_as_subscription_plan
+        
+        validates :code,
+          :presence   => true,
+          :uniqueness => {:case_sensitive => false}
+        
+        validates :name,
+          :presence => true
+        
+        validates :billing_frequency,
+          :presence => true
+        
+        validates :recurring_charge, 
+          :presence     => true,
+          :format       => { :with => /^\d+??(?:\.\d{0,2})?$/ }, 
+          :numericality => {:greater_than_or_equal_to => 0}
+        
+        attr_accessible :code,
+                        :name,
+                        :description,
+                        :billing_frequency,
+                        :recurring_charge,
+                        :active
+        
+        # Synchronizes the local SubscriptionPlan database with the remote backend. This method
+        # will try to update existing plans with new data if possible (based on the :code of
+        # the plan). 
+        #
+        # It will *NOT* however delete any plans locally that have been removed from
+        # the reote system. It is the responsibilty of the developer to remove local copies
+        # themselves if a plan is removed from the remote subscription backend. For safety
+        # it seems more sensible not to automate the removal of plans.
+        def self.sync!
+          plans = ActsAsSubscription::Subscription::Backend.plans
+          plans.each do |plan|
+            # Try to find an existing plan with this code.
+            existing = self.find_by_code(plan[:code])
+            
+            if existing
+              existing.update_attributes(plan)
+            else
+              existing = self.new(plan)
+            end
+            
+            existing.save
+          end
+        end
+        
+        # Returns an array of the current plans, suitable for using with a select 
+        # or radio input within a form. This is provided more as an example, and 
+        # should be over-ridden in your implementing class if you want to do
+        # currency formatting etc.
+        def form_options
+          plans  = self.find_all_by_active(true)
+          result = []
+          plans.each do |plan|
+            label = plan.name
+            if plan.recurring_charge > 0
+              label = "#{plan.name} ($#{plan.recurring_charge})"
+            end
+            result << [label, plan.code]
+          end
+          
+          return result
+        end
+                        
+      end
+    end
+    
+  end
+end

data/lib/acts_as_subscription.rb

@@ -0,0 +1,7 @@
+require File.join(File.dirname(__FILE__), 'acts_as_subscription/railtie.rb')
+
+module ActsAsSubscription # :nodoc:
+  autoload :Subscription,     File.join(File.dirname(__FILE__), 'acts_as_subscription/subscription')
+  autoload :SubscriptionPlan, File.join(File.dirname(__FILE__), 'acts_as_subscription/subscription_plan')
+end
+