servicemerchant 0.1.0

data/subscription_management/test/unit/subscription_management_test.rb

@@ -0,0 +1,40 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+require 'money'
+
+class SubscriptionManagementTest < Test::Unit::TestCase
+
+  def setup
+    @smc = SubscriptionManagement
+  end
+
+  def test_format_feature
+    feature = {'quantity' => 5, 'feature' => {'name'=> 'Quota', 'unit'=> 'Gigabyte'}}
+    assert_equal 'Quota: 5 Gigabytes', @smc.format_feature(feature)
+    feature = {'quantity' => 1, 'feature' => {'name'=> 'Quota', 'unit'=> 'Gigabyte'}}
+    assert_equal 'Quota: 1 Gigabyte', @smc.format_feature(feature)
+    feature = {'quantity' => 0, 'feature' => {'name'=> 'Quota', 'unit'=> 'Gigabyte'}}
+    assert_equal 'Quota: Unlimited', @smc.format_feature(feature)
+    feature = {'quantity' => 2, 'feature' => {'name'=> 'Users'}}
+    assert_equal 'Users: 2', @smc.format_feature(feature)
+    feature = {'feature' => {'name'=> 'SSL Encryption'}}
+    assert_equal 'SSL Encryption', @smc.format_feature(feature)
+  end
+
+  def test_format_periodicity
+    assert_equal 'twice a week', @smc.format_periodicity('0.5 w') 
+    assert_equal 'each month', @smc.format_periodicity('1 m')
+    assert_equal 'each 2 years', @smc.format_periodicity('2 y')
+    assert_equal 'each 42 days', @smc.format_periodicity('42 d')
+    assert_raise ArgumentError do; x = @smc.format_periodicity('random'); end;
+  end
+  
+  def test_get_taxes_id
+    taxes = {"ca"=>{"country"=>"CA", "taxes"=>[{"tax"=>{"name"=>"Goods and Services Tax"}, "rate"=>0.05}], "state"=>"*"},
+             "us_ca"=>{"country"=>"US", "taxes"=>[{"tax"=>{"name"=>"Sample tax"}, "rate"=>0.2}], "state"=>"CA"}}
+    assert_equal 'ca', @smc.get_taxes_id(taxes, 'CA', 'ON')
+    assert_equal 'us_ca', @smc.get_taxes_id(taxes, 'US', 'CA')
+    assert_raise StandardError do; x = @smc.get_taxes_id(taxes, 'US', 'NY'); end
+  end
+
+end

data/tracker/README

@@ -0,0 +1,12 @@
+See demo.rb as a starting point reference
+
+rake tracker:create_tables will create DB sctructure
+
+Dependencies
+============
+Ruby gems:
+ - activerecord
+ - activesupport >= 2.0.0
+ - activemerchant >= 1.3.2
+ - money
+ - sqlite3-ruby

data/tracker/Rakefile

@@ -0,0 +1,40 @@
+require 'rake'
+require File.dirname(__FILE__) + '/tasks/schema'
+
+require 'rake/testtask'
+namespace :test do
+
+  Rake::TestTask.new(:remote_tracker) do |t|
+    t.pattern = 'test/remote/**/*_test.rb'
+    t.ruby_opts << '-rubygems'
+    t.verbose = true
+  end
+
+  desc "Run all remote tests"
+  task :remote => [:remote_tracker]
+
+  Rake::TestTask.new(:unit_tracker) do |t|
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.ruby_opts << '-rubygems'
+    t.verbose = true
+  end
+
+  desc "Run all unit tests"
+  task :unit => [:unit_tracker]
+
+  task :rcov do
+    begin
+      require 'rcov/rcovtask'
+      Rcov::RcovTask.new do |t|
+        t.name = 'test'
+        t.libs << 'test'
+        t.test_files = FileList['test/**/**/*test.rb']
+        t.verbose = true
+        t.rcov_opts = ['-i', '^lib', '-x', 'recurring_billing']
+      end
+    rescue StandardError
+      # ignore missing rcov
+    end
+  end
+
+end

