solidus_promotions 4.6.2 → 4.7.0

data/app/models/solidus_promotions/calculators/flat_rate.rb

@@ -4,20 +4,66 @@ require_dependency "spree/calculator"
 
 module SolidusPromotions
   module Calculators
+    # A calculator that applies a flat rate discount amount.
+    #
+    # This calculator returns a fixed discount amount if the item's order currency
+    # matches the preferred currency, otherwise it returns zero.
     class FlatRate < Spree::Calculator
       include PromotionCalculator
 
-      preference :amount, :decimal, default: 0
+      preference :amount, :decimal, default: Spree::ZERO
       preference :currency, :string, default: -> { Spree::Config[:currency] }
 
-      def compute(object = nil)
-        currency = object.order.currency
-        if object && preferred_currency.casecmp(currency).zero?
-          preferred_amount
+      # Computes the discount amount for an item.
+      #
+      # Returns the preferred amount if the item's order currency matches the
+      # preferred currency, otherwise returns 0.
+      #
+      # @param item [Object] The item to calculate the discount for (e.g., LineItem, Shipment, ShippingRate)
+      #
+      # @return [BigDecimal] The discount amount (preferred_amount if currency matches, 0 otherwise)
+      #
+      # @example Computing discount for a line item with matching currency
+      #   calculator = FlatRate.new(preferred_amount: 10, preferred_currency: 'USD')
+      #   line_item.order.currency # => 'USD'
+      #   calculator.compute_item(line_item) # => 10.0
+      #
+      # @example Computing discount for a line item with non-matching currency
+      #   calculator = FlatRate.new(preferred_amount: 10, preferred_currency: 'USD')
+      #   line_item.order.currency # => 'EUR'
+      #   calculator.compute_item(line_item) # => 0
+      def compute_item(item)
+        currency = item.order.currency
+        if item && preferred_currency.casecmp(currency).zero?
+          compute_for_amount(item.discountable_amount)
         else
-          0
+          Spree::ZERO
         end
       end
+      alias_method :compute_line_item, :compute_item
+      alias_method :compute_shipment, :compute_item
+      alias_method :compute_shipping_rate, :compute_item
+
+      def compute_price(price, options = {})
+        order = options[:order]
+        quantity = options[:quantity]
+        return preferred_amount unless order
+        return Spree::ZERO if order.currency != preferred_currency
+        line_item_with_variant = order.line_items.detect { _1.variant == price.variant }
+        desired_extra_amount = quantity * price.discountable_amount
+        current_discounted_amount = line_item_with_variant ? line_item_with_variant.discountable_amount : Spree::ZERO
+        round_to_currency(
+          (compute_for_amount(current_discounted_amount + desired_extra_amount.to_f) -
+            compute_for_amount(current_discounted_amount)) / quantity,
+          preferred_currency
+        )
+      end
+
+      private
+
+      def compute_for_amount(amount)
+        [amount, preferred_amount].min
+      end
     end
   end
 end

data/app/models/solidus_promotions/calculators/flexi_rate.rb

@@ -4,19 +4,82 @@ require_dependency "spree/calculator"
 
 module SolidusPromotions
   module Calculators
+    # A calculator that applies different discount amounts for the first item and additional items.
+    #
+    # This calculator allows setting a discount for the first item in a line item and a
+    # different discount for each additional item. Optionally, a maximum number of items
+    # can be specified to limit the discount calculation.
+    #
+    # @example
+    #   # $5 off first item, $2 off each additional item, max 5 items
+    #   calculator = FlexiRate.new(
+    #     preferred_first_item: 5,
+    #     preferred_additional_item: 2,
+    #     preferred_max_items: 5
+    #   )
+    #   # Line item with quantity 3: $5 + ($2 × 2) = $9 discount
+    #   # Line item with quantity 10: $5 + ($2 × 4) = $13 discount (limited to 5 items)
     class FlexiRate < Spree::Calculator
       include PromotionCalculator
 
