spree_core 5.5.2 → 5.6.0.rc1

data/app/models/spree/promotion/rules/market.rb

@@ -0,0 +1,37 @@
+# A rule to limit a promotion based on the order's market.
+module Spree
+  class Promotion
+    module Rules
+      class Market < PromotionRule
+        # Stored as raw IDs. Accepts prefixed IDs (`mkt_…`) from API
+        # callers and decodes them on write so eligibility checks compare
+        # against the order's raw `market_id` directly. Scope confines the
+        # existence check to the promotion's store so cross-store market
+        # IDs can't sneak in.
+        preference :market_ids, :array, default: [],
+                   parse_on_set: normalize_id_preference(
+                     klass: Spree::Market,
+                     scope: ->(rule) { rule.promotion&.store&.markets || Spree::Market.none }
+                   )
+
+        def applicable?(promotable)
+          promotable.is_a?(Spree::Order)
+        end
+
+        def markets
+          return Spree::Market.none if preferred_market_ids.blank?
+
+          promotion.store.markets.where(id: preferred_market_ids)
+        end
+
+        def eligible?(order, _options = {})
+          return false if preferred_market_ids.empty?
+          return true if preferred_market_ids.map(&:to_s).include?(order.market_id.to_s)
+
+          eligibility_errors.add(:base, eligibility_error_message(:no_matching_market))
+          false
+        end
+      end
+    end
+  end
+end

data/app/models/spree/promotion.rb

@@ -2,12 +2,14 @@ module Spree
   class Promotion < Spree.base_class
     has_prefix_id :promo  # Spree-specific: promotion
 
-    include Spree::StoreScopedResource
+    include Spree::SingleStoreResource
     include Spree::Metafields
     include Spree::Metadata
     if defined?(Spree::Security::Promotions)
       include Spree::Security::Promotions
     end
+    # Multi-store sharing moved to the spree_multi_store extension in 5.6.
+    include Spree::LegacyMultiStoreSupport unless defined?(SpreeMultiStore)
 
     publishes_lifecycle_events
 
@@ -37,8 +39,7 @@ module Spree
     has_many :coupon_codes, -> { order(created_at: :asc) }, dependent: :destroy, class_name: 'Spree::CouponCode'
     has_many :order_promotions, class_name: 'Spree::OrderPromotion'
     has_many :orders, through: :order_promotions, class_name: 'Spree::Order'
-    has_many :store_promotions, class_name: 'Spree::StorePromotion'
-    has_many :stores, class_name: 'Spree::Store', through: :store_promotions
+    belongs_to :store, class_name: 'Spree::Store'
 
     after_save :apply_pending_rules_and_actions, if: :pending_rules_or_actions?
 
@@ -60,6 +61,7 @@ module Spree
     #
     validates_associated :rules
     validates :name, presence: true
+    validates :store, presence: true, unless: -> { Spree::Config[:disable_store_presence_validation] }
     validates :usage_limit, numericality: { greater_than: 0, allow_nil: true }
     validates :description, length: { maximum: 255 }, allow_blank: true
     validate :expires_at_must_be_later_than_starts_at, if: -> { starts_at && expires_at }

data/app/models/spree/promotion_handler/promotion_duplicator.rb

@@ -11,7 +11,7 @@ module Spree
         @new_promotion.path = "#{@promotion.path}_#{@random_string}"
         @new_promotion.name = "New #{@promotion.name}"
         @new_promotion.code = "#{@promotion.code}_#{@random_string}"
-        @new_promotion.stores = @promotion.stores
+        @new_promotion.store = @promotion.store
 
         ActiveRecord::Base.transaction do
           @new_promotion.save

data/app/models/spree/role_user.rb

@@ -1,11 +1,14 @@
 module Spree
   class RoleUser < Spree.base_class
+    include Spree::SingleStoreResource
+
     #
     # Associations
     #
     belongs_to :role, class_name: 'Spree::Role', foreign_key: :role_id
     belongs_to :user, polymorphic: true
     belongs_to :resource, polymorphic: true
