saas 0.1

data/README.rdoc

@@ -0,0 +1,2 @@
+based on
+  $ script/plugin install git://github.com/linoj/saasramp.git

data/app/controllers/subscriptions_controller.rb

@@ -0,0 +1,84 @@
+class SubscriptionsController < ApplicationController
+  before_filter :login_required
+  before_filter :find_subscription
+
+  def show    
+  end  
+
+  def edit
+    # to change plans
+    @allowed_plans = @subscription.allowed_plans
+  end
+
+  def update
+    # find the plan
+    plan = SubscriptionPlan.find params[:subscription][:plan]
+    if plan.nil?
+      flash[:notice] = "Plan not available"
+      
+    # make sure its an allowed plan
+    elsif exceeded = @subscription.exceeds_plan?( plan ) 
+      flash[:notice] = "You cannot change to plan #{plan.name}. Resources exceeded"
+      flash[:notice] << ": #{exceeded.keys.join(', ')}" if exceeded.is_a?(Hash)
+      
+    # perform the change
+    # note, use #change_plan, dont just assign it
+    elsif @subscription.change_plan(plan)  
+      flash[:notice] = "Successfully changed plans. "
+      
+      # after change_plan, call renew
+      case result = @subscription.renew
+      when false
+        flash[:notice] << "An error occured trying to charge your credit card. Please update your card information."
+      when Money
+        flash[:notice] << "Thank you for your payment. Your credit card has been charged #{result.format}"
+      end
+      return redirect_to subscription_path(:current)
+    end
+    
+    # failed above for some reason
+    @allowed_plans = @subscription.allowed_plans
+    render :action => 'edit'
+  end
+
+  def cancel
+    @subscription.cancel
+    flash[:notice] = 'Your subscription has been canceled. You still have limited access to this site.'
+    redirect_to subscription_path(:current)
+  end
+
+  # could put these in separate controllers, but keeping it simple for now
+	def credit_card
+	  @profile = @subscription.profile
+	end
+	
+	def store_credit_card
+	  @subscription.profile.credit_card = params[:profile][:credit_card]
+	  @subscription.profile.request_ip = request.remote_ip
+	  if @subscription.profile.save
+	    #debugger
+	    case result = @subscription.renew
+      when false
+        flash[:notice] = "An error occured trying to charge your credit card. Please update your card information."
+      when Money
+	      flash[:notice] = "Thank you for your payment. Your credit card has been charged #{result.format}"
+      else
+	      flash[:notice] = "Credit card info successfully updated. No charges have been made at this time."  
+      end
+	    return redirect_to subscription_path(:current)
+    else
+	    @profile = @subscription.profile
+      render :action => 'credit_card'
+    end
+	end
+	
+	def history
+	  @transactions = @subscription.transactions
+	end
+	
+  private
+
+  def find_subscription
+    @subscription = current_user.subscription
+  end
+end

data/app/models/subscription.rb

