spree_core 5.6.1 → 6.0.0.beta1

data/app/models/concerns/spree/has_library_media.rb

@@ -0,0 +1,94 @@
+module Spree
+  # Puts a model's named image slots in the media library.
+  #
+  # A file uploaded straight to a category's image slot used to exist only as
+  # an ActiveStorage attachment — in storage but invisible to the library: no
+  # grid entry, no search, no reuse. Declaring the slots here keeps them
+  # reconciled with real +Spree::Media+ placements (+viewable+ = this record)
+  # sharing the slot blobs, so the library sees what the merchant uploaded and
+  # can hand the file to anything else.
+  #
+  # The named attachments remain the operational storage every serializer and
+  # storefront reads; the placements are the library's view of them. Clearing
+  # or replacing a slot UNPLACES its row — back to the library pool — rather
+  # than destroying it, because the merchant's file outliving one use is the
+  # point of having a library.
+  #
+  #   include Spree::HasLibraryMedia
+  #   has_library_media :image, :square_image
+  #
+  # Until a real gallery arrives for these models, reconciliation owns every
+  # placement on the record: a row whose blob no slot holds is unplaced. A
+  # future gallery replaces the slots as the source of truth and this concern
+  # dissolves into it.
+  module HasLibraryMedia
+    extend ActiveSupport::Concern
+
+    included do
+      # nullify, not destroy: deleting the record returns its files to the
+      # library instead of taking them along.
+      has_many :media, class_name: 'Spree::Media', as: :viewable, dependent: :nullify
+
+      class_attribute :library_media_slots, instance_writer: false, default: [].freeze
+
+      before_save :note_library_media_changes
+      after_commit :sync_changed_library_media, on: %i[create update]
+    end
+
+    class_methods do
+      # Declares which attachment slots live in the library.
+      #
+      # @param slots [Array<Symbol>] attachment names, e.g. +:image+
+      # @return [void]
+      def has_library_media(*slots)
+        self.library_media_slots = (library_media_slots | slots.map(&:to_s)).freeze
+      end
+    end
+
+    # Reconciles this record's placements against its slots: a slot blob with
+    # no placement gains one, a placement whose blob no slot holds is
+    # unplaced. Runs on save when a slot changed; callable directly for
+    # backfills.
+    #
+    # @return [void]
+    def sync_library_media!
+      desired_blobs = library_media_slots.each_with_object({}) do |slot, blobs|
+        attachment = public_send(slot)
+        blobs[attachment.blob.id] ||= attachment.blob if attachment.attached?
+      end
+
+      media.includes(attachment_attachment: :blob).each do |placement|
+        blob_id = placement.attachment_blob&.id
+        next if blob_id && desired_blobs.delete(blob_id)
+
+        placement.update!(viewable: nil)
+      end
+
+      desired_blobs.each_value do |blob|
+        placement = Spree::Media.new(viewable: self, alt: blob.filename.to_s)
+        placement.attachment.attach(blob)
+        placement.save!
+      end
+    end
+
+    private
+
+    # Attachment changes are consumed by the save, so whether a slot moved has
+    # to be noted before it and acted on after commit — reconciling on every
+    # save would tax frequent slot-less writes like category repositioning.
+    def note_library_media_changes
+      @library_media_slots_changed ||= library_media_slots.any? do |slot|
+        attachment_changes.key?(slot)
+      end
+
+      true
+    end
+
+    def sync_changed_library_media
+      return unless @library_media_slots_changed
+
+      @library_media_slots_changed = false
+      sync_library_media!
+    end
+  end
+end

data/app/models/concerns/spree/has_list_position.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spree
+  # Shared list-position ordering for models using acts_as_list.
+  #
+  # Position is the merchant-facing precedence; id breaks ties so two rows
+  # sharing a position resolve the same way on every read.
+  module HasListPosition
+    extend ActiveSupport::Concern
+
+    included do
+      scope :ordered, -> { order(Arel.sql("#{table_name}.position ASC, #{table_name}.id ASC")) }
+    end
+  end
+end

data/app/models/concerns/spree/has_number.rb

