freemium 0.0.1

data/lib/freemium/credit_card.rb

@@ -0,0 +1,273 @@
+module Freemium
+  module CreditCard
+
+    CARD_COMPANIES = {
+      'visa'               => /^4\d{12}(\d{3})?$/,
+      'master'             => /^(5[1-5]\d{4}|677189)\d{10}$/,
+      'discover'           => /^(6011|65\d{2})\d{12}$/,
+      'american_express'   => /^3[47]\d{13}$/,
+      'diners_club'        => /^3(0[0-5]|[68]\d)\d{11}$/,
+      'jcb'                => /^3528\d{12}$/,
+      'switch'             => /^6759\d{12}(\d{2,3})?$/,
+      'solo'               => /^6767\d{12}(\d{2,3})?$/,
+      'dankort'            => /^5019\d{12}$/,
+      'maestro'            => /^(5[06-8]|6\d)\d{10,17}$/,
+      'forbrugsforeningen' => /^600722\d{10}$/,
+      'laser'              => /^(6304[89]\d{11}(\d{2,3})?|670695\d{13})$/
+    }
+
+    def self.included(base)
+      base.class_eval do
+        # Essential attributes for a valid, non-bogus creditcards
+        attr_accessor :number, :month, :year, :first_name, :last_name
+
+        # Required for Switch / Solo cards
+        attr_accessor :start_month, :start_year, :issue_number
+
+        # Optional verification_value (CVV, CVV2 etc). Gateways will try their best to
+        # run validation on the passed in value if it is supplied
+        attr_accessor :verification_value
+
+        attr_accessible :number, :month, :year, :first_name, :last_name, :start_month, :start_year, :issue_number, :verification_value, :card_type, :zip_code
+
+        has_one :subscription, :class_name => "Subscription"
+
+        before_validation :sanitize_data, :if => :changed?
+
+        validate :validate_card
+      end
+
+      base.extend(ClassMethods)
+    end
+
+    ##
+    ## Callbacks
+    ##
+
+    protected
+
+    def sanitize_data #:nodoc:
+      self.month = month.to_i
+      self.year  = year.to_i
+      self.number = number.to_s.gsub(/[^\d]/, "")
+      self.card_type.downcase! if card_type.respond_to?(:downcase)
+      self.card_type = self.class.card_type?(number) if card_type.blank?
+      self.display_number = display_number
+    end
+
+    public
+
+    ##
+    ## Class Methods
+    ##
+
+    module ClassMethods
+      # Returns true if it validates. Optionally, you can pass a card type as an argument and
+      # make sure it is of the correct type.
+      #
+      # References:
+      # - http://perl.about.com/compute/perl/library/nosearch/P073000.htm
+      # - http://www.beachnet.com/~hstiles/cardtype.html
+      def valid_number?(number)
+        valid_card_number_length?(number) &&
+          valid_checksum?(number)
+      end
+
+      # Regular expressions for the known card companies.
+      #
+      # References:
+      # - http://en.wikipedia.org/wiki/Credit_card_number
+      # - http://www.barclaycardbusiness.co.uk/information_zone/processing/bin_rules.html
+      def card_companies
+        CARD_COMPANIES
+      end
+
+      # Returns a string containing the type of card from the list of known information below.
+      # Need to check the cards in a particular order, as there is some overlap of the allowable ranges
+      #--
+      # TODO Refactor this method. We basically need to tighten up the Maestro Regexp.
+      #
+      # Right now the Maestro regexp overlaps with the MasterCard regexp (IIRC). If we can tighten
+      # things up, we can boil this whole thing down to something like...
+      #
+      #   def type?(number)
+      #     return 'visa' if valid_test_mode_card_number?(number)
+      #     card_companies.find([nil]) { |type, regexp| number =~ regexp }.first.dup
+      #   end
+      #
+      def card_type?(number)
+        card_companies.reject { |c,p| c == 'maestro' }.each do |company, pattern|
+          return company.dup if number =~ pattern
+        end
+
+        return 'maestro' if number =~ card_companies['maestro']
+
+        return nil
+      end
+
+      def last_digits(number)
+        number.to_s.length <= 4 ? number : number.to_s.slice(-4..-1)
+      end
+
+      def mask(number)
+        "XXXX-XXXX-XXXX-#{last_digits(number)}"
+      end
+
+      # Checks to see if the calculated type matches the specified type
+      def matching_card_type?(number, card_type)
+        card_type?(number) == card_type
+      end
+
+      private
+
+      def valid_card_number_length?(number) #:nodoc:
+        number.to_s.length >= 12
+      end
+
+      # Checks the validity of a card number by use of the the Luhn Algorithm.
+      # Please see http://en.wikipedia.org/wiki/Luhn_algorithm for details.
+      def valid_checksum?(number) #:nodoc:
+        sum = 0
+        for i in 0..number.length
+          weight = number[-1 * (i + 2), 1].to_i * (2 - (i % 2))
+          sum += (weight < 10) ? weight : weight - 9
+        end
+
+        (number[-1,1].to_i == (10 - sum % 10) % 10)
+      end
+
+    end
+
+    ##
+    ## From ActiveMerchant::Billing::CreditCard
+    ##
+
+    # Provides proxy access to an expiry date object
+    def expiration_date
+      unless self['expiration_date']
+        month_days = [nil,31,28,31,30,31,30,31,31,30,31,30,31]
+        begin
+          month_days[2] = 29 if Date.leap?(@year)
+          str = "#{month_days[@month]}/#{@month}/#{@year} 23:59:59"
+          self['expiration_date'] = Time.parse(str)
+        end
+      end
+      self['expiration_date']
+    end
+
+    def expired?
+      return false unless expiration_date
+      Time.now > expiration_date
+    end
+
+    def name?
+      first_name? && last_name?
+    end
+
+    def first_name?
+      !@first_name.blank?
+    end
+
+    def last_name?
+      !@last_name.blank?
+    end
+
+    def name
+      "#{@first_name} #{@last_name}"
+    end
+
+    # Show the card number, with all but last 4 numbers replace with "X". (XXXX-XXXX-XXXX-4338)
+    def display_number
+      self['display_number'] ||= self.class.mask(number)
+      self['display_number']
+    end
+
+    def last_digits
+      self.class.last_digits(number)
+    end
+
+    def address
+      unless @address
+        @address = Address.new
+        @address.zip = self.zip_code
+      end
+      @address
+    end
+
+    ##
+    ## Overrides
+    ##
+
+    # We're overriding AR#changed? to include instance vars that aren't persisted to see if a new card is being set
+    def changed?
+      card_type_changed? || [:number, :month, :year, :first_name, :last_name, :start_month, :start_year, :issue_number, :verification_value].any? {|attr| !self.send(attr).nil?}
+    end
+
+    ##
+    ## Validation
+    ##
+
+    def validate_card
+      # We don't need to run validations unless it's a new record or the
+      # record has changed
+      return unless new_record? || changed?
+
+      validate_essential_attributes
+
+      # Bogus card is pretty much for testing purposes. Lets just skip these extra tests if its used
+      return if card_type == 'bogus'
+
+      validate_card_type
+      validate_card_number
+      validate_switch_or_solo_attributes
+    end
+
+    private
+
+    def validate_card_number #:nodoc:
+      errors.add :number, "is not a valid credit card number" unless self.class.valid_number?(number)
+      unless errors[:number] || errors[:type]
+        errors.add :card_type, "is not the correct card type" unless self.class.matching_card_type?(number, card_type)
+      end
+    end
+
+    def validate_card_type #:nodoc:
+      errors.add :card_type, "is required" if card_type.blank?
+      errors.add :card_type, "is invalid"  unless self.class.card_companies.keys.include?(card_type)
+    end
+
+    def validate_essential_attributes #:nodoc:
+      errors.add :first_name, "cannot be empty"      if @first_name.blank?
+      errors.add :last_name,  "cannot be empty"      if @last_name.blank?
+      errors.add :month,      "is not a valid month" unless valid_month?(@month)
+      errors.add :year,       "expired"              if expired?
+      errors.add :year,       "is not a valid year"  unless valid_expiration_year?(@year)
+    end
+
+    def validate_switch_or_solo_attributes #:nodoc:
+      if %w[switch solo].include?(card_type)
+        unless valid_month?(@start_month) && valid_start_year?(@start_year) || valid_issue_number?(@issue_number)
+          errors.add :start_month,  "is invalid"      unless valid_month?(@start_month)
+          errors.add :start_year,   "is invalid"      unless valid_start_year?(@start_year)
+          errors.add :issue_number, "cannot be empty" unless valid_issue_number?(@issue_number)
+        end
+      end
+    end
+
+    def valid_month?(month)
+      (1..12).include?(month)
+    end
+
+    def valid_expiration_year?(year)
+      (Time.now.year..Time.now.year + 20).include?(year)
+    end
+
+    def valid_start_year?(year)
+      year.to_s =~ /^\d{4}$/ && year.to_i > 1987
+    end
+
+    def valid_issue_number?(number)
+      number.to_s =~ /^\d{1,2}$/
+    end
+  end
+end