data/tracker/demo.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# This is a smoke test for Tracker component
+
+require 'tracker'
+puts "Verifying models classes..."
+Transaction
+RecurringPaymentProfile
+puts "Verifying DB..."
+require 'test/connection'
+Transaction.count
+RecurringPaymentProfile.find :first
+puts "All OK"

data/tracker/lib/models/recurring_payment_profile.rb

@@ -0,0 +1,134 @@
+class RecurringPaymentProfile < ActiveRecord::Base
+  # We cannot just use `table_name_prefix = "tracker_"' because it uses broken
+  # cattr_accessor and applies to all ActiveRecord::Base descendants when
+  # tracker is loaded from Subscription Manager
+  def self.table_name_prefix
+    "tracker_"
+  end
+  has_many :transactions
+
+  # Returns single payment amount (sum of net amount and taxes)
+  def amount
+    self.net_amount+self.taxes_amount
+  end
+
+  def money
+    Money.new(self.amount, self.currency)
+  end
+
+  # Sets net amount
+  def net_money=(x_amount)
+    self[:net_amount] = x_amount.cents
+    if !self[:currency].nil? && x_amount.currency != self[:currency]
+      raise ArgumentError, 'Cannot change currency. Please, clean it first'
+    end
+    self[:currency] = x_amount.currency
+  end
+
+  # Sets taxes amount
+  def taxes_money=(x_amount)
+    self[:taxes_amount] = x_amount.cents
+    if !self[:currency].nil? && x_amount.currency != self[:currency]
+      raise ArgumentError, 'Cannot change currency. Please, clean it first'
+    end
+    self[:currency] = x_amount.currency
+  end
+
+  # Parses card and set related fields. 
+  def parse_and_set_card(card, hint=nil)
+    self[:card_type] = card.type
+    number = card.number
+    default_hint = "#{card.first_name} #{card.last_name}, #{card.type.upcase}, #{mask_card_number(number)}, exp. #{card_exp_date(card)}"
+    self[:card_owner_memo] = (hint) ? hint : default_hint
+  end
+
+  # Masks card number (only last 4 digits are shown)
+  #
+  # Example:
+  # '031641616161' => 'XXXXXXXX6161'
+  def mask_card_number(number)
+    number.to_s.size < 5 ? number.to_s : (('X' * number.to_s[0..-5].length) + number.to_s[-4..-1])
+  end
+
+  # Returns formatted expiration date for given Card object
+  def card_exp_date(card)
+    '%04d-%02d' % [card.year, card.month]
+  end
+
+  # Returns formatted amount for current record
+  def money_formatted
+    '%.2f %s' % [self.amount/100.00, self.currency.upcase]
+  end
+
+  def net_money_formatted
+    '%.2f %s' % [self.net_amount/100.00, self.currency.upcase]
+  end
+
+  def taxes_money_formatted
+    '%.2f %s' % [self.taxes_amount/100.00, self.currency.upcase]
+  end
+
+  # Marks current profile as active and saves it
+  def set_profile_active_and_save!
+    self.status = 'active'
+    self.save
+  end
+
+  # Updates profile fields after it was UPDATEd via remote gateway
+  def set_profile_after_update!(amount, card, payment_options, recurring_options)
+
+    if amount
+      # Split amount into net/taxes
+      if payment_options.has_key?(:taxes_amount_included)
+        self.net_money = amount - payment_options[:taxes_amount_included]
+        self.taxes_money = payment_options[:taxes_amount_included]
+        payment_options.delete(:taxes_amount_included)
+      else
+        self.net_money = amount
+        self.taxes_amount = 0
+      end
+    end
+
+    self.parse_and_set_card(card) if card
+    self.subscription_name = payment_options[:subscription_name] if payment_options[:subscription_name]
+    unless (ro = recurring_options).empty?
+      self.pay_on_day_x = ro[:pay_on_day_x] unless ro[:pay_on_day_x].nil?
+    end
+    self.save
+  end
+
+  # Updates profile fields after it was INQUIREDd via remote gateway
+  def set_profile_after_inquiry!(result)
+    self.status = result['profile_status']
+    self.outstanding_balance = result['outstanding_balance'].cents
+    self.complete_payments_count = result['number_cycles_completed']
+    self.failed_payments_count = result['failed_payment_count']
+    self.remaining_payments_count = result['number_cycles_remaining']
+    self.last_synchronized_at = DateTime.now
+    self.save
+  end
+
+  # Updates given hash from current profile fields
+  def update_options_from_profile!(options)
+    options[:subscription_name] ||= self[:subscription_name]
+    options[:amount] ||= Money.new(self.amount, self[:currency])
+    options[:taxes_amount_included] ||= Money.new(self.taxes_amount, self[:currency])
+    options[:interval] ||= self[:periodicity]
+    options[:start_date] ||= (Date.new(self[:created_at].year,self[:created_at].month, self[:created_at].mday) + self[:trial_days].to_i)
+    unless options[:trial_days]
+      trial_days = options[:start_date] - Date.today
+      options[:trial_days] = trial_days if trial_days > 0
+    end
+    self[:complete_payments_count] = 0 unless self[:complete_payments_count].to_i > 0
+    options[:occurrences] = self[:total_payments_count] - self[:complete_payments_count]
+    options[:pay_on_day_x] ||= self[:pay_on_day_x]
+  end
+
+  # Marks profile as deleted
+  def mark_as_deleted!
+    self[:deleted_at] = Time.now
+    self[:status] = 'deleted'
+    self.save
+  end
+
+end