+    belongs_to :store, class_name: 'Spree::Store'
     belongs_to :invitation, class_name: 'Spree::Invitation', optional: true, inverse_of: :role_user
 
     #
@@ -14,6 +17,7 @@ module Spree
     validates :role, presence: true
     validates :user, presence: true
     validates :resource, presence: true
+    validates :store, presence: true
     validates :role_id, uniqueness: { scope: [:user_id, :resource_id, :user_type, :resource_type] }
 
     #

data/app/models/spree/search_provider/meilisearch.rb

@@ -158,6 +158,7 @@ module Spree
 
         Rails.logger.debug { "[Meilisearch] index=#{index_name} query=#{query.inspect} #{search_params.compact.inspect}" }
 
+        settings_refreshed = false
         begin
           if return_facets && grouped_options.any?
             queries = [{ indexUid: index_name, q: query.to_s, **search_params }]
@@ -175,6 +176,16 @@ module Spree
             facet_distribution = ms_result['facetDistribution'] || {}
           end
         rescue ::Meilisearch::ApiError => e
+          # Self-heal when a newly added filterable attribute (e.g. `preorder`)
+          # is referenced before the index settings were refreshed — otherwise
+          # every search on an upgraded store returns empty until a reindex or
+          # the next product write.
+          if e.code == 'invalid_search_filter' && !settings_refreshed
+            settings_refreshed = true
+            ensure_index_settings!
+            retry
+          end
+
           Rails.logger.warn { "[Meilisearch] Search failed: #{e.message}. Run `rake spree:search:reindex` to initialize the index." }
           Rails.error.report(e, handled: true, context: { index: index_name, query: query })
           return nil
@@ -233,7 +244,7 @@ module Spree
       end
 
       def filterable_attributes
-        %w[product_id status in_stock store_ids channel_ids locale currency available_on discontinue_on price category_ids tags option_value_ids]
+        %w[product_id status in_stock preorder store_ids channel_ids locale currency available_on discontinue_on price category_ids tags option_value_ids]
       end
 
       def sortable_attributes
@@ -266,14 +277,16 @@ module Spree
         conditions << "status = 'active'"
         conditions << "locale = '#{locale.to_s.gsub(/[^a-zA-Z_-]/, '')}'"
         conditions << "currency = '#{currency.to_s.gsub(/[^A-Z]/, '')}'"
-        # Exclude future-dated products — mirrors +Product.available(Time.current)+.
-        # ISO 8601 strings sort lexicographically in chronological order, so the
-        # string compare is sound. +NOT EXISTS+ catches docs indexed before this
-        # attribute was emitted (legacy indexes), +IS NULL+ catches docs where
-        # the field was emitted as explicit null, and the +<=+ clause filters
-        # the remaining future-dated docs — so the upgrade is non-breaking and
-        # no reindex is required.
-        conditions << "(available_on NOT EXISTS OR available_on IS NULL OR available_on <= '#{now.iso8601}')"
+        # Exclude future-dated products — mirrors
+        # +Product.available(Time.current, include_preorderable: true)+. ISO 8601
+        # strings sort lexicographically in chronological order, so the string
+        # compare is sound; +NOT EXISTS+/+IS NULL+ keep the available_on clause
+        # backward-compatible with legacy docs. The trailing +preorder = true+
+        # keeps scheduled "coming soon" pre-orders searchable before their
+        # publish date. It filters on the new +preorder+ attribute, so a
+        # +rake spree:search:reindex+ (or the next product write, which refreshes
+        # the index settings) is required after deploy before it takes effect.
+        conditions << "(available_on NOT EXISTS OR available_on IS NULL OR available_on <= '#{now.iso8601}' OR preorder = true)"
         conditions << "(discontinue_on = 0 OR discontinue_on > #{now.to_i})"
         conditions
       end

data/app/models/spree/setup_task.rb

@@ -0,0 +1,12 @@
+module Spree
+  # An evaluated onboarding task — the serializable result of running a
+  # {Spree::SetupTasks} registry entry against its subject (e.g. a store).
+  # See {Spree::Store#setup_tasks}.
+  class SetupTask
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :name, :string
+    attribute :done, :boolean
+  end
+end

