freemium 0.0.1

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/recurring_billing.rb

@@ -0,0 +1,59 @@
+module Freemium
+  # adds recurring billing functionality to the Subscription class
+  module RecurringBilling
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # the process you should run periodically
+      def run_billing
+        # first, synchronize transactions
+        transactions = process_transactions
+
+        # then, set expiration for any subscriptions that didn't process
+        find_expirable.each(&:expire_after_grace!)
+        # then, actually expire any subscriptions whose time has come
+        expire
+
+        # send the activity report
+        Freemium.mailer.deliver_admin_report(
+          transactions
+        ) if Freemium.admin_report_recipients && !new_transactions.empty?
+      end
+
+      protected
+
+      # retrieves all transactions posted after the last known transaction
+      #
+      # please note how this works: it calculates the maximum last_transaction_at
+      # value and only retrieves transactions after that. so be careful that you
+      # don't accidentally update the last_transaction_at field for some subset
+      # of subscriptions, and leave the others behind!
+      def new_transactions
+        Freemium.gateway.transactions(:after => self.maximum(:last_transaction_at))
+      end
+
+      # updates all subscriptions with any new transactions
+      def process_transactions(transactions = new_transactions)
+        transaction do
+          transactions.each do |t|
+            subscription = ::Subscription.find_by_billing_key(t.billing_key)
+            subscription.transactions << t
+            t.success? ? subscription.receive_payment!(t) : subscription.expire_after_grace!(t)
+          end
+        end
+        transactions
+      end
+
+      # finds all subscriptions that should have paid but didn't and need to be expired
+      # because of coupons we can't trust rate_cents alone and need to verify that the account is indeed paid?
+      def find_expirable
+        paid.
+          where(['paid_through < ?', Date.today]).
+          where('(expire_on IS NULL OR expire_on < paid_through)').
+          select { |s| s.paid? }
+      end
+    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,350 @@
+# == 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, :class_name => "SubscriptionPlan"
+        belongs_to :subscribable, :polymorphic => true
+        belongs_to :credit_card, :dependent => :destroy, :class_name => "CreditCard"
+        has_many :coupon_redemptions, :conditions => "coupon_redemptions.expired_on IS NULL", :class_name => "CouponRedemption", :foreign_key => :subscription_id, :dependent => :destroy
+        has_many :coupons, :through => :coupon_redemptions, :conditions => "coupon_redemptions.expired_on IS NULL"
+
+        # Auditing
+        has_many :transactions, :class_name => "AccountTransaction", :foreign_key => :subscription_id
+
+        scope :paid, includes(:subscription_plan).where("subscription_plans.rate_cents > 0")
+        scope :due, lambda {
+          where(['paid_through <= ?', Date.today]) # could use the concept of a next retry date
+        }
+        scope :expired, lambda {
+          where(['expire_on >= paid_through AND expire_on <= ?', Date.today])
+        }
+
+        before_validation :set_paid_through
+        before_validation :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 :paid_through, :if => :paid?
+        validates_presence_of :started_on
+        validates_presence_of :credit_card, :if => :store_credit_card?
+        validates_associated  :credit_card#, :if => :store_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.gateway
+    end
+
+
+    protected
+
+    ##
+    ## Validations
+    ##
+
+    def gateway_validates_credit_card
+      if credit_card && credit_card.changed? && credit_card.valid?
+        response = gateway.validate(credit_card, credit_card.address)
+        unless response.success?
+          errors.add(:base, "Credit card could not be validated: #{response.message}")
+        end
+      end
+    end
+
+    ##
+    ## Callbacks
+    ##
+
+    def set_paid_through
+      if subscription_plan_id_changed? && !paid_through_changed?
+        if paid?
+          if new_record?
+            # paid + new subscription = in free trial
+            self.paid_through = Date.today + Freemium.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
+
+    # Simple assignment of a credit card. Note that this may not be
+    # useful for your particular situation, especially if you need
+    # to simultaneously set up automated recurrences.
+    #
+    # Because of the third-party interaction with the gateway, you
+    # need to be careful to only use this method when you expect to
+    # be able to save the record successfully. Otherwise you may end
+    # up storing a credit card in the gateway and then losing the key.
+    #
+    # NOTE: Support for updating an address could easily be added
+    # with an "address" property on the credit card.
+    def store_credit_card_offsite
+      if credit_card && credit_card.changed? && credit_card.valid?
+        response = billing_key ? gateway.update(billing_key, credit_card, credit_card.address) : gateway.store(credit_card, credit_card.address)
+        raise Freemium::CreditCardStorageError.new(response.message) unless response.success?
+        self.billing_key = response.billing_key
+        self.expire_on = nil
+        self.credit_card.reload # to prevent needless subsequent store() calls
+      end
+    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 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 expire
+        self.expired.select{|s| s.paid?}.each(&:expire!)
+      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
+
+    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
+      self.errors.add :coupon, "could not be found for '#{@coupon_key}'" if !@coupon_key.blank? && ::Coupon.find_by_redemption_key(@coupon_key).nil?
+    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
+      (self.paid_through - Date.today)
+    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.days_grace
+      transaction.message = "now set to expire on #{self.expire_on}" if transaction
+      Freemium.mailer.expiration_warning(self).deliver
+      transaction.save! if transaction
+      save!
+    end
+
+    # sends an expiration email, then downgrades to a free plan
+    def expire!
+      Freemium.mailer.expiration_notice(self).deliver
+      # downgrade to a free plan
+      self.expire_on = Date.today
+      self.subscription_plan = Freemium.expired_plan if Freemium.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.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
+
+  end
+end

