spree_core 5.6.0 → 6.0.0.beta1

data/app/models/spree/imports/price_list_prices.rb

@@ -0,0 +1,72 @@
+module Spree
+  module Imports
+    # Prices for one price list, one rung per row, merged into the list: a row
+    # writes or updates its rung, a blank price removes it, and rungs the file
+    # does not mention stay as they are (docs/plans/6.0-volume-pricing.md).
+    #
+    # The list is a preference rather than a column because it is the only
+    # import type with a parent, and the same serialized store already carries
+    # the other per-type settings.
+    class PriceListPrices < Spree::Import
+      preference :price_list_id, :string, default: nil
+
+      # On create only: the list can be deleted while rows are still being
+      # processed, and the import must still be able to finish (its rows fail
+      # with a message) and to be deleted afterwards.
+      validate :price_list_present, on: :create
+
+      def row_processor_class
+        Spree::Imports::RowProcessors::PriceListPrice
+      end
+
+      # Every rung of a variant is processed together, so the break cap is
+      # judged on the whole ladder the file carries for it.
+      def group_column
+        'sku'
+      end
+
+      def model_class
+        Spree::Price
+      end
+
+      def self.model_class
+        Spree::Price
+      end
+
+      # Price lists are gated by the products scope family, like their own
+      # endpoints (see Admin::PriceListsController).
+      def self.required_scope
+        :products
+      end
+
+      # The list being written. Read through the store, so a preference
+      # pointing at another store's list answers nil and the import is refused.
+      #
+      # @return [Spree::PriceList, nil]
+      def price_list
+        return if preferred_price_list_id.blank? || store.nil?
+
+        store.price_lists.find_by(id: preferred_price_list_id)
+      end
+
+      # @param list [Spree::PriceList, nil]
+      def price_list=(list)
+        self.preferred_price_list_id = list&.id&.to_s
+      end
+
+      # The list's public id without loading it — the serializer emits this
+      # on every poll, and the id was resolved through the store at create.
+      #
+      # @return [String, nil]
+      def price_list_prefixed_id
+        Spree::PriceList.prefixed_id_for(preferred_price_list_id) if preferred_price_list_id.present?
+      end
+
+      private
+
+      def price_list_present
+        errors.add(:price_list, :blank) if price_list.nil?
+      end
+    end
+  end
+end

data/app/models/spree/imports/purchase_orders.rb

@@ -0,0 +1,28 @@
+module Spree
+  module Imports
+    # Draft purchase orders from a supplier's line sheet. Rows sharing a
+    # `reference` are one order; every order this import creates is a draft,
+    # to be checked and placed from its own screen.
+    class PurchaseOrders < Spree::Import
+      def row_processor_class
+        Spree::Imports::RowProcessors::PurchaseOrder
+      end
+
+      def group_column
+        'reference'
+      end
+
+      def model_class
+        Spree::PurchaseOrder
+      end
+
+      def self.model_class
+        Spree::PurchaseOrder
+      end
+
+      def self.required_scope
+        :purchasing
+      end
+    end
+  end
+end

data/app/models/spree/integration.rb

@@ -2,7 +2,29 @@ module Spree
   class Integration < Spree.base_class
     has_prefix_id :int
 
+    # Raised by {#parse_webhook_event} when a webhook's signature is missing
+    # or does not match this integration's secret. The webhook controller
+    # answers 401, so the sender knows its configuration is wrong rather than
+    # retrying forever.
+    WebhookSignatureError = Class.new(StandardError)
+
     include Spree::SingleStoreResource
+    include Spree::PreferenceSchema
+
+    # Spree::Current.integrations snapshots the active set for the request;
+    # connecting or deactivating one mid-request (the activate-and-verify
+    # flow does) must not leave later reads serving the stale snapshot.
+    after_commit -> { Spree::Current.integrations = nil }
+
+    registers_subclasses_via { registered_classes }
+
+    # Integration classes registered via +Spree.integrations+. Entries may be
+    # class-name strings (the documented extension form) or classes.
+    #
+    # @return [Array<Class>]
+    def self.registered_classes
+      Spree.integrations.map { |entry| entry.is_a?(Class) ? entry : entry.to_s.constantize }
+    end
 
     #
     # Associations
