freemium 0.0.1

data/.gitignore

@@ -0,0 +1,53 @@
+# yard generated
+doc
+.yardoc
+
+
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/public/
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+#
+# For TextMate
+#*.tmproj
+#tmtags
+#
+# For emacs:
+#*~
+#\#*
+#.\#*
+#
+# For vim:
+#*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in freemium.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,121 @@
+PATH
+  remote: .
+  specs:
+    freemium (0.0.1)
+      money
+      rails (~> 3.1.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ZenTest (4.6.2)
+    actionmailer (3.1.4)
+      actionpack (= 3.1.4)
+      mail (~> 2.3.0)
+    actionpack (3.1.4)
+      activemodel (= 3.1.4)
+      activesupport (= 3.1.4)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      i18n (~> 0.6)
+      rack (~> 1.3.6)
+      rack-cache (~> 1.1)
+      rack-mount (~> 0.8.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.0.3)
+    activemodel (3.1.4)
+      activesupport (= 3.1.4)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activerecord (3.1.4)
+      activemodel (= 3.1.4)
+      activesupport (= 3.1.4)
+      arel (~> 2.2.3)
+      tzinfo (~> 0.3.29)
+    activeresource (3.1.4)
+      activemodel (= 3.1.4)
+      activesupport (= 3.1.4)
+    activesupport (3.1.4)
+      multi_json (~> 1.0)
+    arel (2.2.3)
+    autotest (4.4.6)
+      ZenTest (>= 4.4.1)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
+    hike (1.2.1)
+    i18n (0.6.0)
+    json (1.6.5)
+    mail (2.3.0)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.17.2)
+    money (4.0.2)
+      i18n (~> 0.4)
+      json
+    multi_json (1.1.0)
+    polyglot (0.3.3)
+    rack (1.3.6)
+    rack-cache (1.1)
+      rack (>= 0.4)
+    rack-mount (0.8.3)
+      rack (>= 1.0.0)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.1.4)
+      actionmailer (= 3.1.4)
+      actionpack (= 3.1.4)
+      activerecord (= 3.1.4)
+      activeresource (= 3.1.4)
+      activesupport (= 3.1.4)
+      bundler (~> 1.0)
+      railties (= 3.1.4)
+    railties (3.1.4)
+      actionpack (= 3.1.4)
+      activesupport (= 3.1.4)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    rspec-rails (2.8.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec (~> 2.8.0)
+    sprockets (2.0.3)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.5)
+    sqlite3-ruby (1.3.3)
+      sqlite3 (>= 1.3.3)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.32)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  autotest
+  bundler (~> 1.1.rc.8)
+  freemium!
+  rspec-rails
+  sqlite3-ruby

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Lance Ivy
+
+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.rdoc