@@ -0,0 +1,139 @@
+module Spree
+  # Declarative human-readable document number for models whose number is
+  # shown to a person — on an order confirmation, a supplier purchase order,
+  # a transfer slip taped to a box (docs/plans/6.0-document-numbers.md).
+  #
+  #   class Spree::Order < Spree.base_class
+  #     has_spree_number prefix: 'R'
+  #   end
+  #
+  # Included into {Spree::Base}, so the macro is available on every model and
+  # nothing happens until one calls it — no callback, no class attributes.
+  #
+  # The concern owns the parts that never vary: assigning a number before
+  # validation, retrying on collision, and rescuing the unique-index race.
+  # Which string to try is the generator's job, and the generator is resolved
+  # per record at save time rather than frozen at class-definition time —
+  # that is what lets a merchant switch formats in settings, and an extension
+  # swap the whole strategy through {Spree.number_generators}, without
+  # reopening this class.
+  module HasNumber
+    extend ActiveSupport::Concern
+
+    # A generator that keeps colliding is a bug in the generator, not bad
+    # luck. Bail loudly rather than spinning in a save.
+    MAX_ATTEMPTS = 10
+
+    class GenerationError < StandardError; end
+
+    class_methods do
+      # @param prefix [String] leads every number for this model, e.g. 'R'
+      # @param key [Symbol] registry key; defaults to the demodulized,
+      #   underscored model name (`Spree::StockTransfer` → `:stock_transfer`)
+      def has_spree_number(prefix:, key: nil)
+        class_attribute :number_prefix, default: prefix, instance_writer: false
+        class_attribute :number_key,
+                        default: (key || name.demodulize.underscore).to_sym,
+                        instance_writer: false
+
+        before_validation :generate_number, on: :create
+      end
+
+      # Whether this model opted into generated numbers. The concern lives on
+      # every model through {Spree::Base}, so ask rather than assuming.
+      #
+      # @return [Boolean]
+      def has_spree_number?
+        respond_to?(:number_key)
+      end
+
+      # The generator instance for this model, resolved fresh each call so a
+      # host app can swap the registry entry at runtime (and so Zeitwerk
+      # reloads pick up a redefined class in development).
+      #
+      # @param store [Spree::Store, nil] the record's store, whose format
+      #   preference picks the strategy when nothing is registered
+      # @return [Spree::NumberGenerators::Base]
+      def number_generator(store: nil)
+        Spree.number_generators.for(number_key, store: store)
+      end
+    end
+
+    # Assigns a number unless one was supplied. Public so a workflow can
+    # force assignment before validation when it needs the number earlier.
+    #
+    # @return [String] the assigned number
+    def generate_number
+      return number if number.present?
+
+      generator = self.class.number_generator(store: number_store)
+
+      MAX_ATTEMPTS.times do
+        candidate = generator.generate(self)
+        next if candidate.blank?
+
+        unless number_taken?(candidate)
+          @number_generated = true
+          return self.number = candidate
+        end
+      end
+
+      raise GenerationError,
+            "#{self.class.name} could not generate a unique number after " \
+            "#{MAX_ATTEMPTS} attempts using #{generator.class.name}"
+    end
+
+    # The store whose number settings apply. Most numbered models belong to a
+    # store directly; stock transfers reach one through their destination
+    # location. Falls back to the current store so a numbered model added
+    # later works without teaching this concern about it.
+    #
+    # @return [Spree::Store, nil]
+    def number_store
+      return store if respond_to?(:store) && store.present?
+
+      Spree::Current.store
+    end
+
+    private
+
+    # Advisory only — a concurrent writer can take the number between this
+    # check and the insert, which is what the unique-index rescue below is
+    # for. Unscoped because the index is global.
+    def number_taken?(candidate)
+      self.class.unscoped.exists?(number: candidate)
+    end
+
+    # Last line of defence. The pre-check and the uniqueness validation both
+    # read committed rows, so neither can see a number another writer commits
+    # in the instant between the check and this insert — only the index can.
+    #
+    # The insert runs in a savepoint because a constraint violation poisons
+    # the surrounding PostgreSQL transaction: without one, the regenerate
+    # queries below would themselves die with PG::InFailedSqlTransaction
+    # instead of recovering. Only creates whose number this concern generated
+    # pay for the savepoint — caller-supplied numbers should surface their
+    # collision, and updates never touch the number.
+    #
+    # Regenerate and retry once; a second collision is a real problem worth
+    # surfacing rather than looping on.
+    def create_or_update(**, &block)
+      return super unless new_record? && @number_generated
+
+      begin
+        self.class.transaction(requires_new: true) { super }
+      rescue ActiveRecord::RecordNotUnique => error
+        raise error if @number_regenerated || !number_collision?(error)
+
+        @number_regenerated = true
+        self.number = nil
+        generate_number
+        retry
+      end
+    end
+
+    def number_collision?(error)
+      error.message.to_s.downcase.include?('number')
+    end
+  end
+end