@@ -0,0 +1,332 @@
+class Subscription < ActiveRecord::Base
+  
+  belongs_to :subscriber, :polymorphic => true  
+  belongs_to :plan,         :class_name => 'SubscriptionPlan'
+  has_one    :profile,      :class_name => 'SubscriptionProfile', :dependent => :destroy  
+  has_many   :transactions, :class_name => 'SubscriptionTransaction', :dependent => :destroy, :order => 'id DESC' #created_at is in seconds not microseconds?! so assume higher id's are newer
+  composed_of :balance, :class_name => 'Money', :mapping => [ %w(balance_cents cents) ], :allow_nil => true
+  
+  before_validation :initialize_defaults
+  after_create      :initialize_state_from_plan
+  # if you destroy a subscription all transaction history is lost so you may not really want to do that
+  before_destroy    :cancel
+
+  attr_accessor :current_password
+
+  attr_accessible # none
+  
+  # ------------
+  # states: :pending, :free, :trial, :active, :past_due, :expired
+  state_machine :state, :initial => :pending do 
+    # set next renewal date when entering a state
+    before_transition any => :free,     :do => :setup_free
+    before_transition any => :trial,    :do => :setup_trial
+    before_transition any => :active,   :do => :setup_active
+    after_transition any => :expired, :do => :setup_expired
+    
+    # always reset warning level when entering a different state
+    before_transition any => [any - same] do |sub| sub.warning_level = nil; end
+    
+    # for simpicity, event names are the same as the state
+    event :free do
+      transition any => :free
+    end
+    event :trial do
+      transition [:pending, :free] => :trial
+    end
+    event :active do
+      transition any => :active
+    end
+    event :past_due do
+      from = any - [:expired]
+      transition from => :past_due, :if => Proc.new {|s| s.due? }
+    end
+    event :expired do
+      transition any => :expired
+    end
+    
+  end
+    
+  def setup_free
+    self.next_renewal_on = nil 
+  end
+  
+  def setup_trial
+    start = Time.zone.today
+    self.next_renewal_on = start + SubscriptionConfig.trial_period.days
+  end
+  
+  def setup_active
+    # next renewal is from when subscription ran out (to change this behavior, set next_renewal to nil before doing renew)
+    start = next_renewal_on || Time.zone.today
+    self.next_renewal_on = start + plan.interval.months
+  end
+
+  def setup_expired
+    change_plan SubscriptionPlan.expired_plan
+  end
+  
+  # returns nil if not past due, false for failed, true for success, or amount charged for success when card was charged
+  def renew
+    # make sure it's time
+    return nil unless due?
+    transaction do # makes this atomic
+      #debugger
+      # adjust current balance (except for re-tries)
+      self.balance += plan.rate unless past_due?
+      
+      # charge the amount due
+      case charge = charge_balance
+        # transaction failed: past due and return false
+        when false then
+          Rails.logger.debug 'transaction failed: past due and return false'   
+          past_due && false
+        # not charged, subtracted from current balance: update renewal and return true
+        when nil then
+          Rails.logger.debug 'not charged, subtracted from current balance: update renewal and return true'
+          active && true
+        # card was charged: update renewal and return amount
+        else
+          Rails.logger.debug 'card was charged: update renewal and return amount'
+          active && charge
+      end
+    end
+  end
+  
+  # cancelling can mean revert to a free plan and credit back their card
+  # if it also means destroying or disabling the user account, that happens elsewhere in your app 
+  # returns same results as change_plan (nil, false, true)
+  def cancel
+    change_plan SubscriptionPlan.default_plan
+    # uncomment if you want to refund unused value to their credit card, otherwise it just says on balance here
+    #credit_balance
+  end
+   
+  # ------------
+  # changing the subscription plan
+  # usage: e.g in a SubscriptionsController
+  # if !@subscription.exceeds_plan?( plan )  &&  @subscription.change_plan( plan )
+  #   @subscription.renew
+  # end
+  
+  # the #change_plan method sets the new current plan, 
+  # prorates unused service from previous billing
+  # billing cycle for the new plan starts today
+  # if was in trial, stays in trial until the trial period runs out
+  # note, you should call #renew right after this
+  
+  # returns nil if no change, false if failed, or true on success
+  
+  def change_plan( new_plan )
+    # not change?
+    return if plan == new_plan
+    
+    # return unused prepaid value on current plan
+    self.balance -= plan.prorated_value( days_remaining ) if SubscriptionConfig.return_unused_balance && active?
+    # or they owe the used (although unpaid) value on current plan [comment out if you want to be more forgiving]
+    self.balance -= plan.rate - plan.prorated_value( past_due_days ) if past_due?
+    
+    # update the plan
+    self.plan = new_plan
+    
+    # update the state and initialize the renewal date
+    if plan.free?
+      self.free
+      
+    elsif (e = trial_ends_on)
+      self.trial
+      self.next_renewal_on = e #reset end date
+    
+    else #active or past due
+      # note, past due grace period resets like active ones due today, ok?
+      self.active
+      self.next_renewal_on = Time.zone.today
+      self.warning_level = nil
+    end
+    # past_due and expired fall through till next renew
+    
+    # save changes so far
+    save
+  end
+  
+  # list of plans this subscriber is allowed to choose
+  # use the subscription_plan_check callback in subscriber model
+  def allowed_plans
+    SubscriptionPlan.all.collect {|plan| plan unless exceeds_plan?(plan) }.compact
+  end
+  
+  # test if subscriber can use a plan, returns true or false
+  def exceeds_plan?( plan = self.plan)
+    !(plan_check(plan).blank?)
+  end
+  
+  # check if subscriber can use a plan and returns list of attributes exceeded, or blank for ok
+  def plan_check( plan = self.plan)
+    subscriber.subscription_plan_check(plan)       
+  end  
+  
+  # -------------
+  # charge the current balance against the subscribers credit card  
+  # return amount charged on success, false for failure, nil for nothing happened
+  def charge_balance
+    #debugger
+    # nothing to charge? (0 or a credit)
+    return if balance_cents <= 0
+    # no cc on fle
+    return false if profile.no_info? || profile.profile_key.nil?
+
+    transaction do # makes this atomic
+      #debugger
+      # charge the card
+      tx  = SubscriptionTransaction.charge( balance, profile.profile_key )
+      # save the transaction
+      transactions.push( tx )
+      # set profile state and reset balance
+      if tx.success
+        self.update_attribute :balance_cents, 0
+        profile.authorized
+      else
+        profile.error
+      end
+      tx.success && tx.amount
+    end
+  end
+
+  # -------------
+  # charge the current balance
+  # return amount charged on success, nil for nothing happened
+  def manual_charge_balance
+    #debugger
+    # nothing to charge? (0 or a credit)
+    return if balance_cents <= 0
+
+    transaction do # makes this atomic
+      #debugger
+      # charge the card
+      tx  = SubscriptionTransaction.new(:success => true, :message => 'Successfull', :action => 'Manual Charge', :amount_cents => balance_cents)
+      # save the transaction
+      transactions.push( tx )
+      self.update_attribute :balance_cents, 0
+      self.active
+      tx.success && tx.amount
+    end
+  end
+
+  # credit a negative balance to the subscribers credit card
+  # returns amount credited on success, false for failure, nil for nothing 
+  def credit_balance
+    #debugger
+    # nothing to credit?
+    return if balance_cents >= 0
+    # no cc on fle
+    return false if profile.no_info? || profile.profile_key.nil?
+
+    transaction do # makes this atomic
+      #debugger
+      # credit the card
+      tx  = SubscriptionTransaction.credit( -balance_cents, profile.profile_key, :subscription => self )
+      # save the transaction
+      transactions.push( tx )
+      # set profile state and reset balance
+      if tx.success
+        self.update_attribute :balance_cents, 0
+        profile.authorized
+      else
+        profile.error
+      end
+      tx.success && tx.amount
+    end
+  end
+
+  # -------------
+  # true if account is due today or before
+  def due?( days_from_now = 0)
+    days_remaining && (days_remaining <= days_from_now)
+  end
+  
+  # date trial ends, or nil if not eligable
+  def trial_ends_on
+    # no trials?
+    return if SubscriptionConfig.trial_period.to_i==0
+    case 
+      # in trial, days remaining
+      when trial?     then    next_renewal_on
+      # new record? would start from today
+      when plan.nil?  then    Time.zone.today + SubscriptionConfig.trial_period.days
+      # start or continue a trial? prorate since creation
+      #when active?    :
+    else
+          d = created_at.to_date + SubscriptionConfig.trial_period.days
+                           d unless d <= Time.zone.today
+      # else nil not eligable
+    end
+  end
+  
+  # number of days until next renewal
+  def days_remaining
+    (next_renewal_on - Time.zone.today) unless next_renewal_on.nil?
+  end
+  
+  # number of days account is past due (negative of days_remaining)
+  def past_due_days
+    (Time.zone.today - next_renewal_on) unless next_renewal_on.nil?
+  end
+  
+  # number of days until account expires
+  def grace_days_remaining
+    (next_renewal_on + SubscriptionConfig.grace_period.days - Time.zone.today) if past_due?
+  end
+  
+  # most recent transaction
+  def latest_transaction
+    transactions.first
+  end
+  
+  # ------------
+  # named scopes
+  # used in daily rake task
+  # note, 'due' scopes find up to and including the specified day
+  scope :due_now, lambda {
+    { :conditions => ["next_renewal_on <= ?", Time.zone.today] }
+  }
+  scope :due_on, lambda {|date|
+    { :conditions => ["next_renewal_on <= ?", date] }
+  }
+  scope :due_in, lambda {|days|
+    { :conditions => ["next_renewal_on <= ?", Time.zone.today + days] }
+  }
+  scope :due_ago, lambda {|days|
+    { :conditions => ["next_renewal_on <= ?", Time.zone.today - days] }
+  }
+  
+  scope :with_no_warnings, lambda {
+    { :conditions => { :warning_level => nil } }
+  }
+  scope :with_warning_level, lambda {|level|
+    { :conditions => { :warning_level => level } }
+  }
+  
+  # -----------
+  protected
+  
+  def initialize_defaults
+    # default plan
+    self.plan ||= SubscriptionPlan.default_plan
+    # bug fix: when aasm sometimes doesnt initialize
+    self.state ||= 'pending'
+  end
+  
+  def initialize_state_from_plan
+    # build profile if not present
+    self.create_profile if profile.nil?
+    # initialize the state (and renewal date) [doing this after create since aasm saves]
+    if plan.free?
+      self.free
+    elsif SubscriptionConfig.trial_period > 0
+      self.trial
+    else
+      self.active
+    end
+  end
+  
+end