data/app/models/spree/setup_tasks.rb

@@ -0,0 +1,86 @@
+module Spree
+  # Registry of onboarding tasks for a given subject type. `Spree.store_setup_tasks`
+  # holds the Getting Started checklist evaluated against a store; future
+  # registries (e.g. vendor onboarding) instantiate the same class against
+  # their own subject. Defaults are registered in
+  # `config/initializers/spree_store_setup_tasks.rb`; extensions and host apps
+  # can add or remove tasks at boot:
+  #
+  #   Rails.application.config.after_initialize do
+  #     Spree.store_setup_tasks.add :connect_stripe,
+  #       position: 25,
+  #       done: ->(store) { store.payment_methods.active.exists?(type: 'Spree::PaymentMethod::Stripe') }
+  #
+  #     Spree.store_setup_tasks.remove :setup_taxes_collection
+  #   end
+  #
+  # The registry holds domain data only — each frontend maps task keys to its
+  # own presentation: the legacy admin renders the
+  # `spree/admin/dashboard/setup_tasks/_<key>` partial titled by the
+  # `admin.store_setup_tasks.<key>` translation (both resolved across engine
+  # paths, so extensions ship theirs by convention), and the React dashboard
+  # consumes tasks as {Spree::SetupTask} records via the Admin API.
+  class SetupTasks
+    class Definition
+      attr_reader :key, :position
+
+      def initialize(key, position:, done:, **options)
+        raise ArgumentError, "done: must respond to #call" unless done.respond_to?(:call)
+
+        @key = key.to_sym
+        @position = position
+        @done = done
+        @if = options[:if]
+      end
+
+      # @param subject [Object] the record the checklist belongs to (e.g. a store)
+      # @return [Boolean] whether the task is complete
+      def done?(subject)
+        !!@done.call(subject)
+      end
+
+      # @param subject [Object] the record the checklist belongs to
+      # @return [Boolean] whether the task applies to this subject at all
+      def available?(subject)
+        @if.nil? || !!@if.call(subject)
+      end
+    end
+
+    def initialize
+      @tasks = {}
+    end
+
+    # Registers a task (replacing any existing task with the same key).
+    #
+    # @param key [Symbol] identifies the task; frontends derive presentation from it
+    # @param position [Integer] sort order in the checklist
+    # @param done [#call] receives the subject, returns whether the task is complete
+    # @param options [Hash] optional :if (per-subject visibility callable)
+    # @return [Definition]
+    def add(key, position:, done:, **options)
+      key = key.to_sym
+      @tasks[key] = Definition.new(key, position: position, done: done, **options)
+    end
+
+    # @param key [Symbol]
+    # @return [Definition, nil] the removed task
+    def remove(key)
+      @tasks.delete(key.to_sym)
+    end
+
+    def find(key)
+      @tasks[key.to_sym]
+    end
+
+    # @return [Array<Definition>] all tasks sorted by position
+    def tasks
+      @tasks.values.sort_by(&:position)
+    end
+
+    # @param subject [Object] the record the checklist belongs to (e.g. a store)
+    # @return [Array<Definition>] the tasks applicable to the given subject, sorted by position
+    def for(subject)
+      tasks.select { |task| task.available?(subject) }
+    end
+  end
+end

data/app/models/spree/shipment.rb

@@ -130,6 +130,17 @@ module Spree
       cost
     end
 
+    # Strict decimal bridge for string input — raises ArgumentError on
+    # malformed values instead of letting Rails' cast silently truncate
+    # ("12 boxes" would otherwise become 12.0). Blank strings cast to nil,
+    # matching the default Rails behavior.
+    #
+    # @param value [String, Numeric, nil]
+    def cost=(value)
+      value = value.blank? ? nil : BigDecimal(value.strip) if value.is_a?(String)
+      super
+    end
+
     def digital?
       shipping_method&.digital? || false
     end
@@ -347,6 +358,23 @@ module Spree
       shipping_rates
     end
 
