merchant_sidekick 0.4.2

data/lib/merchant_sidekick/railtie.rb

@@ -0,0 +1,7 @@
+module MerchantSidekick
+  class Railtie < ::Rails::Railtie
+    generators do
+      require File.expand_path("../install.rb", __FILE__)
+    end
+  end
+end

data/lib/merchant_sidekick/sales_invoice.rb

@@ -0,0 +1,56 @@
+# Implements inbound invoices, i.e. the merchant sells a product to a client.
+module MerchantSidekick
+  class SalesInvoice < Invoice
+    #--- associations
+    #has_many :sales_orders, :class_name => "MerchantSidekick::SalesOrder"
+
+    #--- instance methods
+
+    def sales_invoice?
+      true
+    end
+
+    # cash invoice, combines authorization and capture in one step
+    def cash(payment_object, options={})
+      transaction do
+        cash_result = MerchantSidekick::Payment.class_for(payment_object).transfer(
+          gross_total,
+          payment_object,
+          payment_options(options)
+        )
+        self.push_payment(cash_result)
+
+        save(:validate => false)
+
+        if cash_result.success?
+          payment_paid!
+        else
+          transaction_declined!
+        end
+        cash_result
+      end
+    end
+
+    # returns a hash of additional merchant data passed to authorize
+    # you want to pass in the following additional options
+    #
+    #   :ip => ip address of the buyer
+    #
+    def payment_options(options={})
+      { # general
+        :buyer => self.buyer,
+        :seller => self.seller,
+        :payable => self,
+        # active merchant relevant
+        :customer => "#{self.seller.name} (#{self.seller.id})",
+        :email => self.seller && self.seller.respond_to?(:email) ? self.seller.email : nil,
+        :invoice => self.number,
+        :merchant => self.buyer ? "#{self.buyer.name} (#{self.buyer.id})" : nil,
+        :currency => self.currency,
+        :billing_address => self.billing_address ? self.billing_address.to_merchant_attributes : nil,
+        :shipping_address =>  self.shipping_address ? self.shipping_address.to_merchant_attributes : nil
+      }.merge(options)
+    end
+
+  end
+end

data/lib/merchant_sidekick/sales_order.rb

@@ -0,0 +1,122 @@
+# Implements inbound orders, i.e. when merchant sells a product.
+module MerchantSidekick
+  class SalesOrder < Order
+    belongs_to :sales_invoice, :foreign_key => :invoice_id, :class_name => "::MerchantSidekick::SalesInvoice"
+
+    # Cash the order and generate invoice
+    def cash(payment_object, options={})
+      defaults = { :order_id => number }
+      options = defaults.merge(options).symbolize_keys
+
+      # before_payment
+      seller.send( :before_payment, self ) if seller && seller.respond_to?( :before_payment )
+
+      self.build_addresses
+      self.build_invoice unless self.invoice
+
+      payment = self.invoice.cash(payment_object, options)
+      if payment.success?
+        process_payment!
+        approve_payment!
+      end
+
+      # after_payment
+      buyer.send( :after_payment, self ) if buyer && buyer.respond_to?( :after_payment )
+      payment
+    end
+
+    def sales_order?
+      true
+    end
+
+    # used in build_invoice to determine which type of invoice
+    def to_invoice_class_name
+      "MerchantSidekick::SalesInvoice"
+    end
+
+    def invoice
+      self.sales_invoice
+    end
+
+    def invoice=(an_invoice)
+      self.sales_invoice = an_invoice
+    end
+
+    def build_invoice #:nodoc:
+      new_invoice = self.build_sales_invoice(
+        :line_items => self.line_items,
+        :net_amount => self.net_total,
+        :tax_amount => self.tax_total,
+        :gross_amount => self.gross_total,
+        :buyer => self.buyer,
+        :seller => self.seller,
+        :origin_address => self.origin_address ? self.origin_address.dup : nil,
+        :billing_address => self.billing_address ? self.billing_address.dup : nil,
+        :shipping_address => self.shipping_address ? self.shipping_address.dup : nil
+      )
+
+      # set new invoice's line items to invoice we just created
+      new_invoice.line_items.each do |li|
+        if li.new_record?
+          li.invoice = new_invoice
+        else
+          li.update_attribute(:invoice, new_invoice)
+        end
+      end
+
+      # copy addresses
+      new_invoice.build_origin_address(self.origin_address.content_attributes) if self.origin_address
+      new_invoice.build_billing_address(self.billing_address.content_attributes) if self.billing_address
+      new_invoice.build_shipping_address(self.shipping_address.content_attributes) if self.shipping_address
+
+      self.invoice = new_invoice
+
+      new_invoice
+    end
+
+    # Builds billing, shipping and origin addresses
+    def build_addresses(options={})
+      raise ArgumentError.new("No address declared for buyer (#{buyer.class.name} ##{buyer.id}), use acts_as_addressable") \
+        unless buyer.respond_to?(:find_default_address)
+
+      # buyer's billing address
+      unless self.default_billing_address
+        if buyer.respond_to?(:billing_address) && buyer.default_billing_address
+          self.build_billing_address(buyer.default_billing_address.content_attributes)
+        else
+          if buyer_default_address = buyer.find_default_address
+            self.build_billing_address(buyer_default_address.content_attributes)
+          else
+            raise ArgumentError.new(
+              "No billing or default address found for buyer (#{buyer.class.name} ##{buyer.id}), use acts_as_addressable")
+          end
+        end
+      end
+
+      # buyer's shipping address is optional
+      if buyer.respond_to?(:shipping_address)
+        self.build_shipping_address(buyer.find_shipping_address_or_clone_from(
+          self.billing_address
+        ).content_attributes) unless self.default_shipping_address
+      end
+
+      # seller's address for origin address
+      raise ArgumentError.new("No address declared for seller (#{seller.class.name} ##{seller.id}), use acts_as_addressable") \
+        unless seller.respond_to?(:find_default_address)
+
+      unless default_origin_address
+        if seller.respond_to?(:billing_address) && seller.default_billing_address
+          self.build_origin_address(seller.default_billing_address.content_attributes)
+        else
+          if seller_default_address = seller.find_default_address
+            self.build_origin_address(seller_default_address.content_attributes)
+          else
+            raise ArgumentError.new(
+              "No billing or default address found for seller (#{seller.class.name} ##{seller.id}), use acts_as_addressable")
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/merchant_sidekick/sellable.rb