data/app/models/subscription_config.rb

@@ -0,0 +1,30 @@
+class SubscriptionConfig  
+  def self.load
+    config_file = File.join(Rails.root, "config", "subscription.yml")
+
+    if File.exists?(config_file)
+      text = ERB.new(File.read(config_file)).result
+      hash = YAML.load(text)
+      config = hash.stringify_keys[ ENV['RAILS_ENV'] || Rails.env]
+      config.keys.each do |key|
+        cattr_accessor key
+        send("#{key}=", config[key])
+      end
+    end
+  end
+  
+  # this is initialized to an instance of ActiveMerchant::Billing::Base.gateway
+  cattr_accessor :gateway
+  
+  def self.bogus?
+    gateway.is_a? ActiveMerchant::Billing::BogusGateway
+  end
+  
+  def self.mailer
+    @mailer ||= mailer_class.constantize rescue SubscriptionMailer
+  end
+  
+end
+
+# load configuration settings
+SubscriptionConfig.load

data/app/models/subscription_mailer.rb

@@ -0,0 +1,54 @@
+class SubscriptionMailer < ActionMailer::Base
+  self.prepend_view_path File.dirname(__FILE__)
+    
+  def trial_expiring(subscription)
+    setup_email(subscription)
+    @subject += "Your trial is ending soon"
+  end
+  
+  def charge_success(subscription, transaction)
+    setup_email(subscription, transaction)
+    @subject += "Service invoice"
+  end
+  
+  def charge_failure(subscription, transaction)
+    setup_email(subscription, transaction)
+    @subject += "Billing error" 
+  end      
+  
+  def second_charge_failure(subscription, transaction)
+    setup_email(subscription, transaction)
+    @subject += "Second notice: Your subscription is set to expire"
+  end
+  
+  def credit_success(subscription, transaction)
+    setup_email(subscription, transaction)
+    @subject += "Credit"
+  end
+  
+  def subscription_expired(subscription)
+    setup_email(subscription)
+    @subject += "Your subscription has expired"
+  end
+  
+  # def admin_report(admin, activity_log)
+  #   @subject    = "Example app: Subscription admin report"
+  #   @recipients = admin
+  #   @from       = "billing@example.com"
+  #   @sent_on    = Time.now
+  #   @body[:log] = activity_log
+  # end
+  
+  protected
+  
+  def setup_email(subscription, transaction=nil)
+    @recipients          = subscription.subscriber.email
+    @from                = "billing@example.com"
+    @subject             = "Example app: "
+    @sent_on             = Time.now
+    @body[:transaction]  = transaction
+    @body[:subscription] = subscription
+    @body[:user]         = subscription.subscriber
+    @bcc                 = SubscriptionConfig.admin_report_recipients if SubscriptionConfig.admin_report_recipients
+  end
+end