+    # Public API v3 name for the selected rate (see docs/plans/6.0-fulfillment-and-delivery.md).
+    #
+    # @return [String, nil] the selected delivery rate's prefixed ID
+    def selected_delivery_rate_id
+      selected_shipping_rate&.prefixed_id
+    end
+
+    # Selects a delivery rate by its public prefixed ID (+dr_...+); raw IDs
+    # are accepted for internal callers. The model owns this naming bridge so
+    # API clients never deal with the legacy shipping-rate name.
+    #
+    # @param id [String, Integer] delivery rate prefixed or raw ID
+    def selected_delivery_rate_id=(id)
+      rate = Spree::PrefixedId.prefixed_id?(id) ? shipping_rates.find_by_prefix_id!(id) : shipping_rates.find(id)
+      self.selected_shipping_rate_id = rate.id
+    end
+
     def selected_shipping_rate_id
       selected_shipping_rate.try(:id)
     end
@@ -422,8 +450,17 @@ module Spree
       package
     end
 
+    # External systems (3PLs, courier APIs) often hand over a complete
+    # tracking link rather than a bare tracking code — returned as-is
+    # instead of being templated into the delivery method's tracking URL.
+    #
+    # @return [String, nil]
     def tracking_url
-      @tracking_url ||= shipping_method&.build_tracking_url(tracking)
+      @tracking_url ||= if tracking&.start_with?('https://')
+                          tracking
+                        else
+                          shipping_method&.build_tracking_url(tracking)
+                        end
     end
 
     def update_amounts

data/app/models/spree/shipment_handler.rb

@@ -7,7 +7,7 @@ module Spree
         # Do we have a specialized shipping-method-specific handler? e.g:
         # Given shipment.shipping_method = Spree::ShippingMethod::DigitalDownload
         # do we have Spree::ShipmentHandler::DigitalDownload?
-        if sm_handler = "Spree::ShipmentHandler::#{shipment.shipping_method.name.split('::').last}".safe_constantize
+        if sm_handler = "Spree::ShipmentHandler::#{shipment.shipping_method&.name&.split('::')&.last}".safe_constantize
           sm_handler.new(shipment)
         else
           new(shipment)

data/app/models/spree/stock/availability_validator.rb

@@ -14,7 +14,7 @@ module Spree
         display_name = variant.name.to_s
         display_name += " (#{variant.options_text})" unless variant.options_text.blank?
 
-        if variant.available?
+        if variant.available? || variant.preorder?
           line_item.errors.add(:quantity,
                                :selected_quantity_not_available,
                                message: Spree.t(:selected_quantity_not_available, item: display_name.inspect))

data/app/models/spree/stock/quantifier.rb

@@ -88,8 +88,28 @@ module Spree
         @backorderable ||= stock_items.any?(&:backorderable)
       end
 
+      # Whether the requested quantity can be supplied. Beyond on-hand stock a
+      # variant may oversell two ways: +backorderable+ stock, or a pre-order
+      # (which also lifts the publish gate for a scheduled launch). Either way
+      # the variant's +backorder_limit+ caps how far below zero it may go; a nil
+      # (empty) limit means unlimited.
       def can_supply?(required = 1)
-        variant.available? && (backorderable? || total_on_hand >= required)
+        return false unless variant.available? || variant.preorder?
+        return true unless variant.should_track_inventory?
+
+        oversellable = backorderable? || variant.preorder?
+        limit = variant.backorder_limit
+        return true if oversellable && limit.nil?
+
+        # On-hand stock, plus — for a capped oversell — the room to sell below
+        # zero down to +-backorder_limit+ (a single clamp of signed on-hand plus
+        # the limit).
+        supplyable = if oversellable
+                       [available_stock - reserved_quantity + limit, 0].max
+                     else
+                       total_on_hand
+                     end
+        supplyable >= required
       end
 
       def stock_items

data/app/models/spree/stock_item.rb

@@ -107,7 +107,8 @@ module Spree
     private
 
     def verify_count_on_hand?