@@ -0,0 +1,88 @@
+module MerchantSidekick
+  module Sellable
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Declares a model as sellable.
+      #
+      # E.g.
+      #
+      #   class Product < ActiveRecord::Base
+      #     acts_as_sellable :cents => :price_in_cents, :currency => false
+      #   end
+      #
+      #   @product.orders.
+      #
+      def acts_as_sellable(options = {})
+        include MerchantSidekick::Sellable::InstanceMethods
+        extend MerchantSidekick::Sellable::SingletonMethods
+        money :price, options
+        has_many :line_items, :as => :sellable, :class_name => "MerchantSidekick::LineItem"
+        has_many :orders, :through => :line_items, :class_name => "MerchantSidekick::Order"
+      end
+    end
+
+    module SingletonMethods
+      def sellable?
+        true
+      end
+    end
+
+    module InstanceMethods
+
+      def sellable?
+        true
+      end
+
+      # Funny name, but it returns true if the :price represents
+      # a gross price including taxes. For that there must be a
+      # method called price_is_gross or price_is_gross! as it is
+      # in Issue model
+      # price_is_net? and/or price_is_gross? should be overwritten
+      def price_is_gross?
+        false
+      end
+
+      # Opposite of price_is_gross?
+      def price_is_net?
+        true
+      end
+
+      # This is a product, where the gross and net prices are equal, or in other words
+      # a tax for this product is not applicable, e.g. for $10 purchasing credit
+      # should be overwritten if otherwise
+      def taxable?
+        true
+      end
+
+      # There can only be one authorized order per sellable,
+      # so the first authorziation is it!
+      #
+      # Usage:
+      #   order = issue.settle
+      #   order.capture unless order.nil?
+      # Options:
+      #   issue.settle :merchant => person
+      #
+      def settle(options={})
+        self.orders.each do |order|
+          if order.kind == 'authorization' && current_line_item = order.line_items_find(
+            :first, :condition => ["sellable_id => ? AND sellable_type = ?", self.id, self.class.name]
+          )
+            if adjusted_line_item=order.line_items.build( :order => order, :sellable => self )
+              current_line_items.destroy
+              order.build_addresses
+              order.update
+              order.save!
+              return order
+            end
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/merchant_sidekick/seller.rb