data/app/models/subscription_observer.rb

@@ -0,0 +1,40 @@
+# use this observer to send out email notifications when transactions are saved
+# unclutters the models and ensures users get notified whenever their credit card is accessed
+# tracks warning levels so the same message isnt duplicated, 
+# and handles when subscription is expired (move that out of here? but we did try to charge the card one last time)
+# Install in environment.rb config.active_record.observers = :subscription_observer
+
+class SubscriptionObserver < ActiveRecord::Observer
+  observe :subscription_transaction
+  
+  def after_save(transaction)
+    sub = transaction.subscription
+    case transaction.action
+    when 'charge'
+      if transaction.success?
+        SubscriptionConfig.mailer.deliver_charge_success(sub, transaction)
+      else 
+        sub.increment!(:warning_level)
+        case sub.warning_level
+        when 1
+          SubscriptionConfig.mailer.deliver_charge_failure(sub, transaction)
+        when 2
+          SubscriptionConfig.mailer.deliver_second_charge_failure(sub, transaction)
+        else
+          # expired: do in the app whatever it means to become expired
+          # send no mail here
+        end
+      end
+      
+    when 'credit', 'refund'
+      if transaction.success?
+        SubscriptionConfig.mailer.deliver_credit_success(sub, transaction)
+      end
+      # else no email
+      
+    else # 'validate', 'store', 'update', 'unstore'
+      # send no email
+    end
+  end
+  
+end

data/app/models/subscription_plan.rb

@@ -0,0 +1,36 @@
+class SubscriptionPlan < ActiveRecord::Base
+  has_many :subscriptions
+  
+  composed_of :rate, :class_name => 'Money', :mapping => [ %w(rate_cents cents) ]
+
+  validates_presence_of :name
+  validates_uniqueness_of :name
+  validates_presence_of :rate_cents  
+  validates_numericality_of :interval # in months
+  
+  def free?
+    rate.zero?
+  end
+  
+  def prorated_value( days )
+    days ||= 0 # just in case called with nil
+    # this calculation is a little off, we're going to assume 30 days/month rather than varying it month to month
+    total_days = interval * 30
+    daily_rate = rate_cents.to_f / total_days
+    # round down to penny
+    Money.new( (days * daily_rate).to_i )
+  end
+  
+  # ---------------
+  
+  def self.default_plan
+    default_plan = SubscriptionPlan.find_by_name(SubscriptionConfig.default_plan) if SubscriptionConfig.respond_to? :default_plan
+    default_plan ||= SubscriptionPlan.first( :conditions => { :rate_cents => 0 })
+    default_plan ||= SubscriptionPlan.create( :name => 'free' ) #bootstrapper and tests
+  end
+
+  def self.expired_plan
+    expired_plan = SubscriptionPlan.find_by_name(SubscriptionConfig.expired_plan) if SubscriptionConfig.respond_to? :expired_plan
+    expired_plan ||= default_plan
+  end
+end

data/app/models/subscription_profile.rb