data/app/models/concerns/spree/has_status.rb

@@ -0,0 +1,76 @@
+module Spree
+  # Declarative status column for models whose transitions belong to workflows
+  # rather than a state machine (docs/plans/6.0-service-workflows.md,
+  # decision 11).
+  #
+  #   class Spree::Return < Spree.base_class
+  #     include Spree::HasStatus
+  #     has_status :requested, :approved, :received, :refunded, :canceled,
+  #                default: :requested
+  #   end
+  #
+  # Generates an inclusion validation, a predicate per value (`#received?`)
+  # and a scope per value (`.received`) — nothing else. There are no events,
+  # no transition graph and no callbacks: moving a record between statuses is
+  # a workflow's job, which is what lets a transition take arguments, perform
+  # gateway I/O outside a transaction, and compensate when a later step fails.
+  #
+  # Values live in a class_attribute rather than a frozen constant so an
+  # extension can add its own without reopening core.
+  module HasStatus
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # @param values [Array<Symbol, String>] the valid statuses, in order
+      # @param default [Symbol, String] applied as an attribute default at
+      #   instantiation — never a database default (see the migration rules
+      #   in CLAUDE.md)
+      def has_status(*values, default:)
+        values = values.map(&:to_s)
+
+        class_attribute :statuses, default: values, instance_writer: false
+        class_attribute :default_status, default: default.to_s, instance_writer: false
+
+        attribute :status, :string, default: default.to_s
+
+        validates :status, inclusion: { in: ->(record) { record.class.statuses } }
+
+        values.each { |value| define_status_methods(value) }
+
+        # Multi-value lookup, replacing what state_machines-activerecord
+        # generated. The single-value scopes read better for one status;
+        # this exists for the "any of these" case.
+        scope :with_status, ->(*wanted) { where(status: wanted.flatten.map(&:to_s)) }
+      end
+
+      # Appends a status. Additive by design: core workflows guard on core
+      # statuses (`Returns::Refund` requires `received?`), so allowing removal
+      # would silently break those guards — they would simply never pass.
+      #
+      # A custom status needs a custom workflow to move records into it. That
+      # is deliberate rather than a gap: validating transitions centrally
+      # would be a state machine by another name.
+      #
+      # @param value [Symbol, String]
+      # @param after [Symbol, String, nil] position in the list; appended when nil
+      def add_status(value, after: nil)
+        value = value.to_s
+        return if statuses.include?(value)
+
+        index = after ? statuses.index(after.to_s)&.succ : nil
+        self.statuses = statuses.dup.insert(index || statuses.size, value)
+        define_status_methods(value)
+      end
+
+      private
+
+      def define_status_methods(value)
+        # A status may collide with a method Rails already defines — Payment's
+        # `invalid` vs ActiveModel#invalid? — so an existing method is never
+        # redefined. The status itself stays valid; callers compare `status`.
+        define_method(:"#{value}?") { status == value } unless method_defined?(:"#{value}?")
+        scope value, -> { where(status: value) } unless respond_to?(value)
+      end
+    end
+  end
+end

data/app/models/concerns/spree/has_tracking_carrier.rb