@@ -14,6 +36,14 @@ module Spree
     #
     validates :type, presence: true
     validates :store, presence: true, uniqueness: { scope: :type }
+    # An unregistered type can't be configured or displayed — reject it at
+    # save rather than surfacing as a broken card in the dashboard. On change
+    # only, so rows survive their gem being uninstalled.
+    validate :type_must_be_registered, if: :type_changed?
+    # Verify-before-activate (decisions.md 2026-08-06): saving credentials
+    # never makes a network call; flipping active on does, and a failed
+    # connection blocks going live with the seller's message attached.
+    validate :must_connect_when_activating, if: -> { active? && will_save_change_to_active? }
 
     #
     # Scopes
@@ -34,24 +64,94 @@ module Spree
       nil
     end
 
-    def self.icon_path
+    # Logo shown on the gallery card: an absolute URL to publicly hosted
+    # brand assets, or a `data:` URI for gems that want to be self-contained
+    # (works air-gapped, no CSP domain to allowlist). Anything an `<img src>`
+    # accepts. Deliberately not an asset-pipeline path — integration gems
+    # must not force an asset pipeline onto headless API hosts. Hosted logos
+    # are a courtesy, not a guarantee: the dashboard falls back to a letter
+    # avatar when unset or unreachable.
+    #
+    # @return [String, nil]
+    def self.logo_url
       nil
     end
 
+    # One-line marketing description shown on the integration's gallery card.
+    # Localize by shipping a Rails translation instead (or additionally):
+    # `spree.integrations.<api_type>.description` wins over this fallback.
+    #
+    # @return [String, nil]
+    def self.description
+      nil
+    end
+
+    # Description for the current locale: the gem's Rails translation when
+    # present, otherwise the {.description} fallback. Named per the
+    # human_name/human_description convention of the rule families.
+    #
+    # @return [String, nil]
+    def self.human_description
+      Spree.t("integrations.#{api_type}.description", default: description)
+    end
+
+    # Wire entries for the admin types-discovery endpoint — every registered
+    # integration with its gallery metadata and configuration schema, stably
+    # ordered by name.
+    #
+    # @return [Array<Hash>]
+    def self.discovery_entries
+      registered_classes.map do |klass|
+        {
+          type: klass.api_type,
+          name: klass.integration_name,
+          group: klass.integration_group,
+          description: klass.human_description,
+          logo_url: klass.logo_url,
+          preference_schema: klass.serialized_preference_schema
+        }
+      end.sort_by { |entry| entry[:name] }
+    end
+
     def self.integration_name
       name.demodulize.titleize.strip
     end
 
-    def self.integration_key
-      name.demodulize.underscore
+    # Wire shorthand for the admin API. Provider gems follow the
+    # `SpreeEasyPost::Integration` convention, where demodulizing collapses
+    # every gem to 'integration' — so classes named exactly `Integration`
+    # derive the shorthand from their outer module instead
+    # (`SpreeEasyPost` → 'easy_post').
+    def self.api_type
+      return super unless name.demodulize == 'Integration'
+
+      outer = name.deconstantize.delete_prefix('Spree')
+      return super if outer.blank?
+
+      outer.underscore
     end
 
     def name
       self.class.integration_name
     end
 