@@ -0,0 +1,182 @@
+class SubscriptionProfile < ActiveRecord::Base  
+  belongs_to            :subscription 
+  #validates_presence_of :subscription_id   
+  
+  attr_accessor       :request_ip, :credit_card
+  validate            :validate_card  
+  before_save         :store_card
+  before_destroy      :unstore_card
+  
+  attr_accessible # none
+  
+  # ------------
+  state_machine :state, :initial => :no_info do
+    before_transition any => :no_info,   :do => :unstore_card
+
+    event :authorized do 
+      transition any => :authorized
+    end
+    event :error do
+      transition any => :error
+    end
+    event :remove do
+      from = any - [:no_info]
+      transition from => :no_info
+    end
+  end
+  
+  # ------------
+  # behave like it's 
+  #   has_one :credit_card 
+  #   accepts_nested_attributes_for :credit_card
+   
+  def credit_card=( card_or_params )
+    @credit_card = case card_or_params
+      when ActiveMerchant::Billing::CreditCard, nil
+        card_or_params
+      else
+        ActiveMerchant::Billing::CreditCard.new(card_or_params)
+      end
+  end
+  
+  def new_credit_card
+    # populate new card with some saved values
+    ActiveMerchant::Billing::CreditCard.new(
+      :first_name  => card_first_name,
+      :last_name   => card_last_name,
+      # :address etc too if we have it
+      :type        => card_type
+    )
+  end
+  
+  # -------------
+  # move this into a test helper...
+  def self.example_credit_card_params( params = {})
+    default = { 
+      :first_name         => 'First Name', 
+      :last_name          => 'Last Name', 
+      :type               => 'visa',
+      :number             => '4111111111111111', 
+      :month              => '10', 
+      :year               => '2012', 
+      :verification_value => '999' 
+    }.merge( params )
+    
+    specific = case SubscriptionConfig.gateway_name
+      when 'authorize_net_cim'
+        { 
+          :type               => 'visa',
+          :number             => '4007000000027', 
+        }
+        # 370000000000002 American Express Test Card
+        # 6011000000000012 Discover Test Card
+        # 4007000000027 Visa Test Card
+        # 4012888818888 second Visa Test Card
+        # 3088000000000017 JCB 
+        # 38000000000006 Diners Club/ Carte Blanche
+        
+      when 'bogus'
+        { 
+          :type               => 'bogus',
+          :number             => '1', 
+        }   
+        
+      else
+        {}     
+      end
+      
+    default.merge(specific).merge(params)
+  end
+
+  def unstore_card
+    return if no_info? || profile_key.nil?
+    transaction do # atomic
+      tx  = SubscriptionTransaction.unstore( profile_key )
+      subscription.transactions.push( tx )
+      if tx.success?
+        # clear everything in case this is ever called without destroy
+        self.profile_key         = nil
+        self.card_first_name     = nil
+        self.card_last_name      = nil
+        self.card_type           = nil
+        self.card_display_number = nil
+        self.card_expires_on     = nil
+        self.credit_card         = nil
+       # change profile state
+        self.state               = 'no_info' # can't call no_info! here, it saves
+      else
+        #errors.add(:credit_card, "failed to #{tx.action} card: #{tx.message}")
+        errors.add_to_base "Failed to #{tx.action} card: #{tx.message}"
+      end
+      tx.success
+    end
+  end
+
+  # -------------
+  private
+  
+  # validate :validate_card
+  def validate_card
+    #debugger
+    return if credit_card.nil?
+    # first validate via ActiveMerchant local code
+    unless credit_card.valid?
+      # collect credit card error messages into the profile object
+      #errors.add(:credit_card, "must be valid") 
+      credit_card.errors.full_messages.each do |message|
+        errors.add_to_base message
+      end
+      return
+    end
+    
+    if SubscriptionConfig.validate_via_transaction
+      transaction do # makes this atomic
+        tx = SubscriptionTransaction.validate_card( credit_card )
+        subscription.transactions.push( tx )
+        if ! tx.success?
+          #errors.add(:credit_card, "failed to #{tx.action} card: #{tx.message}")
+          errors.add_to_base "Failed to #{tx.action} card: #{tx.message}"
+          return
+        end
+      end
+    end
+    true
+  end
+  
+  def store_card
+    #debugger
+    return unless credit_card && credit_card.valid?
+    
+    transaction do # makes this atomic
+      if profile_key
+        tx  = SubscriptionTransaction.update( profile_key, credit_card)
+      else
+        tx  = SubscriptionTransaction.store(credit_card)
+      end
+      subscription.transactions.push( tx )    
+      if tx.success?
+        # remember the token/key/billing id (whatever)
+        self.profile_key = tx.token
+    
+        # remember some non-secure params for convenience
+        self.card_first_name     = credit_card.first_name
+        self.card_last_name      = credit_card.last_name
+        self.card_type           = credit_card.type
+        self.card_display_number = credit_card.display_number
+        self.card_expires_on     = credit_card.expiry_date.expiration.to_date
+    
+        # clear the card in memory
+        self.credit_card = nil
+    
+        # change profile state
+        self.state = 'authorized' # can't call authorized! here, it saves
+        
+      else # ! tx.success
+        #errors.add(:credit_card, "failed to #{tx.action} card: #{tx.message}")
+        errors.add_to_base "Failed to #{tx.action} card: #{tx.message}"
+      end
+      
+      tx.success
+    end
+  end
+end