@@ -0,0 +1,67 @@
+= Freemium
+
+The Freemium plugin attempts to encapsulate the Right Way to offer service subscriptions. It is built to handle multiple subscription plans (free, premium, premium plus, etc.), let you control your own invoices, and to interact with any merchant gateway that supports either automated recurring billing or credit card storage.
+
+Freemium is a different beast from ActiveMerchant. Where the latter is optimized for one-off billing of credit cards (as in a retail environment), Freemium is optimized for storage and recurring billing of credit cards. This makes it a much cleaner and more complete solution for handling subscriptions. At the time of this writing, however, Freemium actually depends on ActiveMerchant because of its excellent CreditCard model, which I plan to steal.
+
+This plugin was born out of my attempts to figure out the correct way to handle subscriptions. I decided that the safest/cleanest way was to simply keep track of how far out the subscription had been paid, and when that date came near, bill the subscription again to extend the paid_through date. The approach has turned out well, I think, though I strongly encourage anyone and everyone to review the processes in this plugin to make sure the assumptions it makes are appropriate.
+
+= Gateway Requirements
+
+Rule #1: You never want to store credit card numbers yourself. This means that you need a gateway that either provides Automated Recurring Billing (ARB - a common offering) or credit card storage (e.g. TrustCommerce's Citadel).
+
+Freemium will work with any gateway that provides credit card storage (the preferred method!), but it will not work with every gateway that provides ARB. Just because your gateway provides ARB doesn't mean that your application can fire-and-forget; you still needs to know about successful transactions (to send invoices) and failed transactions (to send warnings and/or expire a subscription). In order for your _application_ to know about these events without your intervention, the ARB module either needs to send event notifications or it needs to provide an API to retrieve and review recent transactions.
+
+Freemium will only work with ARB modules that provide an API to retrieve and review recent transactions. This is by far the safest route, since most gateways only send email notifications that must be manually processed by a human (ugh!) and the others can have unreliable event notification systems (e.g. PayPal, see http://talklikeaduck.denhaven2.com/articles/2007/09/02/how-to-cure-the-paypal-subscription-blues). And in any case, ARB modules that send event notifications hardly ever tell you about successful transactions, so you still have to keep track of the periodic cycles so you can send invoices, which makes the whole ARB thing barely useful.
+
+So what we really need is a list of known good and known bad gateways. The list below is just the beginning, off the top of my head.
+
+=== Good Gateways:
+* TrustCommerce with Citadel (can use Citadel and/or ARB)
+* Braintree Payment Solutions (SecureVault, or ARB)
+
+=== Probably Good Gateways:
+* Authorize.net (CIM, or ARB if they also offer transaction review API)
+
+=== Bad Gateways:
+* LoudCommerce's LinkPoint (no storage, and no transaction review)
+
+= Expiration
+
+I've tried to build Freemium with the understanding that sometimes a cron task might not run, and if that happens the customers should not get screwed. That means, for example, not expiring a customer account just because a billing process didn't run. So the process for expiring a subscription is as follows: the first nightly billing process that runs _after_ a subscription's last paid day will set the final expiration date of that subscription. The final expiration date will be calculated as a certain number of days (the grace period) after the date of the billing process (grace begins when the program _knows_ the account is pastdue). The first billing process that runs on or after the expiration date will then actually expire the subscription.
+
+So there's some possible slack in the timeline. Suppose a subscription is paid through the 14th and there's a 2 day grace period. That means if a billing process runs on the 13th, then not until the 15th, the subscription will be set to expire on the 17th - the subscriber gets an extra day of grace because your billing process didn't run.
+
+= Misc
+* If there's no grace period then the same billing process will both set the expiration date and then actually expire the subscription, thanks to the order of events.
+* Expiring a subscription means downgrading it to a free plan (if any) or removing the plan altogether.
+
+= Install
+
+1) Generate and run the migration:
+
+  > ./script/generate freemium_migration
+  > rake db:migrate
+
+2) Populate the database with your subscription plan (create a migration to create SubscriptionPlan records)
+
+  > ./script/generate migration populate_subscription_plans
+
+3) Create config/initializers/freemium.rb and configure at least the following:
+
+  gateway         pick one, then see rdoc for your gateway's options to see what needs to be configured (api key, etc.)
+  billing_control set to :full or :arb, depending on whether you're using your gateway's ARB module
+  grace period    in days, zero days grace is ok
+  mailer          for customized invoices, etc.
+
+4) Create a SubscriptionsController (or similar) that does whatever it takes to get a unique billing key. This might mean storing the credit card (e.g. TrustCommerce Citadel) and/or setting up automated recurring billing, or getting the three keys from Amazon FPS. Most of these gateways don't have concrete API classes in Freemium yet. If you write a gateway, let me know and I'll include it.
+
+5) Create association from your User model (or whatever) to the Subscription model.
+
+6) Add a before_filter (or other logic) to properly enforce your premium plan. The filter should check that the User has an active Subscription to a SubscriptionPlan of the appropriate type.
+
+7) Add `/PATH/TO/DEPLOYED/APP/script/runner -e production Subscription.run_billing' to a daily cron task.
+
+8) Tell me how any of this could be improved. I want this plugin to make freemium billing dead-simple.
+
+Copyright (c) 2007 Lance Ivy, released under the MIT license

data/Rakefile

@@ -0,0 +1,23 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = Freemium::VERSION
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/autotest/discover.rb

@@ -0,0 +1,2 @@
+Autotest.add_discovery { "rails" }
+Autotest.add_discovery { "rspec2" }

data/config/locales/en.yml

@@ -0,0 +1,2 @@
+en:
+  hello: "Hello world"

data/freemium.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/freemium/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name = "freemium"
+  gem.summary = %Q{Subscription Saas}
+  gem.description = %Q{Subscription Saas, tests are green. Needs some refactoring.}
+  gem.email = "eagle.anton@gmail.com"
+  gem.homepage = "http://github.com/xn/freemium"
+  gem.authors = ["Anton Oryol","xn"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  spec.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  spec.add_development_dependency 'rspec', '> 1.2.3'
+  gem.add_dependency "rails", "~> 3.1.3"
+  gem.add_dependency "money"
+  gem.add_development_dependency "rspec-rails"
+  gem.add_development_dependency "bundler"
+  gem.add_development_dependency 'rspec-rails'
+  gem.add_development_dependency "autotest"
+  gem.add_development_dependency "sqlite3-ruby"
+  gem.add_development_dependency "bundler", "~> 1.1.rc.8"
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ["lib"]
+  gem.version       = Freemium::VERSION
+end

data/lib/freemium/address.rb

@@ -0,0 +1,18 @@
+module Freemium
+  # eventually, this should mimic ActiveMerchant's credit card object, with validation and errors, etc.
+  # for now it's just a dumb (and therefore untested) data structure.
+  class Address
+    attr_accessor :address1, :address2, :city, :state, :zip, :country, :email, :phone_number, :ip_address
+
+    # Allow :street to be used instead of :address1
+    alias_method :street,  :address1
+    alias_method :street=, :address1=
+
+    def initialize(options = {})
+      options.each do |key, value|
+        setter = "#{key}="
+        self.send(setter, value) if self.respond_to? setter
+      end
+    end
+  end
+end

data/lib/freemium/coupon.rb

@@ -0,0 +1,38 @@
+module Freemium
+  module Coupon
+
+    def self.included(base)
+      base.class_eval do
+        has_many :coupon_redemptions, :dependent => :destroy, :class_name => "CouponRedemption", :foreign_key => :coupon_id
+        has_many :subscriptions, :through => :coupon_redemptions
+        has_and_belongs_to_many :subscription_plans, :class_name => "SubscriptionPlan",
+          :join_table => :coupons_subscription_plans, :foreign_key => :coupon_id, :association_foreign_key => :subscription_plan_id
+
+        validates_presence_of :description, :discount_percentage
+        validates_inclusion_of :discount_percentage, :in => 1..100
+
+        before_save :normalize_redemption_key
+      end
+    end
+
+    def discount(rate)
+      rate * (1 - self.discount_percentage.to_f / 100)
+    end
+
+    def expired?
+      (self.redemption_expiration && Date.today > self.redemption_expiration) || (self.redemption_limit && self.coupon_redemptions.count >= self.redemption_limit)
+    end
+
+    def applies_to_plan?(subscription_plan)
+      return true if self.subscription_plans.blank? # applies to all plans
+      self.subscription_plans.include?(subscription_plan)
+    end
+
+    protected
+
+    def normalize_redemption_key
+      self.redemption_key.downcase! unless self.redemption_key.blank?
+    end
+
+  end
+end

data/lib/freemium/coupon_redemption.rb

@@ -0,0 +1,48 @@
+module Freemium
+  module CouponRedemption
+
+    def self.included(base)
+      base.class_eval do
+        belongs_to :subscription, :class_name => "Subscription"
+        belongs_to :coupon, :class_name => "Coupon"
+
+        before_create :set_redeemed_on
+
+        validates_presence_of :coupon
+        validates_presence_of :subscription
+        validates_uniqueness_of :coupon_id, :scope => :subscription_id, :message => "has already been applied"
+        validate :custom_validation, :on => :create
+      end
+    end
+
+    def expire!
+      self.update_attribute :expired_on, Date.today
+    end
+
+    def active?(date = Date.today)
+      expires_on ? date <= self.expires_on : true
+    end
+
+    def expires_on
+      return nil unless self.coupon.duration_in_months
+      self.redeemed_on + self.coupon.duration_in_months.months
+    end
+
+    def redeemed_on
+      self['redeemed_on'] || Date.today
+    end
+
+    protected
+
+    def set_redeemed_on
+      self.redeemed_on = Date.today
+    end
+
+    def custom_validation
+      errors.add :subscription,  "must be paid"             if self.subscription && !self.subscription.subscription_plan.paid?
+      errors.add :coupon,  "has expired"                    if self.coupon && (self.coupon.expired? || self.coupon.expired?)
+      errors.add :coupon,  "is not valid for selected plan" if self.coupon && self.subscription && !self.coupon.applies_to_plan?(self.subscription.subscription_plan)
+    end
+
+  end
+end