-      count_on_hand_changed? && !backorderable? && (count_on_hand < count_on_hand_was) && (count_on_hand < 0)
+      count_on_hand_changed? && !backorderable? && !variant.preorder? &&
+        (count_on_hand < count_on_hand_was) && (count_on_hand < 0)
     end
 
     # Process backorders based on amount of stock received

data/app/models/spree/stock_location.rb

@@ -157,7 +157,10 @@ module Spree
         else
           on_hand = item.count_on_hand
           on_hand = 0 if on_hand < 0
-          backordered = item.backorderable? ? (quantity - on_hand) : 0
+          # A pre-order oversells like a backorder: the shortfall becomes
+          # backordered inventory units (the backorder_limit cap is enforced
+          # upstream by Stock::Quantifier#can_supply?).
+          backordered = item.backorderable? || variant.preorder? ? (quantity - on_hand) : 0
         end
 
         [on_hand, backordered]

data/app/models/spree/store.rb

@@ -28,7 +28,7 @@ module Spree
     #
     TRANSLATABLE_FIELDS = %i[name meta_description meta_keywords seo_title customer_support_email
                              address contact_phone].freeze
-    translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+    translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
     self::Translation.class_eval do
       acts_as_paranoid
       # deleted translation values still need to be accessible - remove deleted_at scope
@@ -46,7 +46,14 @@ module Spree
     # email preferences
     preference :send_consumer_transactional_emails, :boolean, default: true
     # Checkout preferences
+    # Store-level fallback for the channel-owned `guest_checkout` preference
+    # (see Spree::Channel::Gating). Retained so existing accessors keep working.
     preference :guest_checkout, :boolean, default: true
+    # Store-level fallback for the channel-owned `storefront_access` posture.
+    preference :storefront_access, :string, default: 'public'
+    # Canonical storefront origin used in customer-facing emails and links,
+    # e.g. "https://myshop.com" — see #storefront_url for the fallback chain.
+    preference :storefront_url, :string
     preference :special_instructions_enabled, :boolean, default: false
     preference :stock_reservation_ttl_minutes, :integer, default: 10
     # Address preferences
@@ -74,8 +81,9 @@ module Spree
     has_many :return_authorizations, through: :orders, class_name: 'Spree::ReturnAuthorization'
     # has_many :reimbursements, through: :orders, class_name: 'Spree::Reimbursement' FIXME: we should fetch this via Customer Return
 
-    has_many :store_payment_methods, class_name: 'Spree::StorePaymentMethod'
-    has_many :payment_methods, through: :store_payment_methods, class_name: 'Spree::PaymentMethod'
+    # :nullify (not :destroy) — clearing the collection must not cascade into
+    # Promotion#not_used? / payment records; orphaned rows are detached, not deleted.
+    has_many :payment_methods, class_name: 'Spree::PaymentMethod', dependent: :nullify
 
     has_many :products, class_name: 'Spree::Product', dependent: :nullify
     has_many :product_publications, through: :channels, source: :publications, class_name: 'Spree::ProductPublication'
@@ -91,11 +99,10 @@ module Spree
     has_many :store_credit_events, through: :store_credits, class_name: 'Spree::StoreCreditEvent'
 
     has_many :taxonomies, class_name: 'Spree::Taxonomy'
-    has_many :taxons, through: :taxonomies, class_name: 'Spree::Taxon'
-    has_many :categories, through: :taxonomies, class_name: 'Spree::Category', source: :taxons
+    has_many :taxons, class_name: 'Spree::Taxon'
+    has_many :categories, class_name: 'Spree::Category'
 
-    has_many :store_promotions, class_name: 'Spree::StorePromotion'
-    has_many :promotions, through: :store_promotions, class_name: 'Spree::Promotion'
+    has_many :promotions, class_name: 'Spree::Promotion', dependent: :nullify
 
     has_many :wishlists, class_name: 'Spree::Wishlist'
 
