billingly 0.0.0 → 0.1.1

data/app/models/billingly/base_plan.rb

@@ -0,0 +1,16 @@
+module Billingly
+  require 'has_duration'
+  class BasePlan < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name = 'billingly_plans'
+
+    attr_accessible :name, :plan_code, :description, :periodicity,
+      :amount, :payable_upfront, :grace_period
+    
+    has_duration :grace_period
+    validates :grace_period, presence: true
+
+    has_duration :periodicity
+    validates :periodicity, presence: true
+  end
+end

data/app/models/billingly/base_subscription.rb

@@ -0,0 +1,118 @@
+module Billingly
+  require 'has_duration'
+ 
+  # A customer will always have at least one subscription to your application.
+  # Everytime there is a change in a {Customer customer's} subscription, the current one
+  # is terminated immediately and a new one is created.
+  #
+  # For example, changing a {Plan} consists on terminating the current
+  # subscription and creating a new one for the new plan.
+  # Also, a new subscription is created when {Customer customers} reactivate their accounts
+  # after being deactivated.
+  #
+  # The most recent subscription is the one currently being charged for, unless the customer
+  # is deactivated at the moment, in which case the last subscription should not be considered
+  # to be active.
+  class BaseSubscription < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name = 'billingly_subscriptions'
+  
+    has_many :ledger_entries, foreign_key: :subscription_id
+
+    # The date in which this subscription started.
+    # This subscription's first invoice will have it's period_start date
+    # matching the date in which the subscription started.
+    # @property subscribed_on
+    # @return [DateTime]
+    validates :subscribed_on, presence: true
+
+    # The grace period we use when calculating an invoices due date.
+    # If a subscription is payable_upfront, then the customer effectively owes us
+    # since the day in which a given period starts.
+    # If a subscription is payable on 'due-month', then the customer effectively
+    # owes us money since the date in which a given period ended.
+    # When we invoice for a given period we will set the due_date a few days
+    # ahead of the date in which the debt was made effective, we call this
+    # a grace_period.
+    # @property grace_period
+    # @return [ActiveSupport::Duration] It's what you get by doing '1.month', '10.days', etc.
+    has_duration :grace_period
+    validates :grace_period, presence: true
+    
+    # A subscription can be a free trial, ending on the date stored in `is_trial_expiring_on'.
+    # Free trial subscriptions don't have {Invoice invoices}. The {Customer customer} is required
+    # to subscribe to a non-trial plan before the trial subscription expires.
+    #
+    # The {#trial?} convenience method returns wheter this subscription is a trial or not.
+    #
+    # @property is_trial_expiring_on
+    # @return [DateTime] 
+    
+    # When a subscription was started from a {Plan} a reference to the plan is saved.
+    # Although, all the plan's fields are denormalized in this subscription.
+    #
+    # If the subscription was not started from a plan, then this will be nil.
+    #
+    # @property plan
+    # @return [Billingly::Plan, nil] 
+    belongs_to :plan
+    
+    # (see #is_trial_expiring_on)
+    # @property trial?
+    # @return [Boolean]
+    def trial?
+      not is_trial_expiring_on.nil?
+    end
+
+    # Invoices will be generated before their due_date, as soon as possible,
+    # but not sooner than GENERATE_AHEAD days.
+    GENERATE_AHEAD = 3.days
+
+    belongs_to :customer
+    has_many :invoices, foreign_key: :subscription_id
+   
+    has_duration :periodicity
+    validates :periodicity, presence: true
+
+    # The invoice generation process should run frequently, at least on a daily basis.
+    # It will create invoices some time before they are due, to give customers a chance
+    # to pay and settle them.
+    # This method is idempotent, if an upcoming invoice for a subscription already exists,
+    # it does not create yet another one.
+    def generate_next_invoice
+      return if terminated?
+      return if trial?
+      from = invoices.empty? ? subscribed_on : invoices.last.period_end
+      to = from + periodicity
+      due_on = (payable_upfront ? from : to) + grace_period
+      return if GENERATE_AHEAD.from_now < from
+
+      invoice = invoices.create!(customer: customer, amount: amount,
+        due_on: due_on, period_start: from, period_end: to)
+      invoice.charge
+      return invoice
+    end
+    
+    # Terminates this subscription, it could be either because we deactivate a debtor
+    # or because the customer decided to end his subscription on his own terms.
+    def terminate
+      return if terminated?
+      update_attribute(:unsubscribed_on, Time.now)
+      invoices.last.truncate unless trial?
+      return self
+    end
+    
+    def terminated?
+      not unsubscribed_on.nil?
+    end
+    
+    # This class method is called from a cron job, it creates invoices for all the subscriptions
+    # that still need their invoice created.
+    # TODO: This goes through all the active subscriptions, make it smarter so that the batch job runs quicker.
+    def self.generate_next_invoices
+      where(is_trial_expiring_on: nil, unsubscribed_on: nil).each do |subscription|
+        subscription.generate_next_invoice
+      end
+    end
+  end
+end