data/lib/freemium/feature_set.rb

@@ -0,0 +1,45 @@
+module Freemium
+  class FeatureSet
+
+    def initialize(hash = {})
+      hash.each do |key, value|
+        self.class.class_eval { attr_accessor key.intern }
+        self.send("#{key}=", value)
+      end
+    end
+  
+    def method_missing(method, *args, &block)
+      # forward named routes
+      if method.to_s.include? '?'
+        send(method.to_s[0..-2], *args, &block)
+      else
+        super
+      end
+    end
+ 
+    def self.find(id)
+      self.feature_sets[id.to_s]
+    end
+ 
+    protected
+
+    cattr_accessor :config_file
+    def self.config_file
+      @@config_file ||= File.join(RAILS_ROOT, 'config', 'freemium_feature_sets.yml')
+    end
+
+    cattr_accessor :feature_sets
+    self.feature_sets = nil
+ 
+    def self.feature_sets
+      if @@feature_sets.nil?
+        @@feature_sets = {}
+        YAML::load(File.read(self.config_file)).each do |features| 
+          feature_set = FeatureSet.new(features)
+          @@feature_sets[feature_set.id] = feature_set
+        end
+      end
+      @@feature_sets
+    end
+  end
+end

data/lib/freemium/gateways/base.rb