@@ -0,0 +1,93 @@
+module MerchantSidekick
+  module Seller #:nodoc:
+
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # Defines helper methods for a person selling items.
+      #
+      # E.g.
+      #
+      #   class Merchant
+      #     acts_as_seller
+      #     ...
+      #   end
+      #
+      #   # Selling a product to @customer
+      #   @merchant.sell_to @customer, @products
+      #   
+      #   # Alternative syntax
+      #   @merchant.sell @products, :to => @customer
+      #
+      def acts_as_seller(options={})
+        include MerchantSidekick::Seller::InstanceMethods
+        has_many :orders, :as => :seller, :dependent => :destroy, :class_name => "::MerchantSidekick::Order"
+        has_many :invoices, :as => :seller, :dependent => :destroy, :class_name => "::MerchantSidekick::Invoice"
+        has_many :sales_orders, :as => :seller, :class_name => "::MerchantSidekick::SalesOrder"
+        has_many :sales_invoices, :as => :seller, :class_name => "::MerchantSidekick::SalesInvoice"
+      end
+    end
+
+    module InstanceMethods
+
+      def sell_to(buyer, *arguments)
+        sell(arguments, :to => buyer)
+      end
+
+      # Sell sellables (line_items) and add them to a sales order
+      # The seller will be this person.
+      #
+      # e.g.
+      #
+      #   seller.sell(@product, :buyer => @buyer)
+      #
+      def sell(*arguments)
+        sellables = []
+        options = default_sell_options
+
+        # distinguish between options and attributes
+        arguments = arguments.flatten
+        arguments.each do |argument|
+          case argument.class.name
+          when 'Hash'
+            options.merge! argument
+          else
+            sellables << (argument.is_a?(MerchantSidekick::ShoppingCart::Cart) ? argument.line_items : argument)
+          end
+        end
+        sellables.flatten!
+        sellables.reject! {|s| s.blank?}
+
+        raise ArgumentError.new("No sellable (e.g. product) model provided") if sellables.empty?
+        raise ArgumentError.new("Sellable models must have a :price") unless sellables.all? {|sellable| sellable.respond_to? :price}
+
+        self.sales_orders.build do |so|
+          so.buyer = options[:to]
+          so.build_addresses
+
+          sellables.each do |sellable|
+            if sellable && sellable.respond_to?(:before_add_to_order)
+              sellable.send(:before_add_to_order, self)
+              sellable.reload unless sellable.new_record?
+            end
+            li = LineItem.new(:sellable => sellable, :order => so)
+            so.line_items.push(li)
+            sellable.send(:after_add_to_order, self) if sellable && sellable.respond_to?(:after_add_to_order)
+          end
+          self
+        end
+      end
+
+      protected
+
+      # override in model, e.g. :to => @customer
+      def default_sell_options
+        {}
+      end
+
+    end
+  end
+end

data/lib/merchant_sidekick/shopping_cart/cart.rb