data/app/models/billingly/customer.rb

@@ -1,116 +1,3 @@
-# A Customer is the main entity of Billingly:
-#   * Customers are subscribed to plans
-#   * Customers are charged for one-time expenses.
-#   * Payments are received on a Customer's behalf and credited to their account.
-#   * Invoices are generated periodically calculating charges a Customer incurred in.
-#   * Receipts are sent to Customers when their invoices are paid.
-
-require 'validates_email_format_of'
-
-module Billingly
-  class Customer < ActiveRecord::Base
-    has_many :subscriptions
-    has_many :one_time_charges
-    has_many :invoices
-    has_many :ledger_entries
-    
-    attr_accessible :email
-    validates_email_format_of :email
-    
-    # Customers subscribe to the service and perform periodic payments to continue using it.
-    # We offer common plans stating how much and how often they should pay, also, if the
-    # payment is to be done at the beginning or end of the period (upfront or due-month)
-    # Every customer can potentially get a special deal, but we offer common
-    # deals as 'plans' from which a proper subscription is created.
-    def subscribe_to_plan(plan) 
-      subscriptions.last.terminate if subscriptions.last
-
-      subscriptions.build.tap do |new|
-        [:payable_upfront, :description, :periodicity, :amount].each do |k|
-          new[k] = plan[k]
-        end
-        new.subscribed_on = Time.now
-        new.save!
-        new.generate_next_invoice  
-      end
-    end
-    
-    # Returns the actual subscription of the customer. while working with the 
-    # customer API a customer should only have 1 active subscription at a time.
-    def active_subscription
-      subscriptions.last
-    end 
-    
-    # Every transaction is registered in the journal from where a general ledger can
-    # be retrieved.
-    # Due to silly rounding errors on sqlite we need to convert decimals to float and then to
-    # decimals again. :S
-    def ledger
-      Hash.new(0.0).tap do |all|
-        ledger_entries.group_by(&:account).collect do |account, entries|
-          values = entries.collect(&:amount).collect(&:to_f)
-          all[account.to_sym] = values.inject(0.0) do |sum,item|
-            (BigDecimal.new(sum.to_s) + BigDecimal.new(item.to_s)).to_f
-          end
-        end
-      end
-    end
-    
-    # Shortcut for adding ledger_entries for a particular customer.
-    def add_to_ledger(amount, *accounts, extra)
-      accounts = [] if accounts.nil?
-      unless extra.is_a?(Hash)
-        accounts << extra
-        extra = {}
-      end
-      
-      accounts.each do |account|
-        ledger_entries.create!(extra.merge(amount: amount, account: account.to_s))
-      end
-    end
-    
-    # This class method is run periodically deactivate all customers who have overdue invoices.
-    def self.deactivate_all_debtors
-      debtors.where(deactivated_since: nil).all.each{|debtor| debtor.deactivate }
-    end
-    
-    def self.debtors
-       joins(:invoices).readonly(false)
-        .where("#{Billingly::Invoice.table_name}.due_on < ?", Time.now)
-        .where(billingly_invoices: {deleted_on: nil, receipt_id: nil})
-    end
-
-    # Credits a payment for a customer, settling invoices if possible.
-    def credit_payment(amount)
-      Billingly::Payment.credit_for(self, amount)
-      Billingly::Invoice.charge_all(self.invoices)
-      reactivate
-    end
-    
-    def deactivate
-      return if deactivated?
-      active_subscription.terminate
-      update_attribute(:deactivated_since, Time.now)
-      return self
-    end
-
-    # Reactivates a customer that was deactivated when missed a previous payment.
-    # The new subscription is parametrized the same as the old one. The old subscription
-    # is terminated.
-    def reactivate(new_plan = active_subscription)
-      return unless deactivated?
-      return if debtor?
-      update_attribute(:deactivated_since, nil)
-      subscribe_to_plan(new_plan)
-      return self
-    end
-    
-    def deactivated?
-      not deactivated_since.nil?
-    end
-    
-    def debtor?
-      not self.class.debtors.find_by_id(self.id).nil?
-    end
-  end
+# (see Billingly::BaseCustomer)
+class Billingly::Customer < Billingly::BaseCustomer
 end