@@ -0,0 +1,18 @@
+module Spree
+  # A carrier a consignment or a label is pinned to.
+  #
+  # The value is free text by design: +Spree.tracking_carriers+ supplies
+  # display names and tracking-page templates for the carriers Spree knows,
+  # and anything else — a freight forwarder, a courier a merchant uses once —
+  # is a legal value that simply has no entry.
+  module HasTrackingCarrier
+    extend ActiveSupport::Concern
+
+    # @return [String, nil] the registry's display name, or the value as entered
+    def carrier_name
+      return if carrier.blank?
+
+      Spree.tracking_carriers.dig(carrier, :name) || carrier
+    end
+  end
+end

data/app/models/concerns/spree/instruments_gateway_calls.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Spree
+  # Marks a payment-gateway network call for tracing subscribers via the
+  # 'gateway.spree_payments' notification. The payload is PII-safe by
+  # design — gateway action and payment method class only; never amounts,
+  # sources, credentials, or gateway responses.
+  module InstrumentsGatewayCalls
+    private
+
+    def instrument_gateway_call(action, payment_method, &block)
+      ActiveSupport::Notifications.instrument(
+        'gateway.spree_payments',
+        action: action.to_s,
+        payment_method_type: payment_method&.type,
+        &block
+      )
+    end
+  end
+end

data/app/models/concerns/spree/integration_backed_provider.rb

@@ -0,0 +1,89 @@
+module Spree
+  # Shared contract for provider classes whose credentials live on a
+  # {Spree::Integration}: delivery rates, fulfillment, pricing and inventory.
+  #
+  # A provider declares only +integration_class+; whether a store may use it,
+  # how it is labelled in the admin, and how its credentials are resolved all
+  # follow from that. Stating those three rules once means a change to what
+  # "connected" means — an expired OAuth grant, say — lands in one place
+  # rather than in each provider family.
+  module IntegrationBackedProvider
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # The registry key a merchant's store preference stores (and, for
+      # pricing, the value written to +spree_line_items.price_source+).
+      # Gems override it to name their system: 'acme_erp', not 'pricing_provider'.
+      #
+      # @return [String]
+      def key
+        name.demodulize.underscore
+      end
+
+      # The Spree::Integration subclass holding this provider's credentials,
+      # as a class name string. Internal providers need none.
+      #
+      # @return [String, nil]
+      def integration_class
+        nil
+      end
+
+      # Whether the store can use this provider at all — admin pickers hide or
+      # prompt-to-connect providers whose integration is not connected.
+      #
+      # @param store [Spree::Store, nil]
+      # @return [Boolean]
+      def available_for_store?(store)
+        return true if integration_class.blank?
+
+        active_integrations(store).any? { |integration| integration.type == integration_class }
+      end
+
+      # The store's active integrations — through {Spree::Current} for the
+      # request's own store, so a whole registry's availability checks and
+      # every provider's credential lookup share one query per request.
+      #
+      # @param store [Spree::Store, nil]
+      # @return [Array<Spree::Integration>]
+      def active_integrations(store)
+        return [] if store.nil?
+        return Spree::Current.integrations if store.id == Spree::Current.store&.id
+
+        store.integrations.active.to_a
+      end
+
+      # The name a merchant sees when choosing a provider.
+      #
+      # A gem's provider is conventionally named for its family
+      # (+SpreeEasyPost::PricingProvider+), so demodulizing yields the useless
+      # "Pricing Provider" — those derive the label from the gem's outer module
+      # instead (+SpreeEasyPost+ → "EasyPost"), matching
+      # {Spree::Integration.api_type}.
+      #
+      # @return [String]
+      def provider_name
+        leaf = name.demodulize
+        outer = name.deconstantize.delete_prefix('Spree')
+
+        return leaf.titleize if outer.blank? || !leaf.end_with?('Provider')
+
+        # Not `titleize` — it would split the gem's own casing
+        # ("SpreeEasyPost" → "Easy Post"). Brands that need more than the
+        # module name override this method.
+        outer.delete_prefix('::')
+      end
+    end
+
+    # The connected, active integration carrying this provider's credentials.
+    # Request-cached via {Spree::Current.integrations}, so a provider asking
+    # per catalog row costs one query per request, not one per row.
+    #
+    # @param store [Spree::Store, nil]
+    # @return [Spree::Integration, nil]
+    def integration_for(store)
+      return if self.class.integration_class.blank?
+
+      self.class.active_integrations(store).find { |integration| integration.type == self.class.integration_class }
+    end
+  end
+end