-    def key
-      self.class.integration_key
+    # Verifies and parses a provider webhook addressed to this integration.
+    #
+    # The base implementation accepts nothing: an integration that takes
+    # webhooks overrides this, verifies the signature against its own secret
+    # (raising {WebhookSignatureError} when it is missing or wrong), and
+    # returns the event translated into vocabulary core understands. Carrier
+    # integrations return {Spree::Deliveries::UpdateTracking} keyword
+    # arguments plus +tracking_code+; +nil+ means "not an event we act on",
+    # which the endpoint acknowledges without doing anything.
+    #
+    # @param _raw_post [String] the request body exactly as received — HMAC
+    #   signatures are computed over the raw bytes, so it must not be re-parsed
+    #   or re-encoded before verification
+    # @param _headers [#[]] the request headers
+    # @return [Hash, nil]
+    def parse_webhook_event(_raw_post, _headers)
+      nil
     end
 
     # Checks if the integration can establish a connection.
@@ -61,5 +161,28 @@ module Spree
     def can_connect?
       true
     end
+
+    private
+
+    def type_must_be_registered
+      return if type.blank?
+      # An empty registry means no integration gem is installed — nothing to
+      # validate against (and the admin API resolves types through the
+      # registry anyway, so nothing unregistered arrives from there).
+      return if Spree.integrations.empty?
+      return if Spree.integrations.map(&:to_s).include?(type)
+
+      errors.add(:type, :integration_type_not_registered, message: Spree.t('errors.messages.integration_type_not_registered'))
+    end
+
+    # On :base, not :active — the seller's message ("This api key is no
+    # longer active…") is a record-level failure, and an attribute error
+    # would render with the humanized attribute prepended ("Active This
+    # api key…").
+    def must_connect_when_activating
+      return if can_connect?
+
+      errors.add(:base, connection_error_message.presence || Spree.t('errors.messages.integration_connection_failed'))
+    end
   end
 end

data/app/models/spree/inventory_provider/base.rb

@@ -0,0 +1,30 @@
+module Spree
+  module InventoryProvider
+    # Contract for inventory sources — what answers "how many of this variant
+    # exist, and where".
+    #
+    # A provider returns {Spree::StockLevel} rows: {Internal} the persisted
+    # ones, an external provider **unsaved, readonly** instances carrying the
+    # remote system's counts. {Spree::Stock::Quantifier} does the arithmetic
+    # over whatever rows it is handed, so backorder limits, preorders and local
+    # checkout reservations behave the same either way — an external system
+    # does not know about our carts, so those holds must stay local.
+    #
+    # **Only decision points consult a provider.** Add-to-cart, taking a
+    # reservation and completing checkout ask; listings, product pages and
+    # search read the local snapshot the sync feed maintains. A provider on the
+    # read path would mean one remote call per product tile, and would take the
+    # storefront down with the remote system.
+    class Base
+      include Spree::IntegrationBackedProvider
+
+      # @param variant [Spree::Variant]
+      # @param stock_location [Spree::StockLocation, nil] narrows to one location
+      # @return [Enumerable<Spree::StockLevel>]
+      def stock_levels_for(_variant, stock_location: nil)
+        raise NotImplementedError, "#{self.class} must implement #stock_levels_for"
+      end
+
+    end
+  end
+end

data/app/models/spree/inventory_provider/internal.rb

@@ -0,0 +1,22 @@
+module Spree
+  module InventoryProvider
+    # Spree's own stock records. Returns the association untouched so
+    # {Spree::Stock::Quantifier} keeps its loaded-association fast path — a
+    # preloaded variant must not fall back to a query per stock item.
+    #
+    # Location narrowing and active-location filtering stay in the Quantifier,
+    # which already does both; doing them here as well would break that
+    # preload branch for no gain.
+    class Internal < Base
+      # @param variant [Spree::Variant]
+      # @param stock_location [Spree::StockLocation, nil]
+      # @return [Enumerable<Spree::StockLevel>]
+      def stock_levels_for(variant, stock_location: nil)
+        return variant.stock_levels if stock_location.blank?
+        return variant.stock_levels.select { |item| item.stock_location_id == stock_location.id } if variant.association(:stock_levels).loaded?
+
+        variant.stock_levels.where(stock_location: stock_location)
+      end
+    end
+  end
+end