-      preference :first_item, :decimal, default: 0
-      preference :additional_item, :decimal, default: 0
+      preference :first_item, :decimal, default: Spree::ZERO
+      preference :additional_item, :decimal, default: Spree::ZERO
       preference :max_items, :integer, default: 0
       preference :currency, :string, default: -> { Spree::Config[:currency] }
 
-      def compute(object)
-        items_count = object.quantity
-        items_count = [items_count, preferred_max_items].min unless preferred_max_items.zero?
+      # Computes the discount amount for a line item based on its quantity.
+      #
+      # Calculates the total discount by applying the first_item rate to the first unit
+      # and the additional_item rate to remaining units. If max_items is set (non-zero),
+      # the calculation is limited to that number of items.
+      #
+      # @param line_item [Spree::LineItem] The line item to calculate the discount for
+      #
+      # @return [BigDecimal] The total discount amount based on quantity and preferences
+      #
+      # @example Computing discount for a line item with 3 items
+      #   calculator = FlexiRate.new(preferred_first_item: 10, preferred_additional_item: 5)
+      #   line_item.quantity # => 3
+      #   calculator.compute_line_item(line_item) # => 20.0 (10 + 5 + 5)
+      #
+      # @example Computing discount with max_items limit
+      #   calculator = FlexiRate.new(
+      #     preferred_first_item: 10,
+      #     preferred_additional_item: 5,
+      #     preferred_max_items: 2
+      #   )
+      #   line_item.quantity # => 5
+      #   calculator.compute_line_item(line_item) # => 15.0 (10 + 5, limited to 2 items)
+      def compute_line_item(line_item)
+        compute_for_quantity(line_item.quantity)
+      end
+
+      def compute_price(price, options = {})
+        order = options[:order]
+        desired_quantity = options[:quantity] || 0
+        return Spree::ZERO if desired_quantity.zero?
+
+        already_ordered_quantity = if order
+          order.line_items.detect do |line_item|
+            line_item.variant == price.variant
+          end&.quantity || 0
+        else
+          0
+        end
+        possible_discount = compute_for_quantity(already_ordered_quantity + desired_quantity)
+        existing_discount = compute_for_quantity(already_ordered_quantity)
+        round_to_currency(
+          (possible_discount - existing_discount) / desired_quantity,
+          price.currency
+        )
+      end
+
+      private
+
+      def compute_for_quantity(quantity)
+        items_count = preferred_max_items.zero? ? quantity : [quantity, preferred_max_items].min
 
-        return Spree::ZERO if items_count == 0
+        return Spree::ZERO if items_count.zero?
 
         additional_items_count = items_count - 1
         preferred_first_item + preferred_additional_item * additional_items_count

data/app/models/solidus_promotions/calculators/percent.rb

@@ -4,16 +4,52 @@ require_dependency "spree/calculator"
 
 module SolidusPromotions
   module Calculators
+    # A calculator that applies a percentage-based discount.
+    #
+    # This calculator computes the discount as a percentage of the item's discountable amount,
+    # rounded to the appropriate currency precision.
+    #
+    # @example
+    #   calculator = Percent.new(preferred_percent: 15)
+    #   # Line item with discountable_amount of $100
+    #   calculator.compute_item(line_item) # => 15.00 (15% of $100)
     class Percent < Spree::Calculator
       include PromotionCalculator
 
       preference :percent, :decimal, default: 0
 