data/tracker/lib/models/transaction.rb

@@ -0,0 +1,19 @@
+class Transaction < ActiveRecord::Base
+  # We cannot just use `table_name_prefix = "tracker_"' because it uses broken
+  # cattr_accessor and applies to all ActiveRecord::Base descendants when
+  # tracker is loaded from Subscription Manager
+  def self.table_name_prefix
+    "tracker_"
+  end
+
+  belongs_to :recurring_payment_profile
+
+  def money
+    Money.new(self.amount, self.currency)
+  end
+
+  def money_formatted
+    '%.2f %s' % [self.amount/100.00, self.currency.upcase]
+  end
+
+end

data/tracker/lib/recurring_billing_extension.rb

@@ -0,0 +1,103 @@
+require File.dirname(__FILE__) + '/../../recurring_billing/lib/recurring_billing'
+
+module RecurringBilling
+  class RecurringBillingGateway
+
+    # Create recurring payment AND store it
+    def create_with_persist(amount, card, payment_options={}, recurring_options={})
+      if payment_id = create_without_persist(amount, card, payment_options, recurring_options)
+        profile = RecurringPaymentProfile.new
+        profile.gateway_reference = payment_id
+        profile.gateway = code().to_s.upcase
+        profile.subscription_name = payment_options[:subscription_name]
+
+        # Split amount into net/taxes
+        if payment_options.has_key?(:taxes_amount_included)
+          profile.net_money = amount - payment_options[:taxes_amount_included]
+          profile.taxes_money = payment_options[:taxes_amount_included]
+          payment_options.delete(:taxes_amount_included)
+        else
+          profile.net_money = amount
+          profile.taxes_amount = 0
+        end
+
+        profile.parse_and_set_card(card)
+        ro = recurring_options
+        profile.trial_days = trial_days = ro[:trial_days].nil? ? 0 : ro[:trial_days].to_i
+        profile.pay_on_day_x = ro[:pay_on_day_x] unless ro[:pay_on_day_x].nil?
+        start_date = ro[:start_date] - trial_days
+        if get_midnight(start_date) == get_midnight(DateTime.now)
+          profile.created_at = start_date
+        else
+          profile.created_at = get_midnight(start_date)
+        end
+        profile.periodicity = '%d %s' % parse_interval(ro[:interval])
+        if ro[:occurrences].nil?
+          profile.total_payments_count = get_occurrences(ro[:start_date] - trial_days, ro[:interval], ro[:end_date])
+        else
+          profile.total_payments_count = ro[:occurrences]
+        end
+        profile.set_profile_active_and_save!
+        return payment_id
+      end
+    end
+    alias_method_chain :create, :persist
+
+    # Update recurring payment AND its local info
+    def update_with_persist(billing_id, amount, card, payment_options={}, recurring_options={})
+      profile = RecurringPaymentProfile.find_by_gateway_reference(billing_id)
+      #TODO: change to custom error
+      raise StandardError, 'Cannot update a deleted profile (#{billing_id})' if profile.status == 'deleted'
+
+      if update_without_persist(billing_id, amount, card, payment_options, recurring_options)
+        profile.set_profile_after_update!(amount, card, payment_options, recurring_options)
+        return true
+      end
+    end
+    alias_method_chain :update, :persist
+
+    # Inquire about recurring payment AND update its info
+    def inquiry_with_persist(billing_id)
+      result = inquiry_without_persist(billing_id)
+      RecurringPaymentProfile.find_by_gateway_reference(billing_id).set_profile_after_inquiry!(result)
+      return result
+    end
+    alias_method_chain :inquiry, :persist
+
+    # Cancel recurring payment AND update its info
+    def delete_with_persist(billing_id)
+      if delete_without_persist(billing_id)
+        RecurringPaymentProfile.find_by_gateway_reference(billing_id).mark_as_deleted!
+        return true
+      end
+    end
+    alias_method_chain :delete, :persist
+
+    # Tells if update or recreate is needed
+    def can_update?(billing_id, options)
+      begin
+        options = self.class.separate_create_update_params_from_options(options)
+        can_update = correct_update?(billing_id, options[:amount], options[:card], options[:payment_options], options[:recurring_options])
+      rescue Exception
+        can_update = false
+      end
+    end
+
+    # Updates or if updating is impossible, recreates profile with specified billing_id
+    def update_or_recreate(billing_id, options)
+      if can_update?(billing_id, options)
+        options_separated = self.class.separate_create_update_params_from_options(options)
+        update(billing_id, options_separated[:amount], options_separated[:card], options_separated[:payment_options], options_separated[:recurring_options])
+        return billing_id
+      else
+        RecurringPaymentProfile.find_by_gateway_reference(billing_id).update_options_from_profile!(options)
+        options_separated = self.class.separate_create_update_params_from_options(options)
+        correct_create?(options_separated[:amount], options_separated[:card], options_separated[:payment_options], options_separated[:recurring_options])
+        delete(billing_id)
+        return create(options_separated[:amount], options_separated[:card], options_separated[:payment_options], options_separated[:recurring_options])
+      end
+      nil
+    end
+
+  end
+end