data/app/models/concerns/spree/integrations_concern.rb

@@ -1,11 +1,24 @@
 module Spree
+  # @deprecated Use {Spree::Current.integrations}; removed in Spree 6.1.
+  #
+  # Nothing in Spree calls these — the per-request integration set lives on
+  # {Spree::Current} — but the concern sits on Spree::Base, so every model has
+  # carried the methods as public surface since they shipped.
   module IntegrationsConcern
     def store_integrations
-      @store_integrations ||= Spree::Store.current.integrations.active.to_a
+      Spree::Deprecation.warn(
+        'Spree::IntegrationsConcern#store_integrations is deprecated and will be removed in Spree 6.1. '         'Use Spree::Current.integrations instead.'
+      )
+
+      Spree::Current.integrations
     end
 
     def store_integration(name)
-      store_integrations.find { |integration| integration.type.to_s.demodulize.underscore == name }
+      Spree::Deprecation.warn(
+        'Spree::IntegrationsConcern#store_integration is deprecated and will be removed in Spree 6.1. '         'Use Spree::Current.integrations.find { |integration| integration.type.to_s.demodulize.underscore == name } instead.'
+      )
+
+      Spree::Current.integrations.find { |integration| integration.type.to_s.demodulize.underscore == name }
     end
   end
 end

data/app/models/concerns/spree/label_translatable.rb

@@ -0,0 +1,37 @@
+module Spree
+  # Shared by models whose single translatable field is +label+ (OptionType,
+  # OptionValue). Carries the Mobility setup and the translation-table
+  # normalizer in one place so the two models don't restate it.
+  module LabelTranslatable
+    extend ActiveSupport::Concern
+    include Spree::TranslatableResource
+
+    TRANSLATABLE_FIELDS = %i[label].freeze
+
+    included do
+      translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
+
+      self::Translation.class_eval do
+        normalizes :label, with: ->(value) { value&.to_s&.squish&.presence }
+      end
+    end
+
+    # @deprecated The column is +label+ since 6.0; removed in 6.1.
+    #
+    # Unlike the attribute aliases the other 6.0 renames use, this is a plain
+    # method — Mobility owns +label+, so it cannot be an alias_attribute. It
+    # therefore reads and writes only on an instance: +where(presentation:)+
+    # and +find_by(presentation:)+ name a column that no longer exists and
+    # raise. Query by +label+.
+    def presentation(*args, **kwargs)
+      Spree::Deprecation.warn("#{self.class.name}#presentation is deprecated and will be removed in Spree 6.1. Use #label instead.")
+      label(*args, **kwargs)
+    end
+
+    # @deprecated See {#presentation}; removed in 6.1.
+    def presentation=(value)
+      Spree::Deprecation.warn("#{self.class.name}#presentation= is deprecated and will be removed in Spree 6.1. Use #label= instead.")
+      self.label = value
+    end
+  end
+end

data/app/models/concerns/spree/marketplace/order_group.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Spree
+  module Marketplace
+    # What a marketplace wants to know about one checkout's group of orders.
+    #
+    # {Spree::OrderGroup} is deliberately domain-neutral — "N orders placed
+    # together as one customer transaction" — because the same container serves
+    # split-by-location, split-by-availability and B2B split-by-company-location,
+    # none of which involve a seller
+    # (docs/plans/6.0-multi-vendor-marketplace.md, Decision 8). So the seller is
+    # asked about here rather than there, and the primitive keeps meaning the
+    # same thing for its other consumers.
+    module OrderGroup
+      extend ActiveSupport::Concern
+
+      # @return [ActiveRecord::Relation<Spree::Seller>] the sellers this
+      #   checkout reached; the operator's own goods contribute none
+      def sellers
+        store.sellers.where(id: orders.filter_map(&:seller_id).uniq)
+      end
+
+      # @return [Integer]
+      def seller_count
+        orders.filter_map(&:seller_id).uniq.size
+      end
+
+      # @return [Boolean] whether any child order carries no seller — the
+      #   operator's own goods, bought alongside sellers' in one checkout
+      def includes_first_party?
+        orders.any? { |order| order.seller_id.nil? }
+      end
+    end
+  end
+end