@@ -133,7 +140,10 @@ module Spree
     validates :preferred_digital_asset_authorized_clicks, numericality: { only_integer: true, greater_than: 0 }
     validates :preferred_digital_asset_authorized_days, numericality: { only_integer: true, greater_than: 0 }
     validates :preferred_stock_reservation_ttl_minutes, numericality: { only_integer: true, greater_than: 0 }
+    validates :preferred_storefront_access, inclusion: { in: Spree::Channel::Gating::STOREFRONT_ACCESS }
+    validate :preferred_storefront_url_is_an_origin
     validates :mail_from_address, email: { allow_blank: false }
+    validates :customer_support_email, email: { allow_blank: true }
     # FIXME: we should remove this condition in v5
     if !ENV['SPREE_DISABLE_DB_CONNECTION'] &&
        connected? &&
@@ -152,6 +162,7 @@ module Spree
     #
     # Callbacks
     before_validation :set_default_code, on: :create
+    before_validation :normalize_preferred_storefront_url
     before_save :ensure_default_exists_and_is_unique
     after_create :create_default_policies
 
@@ -276,11 +287,15 @@ module Spree
     end
 
     # Returns the storefront origin URL for use in customer-facing emails and links.
-    # Uses the first allowed origin if configured, otherwise falls back to formatted_url.
+    # Uses the `storefront_url` preference when set, then the oldest non-loopback
+    # allowed origin (the `http://localhost` origin seeded on install must never
+    # leak into customer emails), otherwise falls back to formatted_url.
     #
     # @return [String] e.g. "https://myshop.com"
     def storefront_url
-      allowed_origins.order(:created_at).pick(:origin) || formatted_url
+      preferred_storefront_url.presence ||
+        allowed_origins.order(:created_at).reject(&:loopback?).first&.origin ||
+        formatted_url
     end
 
     # Returns true if the given URL's origin matches one of the store's allowed origins.
@@ -412,5 +427,26 @@ module Spree
     def set_default_code
       self.code = 'default' if code.blank?
     end
+
+    # The storefront URL preference must always hold a canonical origin — it
+    # becomes the base for customer-email links and completes the storefront
+    # setup task, and the v3 Admin API writes it without any controller-side
+    # normalization. Parseable input is canonicalized here; garbage is left
+    # in place for the validation below to reject.
+    def normalize_preferred_storefront_url
+      raw = preferred_storefront_url
+      return if raw.blank?
+
+      normalized = Spree::AllowedOrigin.normalize_origin(raw)
+      self.preferred_storefront_url = normalized if normalized
+    end
+
+    def preferred_storefront_url_is_an_origin
+      raw = preferred_storefront_url
+      return if raw.blank?
+      return if Spree::AllowedOrigin.normalize_origin(raw)
+
+      errors.add(:preferred_storefront_url, :invalid)
+    end
   end
 end

data/app/models/spree/store_payment_method.rb

@@ -1,9 +1,13 @@
 module Spree
+  # Legacy join between Store and PaymentMethod. Superseded by the single-store
+  # +PaymentMethod#store+ FK in 5.6; retained only so the +spree_multi_store+
+  # extension can restore +has_many :stores+ and so the backfill task can read
+  # historic attachments. Dropped in 6.0.
   class StorePaymentMethod < Spree.base_class
     self.table_name = 'spree_payment_methods_stores'
 
     belongs_to :store, class_name: 'Spree::Store', touch: true
-    belongs_to :payment_method, class_name: 'Spree::PaymentMethod', touch: true, inverse_of: :store_payment_methods
+    belongs_to :payment_method, class_name: 'Spree::PaymentMethod', touch: true
 
     validates :store, :payment_method, presence: true
     validates :store_id, uniqueness: { scope: :payment_method_id }

data/app/models/spree/store_promotion.rb

@@ -1,4 +1,8 @@
 module Spree
+  # Legacy join between Store and Promotion. Superseded by the single-store
+  # +Promotion#store+ FK in 5.6; retained only so the +spree_multi_store+
+  # extension can restore +has_many :stores+ and so the backfill task can read
+  # historic attachments. Dropped in 6.0.
   class StorePromotion < Spree.base_class
     self.table_name = 'spree_promotions_stores'