data/app/models/subscription_transaction.rb

@@ -0,0 +1,150 @@
+# SubscriptionTransaction encapsulates the ActiveMerchant gateway methods
+# providing a consistent api for the rest of the SaasRamp plugin
+
+class SubscriptionTransaction < ActiveRecord::Base
+  belongs_to  :subscription
+  serialize   :params
+  composed_of :amount, :class_name => 'Money', :mapping => [ %w(amount_cents cents) ], :allow_nil => true
+  attr_accessor :token
+  
+  # find recent 'charge' transactions that are greater or equal to amount
+  scope :charges_at_least, lambda {|amount|
+    { :conditions => ["action = ? AND amount_cents >= ?", 'charge', amount.cents],
+      :order => "created_at DESC" }
+  }
+  
+  class << self
+    # note, according to peepcode pdf, many gateways require a unique order_id on each transaction
+    
+    # validate card via transaction
+    def validate_card( credit_card, options ={})
+      options[:order_id] ||= unique_order_number
+      # authorize $1
+      amount = 100
+      result = process( 'validate', amount ) do |gw|
+        gw.authorize( amount, credit_card, options )
+      end
+      if result.success?
+        # void it
+        result = process( 'validate' ) do |gw|
+          gw.void( result.reference, options )
+        end
+      end
+      result
+    end
+    
+    def store( credit_card, options = {})
+      options[:order_id] ||= unique_order_number
+      process( 'store' ) do |gw|
+        gw.store( credit_card, options )
+      end
+    end
+
+    def update( profile_key, credit_card, options = {})
+      options[:order_id] ||= unique_order_number
+      # some gateways can update, otherwise unstore/store it
+      # thus, always capture the profile key in case it changed
+      if SubscriptionConfig.gateway.respond_to?(:update)
+        process( 'update' ) do |gw|
+          gw.update( profile_key, credit_card, options )
+        end
+      else
+        process( 'update' ) do |gw|
+          gw.unstore( profile_key, options )
+          gw.store( credit_card, options )
+        end
+      end
+    end
+
+    def unstore( profile_key, options = {})
+      options[:order_id] ||= unique_order_number
+      process( 'unstore' ) do |gw|
+        gw.unstore( profile_key, options )
+      end
+    end
+
+
+    def charge( amount, profile_key, options ={})
+      options[:order_id] ||= unique_order_number
+      if SubscriptionConfig.gateway.respond_to?(:purchase)
+        process( 'charge', amount ) do |gw|
+          gw.purchase( amount, profile_key, options )
+        end        
+      else
+        # do it in 2 transactions
+        process( 'charge', amount ) do |gw|
+          result = gw.authorize( amount, profile_key, options )
+          if result.success?
+            gw.capture( amount, result.reference, options )
+          else
+            result
+          end
+        end
+      end
+    end
+    
+    # credit will charge back to the credit card
+    # some gateways support doing arbitrary credits, others require a transaction id, 
+    # we encapsulate this difference here, looking for a recent successful charge if necessary
+    # Note, refund expects the subscription object to be passed in options so it can find a recent charge
+
+    # Note, when using refund (vs credit), the gateway needs time to process the purchase before we can refund against it
+    # for example according to Authorize.net support, thats about every 10 minute in their test environment
+    # in production they "only settle once a day after the merchant defined Transaction Cut Off Time."
+    # so if the credit fails (and transaction was "refund") the app should tell the user to try again in a day (?!)
+    
+    def credit( amount, profile_key, options = {})
+      #debugger
+      options[:order_id] ||= unique_order_number
+      if SubscriptionConfig.gateway.respond_to?(:credit)
+        process( 'credit', amount) do |gw|
+          gw.credit( amount, profile_key, options )
+        end
+      else
+        # need to refund against a previous charge (by this subscriber!)
+        subscription = options[:subscription]
+        tx = subscription.transactions.charges_at_least( amount ).first
+        if tx
+          process( 'refund', amount ) do |gw|
+            # note, syntax follows void 
+            gw.refund( tx.reference, options.merge(:amount => amount) )
+          end
+        end
+      end
+    end
+
+    private
+    
+    def process( action, amount = nil)
+      #debugger
+      result = SubscriptionTransaction.new
+      result.amount_cents = amount.is_a?(Money) ? amount.cents : amount
+      #result.amount       = amount
+      result.action       = action
+      begin 
+        response = yield SubscriptionConfig.gateway 
+
+        result.success   = response.success? 
+        result.reference = response.authorization 
+        result.token     = response.token
+        result.message   = response.message 
+        result.params    = response.params 
+        result.test      = response.test? 
+      rescue ActiveMerchant::ActiveMerchantError => e 
+        result.success   = false 
+        result.reference = nil 
+        result.message   = e.message 
+        result.params    = {} 
+        result.test      = SubscriptionConfig.gateway.test? 
+      end 
+      # TODO: LOGGING
+      result 
+    end 
+    
+    # maybe should make this a callback option to acts_as_subscriber
+    def unique_order_number
+      # "#{Time.now.to_i}-#{rand(1_000_000)}"
+      ActiveMerchant::Utils::generate_unique_id
+    end
+  end
+end

