solidus_promotions 4.6.4 → 4.7.0

data/app/models/solidus_promotions/benefit.rb

@@ -1,65 +1,240 @@
 # frozen_string_literal: true
 
 module SolidusPromotions
-  # Base class for all types of benefit.
+  # Base class for all promotion benefits.
   #
-  # Benefits perform the necessary tasks when a promotion is activated
-  # by an event and determined to be eligible.
+  # A Benefit is the active part of a promotion: once a promotion becomes
+  # eligible for a given promotable (order, line item, or shipment), the benefit
+  # determines how much discount to apply and produces the corresponding
+  # adjustments.
+  #
+  # Subclasses specialize the discounting target (orders, line items, or
+  # shipments) and usually include one of the following mixins to integrate with
+  # Solidus' adjustment system:
+  # - SolidusPromotions::Benefits::AdjustLineItem
+  # - SolidusPromotions::Benefits::AdjustShipment
+  # - SolidusPromotions::Benefits::CreateDiscountedItem
+  #
+  # A benefit can discount any object for which {#can_discount?} returns true.
+  # Implementors must provide a calculator via Spree::CalculatedAdjustments and
+  # may override methods such as {#adjustment_label}.
+  #
+  # Usage example
+  #
+  #   benefit = SolidusPromotions::Benefits::AdjustLineItem.new(promotion: promo)
+  #   if benefit.can_discount?(line_item)
+  #     discount = benefit.discount(line_item)
+  #     # => #<SolidusPromotions::ItemDiscount ...>
+  #   end
+  #
+  # @see SolidusPromotions::Promotion
+  # @see Spree::CalculatedAdjustments
   class Benefit < Spree::Base
     include Spree::Preferences::Persistable
     include Spree::CalculatedAdjustments
     include Spree::AdjustmentSource
+
     before_destroy :remove_adjustments_from_incomplete_orders
     before_destroy :raise_for_adjustments_for_completed_orders
 
     # @!attribute [rw] promotion
     #   The owning promotion.
     #   @return [SolidusPromotions::Promotion]
-    belongs_to :promotion, -> { with_discarded }, inverse_of: :benefits
+    belongs_to :promotion, inverse_of: :benefits
     # @!attribute [rw] original_promotion_action
     #   Back-reference to the original Solidus (Spree) promotion action, when migrated.
     #   @return [Spree::PromotionAction, nil]
     belongs_to :original_promotion_action, class_name: "Spree::PromotionAction", optional: true
+    # @!attribute [r] adjustments
+    #   Adjustments created by this benefit.
+    #   @return [ActiveRecord::Associations::CollectionProxy<Spree::Adjustment>]
     has_many :adjustments, class_name: "Spree::Adjustment", as: :source, dependent: :restrict_with_error
+    # @!attribute [r] shipping_rate_discounts
+    #   Shipping-rate-level discounts generated by this benefit.
+    #   @return [ActiveRecord::Associations::CollectionProxy<SolidusPromotions::ShippingRateDiscount>]
     has_many :shipping_rate_discounts, class_name: "SolidusPromotions::ShippingRateDiscount", inverse_of: :benefit, dependent: :restrict_with_error
+    # @!attribute [r] conditions
+    #   Conditions attached to this benefit.
+    #   @return [ActiveRecord::Associations::CollectionProxy<SolidusPromotions::Condition>]
     has_many :conditions, class_name: "SolidusPromotions::Condition", inverse_of: :benefit, dependent: :destroy
 
+    # @!method self.of_type(type)
+    #   Restricts benefits to the given STI type(s).
+    #   @param type [String, Symbol, Class, Array<String,Symbol,Class>] a single type or list of types
+    #   @return [ActiveRecord::Relation<SolidusPromotions::Benefit>]
     scope :of_type, ->(type) { where(type: Array.wrap(type).map(&:to_s)) }
 
