solidus_promotions 4.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db60a6f38884af89ad6588b3b6306f7bda9b9d67170ffeee5b171ed72a0ddafb
+  data.tar.gz: 756a0ef51fc6355fa90f5b7824d30d96701b3e9f672da33bf92fa05d845addd3
+SHA512:
+  metadata.gz: f8a85cbf84e94bae9702b35cb2dfc376bf5c86f7b144dadfe553637ac51ea8392711cf6fd828773ca358a452f48361a7be5866546a1133fa17cecd46188c75dd
+  data.tar.gz: 0fc83043628ca2454361030801fdd08484a638b9e9a0241d422cd453e40bc6d322cde88c0076741cab1371864a9c75ed1b109c981a762daed816399eefceaec6

data/.eslintrc.json

@@ -0,0 +1,10 @@
+{
+  "extends": "eslint:recommended",
+  "parserOptions": {
+    "ecmaVersion": 2023,
+    "sourceType": "module"
+  },
+  "globals": {
+    "Turbo": "readonly"
+  }
+}

data/.github/stale.yml

@@ -0,0 +1 @@
+_extends: .github

data/MIGRATING.md

@@ -0,0 +1,184 @@
+# Migrating from `solidus_legacy_promotions` to `solidus_promotions`
+
+The system is designed to completely replace the legacy promotion system. This guide shows you how
+to run both systems side-by-side, migrate your store's configuration to the `solidus_promotions`, and
+finally remove the dependency on `solidus_legacy_promotions`.
+
+Follow these steps to migrate your store to the gem:
+
+## Install solidus_promotions
+
+Add the following line to your `Gemfile`:
+
+```rb
+gem "solidus_promotions"
+```
+
+Then run
+
+```sh
+bundle install
+bundle exec rails generate solidus_promotions:install
+```
+
+This will install the extension. It will add new tables, and new routes. It will also change your initializer in `config/initializers/spree.rb`.
+
+For the time being, leave the following lines commented out:
+
+```rb
+# Make sure we use Spree::SimpleOrderContents
+# Spree::Config.order_contents_class = "Spree::SimpleOrderContents"
+# Set the promotion configuration to ours
+# Spree::Config.promotions = SolidusPromotions.configuration
+```
+
+This makes sure that the behavior of the current promotion system does not change - yet.
+
+## Migrate existing promotions
+
+Now, run the promotion migrator:
+
+```sh
+bundle exec rails solidus_promotions:migrate_existing_promotions
+```
+
+This will create equivalents of the legacy promotion configuration in SolidusPromotions.
+
+Now, change `config/initializers/solidus_promotions.rb` to use your new promotion configuration:
+
+## Change store behavior to use SolidusPromotions
+
+```rb
+# Make sure we use Spree::SimpleOrderContents
+Spree::Config.order_contents_class = "Spree::SimpleOrderContents"
+# Set the promotion configuration to ours
+Spree::Config.promotions = SolidusPromotions.configuration
+
+# Sync legacy order promotions with the new promotion system
+SolidusPromotions.config.sync_order_promotions = true
+```
+
+From a user's perspective, your promotions should work as before.
+
+Before you create new promotions, migrate the adjustments and order promotions in your database:
+
+```rb
+bundle exec rails solidus_promotions:migrate_adjustments:up
+bundle exec rails solidus_promotions:migrate_order_promotions:up
+
+```
+
+Check your `spree_adjustments` table for correctness. If things went wrong, you should be able to roll back with
+
+```rb
+bundle exec rails solidus_promotions:migrate_adjustments:down
+bundle exec rails solidus_promotions:migrate_order_promotions:down
+```
+
+Both of these tasks only work if every promotion rule and promotion action have an equivalent condition or benefit in SolidusFrienndlyPromotions. Benefits are connected to their originals promotion action using the `SolidusPromotions#original_promotion_action_id`, Promotions are connected to their originals using the  `SolidusPromotions#original_promotion_id`.
+
+Once these tasks have run and everything works, you can stop syncing legacy order promotions and new order promotions:
+
+```rb
+SolidusPromotions.config.sync_order_promotions = false
+```
+
+## Solidus Starter Frontend (and other custom frontends)
+
+Stores that have a custom coupon codes controller, such as Solidus' starter frontend, have to change the coupon promotion handler to the one from this gem. Cange any reference to `Spree::PromotionHandler::Coupon` to `Spree::Config.promotions.coupon_code_handler_class`.
+
+## Migrating custom rules and actions
+
+If you have custom promotion rules or actions, you need to create new conditions and benefits, respectively.
+
+> [!IMPORTANT]
+> SolidusPromotions only supports actions that discount line items and shipments, as well as creating discounted line items. If you have actions that create order-level adjustments, we have no support for that.
+
+In our experience, using the three actions can do almost all the things necessary, since they are customizable using calculators.
+
+Rules share a lot of the previous API. If you make use of `#actionable?`, you might want to migrate your rule to be a line-item level rule:
+
+```rb
+class MyRule < Spree::PromotionRule
+  def actionable?(promotable)
+    promotable.quantity > 3
+  end
+end
+```
+
+would become:
+
+```rb
+class MyCondition < SolidusPromotions::Condition
+  include LineItemLevelCondition
+
+  def eligible?(promotable)
+    promotable.quantity > 3
+  end
+end
+```
+
+Now, create your own Promotion conversion map:
+
+```rb
+require 'solidus_promotions/promotion_map'
+
+MY_PROMOTION_MAP = SolidusPromotions::PROMOTION_MAP.deep_merge(
+  rules: {
+    MyRule => MyCondition
+  }
+)
+```
+
+The value of the conversion map can also be a callable that takes the original promotion rule and should return a new condition.
+
+```rb
+require 'solidus_promotions/promotion_map'
+
+MY_PROMOTION_MAP = SolidusPromotions::PROMOTION_MAP.deep_merge(
+  rules: {
+    MyRule => ->(old_promotion_rule) {
+      MyCondition.new(preferred_quantity: old_promotion_rule.preferred_count)
+    }
+  }
+)
+```
+
+You can now run our migrator with your map:
+
+```rb
+require 'solidus_promotions/promotion_migrator'
+require 'my_promotion_map'
+
+SolidusPromotions::PromotionMigrator.new(MY_PROMOTION_MAP).call
+```
+
+## Removing `solidus_legacy_promotions`
+
+Once your store runs on `solidus_promotions`, you can now drop the dependency on `solidus_legacy_promotions`.
+In order to do so, first make sure you have no ineligible promotion adjustments left in your database:
+
+```rb
+>> Spree::Adjustment.where(eligible: false)
+=> 0
+>>
+```
+
+If you still have ineligible adjustments in your database, run the following command:
+
+```sh
+bundle exec rails solidus_legacy_promotions:delete_ineligible_adjustments
+```
+
+Now you can safely remove `solidus_legacy_promotions` from your `Gemfile`. If your store depends on the whole `solidus` suite,
+replace that dependency declaration in the `Gemfile` with the individual gems:
+
+```diff
+# Gemfile
+- gem 'solidus', '~> 4,4'
++ gem 'solidus_core', '~> 4.4'
++ gem 'solidus_api', '~> 4.4'
++ gem 'solidus_backend', '~> 4.4'
++ gem 'solidus_admin', '~> 4.4'
++ gem 'solidus_promotions', '~> 4.4'
+```