data/app/models/billingly/invoice.rb

@@ -2,12 +2,11 @@ module Billingly
   class Invoice < ActiveRecord::Base
     belongs_to :subscription
     belongs_to :customer
-    belongs_to :receipt
-    has_many :ledger_entries 
+    has_many :journal_entries 
     attr_accessible :customer, :amount, :due_on, :period_start, :period_end
     
     def paid?
-      not receipt.nil?
+      not paid_on.nil?
     end
     
     def deleted?
@@ -15,19 +14,19 @@ module Billingly
     end
     
     # Settle an invoice by moving money from the cash balance into an expense,
-    # generating a receipt and marking the invoice as paid.
+    # after charged the invoice becomes paid.
     def charge
       return if paid?
       return unless deleted_on.nil?
+      return if period_start > Time.now
       return if customer.ledger[:cash] < amount
-
-      receipt = create_receipt!(customer: customer, paid_on: Time.now)
-      extra = {receipt: receipt, subscription: subscription}
-      customer.add_to_ledger(-(amount), :cash, extra)
-      customer.add_to_ledger(amount, :spent, extra)
-
-      save! # save receipt
-      return receipt
+      
+      update_attribute(:paid_on, Time.now)
+      extra = {invoice: self, subscription: subscription}
+      customer.add_to_journal(-(amount), :cash, extra)
+      customer.add_to_journal(amount, :spent, extra)
+      
+      return self
     end
     
     # When a subscription terminates, it's last invoice gets truncated so that it does
@@ -48,8 +47,8 @@ module Billingly
       if paid?
         reimburse = (old_amount - self.amount).round(2)
         extra = {invoice: self, subscription: subscription}
-        customer.add_to_ledger(reimburse, :cash, extra)
-        customer.add_to_ledger(-(reimburse), :spent, extra)
+        customer.add_to_journal(reimburse, :cash, extra)
+        customer.add_to_journal(-(reimburse), :spent, extra)
       end
       save!
       self.charge
@@ -58,15 +57,14 @@ module Billingly
 
     # Charges all invoices that can be charged from the existing customer cash balances
     def self.charge_all(collection = self)
-      collection.where(deleted_on: nil, receipt_id: nil).order('period_start').each do |invoice|
+      collection.where(deleted_on: nil, paid_on: nil).order('period_start').each do |invoice|
         invoice.charge
       end
     end
     
-    # Send the email notifying that this invoice is due soon and should be paid.
+    # This method is called by Billingly's recurring task to notify all pending invoices.
     def self.notify_all_pending
-      where('due_on < ?', Billingly::Subscription::GRACE_PERIOD.from_now)
-        .where(deleted_on: nil, receipt_id: nil, notified_pending_on: nil)
+      where(deleted_on: nil, paid_on: nil, notified_pending_on: nil)
         .each do |invoice|
           invoice.notify_pending
         end
@@ -76,7 +74,7 @@ module Billingly
       return unless notified_pending_on.nil?
       return if paid?
       return if deleted?
-      return if due_on > Billingly::Subscription::GRACE_PERIOD.from_now
+      return if due_on > subscription.grace_period.from_now
       BillinglyMailer.pending_notification(self).deliver!
       update_attribute(:notified_pending_on, Time.now)
     end
@@ -85,7 +83,7 @@ module Billingly
     # being cancelled
     def self.notify_all_overdue
       where('due_on <= ?', Time.now)
-        .where(deleted_on: nil, receipt_id: nil, notified_overdue_on: nil)
+        .where(deleted_on: nil, paid_on: nil, notified_overdue_on: nil)
         .each do |invoice|
           invoice.notify_overdue
         end
@@ -104,11 +102,12 @@ module Billingly
     # Send the email notifying that this invoice being overdue and the subscription
     # being cancelled
     def self.notify_all_paid
-      where('receipt_id is not null')
+      where('paid_on is not null')
         .where(deleted_on: nil, notified_paid_on: nil).each do |invoice|
           invoice.notify_paid
         end
     end
+
     def notify_paid
       return unless paid?
       return unless notified_paid_on.nil?

data/app/models/billingly/journal_entry.rb

@@ -0,0 +1,15 @@
+module Billingly
+  class JournalEntry < ActiveRecord::Base
+    belongs_to :customer
+    belongs_to :invoice
+    belongs_to :payment
+    belongs_to :subscription
+
+    validates :amount, presence: true
+    validates :customer, presence: true
+    validates :account, presence: true, inclusion: %w(paid cash spent)
+    
+    attr_accessible :customer, :account, :invoice, :payment, :subscription, :amount 
+    
+  end
+end