+    # Base set of order-level condition classes available to all benefits.
+    #
+    # These generic order conditions apply regardless of the concrete benefit
+    # type, as every benefit ultimately operates within the context of an order.
+    # Concrete benefit subclasses may extend or override this to include
+    # additional applicable conditions that are specific to their discount
+    # target (e.g., line-item or shipment conditions).
+    #
+    # @return [Enumerable<Class<SolidusPromotions::Condition>>]
+    def self.applicable_conditions
+      SolidusPromotions::Condition.applicable_to([Spree::Order])
+    end
+
+    # Returns relations that should be preloaded for this condition.
+    #
+    # Override this method in subclasses to specify associations that should be eager loaded
+    # to avoid N+1 queries when computing discounts or performing automations.
+    #
+    # @return [Array<Symbol>] An array of association names to preload
     def preload_relations
       [:calculator]
     end
 
+    # Whether this benefit can discount the given object.
+    #
+    # Subclasses must implement this according to the kinds
+    # of objects they are able to discount.
+    #
+    # @param object [Object] a potential adjustable (order, line item, or shipment)
+    # @return [Boolean]
+    # @see SolidusPromotions::Benefits::AdjustLineItem,
+    #      SolidusPromotions::Benefits::AdjustShipment,
+    #      SolidusPromotions::Benefits::CreateDiscountedItem
     def can_discount?(object)
-      raise NotImplementedError, "Please implement the correct interface, or include one of the `SolidusPromotions::Benefits::OrderBenefit`, " \
-        "`SolidusPromotions::Benefits::LineItemBenefit` or `SolidusPromotions::Benefits::ShipmentBenefit` modules"
+      respond_to?(discount_method_for(object))
     end
 
-    def discount(adjustable)
-      amount = compute_amount(adjustable)
-      return if amount.zero?
-      ItemDiscount.new(
-        item: adjustable,
-        label: adjustment_label(adjustable),
-        amount: amount,
-        source: self
-      )
+    # Calculates and returns a discount for the given adjustable object.
+    #
+    # This method computes the discount amount using the benefit's calculator and returns
+    # an ItemDiscount object representing the discount to be applied. If the computed
+    # amount is zero, no discount is returned.
+    #
+    # @param adjustable [Object] The object to calculate the discount for (e.g., LineItem, Shipment, ShippingRate)
+    # @param ... [args, kwargs] Additional arguments passed to the calculator's compute method
+    #
+    # @return [Spree::Adjustment, SolidusPromotions::ShippingRateDiscount, nil] An ItemDiscount object if a discount applies, nil if the amount is zero
+    #
+    # @example Calculating a discount for a line item
+    #   benefit.discount(line_item)
+    #   # => #<Spree::Adjustment, adjustable: line_item, amount: -10.00, ...>
+    #
+    # @see #compute_amount
+    # @see #adjustment_label
+    def discount(adjustable, ...)
+      if can_discount?(adjustable)
+        send(discount_method_for(adjustable), adjustable, ...)
+      else
+        raise NotImplementedError, "Please implement #{discount_method_for(adjustable)} in your condition"
+      end
     end
 
-    # Ensure a negative amount which does not exceed the object's amount
-    def compute_amount(adjustable)
-      promotion_amount = calculator.compute(adjustable) || Spree::ZERO
+    def self.inherited(klass)
+      def klass.method_added(method_added)
+        if method_added == :discount
+          Spree.deprecator.warn <<~MSG
+            Please refactor `#{name}`. You're defining `#discount`. Instead, define a method for each type of discountable
+            that your benefit can discount. For example:
+            ```
+            class MyBenefit < SolidusPromotions::Benefit
+              def can_discount?(discountable)
+                discountable.is_a?(Spree::LineItem)
+              end
+
+              def discount(order, _options = {})
+                amount = compute_amount(line_item, ...)
+                return if amount.zero?
+
+                ItemDiscount.new(
+                  item: line_item,
+                  label: adjustment_label(line_item),
+                  amount: amount,
+                  source: self
+                )
+              end
+            ```
+            can now become
+            ```
+            class MyBenefit < SolidusPromotions::Benefit
+              def discount_line_item(order, ...)
+                amount = compute_amount(line_item, ...)
+                return if amount.zero?
+
+                ItemDiscount.new(
+                  item: line_item,
+                  label: adjustment_label(line_item),
+                  amount: amount,
+                  source: self
+                )
+              end
+            end
+            ```
+          MSG
+        end
+        super
+      end
+      super
+    end
+
+    # Computes the discount amount for the given adjustable.
+    #
+    # Ensures the returned amount is negative and does not exceed the
+    # adjustable's discountable amount.
+    #
+    # @param adjustable [#discountable_amount] the adjustable to compute for
+    # @param ... [args, kwargs] additional arguments forwarded to the calculator
+    # @return [BigDecimal] a negative amount suitable for creating an adjustment
+    def compute_amount(adjustable, ...)
+      promotion_amount = calculator.compute(adjustable, ...) || Spree::ZERO
       [adjustable.discountable_amount, promotion_amount.abs].min * -1
     end
 