data/tracker/lib/recurring_billing_extension.rdoc

@@ -0,0 +1,34 @@
+
+== Tracker module methods
+Tracker module provides payment profiles local storage capability for simple CRUD
+API RecurringBilling is. As a result, every RecurringBilling action is accompanied by number of Tracker database operations.
+Tracker auto-includes RecurringBilling
+and replaces its create, update, inquiry and delete methods with its own extended implementations while re-aliasing old ones as
+XXX_without_persist. The usual behavior of replacement methods is to execute corresponding old RecurringBilling method and,
+on success, to store given or returned parameters into database. Extending the methods doesn't change the syntax. Also, several
+new methods are added to RecurringBilling class.
+
+=== Updating exising remote payment
+The update method of RecurringBilling is limited by design: if updating payment information on remote gateway is impossible
+with given set of options, update raises Exception (and quits). Given that the main reason of such behavior is that RecurringBilling
+instance methods are isolated from each other payment-wise, Tracker combination of storage and gateway interaction provides an additional
+option to handle such situations. If RecurringBilling returns an Exception (meaning update is impossible), the recurring payment on
+gateway is cancelled and another, with updated options is created instead. For example, that way limitations on changing
+:recurring_options could be overcame.
+
+Two related methods are available for this feature. Both use payment gateway reference ID (+billing_id+) and combined options
+hash (+options+) as parameters. Second parameter may be obtained from usual quad-element structure something like this:
+ options = {}
+ options[:amount] = amount
+ options[:card] = card
+ options.update(payment_options)
+ options.update(recurring_options)
+To check if recurring payment could be updated by usual RecurringBilling means, can_update? method is used. This check is integrated into
+update_or_recreate method that calls can_update? and then performs traditional update, or deletes and then re-creates the payment via gateway.
+For example:
+ ...
+ options = {:start_date => Date + 1337}
+ print 'Warning! The billing profile will be re-created} if gateway.can_update?(billing_id, options)
+ gateway.update_or_recreate(billing_id, options)
+ ...
+Please note that missing but required options for payment re-creation are calculated from database.