@@ -0,0 +1,65 @@
+module Freemium
+  module Gateways
+    class Base #:nodoc:
+      superclass_delegating_accessor :open_timeout
+      self.open_timeout = 60
+
+      superclass_delegating_accessor :read_timeout
+      self.read_timeout = 60
+
+      # cancels the subscription identified by the given billing key.
+      # this might mean removing it from the remote system, or halting the remote
+      # recurring billing.
+      #
+      # should return a Freemium::Response
+      def cancel(billing_key)
+        raise MethodNotImplemented
+      end
+
+      # stores a credit card with the gateway.
+      # should return a Freemium::Response
+      def store(credit_card, address = nil)
+        raise MethodNotImplemented
+      end
+
+      # updates a credit card in the gateway.
+      # should return a Freemium::Response
+      def update(billing_key, credit_card = nil, address = nil)
+        raise MethodNotImplemented
+      end
+
+      # validates a credit card with the gateway.
+      # should return a Freemium::Response
+      def validate(credit_card, address = nil)
+        raise MethodNotImplemented
+      end
+
+      ##
+      ## Only needed to support Freemium.billing_handler = :gateway
+      ##
+
+      # only needed to support an ARB module. otherwise, the manual billing process will
+      # take care of processing transaction information as it happens.
+      #
+      # concrete classes need to support these options:
+      #   :billing_key : - only retrieve transactions for this specific billing key
+      #   :after :       - only retrieve transactions after this datetime (non-inclusive)
+      #   :before :      - only retrieve transactions before this datetime (non-inclusive)
+      #
+      # return value should be a collection of Freemium::Transaction objects.
+      def transactions(options = {})
+        raise MethodNotImplemented
+      end
+
+      ##
+      ## Only needed to support Freemium.billing_handler = :manual
+      ##
+
+      # charges money against the given billing key.
+      # should return a Freemium::Transaction
+      def charge(billing_key, amount)
+        raise MethodNotImplemented
+      end
+    end
+  end
+end