data/app/models/spree/inventory_unit.rb

@@ -1,141 +1,5 @@
 module Spree
-  class InventoryUnit < Spree.base_class
-    has_prefix_id :fi
-
-    extend Spree::DisplayMoney
-
-    with_options inverse_of: :inventory_units do
-      belongs_to :variant, -> { with_deleted }, class_name: 'Spree::Variant'
-      belongs_to :order, class_name: 'Spree::Order'
-      belongs_to :shipment, class_name: 'Spree::Shipment', touch: true, optional: true
-      has_many :return_items, class_name: 'Spree::ReturnItem', inverse_of: :inventory_unit
-      has_many :return_authorizations, class_name: 'Spree::ReturnAuthorization', through: :return_items
-      belongs_to :line_item, class_name: 'Spree::LineItem'
-    end
-
-    belongs_to :original_return_item, class_name: 'Spree::ReturnItem'
-
-    scope :backordered, -> { where state: 'backordered' }
-    scope :on_hand, -> { where state: 'on_hand' }
-    scope :on_hand_or_backordered, -> { where state: ['backordered', 'on_hand'] }
-    scope :shipped, -> { where state: 'shipped' }
-    scope :returned, -> { where state: 'returned' }
-    scope :backordered_per_variant, ->(stock_item) do
-      includes(:shipment, :order).
-        where.not(spree_shipments: { state: 'canceled' }).
-        where(variant_id: stock_item.variant_id).
-        where.not(spree_orders: { completed_at: nil }).
-        backordered.order('spree_orders.completed_at ASC')
-    end
-
-    validates :quantity, numericality: { greater_than: 0 }
-
-    money_methods :charged_amount
-
-    # state machine (see http://github.com/pluginaweek/state_machine/tree/master for details)
-    state_machine initial: :on_hand do
-      event :fill_backorder do
-        transition to: :on_hand, from: :backordered
-      end
-      after_transition on: :fill_backorder, do: :fulfill_order
-
-      event :ship do
-        transition to: :shipped, if: :allow_ship?
-      end
-
-      event :return do
-        transition to: :returned, from: :shipped
-      end
-    end
-
-    # This was refactored from a simpler query because the previous implementation
-    # led to issues once users tried to modify the objects returned. That's due
-    # to ActiveRecord `joins(shipment: :stock_location)` only returning readonly
-    # objects
-    #
-    # Returns an array of backordered inventory units as per a given stock item
-    def self.backordered_for_stock_item(stock_item)
-      backordered_per_variant(stock_item).select do |unit|
-        unit.shipment.stock_location == stock_item.stock_location
-      end
-    end
-
-    def self.finalize_units!
-      update_all(pending: false, updated_at: Time.current)
-    end
-
-    def find_stock_item
-      shipment.stock_location.stock_item_or_create(variant)
-    end
-
-    def self.split(original_inventory_unit, extract_quantity)
-      split = original_inventory_unit.dup
-      split.quantity = extract_quantity
-      original_inventory_unit.quantity -= extract_quantity
-      split
-    end
-
-    # This will fail if extract >= available_quantity
-    def split_inventory!(extract_quantity)
-      split = self.class.split(self, extract_quantity)
-      transaction do
-        split.save!
-        save!
-      end
-      split
-    end
-
-    def extract_singular_inventory!
-      split_inventory!(1)
-    end
-
-    def current_or_new_return_item
-      Spree::ReturnItem.from_inventory_unit(self)
-    end
-
-    def additional_tax_total
-      line_item.additional_tax_total * percentage_of_line_item
-    end
-
-    def included_tax_total
-      line_item.included_tax_total * percentage_of_line_item
-    end
-
-    def required_quantity
-      return @required_quantity unless @required_quantity.nil?
-
-      @required_quantity = if exchanged_unit?
-                             original_return_item.return_quantity
-                           else
-                             line_item.quantity
-                           end
-    end
-
-    def exchanged_unit?
-      original_return_item_id?
-    end
-
-    def charged_amount
-      percentage_of_line_item * line_item.pre_tax_amount
-    end
-
-    def percentage_of_line_item
-      quantity / BigDecimal(line_item.quantity)
-    end
-
-    private
-
-    def allow_ship?
-      on_hand?
-    end
-
-    def fulfill_order
-      reload
-      order.fulfill!
-    end
-
-    def current_return_item
-      return_items.not_cancelled.first
-    end
-  end
+  # Constant alias for the legacy Spree::InventoryUnit, renamed to
+  # Spree::FulfillmentItem in 6.0. Remove in 6.1.
+  InventoryUnit = FulfillmentItem
 end

