freemium-ajb 0.0.4

data/lib/freemium/engine.rb

@@ -0,0 +1,7 @@
+require 'freemium'
+require 'rails'
+
+module Freemium
+  class Engine < Rails::Engine
+  end
+end

data/lib/freemium/gateways/base.rb

@@ -0,0 +1,65 @@
+module Freemium
+  module Gateways
+    class Base #:nodoc:
+      superclass_delegating_accessor :open_timeout
+      self.open_timeout = 60
+
+      superclass_delegating_accessor :read_timeout
+      self.read_timeout = 60
+
+      # cancels the subscription identified by the given billing key.
+      # this might mean removing it from the remote system, or halting the remote
+      # recurring billing.
+      #
+      # should return a Freemium::Response
+      def cancel(billing_key)
+        raise MethodNotImplemented
+      end
+
+      # stores a credit card with the gateway.
+      # should return a Freemium::Response
+      def store(credit_card, address = nil)
+        raise MethodNotImplemented
+      end
+
+      # updates a credit card in the gateway.
+      # should return a Freemium::Response
+      def update(billing_key, credit_card = nil, address = nil)
+        raise MethodNotImplemented
+      end
+
+      # validates a credit card with the gateway.
+      # should return a Freemium::Response
+      def validate(credit_card, address = nil)
+        raise MethodNotImplemented
+      end
+
+      ##
+      ## Only needed to support Freemium.billing_handler = :gateway
+      ##
+
+      # only needed to support an ARB module. otherwise, the manual billing process will
+      # take care of processing transaction information as it happens.
+      #
+      # concrete classes need to support these options:
+      #   :billing_key : - only retrieve transactions for this specific billing key
+      #   :after :       - only retrieve transactions after this datetime (non-inclusive)
+      #   :before :      - only retrieve transactions before this datetime (non-inclusive)
+      #
+      # return value should be a collection of Freemium::Transaction objects.
+      def transactions(options = {})
+        raise MethodNotImplemented
+      end
+
+      ##
+      ## Only needed to support Freemium.billing_handler = :manual
+      ##
+
+      # charges money against the given billing key.
+      # should return a Freemium::Transaction
+      def charge(billing_key, amount)
+        raise MethodNotImplemented
+      end
+    end
+  end
+end

data/lib/freemium/gateways/brain_tree.rb