-      def compute(object)
-        preferred_currency = object.order.currency
-        currency_exponent = ::Money::Currency.find(preferred_currency).exponent
-        (object.discountable_amount * preferred_percent / 100).round(currency_exponent)
+      # Computes the percentage-based discount for an item.
+      #
+      # Calculates the discount by applying the preferred percentage to the item's
+      # discountable amount, then rounds the result to the appropriate precision
+      # for the order's currency.
+      #
+      # @param object [Object] The object to calculate the discount for (e.g., LineItem, Shipment, ShippingRate)
+      #
+      # @return [BigDecimal] The discount amount, rounded to the order's currency precision
+      #
+      # @example Computing a 20% discount on a $50 line item
+      #   calculator = Percent.new(preferred_percent: 20)
+      #   line_item.discountable_amount # => 50.00
+      #   calculator.compute_item(line_item) # => 10.00
+      #
+      # @example Computing a 15% discount on a shipment
+      #   calculator = Percent.new(preferred_percent: 15)
+      #   shipment.discountable_amount # => 25.00
+      #   calculator.compute_item(shipment) # => 3.75
+      #
+      # @example Computing a 15% discount on a price
+      #   calculator = Percent.new(preferred_percent: 15)
+      #   price.discountable_amount # => 100.00
+      #   calculator.compute_item(shipment) # => 15
+      def compute_item(object, _options = {})
+        currency = object.respond_to?(:currency) ? object.currency : object.order.currency
+        round_to_currency(object.discountable_amount * preferred_percent / 100, currency)
       end
+      alias_method :compute_line_item, :compute_item
+      alias_method :compute_shipment, :compute_item
+      alias_method :compute_shipping_rate, :compute_item
+      alias_method :compute_price, :compute_item
     end
   end
 end

data/app/models/solidus_promotions/calculators/percent_with_cap.rb

@@ -2,11 +2,52 @@
 
 module SolidusPromotions
   module Calculators
-    class PercentWithCap < Percent
+    # A calculator that applies a percentage-based discount with a maximum cap.
+    #
+    # This calculator computes a discount as a percentage of the line item's discountable amount,
+    # but limits the total discount to a maximum amount distributed across all applicable line items.
+    # The actual discount applied is the lesser of the percentage discount and the proportional
+    # share of the maximum cap.
+    #
+    # @example
+    #   calculator = PercentWithCap.new(preferred_percent: 20, preferred_max_amount: 50)
+    #   # Line item with $100 discountable amount
+    #   # Percentage would be $20 (20% of $100)
+    #   # But if the max cap distributes only $15 to this item, it gets $15
+    class PercentWithCap < Spree::Calculator
+      include PromotionCalculator
+
+      preference :percent, :decimal, default: 0
       preference :max_amount, :integer, default: 100
 