data/lib/freemium/subscription_change.rb

@@ -0,0 +1,20 @@
+module Freemium
+  module SubscriptionChange
+
+    def self.included(base)
+      base.class_eval do
+        belongs_to :subscribable, :polymorphic => true
+
+        belongs_to :original_subscription_plan, :class_name => "SubscriptionPlan"
+        belongs_to :new_subscription_plan, :class_name => "SubscriptionPlan"
+
+        composed_of :new_rate, :class_name => 'Money', :mapping => [ %w(new_rate_cents cents) ], :allow_nil => true
+        composed_of :original_rate, :class_name => 'Money', :mapping => [ %w(original_rate_cents cents) ], :allow_nil => true
+
+        validates_presence_of :reason
+        validates_inclusion_of :reason, :in => %w(new upgrade downgrade expiration cancellation)
+      end
+    end
+
+  end
+end

data/lib/freemium/subscription_mailer/admin_report.rhtml

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

data/lib/freemium/subscription_mailer/expiration_notice.rhtml

@@ -0,0 +1 @@
+Your subscription has expired.

data/lib/freemium/subscription_mailer/expiration_warning.rhtml

@@ -0,0 +1 @@
+We were unable to process your payment, and your subscription is set to expire in <%= @subscription.remaining_days_of_grace %> days. Please contact us to correct this.

data/lib/freemium/subscription_mailer/invoice.text.plain.erb

@@ -0,0 +1,5 @@
+Thanks for paying!
+
+  Your Plan: <%= @subscription.subscription_plan.name %> (<%= @subscription.subscription_plan.rate %> / month)
+  Paid: <%= @amount %>
+  Paid Through: <%= @subscription.paid_through.to_s %>

data/lib/freemium/subscription_mailer.rb

@@ -0,0 +1,36 @@
+class SubscriptionMailer < ActionMailer::Base
+  prepend_view_path(File.dirname(__FILE__))
+
+   default :from => 'billing@example.com',
+           :return_path => 'no-reply@example.com'
+
+  def invoice(transaction)
+    @amount = transaction.amount
+    @subscription = transaction.subscription
+    mail(:to => transaction.subscription.subscribable.email,
+         :bcc => Freemium.admin_report_recipients,
+         :subject => "Your invoice")
+  end
+
+  def expiration_warning(subscription)
+    @subscription = subscription
+    mail(:to => subscription.subscribable.email,
+         :bcc => Freemium.admin_report_recipients,
+         :subject => "Your subscription is set to expire")
+  end
+
+  def expiration_notice(subscription)
+    @subscription = subscription
+    mail(:to => subscription.subscribable.email,
+         :bcc => Freemium.admin_report_recipients,
+         :subject => "Your subscription has expired")
+  end
+  
+  def admin_report(transactions)
+    @amount_charged       = transactions.select{|t| t.success?}.collect{|t| t.amount}.sum
+    @transactions = transactions
+    @amount_charged = @amount_charged
+    mail(:to => Freemium.admin_report_recipients,
+         :subject => "Billing report (#{@amount_charged} charged)")
+  end  
+end

data/lib/freemium/subscription_plan.rb