data/app/views/subscription_mailer/admin_report.html.erb

@@ -0,0 +1,4 @@
+<% @log.each do |subscription, events| %>
+subscription #<%= subscription.id %> (customer key <%= subscription.profile_key %>)
+<%= events.collect{|e| "- #{e.to_s}"}.join("\n") %>
+<% end %>

data/app/views/subscription_mailer/charge_failure.html.erb

@@ -0,0 +1,5 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+We were unable to process your payment, and your subscription is set to expire in <%= pluralize @subscription.grace_days_remaining, 'day' %>. If your card information need updating, please do so. 
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscription_mailer/charge_success.html.erb

@@ -0,0 +1,13 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+This email is to let you know we charged your credit card.
+
+  Your Plan: <%= @subscription.plan.name %> (<%= @subscription.plan.rate %> per <%= @subscription.plan.interval==1 ? "month" : pluralize( @subscription.plan.interval, "month") %>)
+  Paid: <%= @transaction.amount.format %>
+  Paid Through: <%= @subscription.next_renewal_on %>
+  Card number: <%= @subscription.profile.card_display_number %>
+  Date: <%= @transaction.created_at.to_date %>
+
+Thank you!
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscription_mailer/credit_success.html.erb

@@ -0,0 +1,11 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+This email is to let you know we have credited your credit card.
+
+  Card number: <%= @subscription.profile.card_display_number %>
+  Refund: <%= @transaction.amount.format %>
+  Date: <%= @transaction.created_at.to_date %>
+
+Thank you!
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscription_mailer/second_charge_failure.html.erb

@@ -0,0 +1,5 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+We were unable to process your payment, and your subscription is set to expire in <%= pluralize @subscription.grace_days_remaining, 'day' %>. If your card information need updating, please do so.
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscription_mailer/subscription_expired.html.erb

@@ -0,0 +1,5 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+Your subscription has expired. 
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscription_mailer/trial_expiring.html.erb

@@ -0,0 +1,17 @@
+<%#= render :partial => "/shared/email_header", :locals => {:user => @user} %>
+
+Just to let you know, your trial is expiring soon. We hope you are pleased with our service.
+
+<% if @subscription.profile.authorized? %>
+If you want to continue the service, you don't need to do anything, 
+you'll be automatically billed.
+
+If, however, you want to discontinue the service, please cancel it before that time. 
+Otherwise you'll be charged and begin your paid subscription.
+<% else %>
+We do not presently have an authorized credit card on file. Please log in and update your credit card information.
+
+If, however, you want to discontinue the service, please log in and cancel your subscription to avoid further email warnings.
+<% end %>
+
+<%#= render :partial => "/shared/email_footer" %>

data/app/views/subscriptions/credit_card.html.erb

@@ -0,0 +1,33 @@
+<h1>Credit Card</h1>
+
+<% form_for :profile, :url => {:action => :store_credit_card} do |form| %>
+	<%= form.error_messages %>
+	<% form.fields_for :credit_card, @profile.credit_card do |f| %>
+  <p>
+    <%= f.label :first_name %><br />
+    <%= f.text_field :first_name %>
+  </p>
+  <p>
+    <%= f.label :last_name %><br />
+    <%= f.text_field :last_name %>
+  </p>
+  <p>
+    <%= f.label :type, 'Card type' %><br />
+    <%= f.select :type, SubscriptionConfig.gateway.supported_cardtypes.collect {|c| [c.to_s.titleize, c.to_s]} %>
+  </p>
+  <p>
+    <%= f.label :number, 'Card number' %><br />
+    <%= f.text_field :number %>
+  </p>
+  <p>
+    <%= f.label :verification_value, 'Card Verification Value (CVV)' %><br />
+    <%= f.text_field :verification_value, :size => 4 %>
+  </p>
+  <p>
+    <%= f.label :month, 'Card expires on:' %><br />
+		month: <%= f.select :month,  (1..12).map  { |i| "%02d" % i } %>
+		year: <%= f.select :year, (Date.today.year..(Date.today.year+10)) %>
+  </p>
+	<% end %>
+  <p><%= form.submit "Submit", :disable_with => "One moment please..." %></p>
+<% end %>