data/README.md

@@ -0,0 +1,122 @@
+# Solidus Promotions
+
+This gem contains Solidus' recommended promotion system. It is slated to replace the promotion system in the `legacy_promotions` gem.
+
+The basic architecture is very similar to the legacy promotion system, but with a few decisive tweaks, which I'll explain in the coming sections.
+
+## Architecture
+
+This extension centralizes promotion handling in the order updater. A service class, the `SolidusPromotions::OrderAdjuster` applies the current promotion configuration to the order, adjusting or removing adjustments as necessary.
+
+`SolidusPromotions::Promotion` objects have benefits, and benefits have conditions. For example, a promotion that is "20% off shirts" would have a benefit of type "AdjustLineItem", and that benefit would have a condition of type "LineItemTaxon" that makes sure only line items with the "shirts" taxon will get the benefit.
+
+### Promotion lanes
+
+Promotions get applied by "lane". Promotions within a lane conflict with each other, whereas promotions that do not share a lane will apply sequentially in the order of the lanes. By default these are "pre", "default" and "post", but you can configure this using the SolidusPromotions initializer:
+
+```rb
+SolidusPromotions.configure do |config|
+  config.preferred_lanes = {
+    pre: 0,
+    default: 1,
+    grogu: 2,
+    post: 3
+  }
+end
+```
+
+### Benefits
+
+Solidus Friendly Promotions ships with only three benefit types by default that should cover most use cases: `AdjustLineItem`, `AdjustShipment` and `CreateDiscountedItem`. There is no benefit that creates order-level adjustments, as this feature of Solidus' legacy promotions system has proven to be very difficult for customer service and finance departments due to the difficulty of accruing order-level adjustments to individual line items when e.g. processing returns. In order to give a fixed discount to all line items in an order, use the `AdjustLineItem` benefit with the `DistributedAmount` calculator.
+
+Alle benefits are calculable. By setting their `calculator` to one of the classes provided, a great range of discounts is possible.
+
+#### `AdjustLineItem`
+
+Benefits of this class will create promotion adjustments on line items. By default, they will create a discount on every line item in the order. If you want to restrict which line items get the discount, add line-item level conditions, such as `LineItemProduct`.
+
+#### `AdjustShipment`
+
+Benefits of this class will create promotion adjustments on shipments. By default, they will create a discount on every shipment in the order. If you want to restrict which shipments get a discount, add shipment-level conditions, such as `ShippingMethod`.
+
+### Conditions
+
+Every type of benefit has a list of rules that can be applied to them. When calculating adjustments for an order, benefits will only produce adjustments on line items or shipments if all their respective conditions are true.
+
+### Connecting promotions to orders
+
+When there is a join record `SolidusPromotions::OrderPromotion`, the promotion and the order will be "connected", and the promotion will be applied even if it does not `apply_automatically` (see below). This is different from Solidus' legacy promotion system here in that promotions are not automatically connected to orders when they produce an adjustment.
+
+If you want to create an `OrderPromotion` record, the usual way to do this is via a promotion handler:
+
+- `SolidusPromotions::PromotionHandler::Coupon`: Connects orders to promotions if a customer or service agent enters a matching promotion code.
+- `SolidusPromotions::PromotionHandler::Page`: Connects orders to promotions if a customer visits a page with the correct path. This handler is not integrated in core Solidus, and must be integrated by you.
+- `SolidusPromotions::PromotionHandler::Page`: Connects orders to promotions if a customer visits a page with the correct path. This handler is not integrated in core Solidus, and must be integrated by you.
+
+### Promotion categories
+
+Promotion categories simply allow admins to group promotions. They have no further significance with regards to the functionality of the promotion system.
+
+### Promotion recalculation
+
+Solidus allows changing orders up until when they are shipped. SolidusPromotions therefore will recalculate orders up until when they are shipped as well. If your admins change promotions rather than add new ones and carefully manage the start and end dates of promotions, you might want to disable this feature:
+
+```rb
+SolidusPromotions.configure do |config|
+  config.recalculate_complete_orders = false
+end
+```
+
+## Installation
+
+Add solidus_promotions to your Gemfile:
+
+```ruby
+gem 'solidus_promotions'
+```
+
+Once this project is out of the research phase, a proper gem release will follow.
+
+Bundle your dependencies and run the installation generator:
+
+```shell
+bin/rails generate solidus_promotions:install
+```
+
+This will create the tables for this extension. It will also replace the promotion administration system under
+`/admin/promotions` with a new one that needs `turbo-rails`. It will also create an initializer within which Solidus is configured to use `Spree::SimpleOrderContents` and this extension's `OrderAdjuster` classes. Feel free to override with your own implementations!
+
+## Usage
+
+Add a promotion using the admin. Add benefits with conditions, and observe promotions getting applied how you'd expect them to.
+
+In the admin screen, you can set a number of attributes on your promotion:
+- Name: The name of the promotion. The `name` attribute will also be used to generate adjustment labels. In multi-lingual stores, you probably want different promotions per language for this reason.
+
+- Description: This is purely informative. Some stores use `description` in order display information about this promotion to customers, but there is nothing in core Solidus that does it.
+
+- Start and End: Outside of the time range between `starts_at` and `expires_at`, the promotion will not be eligible to any order.
+
+- Usage Limit: `usage_limit` controls to how many orders this promotion can be applied, independent of promotion code or user. This is most commonly used to limit the risk of losing too much revenue with a particular promotion.
+
+- Path: `path` is a URL path that connects the promotion to the order upon visitation. Not currently implemented in either Solidus core or this extension.
+
+- Per Code Usage Limit: How often each code can be used. Useful for limiting how many orders can be placed with a single promotion code.
+
+- Apply Automatically: Whether this promotion should apply automatically. This means that the promotion is checked for eligibility every time the customer's order is recalculated. Promotion Codes and automatic applications are incompatible.
+
+- Promotion Category: Used to group promotions in the admin view.
+
+## Development
+
+When testing your application's integration with this extension you may use its factories.
+You can load Solidus core factories along with this extension's factories using this statement:
+
+```ruby
+SolidusDevSupport::TestingSupport::Factories.load_for(SolidusPromotions::Engine)
+```
+
+
+## License
+
+Copyright (c) 2024 Martin Meyerhoff, Solidus Team, released under the New BSD License.

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "rake"
+require "rake/testtask"
+require "rspec/core/rake_task"
+require "solidus_legacy_promotions"
+require "spree/testing_support/dummy_app/rake_tasks"
+require "solidus_admin/testing_support/dummy_app/rake_tasks"
+require "bundler/gem_tasks"
+
+RSpec::Core::RakeTask.new
+task default: :spec
+
+DummyApp::RakeTasks.new(
+  gem_root: File.dirname(__FILE__),
+  lib_name: "solidus_promotions"
+)
+
+task test_app: "db:reset"