data/app/models/spree/invitation.rb

@@ -13,7 +13,7 @@ module Spree
     #
     # Associations
     #
-    belongs_to :resource, polymorphic: true # eg. Store, Vendor, Account
+    belongs_to :resource, polymorphic: true # eg. Store, Seller, Account
     belongs_to :inviter, polymorphic: true # User or AdminUser
     belongs_to :invitee, polymorphic: true, optional: true # User or AdminUser
     belongs_to :role, class_name: 'Spree::Role'
@@ -24,9 +24,10 @@ module Spree
     #
     validates :email, email: true, presence: true
     validates :token, presence: true, uniqueness: true
-    validates :inviter, :resource, :role, presence: true
+    validates :inviter, :resource, presence: true
     validate :invitee_is_not_inviter, on: :create
     validate :invitee_already_exists, on: :create
+    validate :role_belongs_to_resource
 
     #
     # Scopes
@@ -36,25 +37,21 @@ module Spree
     scope :not_expired, -> { where('expires_at > ?', Time.current) }
 
     #
-    # State Machine
+    # Status
     #
-    state_machine initial: :pending, attribute: :status do
-      state :accepted do
-        validate :accept_invitation_within_time_limit
-        validates :invitee, presence: true
-      end
-
-      event :accept do
-        transition pending: :accepted
-      end
-      after_transition to: :accepted, do: :after_accept
-      after_transition to: :accepted, do: :publish_invitation_accepted_event
-    end
+    # No state machine — acceptance runs through Spree::Invitations::Accept
+    # (docs/plans/6.0-service-workflows.md), which checks the expiry window
+    # and the invitee before it writes. Those were state-scoped validations
+    # on the machine's `accepted` state; as workflow guards they refuse the
+    # acceptance outright instead of leaving a record that fails to save.
+    include Spree::HasStatus
+    has_status :pending, :accepted, default: :pending
 
     #
     # Callbacks
     #
     after_initialize :set_defaults, if: :new_record?
+    before_validation :set_role_and_resource, if: :new_record?
     before_validation :set_invitee_from_email, on: :create
     after_commit :publish_invitation_created_event, on: :create, unless: :skip_email
 
@@ -79,6 +76,27 @@ module Spree
       expires_at < Time.current
     end
 
+    # @deprecated Call Spree.invitation_accept_workflow — removed in 6.1.
+    def accept
+      Spree::Deprecation.warn('Spree::Invitation#accept is deprecated and will be removed in Spree 6.1. Call Spree.invitation_accept_workflow instead.')
+      Spree.invitation_accept_workflow.call(invitation: self).success?
+    end
+
+    # @deprecated Call Spree.invitation_accept_workflow — removed in 6.1.
+    def accept!
+      Spree::Deprecation.warn('Spree::Invitation#accept! is deprecated and will be removed in Spree 6.1. Call Spree.invitation_accept_workflow instead.')
+      result = Spree.invitation_accept_workflow.call(invitation: self)
+
+      if result.failure?
+        # ResultError#to_s unwraps an ActiveModel::Errors into its full
+        # messages; its `value` would inspect the object into the message.
+        errors.add(:base, result.error.to_s)
+        raise ActiveRecord::RecordInvalid, self
+      end
+
+      true
+    end
+
     # Resends the invitation email if the invitation is pending and not expired
     def resend!
       return if expired? || deleted? || accepted?