data/app/models/concerns/spree/metadata.rb

@@ -1,35 +1,31 @@
 module Spree
+  # Private, schemaless developer data. Deliberately does NOT pull in
+  # {Spree::HasCustomFields} — custom fields are the separate, public,
+  # schema-defined system. Models that want both include both.
   module Metadata
     extend ActiveSupport::Concern
 
-    include Spree::Metafields unless included_modules.include?(Spree::Metafields)
-
     included do
-      attribute :public_metadata, default: {}
-      attribute :private_metadata, default: {}
-
-      serialize :public_metadata, coder: HashSerializer
-      serialize :private_metadata, coder: HashSerializer
-    end
+      attribute :metadata, default: {}
 
-    # `metadata` is the primary API-facing accessor.
-    # It maps to `private_metadata` under the hood (Stripe-style: write-only, never returned in Store API).
-    def metadata
-      private_metadata
+      serialize :metadata, coder: HashSerializer
     end
 
-    def metadata=(value)
-      self.private_metadata = value
+    # Deprecated alias for the renamed `metadata` column. Removed in Spree 6.1.
+    #
+    # Only the reader and writer are bridged. The column is gone, so the attribute
+    # methods Active Record generated alongside it — `private_metadata?`,
+    # `private_metadata_changed?`, `private_metadata_was`,
+    # `private_metadata_before_type_cast` and the rest of the dirty-tracking family
+    # — no longer exist and raise NoMethodError. Call the `metadata` equivalents.
+    def private_metadata
+      Spree::Deprecation.warn('private_metadata is deprecated and will be removed in Spree 6.1. Use metadata instead.')
+      metadata
     end
 
-    def public_metadata=(value)
-      unless value.blank? || value == {}
-        Spree::Deprecation.warn(
-          'public_metadata is deprecated and will be removed in Spree 6.0. ' \
-          'Use metadata instead. For customer-visible structured data, use metafields with display_on: \'both\'.'
-        )
-      end
-      super
+    def private_metadata=(value)
+      Spree::Deprecation.warn('private_metadata= is deprecated and will be removed in Spree 6.1. Use metadata= instead.')
+      self.metadata = value
     end
 
     # https://nandovieira.com/using-postgresql-and-jsonb-with-ruby-on-rails

data/app/models/concerns/spree/named_type.rb

@@ -1,12 +1,22 @@
 module Spree
+  # Shared behaviour for the reason vocabularies — return, claim, refund and
+  # order cancellation. They are store-owned, listed alphabetically, and
+  # filtered on `active`, so the scoping lives here rather than being
+  # repeated per model.
   module NamedType
     extend ActiveSupport::Concern
 
     included do
+      include Spree::SingleStoreResource
+
       scope :active, -> { where(active: true) }
       default_scope { order(name: :asc) }
 
-      include Spree::UniqueName
+      normalizes :name, with: ->(value) { value&.to_s&.squish&.presence }
+
+      validates :name, presence: true
+      # Per store, not global: two stores can each have their own "Damaged".
+      validates_store_uniqueness :name
     end
   end
 end

data/app/models/concerns/spree/parameterizable_name.rb

@@ -3,12 +3,12 @@ module Spree
     extend ActiveSupport::Concern
 
     included do
-      normalizes :name, :presentation, with: ->(value) { value&.to_s&.squish&.presence }
+      normalizes :name, :label, with: ->(value) { value&.to_s&.squish&.presence }
 
       #
       # Callbacks
       #
-      before_validation :set_name_from_presentation, if: -> { name.blank? }
+      before_validation :set_name_from_label, if: -> { name.blank? }
       before_validation :normalize_name
 
       #
@@ -16,12 +16,12 @@ module Spree
       #
       scope :search_by_name, ->(query) do
         i18n do
-          name.matches("%#{query.downcase}%").or(presentation.matches("%#{query.downcase}%"))
+          name.matches("%#{query.downcase}%").or(label.matches("%#{query.downcase}%"))
         end
       end
 
-      def set_name_from_presentation
-        self.name = presentation
+      def set_name_from_label
+        self.name = label
       end
 
       def normalize_name