data/app/assets/config/solidus_promotions/manifest.js

@@ -0,0 +1,13 @@
+//= link backend/solidus_promotions.js
+//= link backend/solidus_promotions/controllers/application.js
+//= link backend/solidus_promotions/controllers/index.js
+//= link backend/solidus_promotions/controllers/calculator_tiers_controller.js
+//= link backend/solidus_promotions/controllers/flash_controller.js
+//= link backend/solidus_promotions/controllers/product_option_values_controller.js
+//= link backend/solidus_promotions/web_components/option_value_picker.js
+//= link backend/solidus_promotions/web_components/product_picker.js
+//= link backend/solidus_promotions/web_components/user_picker.js
+//= link backend/solidus_promotions/web_components/taxon_picker.js
+//= link backend/solidus_promotions/web_components/variant_picker.js
+//= link backend/solidus_promotions/web_components/number_with_currency.js
+//= link backend/solidus_promotions/web_components/select_two.js

data/app/decorators/models/solidus_promotions/adjustment_decorator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module AdjustmentDecorator
+    def self.prepended(base)
+      base.scope :solidus_promotion, -> { where(source_type: "SolidusPromotions::Benefit") }
+    end
+
+    Spree::Adjustment.prepend self
+  end
+end

data/app/decorators/models/solidus_promotions/line_item_decorator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module LineItemDecorator
+    def self.prepended(base)
+      base.attr_accessor :quantity_setter
+      base.belongs_to :managed_by_order_benefit, class_name: "SolidusPromotions::Benefit", optional: true
+      base.validate :validate_managed_quantity_same, on: :update
+      base.after_save :reset_quantity_setter
+    end
+
+    private
+
+    def validate_managed_quantity_same
+      if managed_by_order_benefit && quantity_changed? && quantity_setter != managed_by_order_benefit
+        errors.add(:quantity, :cannot_be_changed_for_automated_items)
+      end
+    end
+
+    def reset_quantity_setter
+      @quantity_setter = nil
+    end
+
+    Spree::LineItem.prepend self
+    Spree::LineItem.prepend SolidusPromotions::DiscountableAmount
+  end
+end