data/lib/freemium/gateways/brain_tree.rb

@@ -0,0 +1,175 @@
+require 'net/http'
+require 'net/https'
+module Freemium
+  module Gateways
+    # = Setup and Configuration
+    # In your config/initializers/freemium.rb, configure Freemium to use BrainTree:
+    #
+    #   Freemium.gateway = Freemium::Gateways::BrainTree.new
+    #   Freemium.gateway.username = "my_username"
+    #   Freemium.gateway.password = "my_password"
+    #
+    # Note that if you want to use demo/password credentials when not in production mode, this is the place.
+    #
+    # = Data Structures
+    # All amounts should use the Money class (from eponymous gem).
+    # All credit cards should use Freemium::CreditCard class (currently just an alias for ActiveMerchant::Billing::CreditCard).
+    # All addresses should use Freemium::Address class.
+    #
+    # = For Testing
+    # The URL does not change. If your account is in test mode, no charges will be processed. Otherwise,
+    # configure the username and password to be "demo" and "password", respectively.
+    class BrainTree < Base
+      URL = 'https://secure.braintreepaymentgateway.com/api/transact.php'
+      attr_accessor :username, :password
+
+      # using BrainTree's recurring billing is not possible until I have their reporting API
+      #def transactions(options = {}); end
+
+      # Stores a card in SecureVault.
+      def store(credit_card, address = nil)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => "add_customer"
+        })
+        p.params.merge! params_for_credit_card(credit_card)
+        p.params.merge! params_for_address(address)         if address
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Updates a card in SecureVault.
+      def update(vault_id, credit_card = nil, address = nil)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => "update_customer",
+          :customer_vault_id => vault_id
+        })
+        p.params.merge! params_for_credit_card(credit_card) if credit_card
+        p.params.merge! params_for_address(address)         if address
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Manually charges a card in SecureVault. Called automatically as part of manual billing process.
+      def charge(vault_id, amount)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault_id => vault_id,
+          :amount => sprintf("%.2f", amount.cents.to_f / 100)
+        })
+        p.commit(open_timeout, read_timeout)
+        transaction = AccountTransaction.new(:billing_key => vault_id, :amount => amount, :success => p.response.success?)
+        transaction.response = p.response if transaction.respond_to?(:response=)
+        return transaction
+      end
+
+      # Removes a card from SecureVault. Called automatically when the subscription expires.
+      def cancel(vault_id)
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :customer_vault => 'delete_customer',
+          :customer_vault_id => vault_id
+        })
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      # Validates the card.
+      def validate(credit_card, address = nil)
+        # Assume we validated if we're using a demo account
+        return Freemium::Response.new(true) if self.username == 'demo'
+
+        p = Post.new(URL, {
+          :username => self.username,
+          :password => self.password,
+          :type => 'validate'
+        })
+        p.params.merge! params_for_credit_card(credit_card)
+        if address
+          p.params.merge! params_for_address(address)
+        end
+
+        p.commit(open_timeout, read_timeout)
+        return p.response
+      end
+
+      protected
+      def params_for_credit_card(card)
+        params = {
+          :payment   => 'creditcard',
+          :firstname => card.first_name,
+          :lastname  => card.last_name,
+          :ccnumber  => card.number,
+          :ccv       => card.verification_value,
+          :ccexp     => ["%.2i" % card.month, ("%.4i" % card.year)[-2..-1]].join # MMYY
+        }
+      end
+
+      def params_for_address(address)
+        params = {
+          :email     => address.email,
+          :address1  => address.address1,
+          :address2  => address.address2,
+          :city      => address.city,
+          :state     => address.state, # TODO: two-digit code!
+          :zip       => address.zip,
+          :country   => address.country, # TODO: two digit code! (ISO-3166)
+          :phone     => address.phone_number,
+          :ipaddress => address.ip_address
+        }
+      end
+
+      class Post
+        attr_accessor :url
+        attr_accessor :params
+        attr_reader :response
+
+        def initialize(url, params = {})
+          self.url = url
+          self.params = params
+        end
+
+        def commit(open_timeout, read_timeout)
+          data = parse(post(open_timeout, read_timeout))
+          # from BT API: 1 means approved, 2 means declined, 3 means error
+          success = data['response'].to_i == 1
+          @response = Freemium::Response.new(success, data)
+          @response.billing_key = data['customer_vault_id']
+          @response.message = data['responsetext']
+          return self
+        end
+
+        protected
+
+        # BrainTree returns a body of parameters in GET query format, so convert that into a simple hash.
+        def parse(data)
+          {}.tap do |results|
+            data.split('&').each do |pair|
+              key, value = pair.split('=', 2).collect { |v| CGI::unescape(v) }
+              results[key] = value
+            end
+          end
+        end
+
+        # cf. ActiveMerchant's PostsData module.
+        def post(open_timeout, read_timeout)
+          uri = URI.parse(self.url)
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = open_timeout
+          http.read_timeout = read_timeout
+          http.use_ssl      = true
+          http.verify_mode  = OpenSSL::SSL::VERIFY_NONE
+
+          data = self.params.collect { |k, v| "#{k}=#{CGI.escape(v.to_s)}" }.join("&")
+          http.post(uri.request_uri, data).body
+        end
+      end
+    end
+  end
+end