-    def adjustment_label(adjustable)
-      I18n.t(
-        "solidus_promotions.adjustment_labels.#{adjustable.class.name.demodulize.underscore}",
-        promotion: SolidusPromotions::Promotion.model_name.human,
-        promotion_customer_label: promotion.customer_label
-      )
+    # Builds the localized label for adjustments created by this benefit.
+    #
+    # This method attempts to use a calculator-specific label method if available,
+    # falling back to a localized string key based on the adjustable's class name.
+    #
+    # ## Calculator Override
+    #
+    # Calculators can provide custom labels by implementing a method named after the
+    # adjustable type. For example, a calculator that discounts line items could
+    # implement `line_item_adjustment_label`:
+    #
+    # @example Custom calculator with adjustment label
+    #   class MyCalculator < Spree::Calculator
+    #     def compute(adjustable, *args)
+    #       # calculation logic
+    #     end
+    #
+    #     def line_item_adjustment_label(line_item, *args)
+    #       "Custom discount for #{line_item.product.name}"
+    #     end
+    #   end
+    #
+    # The method name follows the pattern: `{adjustable_type}_adjustment_label`
+    # where `{adjustable_type}` is the underscored class name of the adjustable
+    # (e.g., `line_item`, `shipment`, `shipping_rate`).
+    #
+    # If the calculator does not respond to the expected method, the benefit will
+    # fall back to using an i18n translation key based on the adjustable's class.
+    #
+    # @param adjustable [Object] the object being discounted (e.g., Spree::LineItem, Spree::Shipment)
+    # @param ... [args, kwargs] additional arguments forwarded to the calculator's label method
+    # @return [String] a localized label suitable for display in adjustments
+    #
+    # @see #adjustment_label_method_for
+    def adjustment_label(adjustable, ...)
+      if calculator.respond_to?(adjustment_label_method_for(adjustable))
+        calculator.send(adjustment_label_method_for(adjustable), adjustable, ...)
+      else
+        I18n.t(
+          "solidus_promotions.adjustment_labels.#{adjustable.class.name.demodulize.underscore}",
+          promotion: SolidusPromotions::Promotion.model_name.human,
+          promotion_customer_label: promotion.customer_label
+        )
+      end
     end
 
+    # Partial path used for admin forms for this benefit type.
+    #
+    # @return [String]
     def to_partial_path
       "solidus_promotions/admin/benefit_fields/#{model_name.element}"
     end
@@ -68,33 +243,47 @@ module SolidusPromotions
       raise NotImplementedError, "Please implement the correct interface, or include one of the `SolidusPromotions::Benefits::OrderBenefit`, " \
         "`SolidusPromotions::Benefits::LineItemBenefit` or `SolidusPromotions::Benefits::ShipmentBenefit` modules"
     end
+    deprecate :level, deprecator: Spree.deprecator
 
+    # Returns the set of condition classes that can still be attached to this benefit.
+    # Already-persisted conditions are excluded.
+    #
+    # @return [Set<Class<SolidusPromotions::Condition>>]
     def available_conditions
-      possible_conditions - conditions.select(&:persisted?)
+      self.class.applicable_conditions - conditions.select(&:persisted?)
     end
 