@@ -0,0 +1,225 @@
+# The Cart class implements a non-persistant shopping cart. 
+# It provides methods to add, remove and update "sellable" items. Each sellable
+# item added to the cart is converted to a cart line item. It is recommended 
+# to make use of the shopping cart's indirection of purchasing cart line items 
+# as products often change there properties, i.e. price, description, etc., as
+# shown in the following example:
+#
+#   Purchase w/ cart (recommended)      |  Simple purchase wo/ cart
+#   ------------------------------------+------------------------------------
+#   @cart = Cart.new                    |  @order = @buyer.purchase @products
+#   @cart.add @products                 |
+#   @order = @buyer.purchase @cart      |
+#
+module MerchantSidekick
+  module ShoppingCart
+    class Cart
+      attr_reader :line_items
+      attr_reader :currency
+      attr_accessor :options
+
+      def initialize(currency_code = 'USD', options = {})
+        @currency = currency_code
+        @options = {:currency_code => currency_code}.merge(options)
+        empty!
+      end
+
+      # Adds a single or array of sellable products to the cart and 
+      # returns the cart line items.
+      #
+      # E.g.
+      # 
+      #   @cart.add @sellable
+      #   @cart.add @sellable, 4
+      #   @cart.add [@sellable1, @sellable2]
+      #
+      def add(stuff, quantity = 1, options = {})
+        if stuff.is_a?(Array)
+          stuff.inject([]) {|result, element| result << add(element, quantity, options)}
+        elsif stuff.is_a?(MerchantSidekick::ShoppingCart::LineItem)
+          self.add_cart_line_item(stuff, options)
+        else
+          # assuming it is a "product" (e.g. sellable) instance
+          self.add_product(stuff, quantity, options)
+        end
+      end
+
+      # Removes an item from the cart
+      def remove(stuff, options={})
+        if stuff.is_a?(MerchantSidekick::ShoppingCart::LineItem)
+          self.remove_cart_line_item(stuff, options)
+        else
+          self.remove_product(stuff, options)
+        end
+      end
+      alias_method :delete, :remove
+
+      # Updates an existing line_item with quantity by product or line_item
+      # instance. If quanity is <= 0, the item will be removed.
+      def update(stuff, quantity, options={})
+        if stuff.is_a?(MerchantSidekick::ShoppingCart::LineItem)
+          self.update_cart_line_item(stuff, quantity, options)
+        else
+          self.update_product(stuff, quantity, options)
+        end
+      end
+
+      # Finds an instance of line item, by product or line_item
+      #
+      # E.g.
+      #
+      #   @cart.find(:first, @product) # -> @li
+      #   @cart.find(:all, @product)   # -> [@li1, @li2]
+      #
+      def find(what, stuff, options={})
+        if stuff.is_a?(MerchantSidekick::ShoppingCart::LineItem)
+          self.find_line_items(what, stuff, options)
+        else
+          self.find_line_items_by_product(what, stuff, options)
+        end
+      end
+
+      # Remove all line items from cart
+      def empty!
+        @line_items = []
+      end
+
+      # Check to see if cart is empty?
+      def empty?
+        @line_items.empty?
+      end
+
+      # Evaluates the total amount of a sum as all item prices * quantity
+      def total_amount
+        sum = ::Money.new(1, self.currency)
+        @line_items.each {|li| sum += li.total_amount}
+        sum -= ::Money.new(1, self.currency)
+        sum
+      end
+      alias_method :total, :total_amount
+
+      # counts number of line items.
+      def line_items_count
+        self.line_items.size
+      end
+
+      # counts number of entities line_items * quantities.
+      def items_count
+        counter = 0
+        self.line_items.each do |item|
+          counter += item.quantity
+        end
+        counter
+      end
+
+      # Create a product line from a product (sellable) and copies
+      # all attributes that could be modified later
+      def cart_line_item(product, quantity = 1, line_options = {})
+        raise "No price column available for '#{product.class.name}'" unless product.respond_to?(:price)
+        # we need to set currency explicitly here for correct money conversion of the cart_line_item
+        MerchantSidekick::ShoppingCart::LineItem.new do |line_item|
+          line_item.options = self.options.merge(line_options)
+          line_item.currency = self.currency
+          line_item.quantity = quantity
+          line_item.product = product
+          line_item
+        end
+      end
+
+      # Return a list of cart line items from an array of products, e.g. Products
+      def cart_line_items(products)
+        products.map {|p| self.cart_line_item(p)}
+      end
+
+      # cart options setter
+      def options=(some_options = {})
+        @options = some_options.to_hash
+      end
+
+      # cart options getter
+      def options
+        @options || {}
+      end
+
+      protected
+
+      # Add product line
+      # Returns cart total price
+      def add_cart_line_item(newitem, options={})
+        return nil if newitem.nil?
+        item = find(:first, newitem)
+        if item
+          # existing item found, update item quantity and add total_price
+          item.quantity += newitem.quantity
+        else
+          # not in cart yet
+          item = newitem
+          @line_items << item
+        end
+        item
+      end
+
+      # Add purchasable, which most likely will be a product
+      # Returns the total price
+      def add_product(a_product, quantity=1, options={})
+        return nil if a_product.nil?
+        item = find(:first, a_product)
+        if item
+          item.quantity += quantity
+        else
+          item = self.cart_line_item(a_product, quantity, options)
+          @line_items << item
+        end
+        item
+      end
+
+      # Remove a product line and adjust the total price
+      def remove_cart_line_item(a_cart_line_item, options={})
+        deleted_line_item = nil
+        item_to_remove = find(:first, a_cart_line_item)
+        deleted_line_item = @line_items.delete(item_to_remove) if item_to_remove
+        deleted_line_item
+      end
+
+      # Remove a purchasable and adjust the total price
+      def remove_product(a_product, options={})
+        deleted_line_item = nil
+        item_to_remove = find(:first, a_product)
+        deleted_line_item = @line_items.delete(item_to_remove) if item_to_remove
+        deleted_line_item
+      end
+
+      # updates quantity by line item
+      def update_cart_line_item(a_line_item, quantity, options={})
+        return remove(a_line_item, options) if quantity <= 0
+        item = find(:first, a_line_item)
+        item.quantity = quantity if item
+        item
+      end
+
+      # updates quantity py product
+      def update_product(a_product, quantity, options={})
+        return remove(a_product, options) if quantity <= 0
+        item = find(:first, a_product)
+        item.quantity = quantity if item
+        item
+      end
+
+      def find_line_items(what, a_cart_line_item, options={})
+        if :all == what
+          @line_items.select { |i| i.product_id == a_cart_line_item.product.id && i.product_type == a_cart_line_item.product.class.base_class.name }
+        elsif :first == what
+          @line_items.find { |i| i.product_id == a_cart_line_item.product.id && i.product_type == a_cart_line_item.product.class.base_class.name }
+        end
+      end
+
+      def find_line_items_by_product(what, a_product, options={})
+        if :all == what
+          @line_items.select { |i| i.product_id == a_product.id && i.product_type == a_product.class.base_class.name }
+        elsif :first == what
+          @line_items.find { |i| i.product_id == a_product.id && i.product_type == a_product.class.base_class.name }
+        end
+      end
+    end
+  end
+end