billingly 0.0.0 → 0.1.1

data/README.md

@@ -0,0 +1,36 @@
+# Billingly
+
+Billingly is a rails 3 engine that manages paid subscriptions and free trials to your web application. 
+
+Billingly can:
+
+* Subscribe customers to your service:
+  * Subscriptions can have an arbitrary length: A year, a month, 90 days ...
+  * You can request payments upfront or after the subscription period is over.
+
+* Offer standarized subscription plans for self-service sign ups.
+
+* Offer special deals on a per-customer basis.
+
+* Invoice your customers automatically and send receipts once they pay.
+
+* Notify customers about due dates.
+
+* Restrict access to debtors, and let them back in once they pay their debt.
+
+* Let customers upgrade or downgrade to another plan. Prorating and reimbursing in case there were any upfront payments.
+
+* Let you give arbitrary bonuses, vouchers and gifts credited to your customer's account.
+
+* Offer a trial period before you require people to become paying customers.
+
+Billingly does not receive payments directly (from Paypal, or Worldpay for example). However, you can use [ActiveMerchant](http://activemerchant.org) for handling payment notifications from third party services, and easily hookup Billingly to credit the payment into your customer's account. Billingly will take care of all the rest.
+
+# Getting Started
+  * Read the [Getting Started Guide](http://rubydoc.info/github/nubis/billingly/master/file/TUTORIAL.rdoc).
+  * Check out the [Demo App](http://billing.ly).
+  * Explore the [Docs](http://rubydoc.info/github/nubis/billingly/master/frames/file/README.md).
+
+# License
+  MIT License. Copyright 2012 Nubis (nubis@woobiz.com.ar)
+

data/TUTORIAL.rdoc

@@ -0,0 +1,158 @@
+# @markup markdown
+
+# Getting Started
+
+## Preface
+
+At its core, billingly has a {Billingly::Customer} class. A {Billingly::Customer} has a {Billingly::Subscription} to your service, for which she will receive {Billingly::Invoice Invoices} regularly via email.
+Billingly keeps a balance for each one of your {Customer customers}, whenever you receive a payment you should {Billingly::BaseCustomer#credit_payment credit the payment} into their account.
+
+When a payment is credited, billingly will try to settle outstanding invoices, always starting from the oldest one. If the customer's balance is not enough to cover the last pending invoice then nothing will happen. Once an invoice is settled the customer will be sent a receipt via email. 
+
+Invoices have a due date, customers will notified about pending invoices before they are overdue. When a customer misses a payment, billingly will immediately deactivate his account and notify via email about the deactivation.
+
+Deactivated customers will be redirected forcefully to their subscription page where they can see all their invoices. Once they pay their overdue invoices their account is re-activated.
+
+You may change a customers subscription at any point. Under the hood, changing a subscription consist on terminating the current subscription and creating a new one. Any invoices paid for the terminated subscription will be automatically prorated and the remaining balance will be credited back into the customer's account.
+
+Each customer can have a completely custom Subscription, but you will usually want people to sign up to a predefined {Billingly::Plan}. Billingly comes with a {Billingly::Plan} model and a {Billingly::SubscriptionsController} which can be extended and enable you to support self-service subscriptions out of the box.
+
+Billingly also lets you offer free trial subscriptions. You can configure a trial termination date when subscribing a customer to any type of plan, billingly will deactivate the customers account when the date of expiration comes, and will show them a subscription page from where they can signup to any other full plan.
+
+# Installing
+
+## Get the gem
+
+    gem install billingly
+
+    gem 'billingly'
+
+## Create the tables
+
+Use the provided generator to create the migration that will generate all the required tables.
+
+You can add your custom attributes to the customer and plans tables, but changing the table names is not advised. Tables are namespaced with the 'billingly_' prefix.
+
+    rails g billingly_migration
+
+For example, if your application's plans differ in the amount of users they allow, you can
+add a `user_quota` field to your `billingly_plans` table.
+
+You may also add a foreign key to your `billingly_customers` table so that each customer points
+to a user.
+
+## Customize the Models
+
+Billingly models are abstract classes with default implementations, you don't need to override them but you would probably want to override the {Billingly::Customer} model to provide your implementations for the {Billingly::BaseCustomer#on\_subscription\_success} and {Billingly::BaseCustomer#can\_subscribe\_to?}
+
+Continuing with the previous example, this snippet adds a user association to the customer and denormalizes the `user_quota` from the chosen plan into the User for easier lookup. It also prevents customers from subscribing to a plan offering a smaller quota than their current one.
+
+    # app/models/billingly/customer.rb
+    class Billingly::Customer < Billingly::BaseCustomer
+      belongs_to :user
+
+      def on_subscription_success
+        # For simplicity, we assume there is always a user.
+        user.update_attribute(:user_quota, active_subscription.plan.user_quota)
+      end
+      
+      # Return false signifies that the user cannot subscribe to the provided plan
+      # if the current plan has a larger storage quota.
+      def can_subscribe_to?(plan)
+        current_plan = active_subscription.plan
+        if current_plan && current_plan.user_quota > plan.user_quota
+          return false
+        end
+        super
+      end
+    end
+      
+## Provide a Customer to your controllers
+
+Billingly comes with 2 before filters for requiring the current user to be a customer, and
+requiring the current customer to be active (that is, to not be deactivated because of an expired trial, overdue invoices, etc). These methods are called `requires_customer` and `requires_active_customer` respectively.
+
+You provide a customer by overriding `current_customer` on your ApplicationController. Ideally, you would always have a `current_customer` as long as there is a user logged in, even if the currently logged in user has not subscribed to any plan yet. `current_customer` can return `nil` if no concept of a customer is available.
+
+The `requires_customer` before\_filter will call `on_empty_customer` when `current_customer` is `nil`. `on_empty_customer` simply redirects to your root_path but you can override it too.
+
+`requires_active_customer` redirects to the {Billingly::SubscriptionsController#index}, which presents the user with the steps required to reactivate his account.
+
+Continuing with the {https://github.com/plataformatec/devise Devise} compatible examples, here's a snippet that overrides `ApplicationController` to use the customer associated to a user.
+
+    class ApplicationController < ActionController::Base
+      def current_customer
+        current_user.customer
+      end
+    end
+
+`current_customer` is also available on your views as a helper method.
+
+## Customize the Controller
+
+The {Billingly::SubscriptionsController} can be overriden too. You may want to override {Billingly::SubscriptionsController#on\_subscription\_success #on\_subscription\_success} and {Billingly::SubscriptionsController#on\_reactivation\_success #on\_reactivation\_success}.
+
+These are called when your customer subscribes or reactivates his account, respectively.
+
+They both redirect to the `index` action by default.
+
+Here's a snippet overriding them to go to the root path with a flash notice.
+
+    # app/controller/custom_subscriptions_controller.rb
+    class CustomSubscriptionsController < Billingly::SubscriptionsController
+      def on_subscription_success
+        redirect_to root_path, notice: "yay, you subscribed!"
+      end
+
+      def on_reactivation_success
+        redirect_to root_path, notice: "yay, your account was reactivated!"
+      end
+    end
+
+## Mount Routes
+
+We provide a shortcut so you can add the {Billingly::SubscriptionsController SubscriptionsController} to your `routes.rb`.
+
+Here's a snippet showing two different ways of mounting the routes:
+
+    # your routes.rb
+    YourApp::Application.routes.draw do
+
+      # Will mount the default Billingly::SubscriptionsController in the /subscriptions path.
+      add_billingly_routes
+      
+      # Will mount CustomModule::CustomSubscriptionsController in the
+      # /namespaced/subscriptions path
+      add_billingly_routes 'namespaced', 'custom_module/custom_subscriptions_controller'
+    end
+
+## Schedule all the recurring jobs
+All the invoicing, deactivating and emailing is done through a rake task.
+
+The tasks are designed to fail gracefully and you can run them as often as you want without getting into undesired or invalid states. 
+
+Configure a cron job to run this around 4 times a day (should run without failures at least once a day)
+
+    $ rake billingly:all
+
+## Customize the SubscriptionsController templates
+
+Use the provided template generator to copy all of billingly's templates and partials into your application's directory structure.
+
+All templates are provided in Haml format, using Twitter Bootstrap compatible markup.
+
+These templates are used directly on the {http://billing.ly Demo App}
+
+    $ rails g billingly_views
+
+## Customize the mailer templates
+
+Billingly will send emails for the following scenarios:
+
+  * An invoice is available to be paid.
+  * An invoice is about to go overdue.
+  * A payment was processed successfully.
+
+You can copy all the built in templates into your app's directory structure and customize them:
+
+    $ rails g billingly_mailer_views

data/app/controllers/billingly/subscriptions_controller.rb

@@ -1,25 +1,23 @@
 # This controller takes care of managing subscriptions.
 class Billingly::SubscriptionsController < ::ApplicationController
-  before_filter :requires_customer, only: [:index, :reactivate]
-  before_filter :requires_active_customer, except: [:index, :reactivate]
+  before_filter :requires_customer
+  before_filter :requires_active_customer, except: [:index, :reactivate, :invoice]
 
   # Index shows the current subscription to customers while they are active.
   # It's also the page that prompts them to reactivate their account when deactivated.
   # It's likely the only reachable page for deactivated customers.
   def index
     @subscription = current_customer.active_subscription
-    redirect_to(action: :new) unless @subscription
-  end
-  
-  # Should let customers choose a plan to subscribe to, wheter they are subscribing
-  # for the first time or upgrading their plan.
-  def new
     @plans = Billingly::Plan.all
+    @invoices = current_customer.invoices.order('created_at DESC')
   end
-
+  
   # Subscribe the customer to a plan, or change his current plan.
   def create
     plan = Billingly::Plan.find(params[:plan_id])
+    unless current_customer.can_subscribe_to?(plan)
+      return redirect_to subscriptions_path, notice: 'Cannot subscribe to that plan'
+    end
     current_customer.subscribe_to_plan(plan)
     on_subscription_success
   end
@@ -29,20 +27,42 @@ class Billingly::SubscriptionsController < ::ApplicationController
   # Their account will be reactivated to their old subscription plan immediately.
   # They can change plans afterwards.
   def reactivate
-    return render nothing: true, status: 403 unless current_customer.reactivate
+    plan = Billingly::Plan.find_by_id(params[:plan_id])
+    if current_customer.reactivate(plan).nil?
+      return render nothing: true, status: 403
+    end
     on_reactivation_success
   end
+  
+  # Unsubscribes the customer from his last subscription and deactivates his account.
+  # Performing this action would set the deactivation reason to be 'left_voluntarily'
+  def deactivate
+    current_customer.deactivate_left_voluntarily
+    redirect_to(action: :index)
+  end
+  
+  # Shows an invoice.
+  # @todo
+  #   This should actually be the #show action of an InvoicesController but we're lazy ATM.
+  def invoice
+    @invoice = current_customer.invoices.find(params[:invoice_id])
+  end
 
   # When a subscription is sucessful this callback is triggered.
   # Host applications should override it by subclassing this subscriptionscontroller,
   # and include their own behaviour, and for example grant the privileges associated
   # to the subscription plan.
+  #
+  # Redirects to the last invoice by default.
   def on_subscription_success
-    redirect_to(action: :index) 
+    current_customer.reload
+    redirect_to(invoice_subscriptions_path(current_customer.active_subscription.invoices.last.id))
   end
   
+  # Should be overriden to provide a response when the user account is reactivated.
+  #
+  # Defaults to a redirect to :index 
   def on_reactivation_success
-    on_subscription_success
+    redirect_to(action: :index) 
   end
-  
 end

data/app/models/billingly/base_customer.rb

@@ -0,0 +1,306 @@
+require 'validates_email_format_of'
+
+module Billingly
+
+  # A {Customer} is Billingly's main actor.
+  # * Customers have a {Subscription} to your service which entitles them to use it.
+  # * Customers are {Invoice invoiced} regularly to pay for their {Subscription}
+  # * {Payment 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.
+  class BaseCustomer < ActiveRecord::Base
+    self.abstract_class = true
+    self.table_name = 'billingly_customers'
+
+    # The reason why this customer is deactivated.
+    # A customer can be deactivated for one of 3 reasons:
+    #   * trial_expired: Their trial period expired.
+    #   * debtor: They have unpaid invoices.
+    #   * left_voluntarily: They decided to leave the site.
+    # This is important when reactivating their account. If they left in their own terms,
+    # we won't try to reactivate their account when we receive a payment from them.
+    # The message shown to them when they reactivate will also be different depending on
+    # how they left.
+    DEACTIVATION_REASONS = [:trial_expired, :debtor, :left_voluntarily]
+
+    # The Date and Time in which the Customer's account was deactivated (see {#deactivated?}).
+    # This field denormalizes the date in which this customer's last subscription was ended.
+    # @!attribute [r] deactivated_since
+    # @return [DateTime] 
+    validates :deactivated_since, presence: true, if: :deactivation_reason
+
+    # (see Customer::DEACTIVATION_REASONS)
+    # @return [String] 
+    # @!attribute deactivation_reason
+    validates :deactivation_reason, inclusion: DEACTIVATION_REASONS, if: :deactivated?
+
+    # A customer can be {#deactivate deactivated} when they cancel their subscription
+    # or when they miss a payment. Under the hood this function checks the
+    # {#deactivated_since} attribute.
+    # @!attribute [r] deactivated?
+    def deactivated?
+      not deactivated_since.nil?
+    end
+  
+    # Used as contact address, validates format but does not check uniqueness.
+    # @!attribute email
+    # @return [String]
+    attr_accessible :email
+    validates_email_format_of :email
+    
+    # All subscriptions this customer was ever subscribed to.
+    # @!attribute subscriptions
+    # @return [Array<Subscription>]
+    has_many :subscriptions, foreign_key: 'customer_id'
+
+    # All paymetns that were ever credited for this customer
+    # @!attribute payments
+    # @return [Array<Payment>]
+    has_many :payments, foreign_key: 'customer_id'
+
+    # The {Subscription} for which the customer is currently being charged.
+    # @!attribute [r] active_subscription
+    # @return [Subscription, nil]
+    def active_subscription
+      last = subscriptions.last
+      last unless last.nil? || last.terminated?
+    end 
+    
+    # (see Customer.debtors)
+    # @!attribute [r] debtor?
+    # @return [Boolean] whether this customer is a debtor or not.
+    def debtor?
+      not self.class.debtors.find_by_id(self.id).nil?
+    end
+
+    # All {Invoice invoices} ever created for this customer, for any {Subscription}
+    # @!attribute invoices
+    # @return [Array<Invoice>]
+    has_many :invoices, foreign_key: 'customer_id'
+
+    # Every {JournalEntry} ever created for this customer, a {#ledger} is created from these.
+    # See {JournalEntry} for a description on what they are.
+    # @!attribute journal_entries
+    # @return [Array<JournalEntry>]
+    has_many :journal_entries, foreign_key: 'customer_id'
+
+    # (see Customer::DEACTIVATION_REASONS)
+    # @return [Symbol] 
+    # @!attribute deactivation_reason
+    validates :deactivation_reason, inclusion: DEACTIVATION_REASONS, if: :deactivated?
+
+    # Whether the user is on an unfinished trial period.
+    # @!attribute [r] doing_trial?
+    # @return [Boolean] 
+    def doing_trial?
+      active_subscription && active_subscription.trial?
+    end
+    
+    # When the user is doing a trial, this would be how many days are left until it's over.
+    # @!attribute [r] trial_days_left
+    # @return [Integer] 
+    def trial_days_left
+      return unless doing_trial?
+      (active_subscription.is_trial_expiring_on.to_date - Date.today).to_i
+    end
+    
+    # Customers subscribe to the service under certain conditions referred to as a {Plan},
+    # 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 {Plan Plans} from which a proper {Subscription} is created.
+    # A {Subscription} is also an acceptable argument, in that case the new one
+    # will maintain all the characteristics of that one, except the starting date.
+    # @param [Plan, Subscription] 
+    # @return [Subscription] The newly created {Subscription}
+    def subscribe_to_plan(plan, is_trial_expiring_on = nil) 
+      subscriptions.last.terminate if subscriptions.last
+
+      subscriptions.build.tap do |new|
+        [:payable_upfront, :description, :periodicity,
+         :amount, :grace_period].each do |k|
+          new[k] = plan[k]
+        end
+        new.plan = plan if plan.is_a?(Billingly::Plan)
+        new.is_trial_expiring_on = is_trial_expiring_on
+        new.subscribed_on = Time.now
+        new.save!
+        new.generate_next_invoice  
+        on_subscription_success
+      end
+    end
+
+    # Callback called whenever this customer is successfully subscribed to a plan.
+    # This callback does not differentiate if the customer is subscribing for the first time,
+    # reactivating his account or just changing from one plan to another.
+    # self.active_subscription will be the current subscription when this method is called.
+    def on_subscription_success
+    end
+    
+    # Creates a general ledger from {JournalEntry journal entries}.
+    # Every {Invoice} and {Payment} involves movements to the customer's account.
+    # which are registered as a {JournalEntry}.
+    # The ledger can tell us whats the cash balance
+    # in our customer's favor and how much money have they paid overall.
+    # @see JournalEntry
+    # @return [{Symbol => BigDecimal}]
+    # @todo Due to silly rounding errors on sqlite this implementation needs
+    #       to convert decimals to float and then to decimals again. :S
+    def ledger
+      Hash.new(0.0).tap do |all|
+        journal_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 {#journal_entries} for this customer.
+    # @note Most likely, you will never add entries to the customer journal yourself.
+    #       These are created when {Invoice invoicing} or crediting {Payment payments}
+    def add_to_journal(amount, *accounts, extra)
+      accounts = [] if accounts.nil?
+      unless extra.is_a?(Hash)
+        accounts << extra
+        extra = {}
+      end
+      
+      accounts.each do |account|
+        journal_entries.create!(extra.merge(amount: amount, account: account.to_s))
+      end
+    end
+    
+    # This method will deactivate all customers who have overdue {Invoice Invoices}.
+    # It's run periodically through Billingly's Rake Task.
+    def self.deactivate_all_debtors
+      debtors.where(deactivated_since: nil).all.each{|debtor| debtor.deactivate_debtor }
+    end
+    
+    # A customer who has overdue invoices at the time of asking this question is
+    # considered a debtor.
+    #
+    # @note
+    #   A customer may be a debtor and still have an active account until Billingly's
+    #   rake task goes through the process of {#deactivate_all_debtors deactivating all debtors}.
+    #
+    #   Furthermore, customers may unsubscribe before their {Invoice invoices} become overdue,
+    #   hence they may be in a deactivated state and not be debtors yet. 
+    def self.debtors
+       joins(:invoices).readonly(false)
+        .where("#{Billingly::Invoice.table_name}.due_on < ?", Time.now)
+        .where(billingly_invoices: {deleted_on: nil, paid_on: nil})
+    end
+
+    # Credits an amount of money to customer's account and then triggers the corresponding
+    # actions if a {Payment payment} was expected from this customer.
+    #
+    # Apart from creating a {Payment} object this method will try to charge pending invoices
+    # and reactivate a customer who was deactivated for being a debtor.
+    #
+    # @note
+    #   This is the single point of entry for {Payment Payments}.
+    #
+    #   If you're processing payments using {http://activemerchant.org} you should hook
+    #   your 'Incoming Payment Notifications' to call this method to credit the received
+    #   amount to the customer's account.
+    #
+    # @param amount [BigDecimal, float] the amount to be credited.
+    def credit_payment(amount)
+      Billingly::Payment.credit_for(self, amount)
+      Billingly::Invoice.charge_all(self.invoices)
+      reactivate if deactivated? && deactivation_reason == :debtor
+    end
+    
+    # Terminate a customer's subscription to the service.
+    # Customers are deactivated due to lack of payment, because they decide to end their
+    # subscription to your service or because their trial period expired.
+    #
+    # Use the shortcuts:
+    #   {#deactivate_left_voluntarily}, {#deactivate_trial_expired} or {#deactivate_debtor}
+    # 
+    # Deactivated customers can always be {#reactivate reactivated} later.
+    # @param reason [Symbol] the deactivation reason, see {DEACTIVATION_REASONS}
+    # @return [self, nil] nil if the account was already deactivated, self otherwise.
+    def deactivate(reason)
+      return if deactivated?
+      active_subscription.terminate
+      self.deactivated_since = Time.now
+      self.deactivation_reason = reason
+      self.save!
+      return self
+    end
+    
+    DEACTIVATION_REASONS.each do |reason|
+      define_method("deactivate_#{reason}") do
+        deactivate(reason.to_sym)
+      end
+    end
+
+    # @see #deactivate
+    def deactivate_left_voluntarily
+      deactivate(:left_voluntarily)
+    end
+    
+    # @see #deactivate
+    def deactivate_trial_expired
+      deactivate(:trial_expired)
+    end
+
+    # @see #deactivate
+    def deactivate_debtor
+      deactivate(:debtor)
+    end
+
+    # Customers whose account has been {#deactivate deactivated} can always re-join the service
+    # as long as they {#debtor? don't owe any money}
+    # @return [self, nil] nil if the customer could not be reactivated, self otherwise.
+    def reactivate(new_plan = nil)
+      new_plan = new_plan || subscriptions.last
+      return if new_plan.nil?
+      return unless deactivated?
+      return if debtor?
+      update_attribute(:deactivated_since, nil)
+      subscribe_to_plan(new_plan)
+      return self
+    end
+
+    # Customers may be subscribed for a trial period, and they are supposed to re-subscribe
+    # before their trial expires.
+    #
+    # When their trial expires and they have not yet subscribed to another plan, we
+    # deactivate their account immediately.
+    #
+    # This method will deactivate all customers whose trial has expired.
+    # It's run periodically through Billingly's Rake Task.
+    def self.deactivate_all_expired_trials
+       customers = joins(:subscriptions).readonly(false)
+        .where("#{Billingly::Subscription.table_name}.is_trial_expiring_on < ?", Time.now)
+        .where(billingly_subscriptions: {unsubscribed_on: nil})
+        
+      customers.each do |customer|
+        customer.deactivate_trial_expired
+      end
+    end
+
+    # Can this customer subscribe to a plan?.
+    # You may want to prevent customers from upgrading or downgrading to other plans
+    # depending on their usage of your service.
+    #
+    # This method is only used in views and controllers to prevent customers from requesting
+    # to be upgraded or downgraded to a plan without your consent.
+    # The model layer can still subscribe the customer if you so desire.
+    #
+    # The default implementation lets Customers upgrade to any if they are currently doing
+    # a trial period, and it does not let them re-subscribe to the same plan afterwards.
+    # It also always disallows debtors to subscribe to another plan.
+    # @param plan [Billingly::Plan]
+    def can_subscribe_to?(plan)
+      return false if !doing_trial? && active_subscription && active_subscription.plan == plan
+      return false if debtor?
+      return true
+    end
+  end
+end