data/app/models/billingly/ledger_entry.rb

@@ -1,16 +1,15 @@
 module Billingly
-  class LedgerEntry < ActiveRecord::Base
+  class JournalEntry < ActiveRecord::Base
     belongs_to :customer
     belongs_to :invoice
     belongs_to :payment
-    belongs_to :receipt
     belongs_to :subscription
 
     validates :amount, presence: true
     validates :customer, presence: true
     validates :account, presence: true, inclusion: %w(paid cash spent)
     
-    attr_accessible :customer, :account, :invoice, :payment, :receipt, :subscription, :amount 
+    attr_accessible :customer, :account, :invoice, :payment, :subscription, :amount 
     
   end
 end

data/app/models/billingly/payment.rb

@@ -12,7 +12,7 @@ module Billingly
     # is enough to cover them.
     def self.credit_for(customer, amount) 
       create!(amount: amount, customer: customer).tap do |payment|
-        customer.add_to_ledger(amount, :cash, :paid, payment: payment)
+        customer.add_to_journal(amount, :cash, :paid, payment: payment)
       end
     end
   end

data/app/models/billingly/plan.rb

@@ -1,5 +1,3 @@
-module Billingly
-  class Plan < ActiveRecord::Base
-    attr_accessible :name, :description, :periodicity, :amount, :payable_upfront
-  end
+# @see BasePlan
+class Billingly::Plan < Billingly::BasePlan
 end

data/app/models/billingly/subscription.rb

@@ -1,82 +1,3 @@
-module Billingly
-  class Subscription < ActiveRecord::Base
-    has_many :ledger_entries
-    # If a subscription is payable_upfront, then the customer effectively owes us
-    # since the day in which a given period starts.
-    # If a subscription is payable on 'due-month', then the customer effectively
-    # owes us money since the date in which a given period ended.
-    # When we invoice for a given period we will set the due_date a few days
-    # ahead of the date in which the debt was made effective, we call this
-    # a GRACE_PERIOD.
-    GRACE_PERIOD = 10.days
-    
-    # Invoices will be generated before their due_date, as soon as possible,
-    # but not sooner than GENERATE_AHEAD days.
-    GENERATE_AHEAD = 3.days
-
-    # Subscriptions are to be charged periodically. Their periodicity is
-    # stored semantically on the database, but we want to convert it
-    # to actual ruby time ranges to do date arithmetic.
-    PERIODICITIES = {'monthly' => 1.month, 'yearly' => 1.year}
-
-    belongs_to :customer
-    has_many :invoices
-   
-    validates :periodicity, inclusion: PERIODICITIES.keys
-
-    # The periodicity can be set using a symbol, for convenience.
-    # It's still a string under the hood.
-    def periodicity=(value)
-      self[:periodicity] = value.to_s if value
-    end
-    
-    def period_size
-      case periodicity
-      when 'monthly' then 1.month
-      when 'yearly' then 1.year
-      else
-        raise ArgumentError.new 'Cannot get period size without periodicity'
-      end 
-    end
-    
-    # The invoice generation process should run frequently, at least on a daily basis.
-    # It will create invoices some time before they are due, to give customers a chance
-    # to pay and settle them.
-    # This method is idempotent, if an upcoming invoice for a subscription already exists,
-    # it does not create yet another one.
-    def generate_next_invoice
-      return if terminated?
-      from = invoices.empty? ? subscribed_on : invoices.last.period_end
-      to = from + period_size
-      due_on = (payable_upfront ? from : to) + GRACE_PERIOD
-      return if GENERATE_AHEAD.from_now < from
-
-      invoice = invoices.create!(customer: customer, amount: amount,
-        due_on: due_on, period_start: from, period_end: to)
-      invoice.charge
-      return invoice
-    end
-    
-    # Terminates this subscription, it could be either because we deactivate a debtor
-    # or because the customer decided to end his subscription on his own terms.
-    def terminate
-      return if terminated?
-      update_attribute(:unsubscribed_on, Time.now)
-      invoices.last.truncate
-      return self
-    end
-    
-    def terminated?
-      not unsubscribed_on.nil?
-    end
-    
-    # This class method is called from a cron job, it creates invoices for all the subscriptions
-    # that still need their invoice created.
-    # TODO: This goes through all the active subscriptions, make it smarter so that the batch job runs quicker.
-    def self.generate_next_invoices
-      where(unsubscribed_on: nil).each do |subscription|
-        subscription.generate_next_invoice
-      end
-    end
-  end
+# @see BaseSubscription
+class Billingly::Subscription < Billingly::BaseSubscription
 end