data/lib/freemium/gateways/test.rb

@@ -0,0 +1,34 @@
+module Freemium
+  module Gateways
+    class Test < Base
+      def transactions(options = {})
+        options
+      end
+
+      def charge(*args)
+        args
+      end
+
+      def store(*args)
+        response = Freemium::Response.new(true)
+        response.billing_key = Time.now.to_i.to_s
+        response
+      end
+
+      def update(billing_key, *args)
+        response = Freemium::Response.new(true)
+        response.billing_key = billing_key
+        response
+      end
+
+      def cancel(*args)
+        args
+      end
+
+      def validate(*args)
+        response = Freemium::Response.new(true)
+        response
+      end
+    end
+  end
+end

data/lib/freemium/manual_billing.rb

@@ -0,0 +1,73 @@
+module Freemium
+  # adds manual billing functionality to the Subscription class
+  module ManualBilling
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # Override if you need to charge something different than the rate (ex: yearly billing option)
+    def installment_amount(options = {})
+      self.rate(options)
+    end
+
+    # charges this subscription.
+    # assumes, of course, that this module is mixed in to the Subscription model
+    def charge!
+      # Save the transaction immediately
+
+      @transaction = gateway.charge(billing_key, self.installment_amount)
+      self.transactions << @transaction
+      self.last_transaction_at = Time.now # TODO this could probably now be inferred from the list of transactions
+      self.last_transaction_success = @transaction.success?
+
+      self.save(:validate => false)
+
+      begin
+        if @transaction.success?
+          receive_payment!(@transaction)
+        elsif !@transaction.subscription.in_grace?
+          expire_after_grace!(@transaction)
+        end
+      rescue
+      end
+
+      @transaction
+    end
+
+    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 if last_transaction_success
+        self.credit_card.reload # to prevent needless subsequent store() calls
+      end
+    end
+
+    module ClassMethods
+      # the process you should run periodically
+      def run_billing
+        # charge all billable subscriptions
+        @transactions = find_billable.collect{|b| b.charge!}
+        # actually expire any subscriptions whose time has come
+        expire
+
+        # send the activity report
+        Freemium.mailer.deliver_admin_report(
+          @transactions # Add in transactions
+        ) if Freemium.admin_report_recipients && !@transactions.empty?
+
+        @transactions
+      end
+
+      protected
+
+      # a subscription is due on the last day it's paid through. so this finds all
+      # subscriptions that expire the day *after* the given date.
+      # because of coupons we can't trust rate_cents alone and need to verify that the account is indeed paid?
+      def find_billable
+        self.paid.due.select{|s| s.paid?}
+      end
+    end
+  end
+end

data/lib/freemium/railtie.tb

@@ -0,0 +1,7 @@
+require 'freemium'
+require 'rails'
+
+module Freemium
+  class Railtie < Rails::Railtie
+  end
+end