data/app/decorators/models/solidus_promotions/order_decorator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module OrderDecorator
+    module ClassMethods
+      def allowed_ransackable_associations
+        super + ["solidus_promotions", "solidus_order_promotions"]
+      end
+    end
+
+    def self.prepended(base)
+      base.has_many :solidus_order_promotions,
+        class_name: "SolidusPromotions::OrderPromotion",
+        dependent: :destroy,
+        inverse_of: :order
+      base.has_many :solidus_promotions, through: :solidus_order_promotions, source: :promotion
+    end
+
+    def discountable_item_total
+      line_items.sum(&:discountable_amount)
+    end
+
+    def reset_current_discounts
+      line_items.each(&:reset_current_discounts)
+      shipments.each(&:reset_current_discounts)
+    end
+
+    # This helper method excludes line items that are managed by an order benefit for the benefit
+    # of calculators and benefits that discount normal line items. Line items that are managed by an
+    # order benefits handle their discounts themselves.
+    def discountable_line_items
+      line_items.reject(&:managed_by_order_benefit)
+    end
+
+    def free_from_order_benefit?(line_item, _options)
+      !line_item.managed_by_order_benefit
+    end
+
+    Spree::Order.singleton_class.prepend self::ClassMethods
+    Spree::Order.prepend self
+  end
+end

data/app/decorators/models/solidus_promotions/order_recalculator_decorator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module OrderRecalculatorDecorator
+    # This is only needed for stores upgrading from the legacy promotion system.
+    # Once we've removed support for the legacy promotion system, we can remove this.
+    def recalculate
+      if SolidusPromotions.config.sync_order_promotions
+        MigrationSupport::OrderPromotionSyncer.new(order: order).call
+      end
+      super
+    end
+    Spree::Config.order_recalculator_class.prepend self
+  end
+end