@@ -88,16 +106,6 @@ module Spree
 
     private
 
-    # this method can be extended by developers now
-    def after_accept
-      create_role_user
-      set_accepted_at
-    end
-
-    def publish_invitation_accepted_event
-      publish_event('invitation.accepted')
-    end
-
     def publish_invitation_created_event
       publish_event('invitation.created')
     end
@@ -110,16 +118,32 @@ module Spree
 
     def set_defaults
       self.expires_at ||= 2.weeks.from_now
-      self.resource ||= Spree::Store.current
-      self.role ||= Spree::Role.default_admin_role
+    end
+
+    # A role names what it governs, so the invitation follows it — one carrying
+    # another resource's role would grant access somewhere the inviter never
+    # named. Resolved at validation rather than on initialize, since a caller's
+    # own `resource` is not assigned yet when the record is instantiated.
+    def set_role_and_resource
+      self.resource ||= role&.resource || Spree::Store.current
+      self.role ||= Spree::Role.default_admin_role(resource)
     end
 
     def invitee_is_not_inviter
       if invitee == inviter
-        errors.add(:invitee, 'cannot be the same as the inviter')
+        errors.add(:invitee, :same_as_inviter, message: Spree.t('errors.messages.same_as_inviter'))
       end
     end
 
+    # Accepting the invitation grants the role, which carries its own resource
+    # — so a mismatch would hand out access to somewhere else entirely.
+    def role_belongs_to_resource
+      return if role.blank? || resource.blank?
+      return if role.resource == resource
+
+      errors.add(:role, :invitation_role_resource_mismatch, message: Spree.t(:invitation_role_resource_mismatch))
+    end
+
     def invitee_already_exists
       return if resource.blank?
 
@@ -128,32 +152,14 @@ module Spree
       return if user_to_check.blank?
 
       if resource.role_users.exists?(user: user_to_check)
-        errors.add(:email, 'already exists')
+        errors.add(:email, :already_a_member, message: Spree.t('errors.messages.already_a_member'))
       end
     end
 
-    def set_accepted_at
-      update!(accepted_at: Time.current)
-    end
-
-    def create_role_user
-      return if invitee.blank?
-
-      role_user = resource.add_user(invitee, role)
-      self.role_user = role_user
-      save!
-    end
-
     def set_invitee_from_email
       return if invitee.present?
 
       self.invitee = Spree.admin_user_class.find_by(email: email)
     end
-
-    def accept_invitation_within_time_limit
-      if Time.current > expires_at
-        errors.add(:base, 'Invitation expired')
-      end
-    end
   end
 end

data/app/models/spree/label_purchase.rb

@@ -0,0 +1,29 @@
+module Spree
+  # What a label-generating fulfillment provider hands back from
+  # +purchase_label+: the carrier's answer, typed, before core turns it into
+  # a +Spree::ShippingLabel+ and its +Spree::Delivery+. Ephemeral, never
+  # persisted.
+  #
+  # +cost+ and +currency+ are what the merchant paid the carrier; +file_url+
+  # is the provider's hosted copy of the label, fetched into private storage
+  # right after purchase. +metadata+ carries whatever ids the provider needs
+  # to find the purchase again (a tracker id, a shipment id).
+  class LabelPurchase
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    attribute :external_id, :string
+    attribute :carrier, :string
+    attribute :service, :string
+    attribute :tracking_number, :string
+    attribute :tracking_url, :string
+    attribute :cost, :decimal, default: 0
+    attribute :currency, :string
+    attribute :format, :string
+    attribute :file_url, :string
+    attribute :metadata, default: -> { {} }
+
+    validates :tracking_number, presence: true
+    validates :cost, numericality: { greater_than_or_equal_to: 0 }
+  end
+end