data/app/views/subscriptions/edit.html.erb

@@ -0,0 +1,14 @@
+<h1>Change Subscription Plan</h1>
+<p>
+	<strong>Current Plan:</strong>
+	<%= @subscription.plan.name.titleize %>
+</p>
+<% form_for @subscription do |f| %>
+	<p>
+		<%= f.label :plan %><br />
+		<%= f.select :plan, @allowed_plans.collect {|p| [ p.name, p.id ] } %>
+	</p>
+	<p><%= f.submit "Change Plan" %></p>
+<% end %>
+
+<p style="font:small"><%= link_to "I want to cancel my subscription", cancel_subscription_path(:current) , :confirm => 'Are you sure?' %></p>

data/app/views/subscriptions/history.html.erb

@@ -0,0 +1,7 @@
+<h1>Transaction History</h1>
+<ul>
+	<% @transactions.each do |tx| %>
+	  <li> <%= tx.created_at %> : <%= tx.action.titleize %> <%= tx.amount.format if tx.amount %> <%= tx.message unless tx.success? %></li>
+	<% end %>
+</ul>
+<%= link_to "Back", subscription_path(:current) %>

data/app/views/subscriptions/show.html.erb

@@ -0,0 +1,59 @@
+<h1>Subscription Details</h1>
+<fieldset>
+	<legend>Subscription</legend>
+	<p>
+		<strong>Plan:</strong>
+		<% plan = @subscription.plan %>
+		<%= plan.name.titleize %> <%= "(#{plan.rate.format} per #{ plan.interval==1 ? 'month' : pluralize(plan.interval, 'month')})" unless plan.free? %>
+		<%= button_to "Change Plan", edit_subscription_path(:current), :method => :get %>
+	</p>
+	<% unless @subscription.free? %>
+		<p>
+			<strong>Status:</strong>
+			<%= @subscription.state.titleize %>
+			<% if @subscription.past_due? %>
+				<span style="color:red">Account is past due. Please update your credit card information now.</span>
+			<% end %>			
+		</p>
+		<p>
+			<% if @subscription.trial? %>
+				<strong>Trial Period Ends:</strong>
+			<% else %>
+				<strong>Paid Through:</strong>
+			<% end %>
+			<%= @subscription.next_renewal_on %>
+		</p>
+	<% end %>
+	<% unless @subscription.balance.zero? %>
+		<p>
+			<strong>Balance on Account:</strong>
+			<%= @subscription.balance.format %>
+		</p>
+	<% end %>
+</fieldset>
+<fieldset>
+	<legend>Billing Info</legend>
+	<p>
+		<strong>Credit Card:</strong>
+	  <% if @subscription.profile.nil? || @subscription.profile.no_info? %>
+			(no credit card on file)
+		<% else %>
+			<%= "#{@subscription.profile.card_type.titleize} #{@subscription.profile.card_display_number} Expires: #{@subscription.profile.card_expires_on}" %>
+			<% if @subscription.profile.error? %>
+				<span style="color:red">There was an error processing your credit card.</span>
+			<% end %>
+		<% end %>
+		<%= button_to "Update Credit Card", credit_card_subscription_path(:current), :method => :get %>
+	</p>
+	<% if t = @subscription.latest_transaction %>
+	<p>
+		<strong>Latest Transaction:</strong>
+			<%# make this a helper %>
+			<%= t.created_at %> :
+			<%= 'FAILED TO' unless t.success? %>
+			<%= t.action.capitalize %> card.
+			<%= "for #{t.amount.format}" unless t.amount.nil? %>
+			<%= t.message %>
+		<%= "(#{link_to 'history', history_subscription_path(:current)})" %>
+	</p>
+<% end %>

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: saas
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Luis Perichon
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-24 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &83443350 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *83443350
+description: SaaS gem
+email:
+- info@luisperichon.com.ar
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/views/subscription_mailer/charge_success.html.erb
+- app/views/subscription_mailer/admin_report.html.erb
+- app/views/subscription_mailer/credit_success.html.erb
+- app/views/subscription_mailer/subscription_expired.html.erb
+- app/views/subscription_mailer/trial_expiring.html.erb
+- app/views/subscription_mailer/charge_failure.html.erb
+- app/views/subscription_mailer/second_charge_failure.html.erb
+- app/views/subscriptions/show.html.erb
+- app/views/subscriptions/edit.html.erb
+- app/views/subscriptions/history.html.erb
+- app/views/subscriptions/credit_card.html.erb
+- app/controllers/subscriptions_controller.rb
+- app/models/subscription_transaction.rb
+- app/models/subscription_mailer.rb
+- app/models/subscription.rb
+- app/models/subscription_plan.rb
+- app/models/subscription_config.rb
+- app/models/subscription_profile.rb
+- app/models/subscription_observer.rb
+- README.rdoc
+homepage: http://luisperichon.com.ar
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: SaaS gem
+test_files: []