+    # Returns the calculators allowed for this benefit type.
+    #
+    # @return [Array<Class>] calculator classes
     def available_calculators
       SolidusPromotions.config.promotion_calculators[self.class] || []
     end
 
+    # Verifies if the promotable satisfies all applicable conditions of this benefit.
+    #
+    # When dry_run is true, an {SolidusPromotions::EligibilityResults} entry is
+    # recorded for each condition with success/error details; otherwise, the
+    # evaluation short-circuits on the first failure.
+    #
+    # @param promotable [Object] the entity being evaluated (e.g., Spree::Order, Spree::LineItem)
+    # @param dry_run [Boolean] whether to collect detailed eligibility information
+    # @return [Boolean] true when all applicable conditions are eligible
     def eligible_by_applicable_conditions?(promotable, dry_run: false)
-      applicable_conditions = conditions.select do |condition|
-        condition.applicable?(promotable)
-      end
-
-      applicable_conditions.map do |applicable_condition|
-        eligible = applicable_condition.eligible?(promotable)
+      conditions.map do |condition|
+        next unless condition.applicable?(promotable)
+        eligible = condition.eligible?(promotable)
 
         break [false] if !eligible && !dry_run
 
         if dry_run
-          if applicable_condition.eligibility_errors.details[:base].first
-            code = applicable_condition.eligibility_errors.details[:base].first[:error_code]
-            message = applicable_condition.eligibility_errors.full_messages.first
+          if condition.eligibility_errors.details[:base].first
+            code = condition.eligibility_errors.details[:base].first[:error_code]
+            message = condition.eligibility_errors.full_messages.first
           end
           promotion.eligibility_results.add(
             item: promotable,
-            condition: applicable_condition,
+            condition: condition,
             success: eligible,
             code: eligible ? nil : (code || :coupon_code_unknown_error),
             message: eligible ? nil : (message || I18n.t(:coupon_code_unknown_error, scope: [:solidus_promotions, :eligibility_errors]))
@@ -102,21 +291,47 @@ module SolidusPromotions
         end
 
         eligible
-      end.all?
+      end.compact.all?
     end
 
+    # All line items of the order that are eligible for this benefit.
+    #
+    # @param order [Spree::Order]
+    # @return [Array<Spree::LineItem>] eligible line items
     def applicable_line_items(order)
       order.discountable_line_items.select do |line_item|
         eligible_by_applicable_conditions?(line_item)
       end
     end
 
+    # Base set of order-level condition classes available to all benefits.
+    #
+    # These generic order conditions apply regardless of the concrete benefit
+    # type, as every benefit ultimately operates within the context of an order.
+    # Concrete benefit subclasses may extend or override this to include
+    # additional applicable conditions that are specific to their discount
+    # target (e.g., line-item or shipment conditions).
+    #
+    # @return [Set<Class<SolidusPromotions::Condition>>]
     def possible_conditions
-      Set.new(SolidusPromotions.config.order_conditions)
+      Spree.deprecator.warn("Use #{self.class.name}.applicable_conditions instead.")
+      self.class.applicable_conditions
     end
 
     private
 
+    def discount_method_for(adjustable)
+      :"discount_#{adjustable.class.name.demodulize.underscore}"
+    end
+
+    def adjustment_label_method_for(adjustable)
+      :"#{adjustable.class.name.demodulize.underscore}_adjustment_label"
+    end
+
+    # Prevents destroying a benefit when it has adjustments on completed orders.
+    #
+    # Adds an error and aborts the destroy callback chain when such adjustments exist.
+    # @api private
     def raise_for_adjustments_for_completed_orders
       if adjustments.joins(:order).merge(Spree::Order.complete).any?
         errors.add(:base, :cannot_destroy_if_order_completed)

data/app/models/solidus_promotions/benefits/adjust_line_item.rb

@@ -3,10 +3,35 @@
 module SolidusPromotions
   module Benefits
     class AdjustLineItem < Benefit
-      include SolidusPromotions::Benefits::LineItemBenefit
+      def self.applicable_conditions
+        SolidusPromotions::Condition.applicable_to([Spree::Order, Spree::LineItem])
+      end
+
+      def discount_line_item(line_item, ...)
+        adjustment = find_adjustment(line_item) || build_adjustment(line_item)
+        adjustment.amount = compute_amount(line_item, ...)
+        adjustment.label = adjustment_label(line_item)
+        adjustment
+      end
+
+      def level
+        :line_item
+      end
+      deprecate :level, deprecator: Spree.deprecator
+
+      private
+
+      def find_adjustment(line_item)
+        line_item.adjustments.detect do |adjustment|
+          adjustment.source == self
+        end
+      end
 
-      def possible_conditions
-        super + SolidusPromotions.config.line_item_conditions
+      def build_adjustment(line_item)
+        line_item.adjustments.build(
+          order: line_item.order,
+          source: self
+        )
       end
     end
   end

data/app/models/solidus_promotions/benefits/adjust_line_item_quantity_groups.rb

@@ -90,6 +90,7 @@ module SolidusPromotions
         end
 
         def discountable_amount
+          return Spree::ZERO if @line_item.quantity.zero?
           @line_item.discountable_amount / @line_item.quantity.to_d
         end
         alias_method :amount, :discountable_amount

data/app/models/solidus_promotions/benefits/adjust_shipment.rb

@@ -3,10 +3,52 @@
 module SolidusPromotions
   module Benefits
     class AdjustShipment < Benefit
-      include SolidusPromotions::Benefits::ShipmentBenefit
+      def self.applicable_conditions
+        SolidusPromotions::Condition.applicable_to([Spree::Order, Spree::Shipment])
+      end
+
+      def discount_shipment(shipment, ...)
+        adjustment = find_adjustment(shipment) || build_adjustment(shipment)
+        adjustment.amount = compute_amount(shipment, ...)
+        adjustment.label = adjustment_label(shipment)
+        adjustment
+      end
+
+      def discount_shipping_rate(shipping_rate, ...)
+        discount = find_discount(shipping_rate) || build_discount(shipping_rate)
+        discount.amount = compute_amount(shipping_rate, ...)
+        discount.label = adjustment_label(shipping_rate)
+        discount
+      end
+
+      def level
+        :shipment
+      end
+      deprecate :level, deprecator: Spree.deprecator
+
+      private
+
+      def find_adjustment(shipment)
+        shipment.adjustments.detect do |adjustment|
+          adjustment.source == self
+        end
+      end
+
+      def build_adjustment(shipment)
+        shipment.adjustments.build(
+          order: shipment.order,
+          source: self
+        )
+      end
+
+      def find_discount(shipping_rate)
+        shipping_rate.discounts.detect do |discount|
+          discount.benefit == self
+        end
+      end
 
-      def possible_conditions
-        super + SolidusPromotions.config.shipment_conditions
+      def build_discount(shipping_rate)
+        shipping_rate.discounts.build(benefit: self)
       end
     end
   end

data/app/models/solidus_promotions/benefits/advertise_price.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module Benefits
+    class AdvertisePrice < Benefit
+      def self.applicable_conditions
+        Condition.applicable_to([Spree::Order, Spree::Price])
+      end
+
+      def discount_price(price, ...)
+        discount = find_discount(price) || build_discount
+        discount.amount = compute_amount(price, ...)
+        discount.label = adjustment_label(price)
+        discount
+      end
+
+      private
+
+      def find_discount(price)
+        price.discounts.detect { |discount| discount.source == self }
+      end
+
+      def build_discount
+        SolidusPromotions::ItemDiscount.new(source: self)
+      end
+    end
+  end
+end

data/app/models/solidus_promotions/benefits/create_discounted_item.rb

@@ -3,30 +3,53 @@
 module SolidusPromotions
   module Benefits
     class CreateDiscountedItem < Benefit
-      include OrderBenefit
       preference :variant_id, :integer
       preference :quantity, :integer, default: 1
       preference :necessary_quantity, :integer, default: 1
 
       def perform(order)
-        line_item = find_item(order) || create_item(order)
+        line_item = find_item(order) || build_item(order)
         set_quantity(line_item, determine_item_quantity(order))
-        line_item.current_discounts << discount(line_item)
+        discount_line_item(line_item)
       end
 
       def remove_from(order)
-        line_item = find_item(order)
-        order.line_items.destroy(line_item)
+        find_item(order)&.mark_for_destruction
       end
 
+      def level
+        :order
+      end
+      deprecate :level, deprecator: Spree.deprecator
+
       private
 
+      def discount_line_item(line_item, ...)
+        adjustment = find_adjustment(line_item) || build_adjustment(line_item)
+        adjustment.amount = compute_amount(line_item, ...)
+        adjustment.label = adjustment_label(line_item)
+        adjustment
+      end
+
+      def find_adjustment(line_item)
+        line_item.adjustments.detect do |adjustment|
+          adjustment.source == self
+        end
+      end
+
+      def build_adjustment(line_item)
+        line_item.adjustments.build(
+          order: line_item.order,
+          source: self
+        )
+      end
+
       def find_item(order)
         order.line_items.detect { |line_item| line_item.managed_by_order_benefit == self }
       end
 
-      def create_item(order)
-        order.line_items.create!(quantity: determine_item_quantity(order), variant: variant, managed_by_order_benefit: self)
+      def build_item(order)
+        order.line_items.build(quantity: determine_item_quantity(order), variant: variant, managed_by_order_benefit: self)
       end
 
       def determine_item_quantity(order)

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

@@ -2,24 +2,50 @@
 
 require_dependency "spree/calculator"
 
-# This is a calculator for line item adjustment benefits. It accepts a line item
-# and calculates its weighted adjustment amount based on the value of the
-# preferred amount and the price of the other line items. More expensive line
-# items will receive a greater share of the preferred amount.
 module SolidusPromotions
   module Calculators
+    # A calculator that distributes a fixed discount amount across line items based on their value.
+    #
+    # This calculator takes a preferred total discount amount and distributes it proportionally
+    # across applicable line items based on their prices. More expensive line items receive
+    # a greater share of the discount.
+    #
+    # @example
+    #   # Given a $30 discount and line items worth $100, $50, and $50:
+    #   # - $100 line item receives $15 discount (50% of total value)
+    #   # - $50 line item receives $7.50 discount (25% of total value)
+    #   # - $50 line item receives $7.50 discount (25% of total value)
     class DistributedAmount < Spree::Calculator
       include PromotionCalculator
 
-      preference :amount, :decimal, default: 0
+      preference :amount, :decimal, default: Spree::ZERO
       preference :currency, :string, default: -> { Spree::Config[:currency] }
 
+      # Computes the weighted discount amount for a specific line item.
+      #
+      # The discount is calculated by distributing the preferred amount across all
+      # applicable line items, weighted by their prices. Returns 0 if:
+      # - The line item is nil
+      # - The currency doesn't match the preferred currency
+      # - The line item is not in the list of applicable line items
+      #
+      # @param line_item [Spree::LineItem] The line item to calculate the discount for
+      #
+      # @return [BigDecimal] The weighted discount amount for this line item
+      #
+      # @example Computing discount for a line item
+      #   calculator = DistributedAmount.new(preferred_amount: 20, preferred_currency: 'USD')
+      #   # Assuming there are 2 line items: one at $80, one at $20
+      #   calculator.compute_line_item(expensive_line_item) # => 16.0 (80% of 20)
+      #   calculator.compute_line_item(cheaper_line_item)   # => 4.0 (20% of 20)
+      #
+      # @see DistributedAmountsHandler
       def compute_line_item(line_item)
-        return 0 unless line_item
-        return 0 unless preferred_currency.casecmp(line_item.currency).zero?
+        return Spree::ZERO unless line_item
+        return Spree::ZERO unless preferred_currency.casecmp(line_item.currency).zero?
 
         distributable_line_items = calculable.applicable_line_items(line_item.order)
-        return 0 unless line_item.in?(distributable_line_items)
+        return Spree::ZERO unless line_item.in?(distributable_line_items)
 
         DistributedAmountsHandler.new(
           distributable_line_items,