@@ -0,0 +1,175 @@
+require 'net/http'
+require 'net/https'
+module Freemium
+  module Gateways
+    # = Setup and Configuration
+    # In your config/initializers/freemium.rb, configure Freemium to use BrainTree:
+    #
+    #   Freemium.gateway = Freemium::Gateways::BrainTree.new
+    #   Freemium.gateway.username = "my_username"
+    #   Freemium.gateway.password = "my_password"
+    #
+    # Note that if you want to use demo/password credentials when not in production mode, this is the place.
+    #
+    # = Data Structures
+    # All amounts should use the Money class (from eponymous gem).
+    # All credit cards should use Freemium::CreditCard class (currently just an alias for ActiveMerchant::Billing::CreditCard).
+    # All addresses should use Freemium::Address class.
+    #
+    # = For Testing
+    # The URL does not change. If your account is in test mode, no charges will be processed. Otherwise,
+    # configure the username and password to be "demo" and "password", respectively.
+    class BrainTree < Base
+      URL = 'https://secure.braintreepaymentgateway.com/api/transact.php'
+      attr_accessor :username, :password
+
+      # using BrainTree's recurring billing is not possible until I have their reporting API
+      #def transactions(options = {}); end
+
+      # Stores a card in SecureVault.
+      def store(credit_card, address = nil)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => "add_customer"
+        })
+        p.params.merge! params_for_credit_card(credit_card)
+        p.params.merge! params_for_address(address)         if address
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Updates a card in SecureVault.
+      def update(vault_id, credit_card = nil, address = nil)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => "update_customer",
+          :customer_vault_id => vault_id
+        })
+        p.params.merge! params_for_credit_card(credit_card) if credit_card
+        p.params.merge! params_for_address(address)         if address
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Manually charges a card in SecureVault. Called automatically as part of manual billing process.
+      def charge(vault_id, amount)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault_id => vault_id,
+          :amount => sprintf("%.2f", amount.cents.to_f / 100)
+        })
+        p.commit(open_timeout, read_timeout)
+        transaction = AccountTransaction.new(:billing_key => vault_id, :amount => amount, :success => p.response.success?)
+        transaction.response = p.response if transaction.respond_to?(:response=)
+        return transaction
+      end
+
+      # Removes a card from SecureVault. Called automatically when the subscription expires.
+      def cancel(vault_id)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => 'delete_customer',
+          :customer_vault_id => vault_id
+        })
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Validates the card.
+      def validate(credit_card, address = nil)
+        # Assume we validated if we're using a demo account
+        return Freemium::Response.new(true) if self.username == 'demo'
+
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :type => 'validate'
+        })
+        p.params.merge! params_for_credit_card(credit_card)
+        if address
+          p.params.merge! params_for_address(address)
+        end
+
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      protected
+      def params_for_credit_card(card)
+        params = {
+          :payment   => 'creditcard',
+          :firstname => card.first_name,
+          :lastname  => card.last_name,
+          :ccnumber  => card.number,
+          :ccv       => card.verification_value,
+          :ccexp     => ["%.2i" % card.month, ("%.4i" % card.year)[-2..-1]].join # MMYY
+        }
+      end
+
+      def params_for_address(address)
+        params = {
+          :email     => address.email,
+          :address1  => address.address1,
+          :address2  => address.address2,
+          :city      => address.city,
+          :state     => address.state, # TODO: two-digit code!
+          :zip       => address.zip,
+          :country   => address.country, # TODO: two digit code! (ISO-3166)
+          :phone     => address.phone_number,
+          :ipaddress => address.ip_address
+        }
+      end
+
+      class Post
+        attr_accessor :url
+        attr_accessor :params
+        attr_reader :response
+
+        def initialize(url, params = {})
+          self.url = url
+          self.params = params
+        end
+
+        def commit(open_timeout, read_timeout)
+          data = parse(post(open_timeout, read_timeout))
+          # from BT API: 1 means approved, 2 means declined, 3 means error
+          success = data['response'].to_i == 1
+          @response = Freemium::Response.new(success, data)
+          @response.billing_key = data['customer_vault_id']
+          @response.message = data['responsetext']
+          return self
+        end
+
+        protected
+
+        # BrainTree returns a body of parameters in GET query format, so convert that into a simple hash.
+        def parse(data)
+          {}.tap do |results|
+            data.split('&').each do |pair|
+              key, value = pair.split('=', 2).collect { |v| CGI::unescape(v) }
+              results[key] = value
+            end
+          end
+        end
+
+        # cf. ActiveMerchant's PostsData module.
+        def post(open_timeout, read_timeout)
+          uri = URI.parse(self.url)
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+          http.use_ssl      = true
+          http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
+
+          data = self.params.collect { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+          http.post(uri.request_uri, data).body
+        end
+      end
+    end
+  end
+end

data/lib/freemium/gateways/test.rb

@@ -0,0 +1,36 @@
+module Freemium
+  module Gateways
+    class Test < Base
+      attr_accessor :username, :password
+
+      def transactions(options = {})
+        options
+      end
+
+      def charge(*args)
+        args
+      end
+
+      def store(*args)
+        response = Freemium::Response.new(true)
+        response.billing_key = Time.now.to_i.to_s
+        response
+      end
+
+      def update(billing_key, *args)
+        response = Freemium::Response.new(true)
+        response.billing_key = billing_key
+        response
+      end
+
+      def cancel(*args)
+        args
+      end
+
+      def validate(*args)
+        response = Freemium::Response.new(true)
+        response
+      end
+    end
+  end
+end

data/lib/freemium/rates.rb

@@ -0,0 +1,33 @@
+module Freemium
+  module Rates
+
+    # returns the daily cost of this plan.
+    def daily_rate(options = {})
+      yearly_rate(options) / 365
+    end
+
+    # returns the yearly cost of this plan.
+    def yearly_rate(options = {})
+      begin
+        rate(options) * 12
+      rescue
+        rate * 12
+      end
+    end
+
+    # returns the monthly cost of this plan.
+    def monthly_rate(options = {})
+      begin
+        rate(options)
+      rescue
+        rate
+      end
+    end
+
+    def paid?
+      return false unless rate
+      rate.cents > 0
+    end
+
+  end
+end

data/lib/freemium/response.rb

@@ -0,0 +1,24 @@
+module Freemium
+  # used to encapsulate the success/failure/details of a response from some gateway.
+  # intended to be independent of the details of communication (e.g. Freemium::Gateways::BrainTree::Post).
+  class Response
+    # a gateway-specific hash of raw data related to the request.
+    attr_reader :raw_data
+    # may contain a description of the response. should contain an explanation if the response was not a success.
+    attr_accessor :message
+    # the related billing key, if appropriate
+    attr_accessor :billing_key
+
+    def initialize(success, raw_data = {})
+      @success, @raw_data = success, raw_data
+    end
+
+    def success?
+      @success
+    end
+
+    def [](key)
+      raw_data[key]
+    end
+  end
+end

data/lib/freemium/subscription.rb

@@ -0,0 +1,384 @@
+# == Attributes
+#   subscribable:         the model in your system that has the subscription. probably a User.
+#   subscription_plan:    which service plan this subscription is for. affects how payment is interpreted.
+#   paid_through:         when the subscription currently expires, assuming no further payment. for manual billing, this also determines when the next payment is due.
+#   billing_key:          the id for this user in the remote billing gateway. may not exist if user is on a free plan.
+#   last_transaction_at:  when the last gateway transaction was for this account. this is used by your gateway to find "new" transactions.
+#
+module Freemium
+  module Subscription
+    include Rates
+
+    def self.included(base)
+      base.class_eval do
+        belongs_to :subscription_plan
+        belongs_to :subscribable, polymorphic: true
+
+        belongs_to :credit_card, dependent: :destroy
+        has_many :coupon_redemptions, conditions: "coupon_redemptions.expired_on IS NULL", dependent: :destroy
+        has_many :coupons, conditions: "coupon_redemptions.expired_on IS NULL", through: :coupon_redemptions
+
+        has_many :transactions
+
+        scope :paid, -> { includes(:subscription_plan).where("subscription_plans.rate_cents > 0") }
+        scope :due, -> {  where('paid_through <= ?', Date.today) }
+        scope :expired, -> { where('expire_on >= paid_through AND expire_on <= ?', Date.today) }
+
+        before_save :remove_coupon_if_no_longer_applies
+        before_save :set_paid_through
+        before_save :set_started_on
+        before_save :store_credit_card_offsite
+        before_save :discard_credit_card_unless_paid
+        before_destroy :cancel_in_remote_system
+
+        after_create  :audit_create
+        after_update  :audit_update
+        after_destroy :audit_destroy
+
+        validates_presence_of :subscribable
+        validates_associated  :subscribable
+        validates_presence_of :subscription_plan
+        validates_presence_of :credit_card, :if => :store_credit_card?
+        validates_associated  :credit_card
+
+        validate :gateway_validates_credit_card
+        validate :coupon_exist
+      end
+      base.extend ClassMethods
+    end
+
+    def original_plan
+      @original_plan ||= ::SubscriptionPlan.find_by_id(subscription_plan_id_was) unless subscription_plan_id_was.nil?
+    end
+
+    def gateway
+      Freemium.configuration.gateway
+    end
+
+
+    protected
+
+    ##
+    ## Validations
+    ##
+
+    def gateway_validates_credit_card
+      if credit_card && credit_card.changed? && credit_card.valid?
+        response = gateway.validate(credit_card)
+        unless response.success?
+          errors.add(:base, "Credit card could not be validated: #{response.message}")
+        end
+      end
+    end
+
+    ##
+    ## Callbacks
+    ##
+
+    def set_paid_through(force = false)
+      if subscription_plan_id_changed? && (!paid_through_changed? || force)
+        if paid?
+          if new_record?
+            # paid + new subscription = in free trial
+            self.paid_through = Date.today + Freemium.configuration.days_free_trial
+            self.in_trial = true
+          elsif !self.in_trial? && self.original_plan && self.original_plan.paid?
+            # paid + not in trial + not new subscription + original sub was paid = calculate and credit for remaining value
+            value = self.remaining_value(original_plan)
+            self.paid_through = Date.today
+            self.credit(value)
+          else
+            # otherwise payment is due today
+            self.paid_through = Date.today
+            self.in_trial = false
+          end
+        else
+          # free plans don't pay
+          self.paid_through = nil
+        end
+      end
+      true
+    end
+
+    def set_started_on
+      self.started_on = Date.today if subscription_plan_id_changed?
+    end
+
+    def discard_credit_card_unless_paid
+      unless store_credit_card?
+        destroy_credit_card
+      end
+    end
+
+    def destroy_credit_card
+      credit_card.destroy if credit_card
+      cancel_in_remote_system
+    end
+
+    def cancel_in_remote_system
+      if billing_key
+        gateway.cancel(self.billing_key)
+        self.billing_key = nil
+      end
+    end
+
+    ##
+    ## Callbacks :: Auditing
+    ##
+
+    def audit_create
+      ::SubscriptionChange.create(:reason => "new",
+                                        :subscribable => self.subscribable,
+                                        :new_subscription_plan_id => self.subscription_plan_id,
+                                        :new_rate => self.rate,
+                                        :original_rate => Money.empty)
+    end
+
+    def audit_update
+      if self.subscription_plan_id_changed?
+        return if self.original_plan.nil?
+        reason = self.original_plan.rate > self.subscription_plan.rate ? (self.expired? ? "expiration" : "downgrade") : "upgrade"
+        ::SubscriptionChange.create(:reason => reason,
+                                          :subscribable => self.subscribable,
+                                          :original_subscription_plan_id => self.original_plan.id,
+                                          :original_rate => self.rate(:plan => self.original_plan),
+                                          :new_subscription_plan_id => self.subscription_plan.id,
+                                          :new_rate => self.rate)
+      end
+    end
+
+    def remove_coupon_if_no_longer_applies
+      return unless self.subscription_plan_id_changed?
+      return unless self.coupon
+
+      if !self.coupon.applies_to_plan?(self.subscription_plan)
+        self.coupon_redemption.expire!(Date.yesterday)
+        self.coupon_redemptions.reload
+        self.set_paid_through(true)
+      end
+    end
+
+    def audit_destroy
+      ::SubscriptionChange.create(:reason => "cancellation",
+                                        :subscribable => self.subscribable,
+                                        :original_subscription_plan_id => self.subscription_plan_id,
+                                        :original_rate => self.rate,
+                                        :new_rate => Money.empty)
+    end
+
+    public
+
+    ##
+    ## Class Methods
+    ##
+
+    module ClassMethods
+      # expires all subscriptions that have been pastdue for too long (accounting for grace)
+      def find_expired
+        self.expired.select{ |s| s.paid? }
+      end
+
+      def find_billable
+        self.paid.due.select { |s| s.paid? }
+      end
+    end
+
+    ##
+    ## Rate
+    ##
+
+    def rate(options = {})
+      options = {:date => Date.today, :plan => self.subscription_plan}.merge(options)
+
+      return nil unless options[:plan]
+      value = options[:plan].rate
+      value = self.coupon(options[:date]).discount(value) if self.coupon(options[:date])
+      value
+    end
+
+    # is this a paid plan?
+    def paid?
+      return false unless rate
+      rate.cents > 0
+    end
+
+    # Allow for more complex logic to decide if a card should be stored
+    def store_credit_card?
+      paid?
+    end
+
+    ##
+    ## Coupon Redemption
+    ##
+
+    def coupon_key=(coupon_key)
+      @coupon_key = coupon_key ? coupon_key.downcase : nil
+      self.coupon = ::Coupon.find_by_redemption_key(@coupon_key) unless @coupon_key.blank?
+    end
+
+    def coupon_exist
+      if !@coupon_key.blank? && ::Coupon.find_by_redemption_key(@coupon_key).nil?
+        self.errors.add :coupon, "could not be found for '#{@coupon_key}'"
+      end
+    end
+
+    def coupon=(coupon)
+      if coupon
+        s = ::CouponRedemption.new(:subscription => self, :coupon => coupon)
+        coupon_redemptions << s
+      end
+    end
+
+    def coupon(date = Date.today)
+      coupon_redemption(date).coupon rescue nil
+    end
+
+    def coupon_redemption(date = Date.today)
+      return nil if coupon_redemptions.empty?
+      active_coupons = coupon_redemptions.select{|c| c.active?(date)}
+      return nil if active_coupons.empty?
+      active_coupons.sort_by{|c| c.coupon.discount_percentage }.reverse.first
+    end
+
+    ##
+    ## Remaining Time
+    ##
+
+    # returns the value of the time between now and paid_through.
+    # will optionally interpret the time according to a certain subscription plan.
+    def remaining_value(plan = self.subscription_plan)
+      self.daily_rate(:plan => plan) * remaining_days
+    end
+
+    # if paid through today, returns zero
+    def remaining_days
+      if self.paid_through
+        (self.paid_through - Date.today)
+      else
+        0
+      end
+    end
+
+    ##
+    ## Grace Period
+    ##
+
+    # if under grace through today, returns zero
+    def remaining_days_of_grace
+      (self.expire_on - Date.today - 1).to_i
+    end
+
+    def in_grace?
+      remaining_days < 0 and not expired?
+    end
+
+    ##
+    ## Expiration
+    ##
+
+    # sets the expiration for the subscription based on today and the configured grace period.
+    def expire_after_grace!(transaction = nil)
+      return unless self.expire_on.nil? # You only set this once subsequent failed transactions shouldn't affect expiration
+      self.expire_on = [Date.today, paid_through].max + Freemium.configuration.days_grace
+      transaction.message = "now set to expire on #{self.expire_on}" if transaction
+      Freemium.configuration.mailer.expiration_warning(self).deliver
+      transaction.save! if transaction
+      save!
+    end
+
+    # sends an expiration email, then downgrades to a free plan
+    def expire!
+      Freemium.configuration.mailer.expiration_notice(self).deliver
+      # downgrade to a free plan
+      self.expire_on = Date.today
+      self.subscription_plan = Freemium.configuration.expired_plan if Freemium.configuration.expired_plan
+      self.destroy_credit_card
+      self.save!
+    end
+
+    def expired?
+      expire_on and expire_on <= Date.today
+    end
+
+    ##
+    ## Receiving More Money
+    ##
+
+    # receives payment and saves the record
+    def receive_payment!(transaction)
+      receive_payment(transaction)
+      transaction.save!
+      self.save!
+    end
+
+    # extends the paid_through period according to how much money was received.
+    # when possible, avoids the days-per-month problem by checking if the money
+    # received is a multiple of the plan's rate.
+    #
+    # really, i expect the case where the received payment does not match the
+    # subscription plan's rate to be very much an edge case.
+    def receive_payment(transaction)
+      self.credit(transaction.amount)
+      self.save!
+      transaction.subscription.reload  # reloaded to that the paid_through date is correct
+      transaction.message = "now paid through #{self.paid_through}"
+
+      begin
+        Freemium.configuration.mailer.invoice(transaction).deliver
+      rescue => e
+        transaction.message = "error sending invoice: #{e}"
+      end
+    end
+
+    def credit(amount)
+      self.paid_through = if amount.cents % rate.cents == 0
+        self.paid_through + (amount.cents / rate.cents).months
+      else
+        self.paid_through + (amount.cents / daily_rate.cents).days
+      end
+
+      # if they've paid again, then reset expiration
+      self.expire_on = nil
+      self.in_trial = false
+    end
+
+    # Override if you need to charge something different than the rate (ex: yearly billing option)
+    def installment_amount(options = {})
+      self.rate(options)
+    end
+
+    # charges this subscription.
+    # assumes, of course, that this module is mixed in to the Subscription model
+    def charge!
+      # Save the transaction immediately
+
+      @transaction = gateway.charge(billing_key, self.installment_amount)
+      self.transactions << @transaction
+      self.last_transaction_at = Time.now # TODO this could probably now be inferred from the list of transactions
+      self.last_transaction_success = @transaction.success?
+
+      self.save(:validate => false)
+
+      begin
+        if @transaction.success?
+          receive_payment!(@transaction)
+        elsif !@transaction.subscription.in_grace?
+          expire_after_grace!(@transaction)
+        end
+      rescue
+      end
+
+      @transaction
+    end
+
+    def store_credit_card_offsite
+      if credit_card && credit_card.changed? && credit_card.valid?
+        response = billing_key ? gateway.update(billing_key, credit_card) : gateway.store(credit_card)
+        raise Freemium::CreditCardStorageError.new(response.message) unless response.success?
+        self.billing_key = response.billing_key
+        self.expire_on = nil if last_transaction_success
+        self.credit_card.reload # to prevent needless subsequent store() calls
+      end
+    end
+  end
+end