@@ -0,0 +1,32 @@
+# == Attributes
+#   subscriptions:      all subscriptions for the plan
+#   rate_cents:         how much this plan costs, in cents
+#   rate:               how much this plan costs, in Money
+#   yearly:             whether this plan cycles yearly or monthly
+#
+module Freemium
+  module SubscriptionPlan
+    include Rates
+
+    def self.included(base)
+      base.class_eval do
+        # yes, subscriptions.subscription_plan_id may not be null, but
+        # this at least makes the delete not happen if there are any active.
+        has_many :subscriptions, :dependent => :nullify, :class_name => "Subscription", :foreign_key => :subscription_plan_id
+        has_and_belongs_to_many :coupons, :class_name => "SubscriptionPlan",
+          :join_table => :coupons_subscription_plans, :foreign_key => :subscription_plan_id, :association_foreign_key => :coupon_id
+
+        composed_of :rate, :class_name => 'Money', :mapping => [ %w(rate_cents cents) ], :allow_nil => true
+
+        validates_uniqueness_of :redemption_key, :allow_nil => true, :allow_blank => true
+        validates_presence_of :name
+        validates_presence_of :rate_cents
+      end
+    end
+
+    def features
+      Freemium::FeatureSet.find(self.feature_set_id)
+    end
+
+  end
+end

data/lib/freemium/transaction.rb

@@ -0,0 +1,15 @@
+module Freemium
+  module Transaction
+
+    def self.included(base)
+      base.class_eval do
+        scope :since, lambda { |time| where(["created_at >= ?", time]) }
+
+        belongs_to :subscription, :class_name => "Subscription"
+
+        composed_of :amount, :class_name => 'Money', :mapping => [ %w(amount_cents cents) ], :allow_nil => true
+      end
+    end
+
+  end
+end

data/lib/freemium/version.rb

@@ -0,0 +1,3 @@
+module Freemium
+  VERSION = "0.0.1"
+end

data/lib/freemium.rb

@@ -0,0 +1,75 @@
+require 'rails'
+
+require 'money'
+require "freemium/version"
+require 'freemium/address'
+require 'freemium/coupon'
+require 'freemium/coupon_redemption'
+require 'freemium/credit_card'
+require 'freemium/feature_set'
+require 'freemium/manual_billing'
+require 'freemium/rates'
+require 'freemium/recurring_billing'
+require 'freemium/response'
+require 'freemium/subscription'
+require 'freemium/subscription_change'
+require 'freemium/subscription_plan'
+require 'freemium/transaction'
+require 'freemium/gateways/base'
+require 'freemium/gateways/brain_tree'
+require 'freemium/gateways/test'
+require 'freemium/subscription_mailer'
+
+module Freemium
+  class CreditCardStorageError < RuntimeError; end
+
+  # Lets you configure which ActionMailer class contains appropriate
+  # mailings for invoices, expiration warnings, and expiration notices.
+  # You'll probably want to create your own, based on lib/subscription_mailer.rb.
+  mattr_accessor :mailer
+  @@mailer = SubscriptionMailer
+
+  # The gateway of choice. Default gateway is a stubbed testing gateway.
+  mattr_accessor :gateway
+  @@gateway = Freemium::Gateways::Test.new
+
+  # You need to specify whether Freemium or your gateway's ARB module will control
+  # the billing process. If your gateway's ARB controls the billing process, then
+  # Freemium will simply try and keep up-to-date on transactions.
+  def self.billing_handler=(val)
+    case val
+    when :manual  then ::Subscription.send(:include, Freemium::ManualBilling)
+    when :gateway then ::Subscription.send(:include, Freemium::RecurringBilling)
+    else
+      raise "unknown billing_handler: #{val}"
+    end
+  end
+
+  # How many days to keep an account active after it fails to pay.
+  mattr_accessor :days_grace
+  @@days_grace = 3
+
+  # How many days in an initial free trial?
+  mattr_accessor :days_free_trial
+  @@days_free_trial = 0
+
+  # What plan to assign to subscriptions that have expired. May be nil.
+  mattr_writer :expired_plan
+  def self.expired_plan
+    @@expired_plan ||= (::SubscriptionPlan.find_by_redemption_key(expired_plan_key.to_s) if expired_plan_key)
+  end
+
+  # It's easier to assign a plan by it's key (so you don't get errors before you run migrations)
+  # we will reset subscription_plan when we change the key
+  mattr_reader :expired_plan_key
+  def self.expired_plan_key=(key)
+    @@expired_plan_key = key
+    @@expired_plan = nil
+  end
+
+  # If you want to receive admin reports, enter an email (or list of emails) here.
+  # These will be bcc'd on all SubscriptionMailer emails, and will also receive the
+  # admin activity report.
+  mattr_accessor :admin_report_recipients
+
+end