-      def compute(line_item)
-        percent_discount = super
+      # Computes the discount for a line item, capped at a maximum amount.
+      #
+      # Calculates both a percentage-based discount and a distributed maximum discount,
+      # then returns whichever is smaller. This ensures the discount never exceeds
+      # the line item's proportional share of the maximum cap, even if the percentage
+      # would result in a larger discount.
+      #
+      # @param line_item [Spree::LineItem] The line item to calculate the discount for
+      #
+      # @return [BigDecimal] The discount amount, limited by both the percentage and the max cap
+      #
+      # @example Computing discount when percentage is lower than cap
+      #   calculator = PercentWithCap.new(preferred_percent: 10, preferred_max_amount: 100)
+      #   line_item.discountable_amount # => 50.00
+      #   # Percent discount: $5 (10% of $50)
+      #   # Max distributed: $25 (assuming equal distribution)
+      #   calculator.compute_line_item(line_item) # => 5.00
+      #
+      # @example Computing discount when cap is lower than percentage
+      #   calculator = PercentWithCap.new(preferred_percent: 50, preferred_max_amount: 10)
+      #   line_item.discountable_amount # => 100.00
+      #   # Percent discount: $50 (50% of $100)
+      #   # Max distributed: $10 (assuming single line item)
+      #   calculator.compute_line_item(line_item) # => 10.00
+      #
+      # @see DistributedAmount
+      def compute_line_item(line_item)
+        percent_discount = round_to_currency(line_item.discountable_amount * preferred_percent / 100, line_item.order.currency)
         max_discount = DistributedAmount.new(
           calculable:,
           preferred_amount: preferred_max_amount

data/app/models/solidus_promotions/calculators/tiered_flat_rate.rb

@@ -4,24 +4,82 @@ require_dependency "spree/calculator"
 
 module SolidusPromotions
   module Calculators
+    # A calculator that applies tiered flat-rate discounts based on discountable amount thresholds.
+    #
+    # This calculator allows defining multiple discount tiers where each tier specifies a minimum
+    # discountable amount threshold and the corresponding discount amount to apply. The calculator
+    # selects the highest tier that the item qualifies for based on its discountable amount.
+    #
+    # If the item doesn't meet any tier threshold, the base amount is used. The discount is only
+    # applied if the currency matches the preferred currency.
+    #
+    # @example Use case: Volume-based shipping discounts
+    #   # Free shipping on orders over $100, $5 off on orders over $50
+    #   calculator = TieredFlatRate.new(
+    #     preferred_base_amount: 0,
+    #     preferred_tiers: {
+    #       50 => 5,   # $5 discount when amount >= $50
+    #       100 => 15  # $15 discount when amount >= $100
+    #     },
+    #     preferred_currency: 'USD'
+    #   )
+    #
+    # @example Use case: Bulk purchase incentives
+    #   # Tiered discounts for line items based on total line value
+    #   calculator = TieredFlatRate.new(
+    #     preferred_base_amount: 2,
+    #     preferred_tiers: {
+    #       25 => 5,    # $5 off when line total >= $25
+    #       50 => 12,   # $12 off when line total >= $50
+    #       100 => 30   # $30 off when line total >= $100
+    #     },
+    #     preferred_currency: 'USD'
+    #   )
     class TieredFlatRate < Spree::Calculator
       include PromotionCalculator
 
-      preference :base_amount, :decimal, default: 0
-      preference :tiers, :hash, default: { 10 => 10 }
+      preference :base_amount, :decimal, default: Spree::ZERO
+      preference :tiers, :hash, default: {10 => 10}
       preference :currency, :string, default: -> { Spree::Config[:currency] }
 
-      before_validation do
-        # Convert tier values to decimals. Strings don't do us much good.
-        if preferred_tiers.is_a?(Hash)
-          self.preferred_tiers = preferred_tiers.map do |key, value|
-            [cast_to_d(key.to_s), cast_to_d(value.to_s)]
-          end.to_h
-        end
-      end
+      before_validation :transform_preferred_tiers
 
       validate :preferred_tiers_content
 
+      # Computes the tiered flat-rate discount for an item.
+      #
+      # Evaluates the item's discountable amount against all defined tiers and selects
+      # the highest tier threshold that the item meets or exceeds. Returns the discount
+      # amount associated with that tier, or the base amount if no tier threshold is met.
+      # Returns 0 if the currency doesn't match.
+      #
+      # @param object [Object] The object to calculate the discount for (e.g., LineItem, Shipment)
+      #
+      # @return [BigDecimal] The discount amount from the matching tier, base amount, or 0
+      #
+      # @example Computing discount with tier matching
+      #   calculator = TieredFlatRate.new(
+      #     preferred_base_amount: 2,
+      #     preferred_tiers: { 25 => 5, 50 => 10, 100 => 20 }
+      #   )
+      #   line_item.discountable_amount # => 75.00
+      #   calculator.compute_item(line_item) # => 10.00 (matches $50 tier)
+      #
+      # @example Computing discount below all tiers
+      #   calculator = TieredFlatRate.new(
+      #     preferred_base_amount: 2,
+      #     preferred_tiers: { 25 => 5, 50 => 10 }
+      #   )
+      #   line_item.discountable_amount # => 15.00
+      #   calculator.compute_item(line_item) # => 2.00 (base amount)
+      #
+      # @example Computing discount with currency mismatch
+      #   calculator = TieredFlatRate.new(
+      #     preferred_currency: 'USD',
+      #     preferred_tiers: { 50 => 10 }
+      #   )
+      #   line_item.currency # => 'EUR'
+      #   calculator.compute_item(line_item) # => 0
       def compute_item(object)
         _base, amount = preferred_tiers.sort.reverse.detect do |value, _|
           object.discountable_amount >= value
@@ -30,7 +88,7 @@ module SolidusPromotions
         if preferred_currency.casecmp(object.currency).zero?
           amount || preferred_base_amount
         else
-          0
+          Spree::ZERO
         end
       end
       alias_method :compute_shipment, :compute_item
@@ -38,17 +96,21 @@ module SolidusPromotions
 
       private
 
-      def cast_to_d(value)
-        value.to_s.to_d
+      # Transforms preferred_tiers keys and values to BigDecimal for consistent calculations.
+      #
+      # Converts all tier threshold keys and percentage values from strings or other numeric
+      # types to BigDecimal to ensure precision in monetary calculations.
+      def transform_preferred_tiers
+        preferred_tiers.transform_keys! { |key| key.to_s.to_d }
+        preferred_tiers.transform_values! { |value| value.to_s.to_d }
       end
 
+      # Validates that preferred_tiers is a hash with positive numeric keys.
+      #
+      # Ensures the tiers preference is properly formatted for tier-based calculations.
       def preferred_tiers_content
-        if preferred_tiers.is_a? Hash
-          unless preferred_tiers.keys.all? { |key| key.is_a?(Numeric) && key > 0 }
-            errors.add(:base, :keys_should_be_positive_number)
-          end
-        else
-          errors.add(:preferred_tiers, :should_be_hash)
+        unless preferred_tiers.keys.all? { |key| key.is_a?(Numeric) && key > 0 }
+          errors.add(:base, :keys_should_be_positive_number)
         end
       end
     end

data/app/models/solidus_promotions/calculators/tiered_percent.rb

@@ -4,28 +4,93 @@ require_dependency "spree/calculator"
 
 module SolidusPromotions
   module Calculators
+    # A calculator that applies tiered percentage-based discounts based on order item total thresholds.
+    #
+    # This calculator allows defining multiple discount tiers where each tier specifies a minimum
+    # order item total threshold and the corresponding percentage discount to apply to the individual
+    # item. The calculator selects the highest tier that the order qualifies for based on its item total.
+    #
+    # Unlike TieredFlatRate which applies a fixed amount, this calculator applies a percentage of the
+    # item's amount. The tier thresholds are evaluated against the entire order's item total, but the
+    # percentage discount is applied to the individual item (line item or shipment).
+    #
+    # If the order doesn't meet any tier threshold, the base percentage is used. The discount is only
+    # applied if the currency matches the preferred currency.
+    #
+    # @example Use case: Volume-based percentage discounts
+    #   # Higher discounts for larger orders
+    #   calculator = TieredPercent.new(
+    #     preferred_base_percent: 5,
+    #     preferred_tiers: {
+    #       100 => 10,  # 10% off when order total >= $100
+    #       250 => 15,  # 15% off when order total >= $250
+    #       500 => 20   # 20% off when order total >= $500
+    #     },
+    #     preferred_currency: 'USD'
+    #   )
+    #
+    # @example Use case: Wholesale tier pricing
+    #   # Different percentage discounts for different order sizes
+    #   calculator = TieredPercent.new(
+    #     preferred_base_percent: 0,
+    #     preferred_tiers: {
+    #       200 => 5,    # 5% wholesale discount at $200
+    #       500 => 10,   # 10% wholesale discount at $500
+    #       1000 => 15   # 15% wholesale discount at $1000
+    #     },
+    #     preferred_currency: 'USD'
+    #   )
     class TieredPercent < Spree::Calculator
       include PromotionCalculator
 
-      preference :base_percent, :decimal, default: 0
-      preference :tiers, :hash, default: { 50 => 5 }
+      preference :base_percent, :decimal, default: Spree::ZERO
+      preference :tiers, :hash, default: {50 => 5}
       preference :currency, :string, default: -> { Spree::Config[:currency] }
 
-      before_validation do
-        # Convert tier values to decimals. Strings don't do us much good.
-        if preferred_tiers.is_a?(Hash)
-          self.preferred_tiers = preferred_tiers.map do |key, value|
-            [cast_to_d(key.to_s), cast_to_d(value.to_s)]
-          end.to_h
-        end
-      end
+      before_validation :transform_preferred_tiers
 
       validates :preferred_base_percent, numericality: {
-        greater_than_or_equal_to: 0,
+        greater_than_or_equal_to: Spree::ZERO,
         less_than_or_equal_to: 100
       }
       validate :preferred_tiers_content
 
+      # Computes the tiered percentage discount for an item based on the order's item total.
+      #
+      # Evaluates the order's item total against all defined tiers and selects the highest
+      # tier threshold that the order meets or exceeds. Returns a percentage of the item's
+      # amount based on the matching tier, or the base percentage if no tier threshold is met.
+      # Returns 0 if the currency doesn't match.
+      #
+      # @param object [Object] The object to calculate the discount for (e.g., LineItem, Shipment)
+      #
+      # @return [BigDecimal] The percentage-based discount amount, rounded to currency precision
+      #
+      # @example Computing discount with tier matching
+      #   calculator = TieredPercent.new(
+      #     preferred_base_percent: 5,
+      #     preferred_tiers: { 100 => 10, 250 => 15 }
+      #   )
+      #   order.item_total # => 150.00
+      #   line_item.amount # => 50.00
+      #   calculator.compute_item(line_item) # => 5.00 (10% of $50, matches $100 tier)
+      #
+      # @example Computing discount below all tiers
+      #   calculator = TieredPercent.new(
+      #     preferred_base_percent: 5,
+      #     preferred_tiers: { 100 => 10, 250 => 15 }
+      #   )
+      #   order.item_total # => 75.00
+      #   line_item.amount # => 30.00
+      #   calculator.compute_item(line_item) # => 1.50 (5% base percent of $30)
+      #
+      # @example Computing discount with currency mismatch
+      #   calculator = TieredPercent.new(
+      #     preferred_currency: 'USD',
+      #     preferred_tiers: { 100 => 10 }
+      #   )
+      #   order.currency # => 'EUR'
+      #   calculator.compute_item(line_item) # => 0
       def compute_item(object)
         order = object.order
 
@@ -34,10 +99,9 @@ module SolidusPromotions
         end
 
         if preferred_currency.casecmp(order.currency).zero?
-          currency_exponent = ::Money::Currency.find(preferred_currency).exponent
-          (object.amount * (percent || preferred_base_percent) / 100).round(currency_exponent)
+          round_to_currency(object.amount * (percent || preferred_base_percent) / 100, preferred_currency)
         else
-          0
+          Spree::ZERO
         end
       end
       alias_method :compute_shipment, :compute_item
@@ -45,20 +109,27 @@ module SolidusPromotions
 
       private
 
-      def cast_to_d(value)
-        value.to_s.to_d
+      # Transforms preferred_tiers keys and values to BigDecimal for consistent calculations.
+      #
+      # Converts all tier threshold keys and percentage values from strings or other numeric
+      # types to BigDecimal to ensure precision in monetary calculations.
+      def transform_preferred_tiers
+        preferred_tiers.transform_keys! { |key| key.to_s.to_d }
+        preferred_tiers.transform_values! { |value| value.to_s.to_d }
       end
 
+      # Validates that preferred_tiers is properly formatted with valid thresholds and percentages.
+      #
+      # Ensures:
+      # - Tiers is a hash
+      # - All keys (thresholds) are positive numbers
+      # - All values (percentages) are between 0 and 100
       def preferred_tiers_content
-        if preferred_tiers.is_a? Hash
-          unless preferred_tiers.keys.all? { |key| key.is_a?(Numeric) && key > 0 }
-            errors.add(:base, :keys_should_be_positive_number)
-          end
-          unless preferred_tiers.values.all? { |key| key.is_a?(Numeric) && key >= 0 && key <= 100 }
-            errors.add(:base, :values_should_be_percent)
-          end
-        else
-          errors.add(:preferred_tiers, :should_be_hash)
+        unless preferred_tiers.keys.all? { |key| key.is_a?(Numeric) && key > 0 }
+          errors.add(:base, :keys_should_be_positive_number)
+        end
+        unless preferred_tiers.values.all? { |key| key.is_a?(Numeric) && key >= 0 && key <= 100 }
+          errors.add(:base, :values_should_be_percent)
         end
       end
     end