data/tracker/tasks/schema.rb

@@ -0,0 +1,66 @@
+namespace :tracker do
+  desc 'Create Tracker database tables'
+  task :create_tables => :connection do
+    ActiveRecord::Base.connection.create_table :tracker_recurring_payment_profiles, :force => true do |t|
+      t.column :gateway_reference,          :string, :unique => true
+      t.column :gateway,                    :string
+      t.column :subscription_name,          :text
+      t.column :description,                :text
+      t.column :currency,                   :string
+      t.column :net_amount,                 :integer, :null => false
+      t.column :taxes_amount,               :integer, :null => false
+      t.column :outstanding_balance,        :integer
+      t.column :total_payments_count,       :integer
+      t.column :complete_payments_count,    :integer
+      t.column :failed_payments_count,      :integer
+      t.column :remaining_payments_count,   :integer
+      t.column :periodicity,                :string
+      t.column :trial_days,                 :integer, :default => 0
+      t.column :pay_on_day_x,               :integer, :default => 0
+      t.column :status,                     :string
+      t.column :problem_status,             :string
+      t.column :card_type,                  :string
+      t.column :card_owner_memo,            :string
+      t.column :created_at,                 :datetime
+      t.column :updated_at,                 :datetime
+      t.column :deleted_at,                 :datetime
+      t.column :last_synchronized_at,       :datetime
+    end
+    ActiveRecord::Base.connection.add_index :tracker_recurring_payment_profiles, [ :gateway ], :name => 'ix_tracker_recurring_payment_profiles_gateway'
+    ActiveRecord::Base.connection.add_index :tracker_recurring_payment_profiles, [ :gateway_reference ], :unique => true, :name => 'uix_tracker_recurring_payment_profiles_gateway_reference'
+    ActiveRecord::Base.connection.create_table :tracker_transactions, :force => true do |t|
+      t.column :recurring_payment_profile_id, :integer
+      t.column :gateway_reference,            :string
+      t.column :currency,                     :string
+      t.column :amount,                       :integer
+      t.column :result_code,                  :string
+      t.column :result_text,                  :string
+      t.column :card_type,                    :string
+      t.column :card_owner_memo,              :string
+      t.column :created_at,                   :datetime
+      t.column :recorded_at,                  :datetime
+    end
+    ActiveRecord::Base.connection.add_index :tracker_transactions, [ :recurring_payment_profile_id ]
+  end
+
+  desc 'Drop Tracker database tables'
+  task :drop_tables => :connection do
+    ActiveRecord::Base.connection.drop_table :tracker_recurring_payment_profiles
+    ActiveRecord::Base.connection.drop_table :tracker_transactions
+  end
+
+  # Use Rails connection when appropriate or fallback to local test db
+  task :connection do
+    connected = false
+    begin
+      begin
+        connected = true if ActiveRecord::Base.connection
+      rescue ActiveRecord::ConenctionNotEstablished
+      end
+    rescue NameError # ActiveRecord not loaded
+    end
+    require File.dirname(__FILE__) + "/../test/connection" unless connected
+  end
+end
+
+