subscription_fu 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+Gemfile.lock
+pkg/*
+log

data/Gemfile

@@ -0,0 +1,16 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in galakei.gemspec
+gemspec
+
+group :development, :test do
+  gem 'rails'
+  gem 'sqlite3'
+  gem 'haml'
+  gem 'rspec', '>= 2.5.0'
+  gem 'rspec-rails'
+  gem 'shoulda-matchers'
+  gem 'factory_girl'
+  gem 'time_travel', '0.1.0'
+  gem 'webmock'
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Mobalean LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+# Subscriptions for Rails
+
+This gem helps with building services which have paid subscriptions. It includes the models to store subscription status, and provides integration with PayPal for paid subscriptions.
+
+## Assumptions
+
+SubscriptionFu makes the following assumptions on how subscriptions are used:
+
+ * There is a subscription subject, i.e. a user or some other object which needs a subscription in order to access your site. In the examples below we'll use "group".
+
+ * You have a subscription initiator, which is usually the user object. In the examples below we'll use "user"
+
+## Installation
+
+Add to your Gemfile:
+
+    gem 'subscription_fu', :git => "git://github.com/mobalean/subscription_fu.git"
+
+Run "bundle install".
+
+Then install the required files:
+
+    rails g subscription_fu:install
+
+## Configuration
+
+ 1. Edit config/initializers/subscription\_fu.rb (generated by the install generator)
+
+ 2. Add "needs\_subscription" to the subscription subject:
+
+        class Group < ActiveRecord::Base
+          needs_subscription
+          ...
+        end
+
+ 3. Create subscriptions and transactions controllers and views, for example see examples
+
+## General subscription flow
+
+ 1. The user starts the subscription process by selecting a plan (if multiple ones are available, otherwise you can skip this and just have a subscribe button). We assume you'll do that selection in SubscriptionsController#new.
+
+        link_to image_tag("https://www.paypal.com/ja_JP/JP/i/btn/btn_xpressCheckout.gif", :alt => "PayPal で決済を行う"), subscription_path, :method => :post
+
+ 2. The subscribe form posts to SubscriptionsController#create, which creates an inactive subscription and associated transaction, and finally redirects the user to a checkout URL:
+
+        @subscription = current_group.build_next_subscription("basic")
+        @subscription.save!
+        @transaction = @subscription.initiate_activation(current_user)
+        redirect_to @transaction.start_checkout(url_for(:action => :confirm, :controller => "transactions"), url_for(:action => :abort, :controller => "transactions"))
+
+ 3. If the transaction gets approved, the user will get back to TransactionsController#confirm. Otherwise she might not return or return to TransactionsController#abort.
+
+ 4. The TransactionsController#confirm is supposed to show the user a final confirmation screen before executing the transaction. To load a pending transaction, use a before filter like this:
+
+        before_filter :require_valid_transaction
+        def require_valid_transaction
+          @token = params[:token]
+          @transaction = current_group.pending_transaction(@token)
+          unless @transaction
+            logger.info("Invalid transaction for token: #{@token}")
+            flash[:error] = "Invalid transaction, please try again."
+            redirect_to root_path
+          end
+        end
+
+    The form would look like this: (HAML with simple_form)
+
+        = simple_form_for @transaction, :url => transaction_path do |f|
+          = hidden_field_tag :token, @token
+          .submit= f.button :submit, '申込む'
+
+ 5. The confirmation form posts to TransactionsController#update, which completes the transaction:
+
+        if @transaction.complete
+          flash[:notice] = "Sucessfully updated your subscription."
+        else
+          flash[:error] = "Transaction was not successfull, please try again."
+        end
+        redirect_to root_path
+
+That's it.
+
+## Using the subscriptions
+
+Once setup, your subscription subject (the group in our example) will get a couple new methods. To check whether or not it has a subscription, use:
+
+    group.active_subscription?
+
+For getting the group's plan, you can simply use:
+
+    group.subscription_plan
+
+Which will give you an instance of the subscription plan as defined in the initializer.
+
+For more details, see SubscriptionFu::Models
+

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+Bundler::GemHelper.install_tasks
+
+task :default => :spec
+RSpec::Core::RakeTask.new

data/app/models/subscription_fu/plan.rb

@@ -0,0 +1,43 @@
+class SubscriptionFu::Plan
+  include ActionView::Helpers::NumberHelper  # for number_to_currency
+  include Comparable
+
+  TAX = 0.05
+
+  attr_accessor :key
+  attr_accessor :price
+
+  def initialize(key, price, data)
+    self.key = key
+    self.price = price
+    data.each {|k,v| self.send("#{k}=", v) }
+  end
+
+  def human_name
+    I18n.t(key, :scope => [:subscription_fu, :plan, :options])
+  end
+
+  def human_price
+    number_to_currency(price_with_tax)
+  end
+
+  def free_plan?
+    price == 0
+  end
+
+  def price_with_tax
+    (price * (1.0 + TAX)).to_i
+  end
+
+  def price_tax
+    (price * TAX).to_i
+  end
+
+  def currency
+    "JPY"
+  end
+
+  def <=>(other)
+    price <=> other.price
+  end
+end

data/app/models/subscription_fu/subscription.rb

@@ -0,0 +1,117 @@
+class SubscriptionFu::Subscription < ActiveRecord::Base
+  set_table_name :subscriptions
+
+  AVAILABLE_CANCEL_REASONS = %w( update cancel timeout admin )
+
+  default_scope order("created_at ASC", "id ASC")
+
+  belongs_to :subject, :polymorphic => true
+  belongs_to :prev_subscription, :class_name => "SubscriptionFu::Subscription"
+  has_many :transactions, :class_name => "SubscriptionFu::Transaction"
+  has_many :next_subscriptions, :class_name => "SubscriptionFu::Subscription", :foreign_key => "prev_subscription_id"
+
+  validates :subject, :presence => true
+  validates :plan_key, :presence => true, :inclusion => SubscriptionFu.config.available_plans.keys, :on => :create
+  validates :starts_at, :presence => true
+  validates :billing_starts_at, :presence => true
+  validates :paypal_profile_id, :presence => true, :if => :activated_paid_subscription?
+  validates :cancel_reason, :presence => true, :inclusion => AVAILABLE_CANCEL_REASONS, :if => :canceled?
+
+  scope :activated, where("subscriptions.activated_at IS NOT NULL")
+  scope :current, lambda {|time| activated.where("subscriptions.starts_at <= ? AND (subscriptions.canceled_at IS NULL OR subscriptions.canceled_at > ?)", time, time) }
+
+  # TODO this should probably only take plan?key, prev_sub
+  def self.build_for_initializing(plan_key, start_time = Time.now, billing_start_time = start_time, prev_sub = nil)
+    new(:plan_key => plan_key, :starts_at => start_time, :billing_starts_at => billing_start_time, :prev_subscription => prev_sub)
+  end
+
+  def paid_subscription?
+    ! plan.free_plan? && ! sponsored?
+  end
+
+  def activated?
+    ! activated_at.blank?
+  end
+
+  def activated_paid_subscription?
+    activated? && paid_subscription?
+  end
+
+  def canceled?
+    ! canceled_at.blank?
+  end
+
+  def plan
+    SubscriptionFu.config.available_plans[self.plan_key]
+  end
+
+  def human_description
+    I18n.t(:description, :scope => [:subscription_fu, :subscription]) % {
+      :plan_name => plan.human_name,
+      :subject_desc => subject.human_description_for_subscription,
+      :price => plan.human_price }
+  end
+
+  # billing time data about the subscription
+
+  def next_billing_date
+    paypal_recurring_details[:next_billing_date]
+  end
+
+  def estimated_next_billing_date
+    p = last_billing_date
+    p.next_month unless p.nil?
+  end
+
+  def last_billing_date
+    paypal_recurring_details[:last_payment_date]
+  end
+
+  def successor_start_date(new_plan_name)
+    new_plan = SubscriptionFu.config.available_plans[new_plan_name]
+    if new_plan > self.plan
+      # higher plans always start immediately
+      Time.now
+    else
+      # otherwise they start with the next billing cycle
+      successor_billing_start_date
+    end
+  end
+
+  def successor_billing_start_date
+    # in case this plan was already canceled, this date takes
+    # precedence (there won't be a next billing time anymore).
+    canceled_at || next_billing_date || estimated_next_billing_date || Time.now
+  end
+
+  # billing API
+
+  def initiate_activation(admin)
+    gateway = (plan.free_plan? || sponsored?) ? 'nogw' : 'paypal'
+    transactions.create_activation(gateway, admin).tap do |t|
+      if prev_subscription
+        to_cancel = [prev_subscription]
+        to_cancel.push(*prev_subscription.next_subscriptions.where("subscriptions.id <> ?", self).all)
+        to_cancel.each {|s| s.initiate_cancellation(admin, t) }
+      end
+    end
+  end
+
+  def initiate_cancellation(admin, activation_transaction)
+    transactions.create_cancellation(admin, activation_transaction, self)
+  end
+
+  private
+
+  def paypal_recurring_details
+    @paypal_recurring_details ||= (paypal_profile_id.blank? ? {} : SubscriptionFu::Paypal.paypal.recurring_details(paypal_profile_id))
+  end
+
+  def convert_paypal_status(paypal_status)
+    case paypal_status
+    when "ActiveProfile"  then "complete"
+    when "PendingProfile" then "pending"
+    else "invalid"
+    end
+  end
+end

data/app/models/subscription_fu/transaction.rb

@@ -0,0 +1,131 @@
+class SubscriptionFu::Transaction < ActiveRecord::Base
+  set_table_name :subscription_transactions
+
+  belongs_to :subscription
+  belongs_to :initiator, :polymorphic => true
+  belongs_to :related_transaction, :class_name => "SubscriptionFu::Transaction"
+  has_many :related_transactions, :class_name => "SubscriptionFu::Transaction", :foreign_key => "related_transaction_id"
+
+  delegate :plan, :human_description, :starts_at, :billing_starts_at, :paypal_profile_id, :activated?, :canceled?, :cancel_reason, :to => :subscription, :prefix => :sub
+
+  validates :subscription, :presence => true
+  validates :initiator, :presence => true
+  validates :gateway, :presence => true, :inclusion => %w( paypal nogw )
+  validates :action, :presence => true, :inclusion => %w( activation cancellation )
+  validates :status, :presence => true, :inclusion => %w( initiated complete failed aborted )
+
+  scope :paypal, where(:gateway => "paypal")
+  scope :initiated, where(:status => "initiated")
+
+  def self.create_activation(gateway, initiator)
+    create!(:initiator => initiator, :gateway => gateway, :status => 'initiated', :action => "activation")
+  end
+
+  def self.create_cancellation(initiator, related_transaction, subscription)
+    gateway = subscription.paypal_profile_id.blank? ? 'nogw' : 'paypal'
+    create!(:initiator => initiator, :gateway => gateway, :status => 'initiated', :action => "cancellation", :related_transaction => related_transaction)
+  end
+
+  def initiator_email
+    initiator.email if initiator.respond_to?(:email)
+  end
+
+  # billing API
+
+  def needs_authorization?
+    gateway == "paypal" && action == "activation"
+  end
+
+  def start_checkout(return_url, cancel_url)
+    raise "start_checkout is only for activation" unless action == "activation"
+    raise "start_checkout is only for non-activated subscriptions" if sub_activated?
+    raise "start_checkout already called once, have a token" unless identifier.blank?
+    raise "start_checkout only available in initiated state, but: #{status}" unless status == "initiated"
+
+    send("start_checkout_#{gateway}", return_url, cancel_url)
+  end
+
+  def complete(opts = {})
+    raise "complete only available in initiated state, but: #{status}" unless status == "initiated"
+
+    success = true
+    begin
+      send("complete_#{action}_#{gateway}", opts)
+      update_attributes!(:status => "complete")
+    rescue Exception => err
+      if defined? ::ExceptionNotifier
+        data = (err.respond_to?(:data) ? err.data : {}).merge(:subscription => subscription.inspect, :transaction => self.inspect)
+        ::ExceptionNotifier::Notifier.background_exception_notification(err, :data => data).deliver
+      else
+        logger.warn(err)
+        logger.debug(err.backtrace.join("\n"))
+      end
+      update_attributes!(:status => "failed")
+      related_transactions.each { |t| t.abort }
+      success = false
+    end
+    success
+  end
+
+  def abort
+    raise "abort only available in initiated state, but: #{status}" unless status == "initiated"
+    update_attributes(:status => "aborted")
+    related_transactions.each { |t| t.abort }
+    true
+  end
+
+  private
+
+  def start_checkout_paypal(return_url, cancel_url)
+    token = SubscriptionFu::Paypal.paypal.start_checkout(return_url, cancel_url, initiator_email, sub_plan.price_with_tax, sub_plan.currency, sub_human_description)
+    update_attributes!(:identifier => token)
+    "#{SubscriptionFu.config.paypal_landing_url}?cmd=_express-checkout&token=#{CGI.escape(token)}"
+  end
+
+  def start_checkout_nogw(return_url, cancel_url)
+    update_attributes!(:identifier => SubscriptionFu.friendly_token)
+    return_url
+  end
+
+  def complete_activation_paypal(opts)
+    raise "did you call start_checkout first?" if identifier.blank?
+    raise "already activated" if sub_activated?
+
+    paypal_profile_id, paypal_status =
+      SubscriptionFu::Paypal.paypal.create_recurring(identifier, sub_billing_starts_at, sub_plan.price, sub_plan.price_tax, sub_plan.currency, sub_human_description)
+    subscription.update_attributes!(:paypal_profile_id => paypal_profile_id, :activated_at => Time.now)
+    complete_activation
+  end
+
+  def complete_activation_nogw(opts)
+    raise "already activated" if sub_activated?
+
+    subscription.update_attributes!(:activated_at => Time.now)
+    complete_activation
+  end
+
+  def complete_activation
+    related_transactions.each do |t|
+      t.complete(:effective => sub_starts_at, :reason => :update)
+    end
+  end
+
+  def complete_cancellation_paypal(opts)
+    # update the record beforehand, because paypal raises an error if
+    # the profile is already cancelled
+    complete_cancellation(opts)
+    SubscriptionFu::Paypal.paypal.cancel_recurring(sub_paypal_profile_id, sub_cancel_reason)
+  end
+
+  def complete_cancellation_nogw(opts)
+    complete_cancellation(opts)
+  end
+
+  def complete_cancellation(opts)
+    unless sub_canceled?
+      cancel_timestamp = opts[:effective] || Time.now
+      cancel_reason = opts[:reason] || :cancel
+      subscription.update_attributes!(:canceled_at => cancel_timestamp, :cancel_reason => cancel_reason.to_s)
+    end
+  end
+end

data/config/locales/en.yml

@@ -0,0 +1,7 @@
+en:
+  subscription_fu:
+    subscription:
+      description: "%{plan_name} subscription for %{subject_desc}, %{price} per month"
+      cancel_notes:
+        update: "Changed subscription plan"
+        cancel: "Subscription cancelled"

data/examples/routes.rb

@@ -0,0 +1,7 @@
+MyApp::Application.routes.draw do
+  resource :subscription
+  resource :transaction do
+    match 'confirm' => 'transactions#confirm'
+    match 'abort' => 'transactions#abort'
+  end
+end

data/examples/subscriptions_controller.rb

@@ -0,0 +1,12 @@
+class SubscriptionsController < ApplicationController
+  def new
+  end
+
+  def create
+    @subscription = current_group.build_next_subscription("basic")
+    @subscription.save!
+    @transaction = @subscription.initiate_activation(current_user)
+    redirect_to @transaction.start_checkout(url_for(:action => :confirm, :controller => "transactions"), url_for(:action => :abort, :controller => "transactions"))
+  end
+ 
+end

data/examples/transactions_controller.rb

@@ -0,0 +1,33 @@
+class TransactionsController < ApplicationController
+  before_filter :require_valid_transaction
+
+  def confirm
+  end
+
+  def abort
+    @transaction.abort
+    flash[:notice] = "Transaction aborted."
+    redirect_to root_path
+  end
+
+  def update
+    if @transaction.complete
+      flash[:notice] = "Sucessfully updated your subscription."
+    else
+      flash[:error] = "Transaction was not successfull, please try again."
+    end
+    redirect_to root_path
+  end
+
+  private
+
+  def require_valid_transaction
+    @token = params[:token]
+    @transaction = current_group.pending_transaction(@token)
+    unless @transaction
+      logger.info("Invalid transaction for token: #{@token}")
+      flash[:error] = "Invalid transaction, please try again."
+      redirect_to root_path
+    end
+  end
+end

data/lib/generators/subscription_fu/install_generator.rb

@@ -0,0 +1,23 @@
+require "rails/generators/active_record/migration"
+
+module SubscriptionFu
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      extend ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("../templates", __FILE__)
+      desc "Generates the migrations require for subscription_fu"
+
+      def create_migration_file
+        migration_template 'migration.rb', 'db/migrate/create_subscription_fu_tables.rb'
+      end
+      def copy_initializer
+        template 'initializer.rb', 'config/initializers/subscription_fu.rb'
+      end
+      def copy_language_file
+        template 'en.yml', 'config/locales/subscription_fu.en.yml'
+      end
+    end
+  end
+end

data/lib/generators/subscription_fu/templates/en.yml

@@ -0,0 +1,17 @@
+en:
+  subscription_fu:
+    subscription:
+      # description used for Paypal
+      description: "%{plan_name} subscription for %{subject_desc}, %{price} per month"
+      # cancel notes used as description for Paypal
+      cancel_notes:
+        update: "Changed subscription plan"
+        cancel: "Subscription cancelled"
+    plan:
+      options:
+        # match this section with the plan names you are using in
+        # config/initializers/subscription_fu.rb to get human readable names
+        profess: Professional
+        premium: Premium
+        basic: Basic
+        free: Free

data/lib/generators/subscription_fu/templates/initializer.rb

@@ -0,0 +1,24 @@
+<%= Rails.application.class.name %>.configure do
+
+  # change this to your PayPal API User ID
+  config.subscription_fu.paypal_api_user_id = "michae_1272617165_biz_api1.mobalean.com"
+  # change this to your PayPal API password
+  config.subscription_fu.paypal_api_pwd = "1272617171"
+  # change this to your PayPal API signature
+  config.subscription_fu.paypal_api_sig = "ATpPRKe6SEGaLcgDfFD-kBQgVsGuA9iFQwK6d4x6Qs4iti0XYRkZQl9Q"
+
+  # Your subscription plans. You'll need to add at least one plan.
+
+  # You can use a custom class for billing plans. The default is 
+  # SubscriptionFu::Plan, which you can use as the base for custom plans.
+  # Using your custom plan class allows you to further configure system
+  # parameters based on a selected plan.
+  #config.subscription_fu.plan_class_name = "MyPlan"
+
+  # The first parameter is an identifier for this plan. For non-free plans,
+  # the second parameter isthe price. If you would like to add custom plan 
+  # parameters, you can change the class used for plans (see above).
+  config.subscription_fu.add_free_plan 'free'
+  config.subscription_fu.add_plan 'basic', 1000
+  config.subscription_fu.add_plan 'premium', 5000
+end

data/lib/generators/subscription_fu/templates/migration.rb

@@ -0,0 +1,38 @@
+class CreateSubscriptionFuTables < ActiveRecord::Migration
+  def self.up
+    create_table "subscriptions", :force => true do |t|
+      t.references "subject",          :polymorphic => true
+      t.references "prev_subscription"
+      t.string     "plan_key",         :limit => 10, :null => false
+      t.boolean    "sponsored",                      :null => false, :default => false
+      t.string     "paypal_profile_id"
+      t.datetime   "starts_at",                      :null => false
+      t.datetime   "billing_starts_at",              :null => false
+      t.datetime   "activated_at"
+      t.datetime   "canceled_at"
+      t.string     "cancel_reason",     :limit => 10
+      t.timestamps
+    end
+
+    add_index "subscriptions", ["subject_id", "subject_type"]
+
+    create_table "subscription_transactions" do |t|
+      t.references "subscription",                 :null => false
+      t.references "initiator",                    :null => false, :polymorphic => true
+      t.string     "action",         :limit => 15, :null => false
+      t.string     "status",         :limit => 15, :null => false
+      t.string     "gateway",        :limit => 10, :null => false
+      t.string     "identifier"
+      t.references "related_transaction"
+      t.timestamps
+    end
+
+    add_index "subscription_transactions", ["identifier"]
+    add_index "subscription_transactions", ["subscription_id"]
+  end
+
+  def self.down
+    drop_table "subscriptions"
+    drop_table "subscription_transactions"
+  end
+end

data/lib/subscription_fu/config.rb

@@ -0,0 +1,36 @@
+module SubscriptionFu
+  class Config
+    attr_accessor :plan_class_name, :paypal_nvp_api_url, :paypal_api_user_id, :paypal_api_pwd, :paypal_api_sig, :paypal_landing_url
+    attr_reader :available_plans
+
+    def initialize
+      @available_plans = {}
+      @plan_class_name = "SubscriptionFu::Plan"
+      paypal_use_production!
+    end
+
+    def paypal_use_sandbox!
+      self.paypal_nvp_api_url = "https://api-3t.sandbox.paypal.com/nvp"
+      self.paypal_landing_url = "https://www.sandbox.paypal.com/cgi-bin/webscr"
+    end
+
+    def paypal_use_production!
+      self.paypal_nvp_api_url = "https://api-3t.paypal.com/nvp"
+      self.paypal_landing_url = "https://www.paypal.com/cgi-bin/webscr"
+    end
+
+    def add_plan(key, price, data = {})
+      available_plans[key] = plan_class.new(key, price, data)
+    end
+
+    def add_free_plan(key, data = {})
+      add_plan(key, 0, data)
+    end
+
+    private
+
+    def plan_class
+      plan_class_name.constantize
+    end
+  end
+end

data/lib/subscription_fu/engine.rb

@@ -0,0 +1,5 @@
+module SubscriptionFu
+  class Engine < ::Rails::Engine #:nodoc:
+  end
+end
+