data/app/decorators/models/solidus_promotions/shipment_decorator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module ShipmentDecorator
+    Spree::Shipment.prepend SolidusPromotions::DiscountableAmount
+
+    def reset_current_discounts
+      super
+      shipping_rates.each(&:reset_current_discounts)
+    end
+
+    Spree::Shipment.prepend self
+  end
+end

data/app/decorators/models/solidus_promotions/shipping_rate_decorator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module ShippingRateDecorator
+    def self.prepended(base)
+      base.class_eval do
+        has_many :discounts,
+          class_name: "SolidusPromotions::ShippingRateDiscount",
+          foreign_key: :shipping_rate_id,
+          dependent: :destroy,
+          inverse_of: :shipping_rate,
+          autosave: true
+
+        money_methods :total_before_tax, :promo_total
+      end
+    end
+
+    def total_before_tax
+      amount + promo_total
+    end
+
+    def promo_total
+      discounts.sum(&:amount)
+    end
+
+    Spree::ShippingRate.prepend SolidusPromotions::DiscountableAmount
+    Spree::ShippingRate.prepend self
+  end
+end

data/app/helpers/solidus_promotions/admin/benefits_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module Admin
+    module BenefitsHelper
+      def options_for_benefit_calculator_types(benefit)
+        calculators = benefit.available_calculators
+        options = calculators.map { |calculator| [calculator.model_name.human, calculator.name] }
+        options_for_select(options, benefit.calculator_type.to_s)
+      end
+
+      def options_for_benefit_types(benefit)
+        benefits = SolidusPromotions.config.benefits
+        options = benefits.map { |action| [action.model_name.human, action.name] }
+        options_for_select(options, benefit&.type&.to_s)
+      end
+    end
+  end
+end

data/app/helpers/solidus_promotions/admin/conditions_helper.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module Admin
+    module ConditionsHelper
+      def options_for_condition_types(benefit, condition)
+        options = benefit.available_conditions.map do |available_condition|
+          [available_condition.model_name.human, available_condition.name]
+        end
+        options_for_select(options, condition&.type.to_s)
+      end
+    end
+  end
+end

data/app/helpers/solidus_promotions/admin/promotions_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SolidusPromotions
+  module Admin
+    module PromotionsHelper
+      def admin_promotion_status(promotion)
+        return :active if promotion.active?
+        return :not_started if promotion.not_started?
+        return :expired if promotion.expired?
+
+        :inactive
+      end
+    end
+  end
+end

data/app/javascript/backend/solidus_promotions/controllers/application.js

@@ -0,0 +1,9 @@
+import { Application } from "@hotwired/stimulus";
+
+const application = Application.start();
+
+// Configure Stimulus development experience
+application.debug = false;
+window.Stimulus = application;
+
+export { application };

data/app/javascript/backend/solidus_promotions/controllers/calculator_tiers_controller.js

@@ -0,0 +1,37 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["links", "template"];
+
+  connect() {
+    this.wrapperClass = this.data.get("wrapperClass") || "calculator-tiers";
+  }
+
+  add_association(event) {
+    event.preventDefault();
+
+    var content = this.templateTarget.innerHTML;
+    this.linksTarget.insertAdjacentHTML("beforebegin", content);
+  }
+
+  propagate_base_to_value_input(event) {
+    event.preventDefault();
+
+    // targets the content of the last pair of square brackets
+    // we first need to greedily match all other square brackets
+    const regEx = /(\[.*\])\[.*?\]$/;
+    let wrapper = event.target.closest("." + this.wrapperClass);
+    let valueInput = wrapper.querySelector(".js-value-input");
+    valueInput.name = valueInput.name.replace(
+      regEx,
+      `$1[${event.target.value}]`
+    );
+  }
+
+  remove_association(event) {
+    event.preventDefault();
+
+    let wrapper = event.target.closest("." + this.wrapperClass);
+    wrapper.remove();
+  }
+}

data/app/javascript/backend/solidus_promotions/controllers/flash_controller.js

@@ -0,0 +1,10 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  connect() {
+    window.show_flash(
+      this.element.dataset.severity,
+      this.element.dataset.message
+    );
+  }
+}

data/app/javascript/backend/solidus_promotions/controllers/index.js

@@ -0,0 +1,8 @@
+import { application } from "backend/solidus_promotions/controllers/application";
+
+// Eager load all controllers defined in the import map under controllers/**/*_controller
+import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading";
+eagerLoadControllersFrom(
+  "backend/solidus_promotions/controllers",
+  application
+);