spree_core 5.6.1 → 6.0.0.beta1

data/app/models/spree/store_credit.rb

@@ -3,7 +3,7 @@ module Spree
     has_prefix_id :credit
 
     include Spree::SingleStoreResource
-    include Spree::Metafields
+    include Spree::HasCustomFields
     include Spree::Metadata
 
     publishes_lifecycle_events
@@ -19,33 +19,83 @@ module Spree
     ALLOCATION_ACTION = 'allocation'.freeze
 
     belongs_to :store, class_name: 'Spree::Store'
-    belongs_to :user, class_name: "::#{Spree.user_class}", foreign_key: 'user_id'
-    belongs_to :category, class_name: 'Spree::StoreCreditCategory', optional: true
+    # A gift card applied to a guest cart issues store credit with no customer
+    # to attach it to.
+    belongs_to :customer, class_name: "::#{Spree.customer_class}", optional: true
+    include Spree::DeprecatedCustomerAlias
     belongs_to :created_by, class_name: Spree.admin_user_class.to_s, foreign_key: 'created_by_id', optional: true
-    belongs_to :credit_type, class_name: 'Spree::StoreCreditType', foreign_key: 'type_id', optional: true
     belongs_to :originator, polymorphic: true, optional: true
 
     has_many :store_credit_events, class_name: 'Spree::StoreCreditEvent'
     has_many :payments, as: :source, class_name: 'Spree::Payment'
     has_many :orders, through: :payments, class_name: 'Spree::Order'
 
-    validates :currency, :store, presence: true
+    validates :currency, presence: true
     validates :amount, numericality: { greater_than: 0 }
     validates :amount_used, numericality: { greater_than_or_equal_to: 0 }
     validate :amount_used_less_than_or_equal_to_amount
     validate :amount_authorized_less_than_or_equal_to_amount
 
-    delegate :name, to: :category, prefix: true, allow_nil: true
     delegate :email, to: :created_by, prefix: true, allow_nil: true
 
-    scope :order_by_priority, -> { includes(:credit_type).order('spree_store_credit_types.priority ASC') }
+    # Redemption order: the oldest credit is spent first.
+    scope :oldest_first, -> { order(:created_at, :id) }
+    # @deprecated Removed in Spree 6.1 — store credit types are gone; use {.oldest_first}.
+    scope :order_by_priority, lambda {
+      Spree::Deprecation.warn('Spree::StoreCredit.order_by_priority is deprecated and will be removed in Spree 6.1. Use .oldest_first instead.')
+      oldest_first
+    }
 
     scope :not_authorized, -> { where(amount_authorized: 0) }
     scope :not_used, -> { where("#{Spree::StoreCredit.table_name}.amount_used < #{Spree::StoreCredit.table_name}.amount") }
+    # Spendable right now, for the checkout path: a credit with any amount
+    # authorized is mid-payment and must not be authorized again, even though
+    # part of it may still be unspent. Narrower than {.unspent} on purpose.
     scope :available, -> { not_authorized.not_used }
+
+    # Money the store still owes: whatever is neither spent nor committed to an
+    # in-flight authorization. A credit of 100 with 10 authorized has 90 left
+    # and belongs here, which is what separates this from {.available}.
+    scope :unspent, lambda {
+      table = arel_table
+      committed = Arel::Nodes::Grouping.new(table[:amount_used] + table[:amount_authorized])
+      where(committed.lt(table[:amount]))
+    }
+
+    # The complement of {.unspent}: nothing left to draw on.
+    scope :exhausted, lambda {
+      table = arel_table
+      committed = Arel::Nodes::Grouping.new(table[:amount_used] + table[:amount_authorized])
+      where(committed.gteq(table[:amount]))
+    }
     scope :with_gift_card, -> { where(originator_type: 'Spree::GiftCard') }
     scope :without_gift_card, -> { where(originator_type: [nil, '']).or(where.not(originator_type: 'Spree::GiftCard')) }
 
+    # What a merchant filters the credit list by: money still owed, or money
+    # already spent. One ransackable scope with two named states rather than
+    # two bare scopes, so the filter control offers a choice instead of a
+    # checkbox whose unticked state means "no filter".
+    #
+    # Splat, not a defaulted argument: Ransack splats an array predicate, and
+    # asking for both sides is no constraint at all. See Spree::Base.ransack_flag.
+    scope :outstanding, ->(*values) {
+      case Spree::Base.ransack_flag(*values)
+      when true then unspent
+      when false then exhausted
+      else all
+      end
+    }
+
+    # Whether the credit came from redeeming a gift card, as opposed to a
+    # return, an exchange, a claim or an admin issuing it by hand.
+    scope :from_gift_card, ->(*values) {
+      case Spree::Base.ransack_flag(*values)
+      when true then with_gift_card
+      when false then without_gift_card
+      else all
+      end
+    }
+
     after_save :store_event
     before_destroy :validate_no_amount_used
 
@@ -58,8 +108,15 @@ module Spree
       self[:amount] = Spree::LocalizedNumber.parse(amount)
     end
 
-    self.whitelisted_ransackable_attributes = %w[user_id created_by_id amount currency type_id]
-    self.whitelisted_ransackable_associations = %w[type user created_by]
+    self.whitelisted_ransackable_attributes = %w[customer_id created_by_id amount currency memo]
+    self.whitelisted_ransackable_associations = %w[customer created_by]
+    self.whitelisted_ransackable_scopes = %w[outstanding from_gift_card]
+
+    # Two-state scopes: see Spree::Base.ransack_flag? for why the cast is
+    # opted out of here and done inside each scope instead.
+    def self.ransackable_scopes_skip_sanitize_args
+      %i[outstanding from_gift_card]
+    end
 
     def amount_remaining
       amount - amount_used - amount_authorized
@@ -85,16 +142,16 @@ module Spree
         )
         authorization_code
       else
-        errors.add(:base, Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
+        errors.add(:base, :insufficient_authorized_amount, message: Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
         false
       end
     end
 
     def validate_authorization(amount, order_currency)
       if BigDecimal(amount_remaining, 3) < BigDecimal(amount, 3)
-        errors.add(:base, Spree.t('store_credit_payment_method.insufficient_funds'))
+        errors.add(:base, :insufficient_funds, message: Spree.t('store_credit_payment_method.insufficient_funds'))
       elsif currency != order_currency
-        errors.add(:base, Spree.t('store_credit_payment_method.currency_mismatch'))
+        errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
       end
       errors.blank?
     end
@@ -104,7 +161,7 @@ module Spree
 
       if amount <= amount_authorized
         if currency != order_currency
-          errors.add(:base, Spree.t('store_credit_payment_method.currency_mismatch'))
+          errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
           false
         else
           update!(
@@ -118,7 +175,7 @@ module Spree
           authorization_code
         end
       else
-        errors.add(:base, Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
+        errors.add(:base, :insufficient_authorized_amount, message: Spree.t('store_credit_payment_method.insufficient_authorized_amount'))
         false
       end
     end
@@ -134,7 +191,8 @@ module Spree
         )
         true
       else
-        errors.add(:base, Spree.t('store_credit_payment_method.unable_to_void', auth_code: authorization_code))
+        errors.add(:base, :unable_to_void, auth_code: authorization_code,
+                   message: Spree.t('store_credit_payment_method.unable_to_void', auth_code: authorization_code))
         false
       end
     end
@@ -144,7 +202,7 @@ module Spree
       capture_event = store_credit_events.find_by(action: CAPTURE_ACTION, authorization_code: authorization_code)
 
       if currency != order_currency # sanity check to make sure the order currency hasn't changed since the auth
-        errors.add(:base, Spree.t('store_credit_payment_method.currency_mismatch'))
+        errors.add(:base, :currency_mismatch, message: Spree.t('store_credit_payment_method.currency_mismatch'))
         false
       elsif capture_event && amount <= capture_event.amount
         action_attributes = {
@@ -156,7 +214,8 @@ module Spree
         create_credit_record(amount, action_attributes)
         true
       else
-        errors.add(:base, Spree.t('store_credit_payment_method.unable_to_credit', auth_code: authorization_code))
+        errors.add(:base, :unable_to_credit, auth_code: authorization_code,
+                   message: Spree.t('store_credit_payment_method.unable_to_credit', auth_code: authorization_code))
         false
       end
     end
@@ -177,6 +236,16 @@ module Spree
       payment.completed? && payment.credit_allowed > 0
     end
 
+    # Whether the store still owes anything on this credit. The record-level
+    # twin of the `unspent` scope, and the two must agree: the list filters on
+    # the scope and the row renders this, so a client deriving one from the
+    # money columns itself would drift from the filter that hides it.
+    #
+    # @return [Boolean]
+    def outstanding?
+      amount_used + amount_authorized < amount
+    end
+
     def editable?
       amount_used.zero? && amount_authorized.zero?
     end
@@ -208,11 +277,9 @@ module Spree
     def create_credit_record_params(amount)
       {
         amount: amount,
-        user_id: user_id,
-        category_id: category_id,
+        customer_id: customer_id,
         created_by_id: created_by_id,
         currency: currency,
-        type_id: type_id,
         memo: credit_allocation_memo,
         store: store
       }
@@ -237,7 +304,7 @@ module Spree
       event.update!(
         amount: action_amount || amount,
         authorization_code: action_authorization_code || event.authorization_code || generate_authorization_code,
-        user_total_amount: user&.total_available_store_credit || 0,
+        user_total_amount: customer&.total_available_store_credit || 0,
         originator: action_originator
       )
     end

data/app/models/spree/store_credit_category.rb

@@ -1,42 +1,35 @@
 module Spree
+  # @deprecated Removed in Spree 6.1 together with its table. Store credit no
+  #   longer carries a category — the reason a credit exists lives in
+  #   {Spree::StoreCredit#originator} (the return, exchange, claim or gift
+  #   card that issued it) and in its free-text +memo+. The class stays only
+  #   so extensions referencing the constant fail loudly rather than with a
+  #   NameError; nothing in Spree reads or writes these rows any more.
   class StoreCreditCategory < Spree.base_class
     has_prefix_id :sccat
 
-    validates :name, presence: true
-
-    before_destroy :validate_not_used
-
     GIFT_CARD_CATEGORY_NAME = 'Gift Card'.freeze
     DEFAULT_NON_EXPIRING_TYPES = [GIFT_CARD_CATEGORY_NAME]
 
-    self.whitelisted_ransackable_attributes = %w[name]
-
-    def non_expiring?
-      non_expiring_category_types.include? name
-    end
-
-    def non_expiring_category_types
-      DEFAULT_NON_EXPIRING_TYPES | Spree::Config[:non_expiring_credit_types]
-    end
-
-    def store_credit_category_used?
-      Spree::StoreCredit.exists?(category_id: id)
+    after_initialize do
+      Spree::Deprecation.warn('Spree::StoreCreditCategory is deprecated and will be removed in Spree 6.1. ' \
+                              'Store credits no longer carry a category — use StoreCredit#originator and #memo instead.')
     end
 
-    def validate_not_used
-      if store_credit_category_used?
-        errors.add(:base, :cannot_destroy_if_used_in_store_credit)
-        throw(:abort)
+    class << self
+      # @deprecated Removed in Spree 6.1. Refund workflows no longer set a
+      #   category on the store credit they issue.
+      def default_refund_category(_options = {})
+        Spree::Deprecation.warn('Spree::StoreCreditCategory.default_refund_category is deprecated and will be removed in Spree 6.1. ' \
+                                'Store credits no longer carry a category.')
+        first
       end
-    end
 
-    def can_be_deleted?
-      !store_credit_category_used?
-    end
-
-    class << self
-      def default_reimbursement_category(_options = {})
-        Spree::StoreCreditCategory.first
+      # @deprecated use {.default_refund_category}
+      def default_reimbursement_category(options = {})
+        Spree::Deprecation.warn('Spree::StoreCreditCategory.default_reimbursement_category is deprecated and will be removed in Spree 6.1. ' \
+                                'Store credits no longer carry a category.')
+        default_refund_category(options)
       end
     end
   end

data/app/models/spree/store_credit_event.rb

@@ -7,7 +7,7 @@ module Spree
     #
     # Associations
     belongs_to :store_credit
-    belongs_to :originator, polymorphic: true
+    belongs_to :originator, polymorphic: true, optional: true
     has_one :payment, -> { where(source_type: Spree::StoreCredit.to_s) }, foreign_key: :response_code, primary_key: :authorization_code
     has_one :order, through: :payment
 

data/app/models/spree/store_credit_type.rb

@@ -1,10 +1,18 @@
 module Spree
+  # @deprecated Removed in Spree 6.1 together with its table. Nothing in Spree
+  #   ever created a store credit type, so the +priority+ it was meant to
+  #   provide never drove redemption order; store credits are now spent
+  #   oldest first ({Spree::StoreCredit.oldest_first}). The class stays only so
+  #   extensions referencing the constant fail loudly rather than with a
+  #   NameError.
   class StoreCreditType < Spree.base_class
     has_prefix_id :sctype
 
     DEFAULT_TYPE_NAME = 'Expiring'.freeze
-    has_many :store_credits, class_name: 'Spree::StoreCredit', foreign_key: 'type_id'
 
-    validates :name, presence: true
+    after_initialize do
+      Spree::Deprecation.warn('Spree::StoreCreditType is deprecated and will be removed in Spree 6.1. ' \
+                              'Store credits are spent oldest first — see Spree::StoreCredit.oldest_first.')
+    end
   end
 end

data/app/models/spree/store_payment_method.rb

@@ -9,7 +9,6 @@ module Spree
     belongs_to :store, class_name: 'Spree::Store', touch: true
     belongs_to :payment_method, class_name: 'Spree::PaymentMethod', touch: true
 
-    validates :store, :payment_method, presence: true
     validates :store_id, uniqueness: { scope: :payment_method_id }
   end
 end

data/app/models/spree/store_product.rb

@@ -11,7 +11,7 @@ module Spree
   class StoreProduct < Spree.base_class
     self.table_name = 'spree_products_stores'
 
-    belongs_to :product, class_name: 'Spree::Product'
-    belongs_to :store, class_name: 'Spree::Store'
+    belongs_to :product, class_name: 'Spree::Product', optional: true
+    belongs_to :store, class_name: 'Spree::Store', optional: true
   end
 end

data/app/models/spree/store_promotion.rb

@@ -9,7 +9,6 @@ module Spree
     belongs_to :store, class_name: 'Spree::Store', touch: true
     belongs_to :promotion, class_name: 'Spree::Promotion', touch: true
 
-    validates :store, :promotion, presence: true
     validates :store_id, uniqueness: { scope: :promotion_id }
   end
 end

data/app/models/spree/storefront/access_denied.rb

@@ -0,0 +1,22 @@
+module Spree
+  module Storefront
+    # Raised when a storefront access check fails. Rendered by the API's
+    # error handler as the same 403 payload CanCan::AccessDenied produces on
+    # the admin side, so the two branches stay indistinguishable to clients.
+    class AccessDenied < StandardError
+      DEFAULT_MESSAGE = 'You are not authorized to access this page.'.freeze
+
+      def initialize(message = nil)
+        super(message || default_message)
+      end
+
+      private
+
+      # CanCan's key first, so a host that translated admin denials gets the
+      # same wording here.
+      def default_message
+        I18n.t(:default, scope: :unauthorized, default: DEFAULT_MESSAGE)
+      end
+    end
+  end
+end

data/app/models/spree/storefront/access_policy.rb

@@ -0,0 +1,180 @@
+module Spree
+  module Storefront
+    # Storefront record access in one swappable object. The Store API never
+    # consults CanCanCan — customer authorization is ownership, and this
+    # policy is where ownership is decided, for any resource:
+    #
+    # - `readable?` / `writable?` answer per-record access,
+    # - `scope` narrows a relation to what the caller may list.
+    #
+    # The default answer is "the caller owns the record" (guests own
+    # nothing); carts and orders specialize it with guest-token access and a
+    # completed?-guard on writes. New resources — core or extension — get the
+    # ownership default with no wiring.
+    #
+    # This class is the storefront's extension seam: replace it via
+    # `Spree::Dependencies.storefront_access_policy_class` when access must
+    # widen or narrow beyond the owner — e.g. B2B company governance where
+    # only an approver sees the subtree's purchases
+    # (docs/plans/6.0-b2b-companies-and-catalogs.md). Override the entry
+    # points and fall through to `super`:
+    #
+    #   class Enterprise::CompanyAccessPolicy < Spree::Storefront::AccessPolicy
+    #     def scope(base, token: nil)
+    #       return base.where(company_id: standing_company_ids) if
+    #         base.klass <= Spree::Order && approver?
+    #
+    #       super
+    #     end
+    #   end
+    #
+    # Two things deliberately stay out of the policy: action vetoes (approval
+    # required, spending limits) are checkout workflow `validate` hooks, and
+    # the `/customers/me/*` endpoints stay owner-scoped by definition —
+    # company-wide surfaces are their own endpoints built on this policy.
+    class AccessPolicy
+      # @return [Object, nil] the authenticated customer, or nil for guests
+      attr_reader :user
+
+      # @return [Spree::Store]
+      attr_reader :store
+
+      def initialize(user:, store:)
+        @user = user
+        @store = store
+      end
+
+      # Whether the caller may read a record: its owner by default; for carts
+      # and orders, the owner (by JWT) or the bearer of the guest token.
+      #
+      # @param record [ActiveRecord::Base]
+      # @param token [String, nil] the X-Spree-Token header value
+      # @return [Boolean]
+      def readable?(record, token: nil)
+        return purchase_readable?(record, token: token) if purchase?(record)
+        return company_standing?(record) if company_record?(record)
+
+        owned?(record)
+      end
+
+      # Whether the caller may mutate a record. Same as +readable?+ by
+      # default; carts and orders additionally refuse once completed.
+      #
+      # @param record [ActiveRecord::Base]
+      # @param token [String, nil]
+      # @return [Boolean]
+      def writable?(record, token: nil)
+        return purchase_writable?(record, token: token) if purchase?(record)
+        return company_standing?(record) if company_record?(record)
+
+        owned?(record)
+      end
+
+      # Narrows a relation to the records the caller may list: the caller's
+      # own by default; for orders, the guest-token branch serves
+      # order-confirmation lookups.
+      #
+      # @param base [ActiveRecord::Relation] pre-scoped by the controller
+      #   (store, completeness, channel — every axis but ownership)
+      # @param token [String, nil]
+      # @return [ActiveRecord::Relation]
+      def scope(base, token: nil)
+        return purchases_scope(base, token: token) if purchase_class?(base.klass)
+        return company_scope(base) if base.klass <= Spree::Company
+
+        owned_scope(base)
+      end
+
+      protected
+
+      # --- carts and orders: token semantics ---
+
+      def purchase_readable?(purchase, token:)
+        purchase_owner?(purchase) || purchase_token_match?(purchase, token)
+      end
+
+      def purchase_writable?(purchase, token:)
+        !purchase.completed? && purchase_readable?(purchase, token: token)
+      end
+
+      def purchases_scope(base, token:)
+        if user.present?
+          base.where(customer: user)
+        elsif token.present?
+          base.where(token: token)
+        else
+          base.none
+        end
+      end
+
+      def purchase_owner?(purchase)
+        user.present? && purchase.customer == user
+      end
+
+      def purchase_token_match?(purchase, token)
+        purchase.token.present? && token == purchase.token
+      end
+
+      # An order group is a purchase for access purposes: it carries the same
+      # customer and guest token, and a guest who split their basket across
+      # sellers has to be able to see what they bought.
+      def purchase?(record)
+        record.is_a?(Spree::Cart) || record.is_a?(Spree::Order) || record.is_a?(Spree::OrderGroup)
+      end
+
+      def purchase_class?(klass)
+        klass <= Spree::Cart || klass <= Spree::Order || klass <= Spree::OrderGroup
+      end
+
+      # --- the company directory: standing ---
+
+      # OSS ships no company roles: any member with standing over the record's
+      # node — a membership on it or an ancestor — may read and write it.
+      # Enterprise narrows this by overriding these entry points
+      # (docs/plans/6.0-b2b-companies-and-catalogs.md).
+      def company_record?(record)
+        record.is_a?(Spree::Company) ||
+          record.is_a?(Spree::CompanyMembership) || record.is_a?(Spree::CompanyInvitation)
+      end
+
+      def company_standing?(record)
+        return false if user.blank?
+
+        node = record.is_a?(Spree::Company) ? record : record.company
+        user.standing_for?(node)
+      end
+
+      # The nodes the caller may list: their standing within the store.
+      def company_scope(base)
+        return base.none if user.blank?
+
+        base.merge(user.company_standing(store: store))
+      end
+
+      # --- everything else: ownership ---
+
+      # Ownership keys on `customer_id`, the canonical column since the
+      # user_id -> customer_id rename (a record with no such column is owned by
+      # no one, so the check fails closed). Deliberately not the deprecated
+      # `user_id` alias, which disappears with the shim in 6.1.
+      #
+      # A model whose owner is polymorphic (Address, whose row may belong to a
+      # customer, a company or a seller) answers `customer_id` for its own
+      # customer rows only, so a business-owned row is owned by no customer and
+      # the check fails closed there too.
+      def owned?(record)
+        user.present? && record.respond_to?(:customer_id) && record.customer_id == user.id
+      end
+
+      def owned_scope(base)
+        return base.none if user.blank?
+
+        if base.klass.column_names.include?('owner_id')
+          base.where(owner_type: Spree.customer_class.to_s, owner_id: user.id)
+        else
+          base.where(customer_id: user.id)
+        end
+      end
+    end
+  end
+end

data/app/models/spree/subscriber.rb

@@ -9,7 +9,7 @@ module Spree
   #
   # @example Basic subscriber
   #   class OrderCompletedNotifier < Spree::Subscriber
-  #     subscribes_to 'order.completed'
+  #     subscribes_to 'order.placed'
   #
   #     def call(event)
   #       order_id = event.payload['id']
@@ -19,7 +19,7 @@ module Spree
   #
   # @example Multi-event subscriber
   #   class OrderAuditLogger < Spree::Subscriber
-  #     subscribes_to 'order.completed', 'order.canceled', 'order.resumed'
+  #     subscribes_to 'order.placed', 'order.canceled'
   #
   #     def call(event)
   #       AuditLog.create!(
@@ -64,7 +64,7 @@ module Spree
   #
   # @example Synchronous subscriber (runs immediately, not via ActiveJob)
   #   class CriticalOrderHandler < Spree::Subscriber
-  #     subscribes_to 'order.completed', async: false
+  #     subscribes_to 'order.placed', async: false
   #
   #     def call(event)
   #       # This runs synchronously
@@ -81,10 +81,10 @@ module Spree
       # @return [void]
       #
       # @example
-      #   subscribes_to 'order.completed'
-      #   subscribes_to 'order.completed', 'order.canceled'
+      #   subscribes_to 'order.placed'
+      #   subscribes_to 'order.placed', 'order.canceled'
       #   subscribes_to 'order.*'
-      #   subscribes_to 'order.completed', async: false
+      #   subscribes_to 'order.placed', async: false
       #
       def subscribes_to(*patterns, **options)
         @subscription_patterns ||= []

data/app/models/spree/supplier.rb

@@ -0,0 +1,76 @@
+module Spree
+  # Somebody the merchant buys goods from. An address-book entry with a
+  # purchasing history, not a party that transacts on the store — that is
+  # {Spree::Seller}, the marketplace seller (decisions.md 2026-07-14).
+  #
+  # Suppliers belong to one store: a merchant running two storefronts keeps
+  # two lists (docs/plans/6.0-inventory-operations.md, open question 2).
+  class Supplier < Spree.base_class
+    has_prefix_id :sup
+
+    include Spree::SingleStoreResource
+    include Spree::HasCustomFields
+    include Spree::Metadata
+
+    acts_as_paranoid
+
+    publishes_lifecycle_events
+
+    has_many :purchase_orders, class_name: 'Spree::PurchaseOrder', inverse_of: :supplier,
+                               dependent: :restrict_with_error
+
+    # Deliberately not narrowed to live rows: the unique index cannot be, on
+    # every database Spree supports, so a validation that ignored soft-deleted
+    # suppliers would pass and then hit the index. A deleted supplier keeps its
+    # name; restore or rename it to use the name again.
+    validates :name, presence: true,
+                     uniqueness: { scope: [:store_id, *spree_base_uniqueness_scope],
+                                   conditions: -> { unscope(where: :deleted_at) } }
+    validates :email, email: { allow_blank: true }, length: { maximum: 254, allow_blank: true }
+
+    normalizes :email, with: ->(email) { email.strip.downcase }
+    normalizes :name, :contact_name, :phone, with: ->(value) { value.strip }
+
+    self.whitelisted_ransackable_attributes = %w[name contact_name email phone city country_code created_at]
+
+    # The postal address, built from this row's own columns the way
+    # {Spree::StockLocation#address} does. Unsaved, and blank when nothing has
+    # been filled in — check {#postable?} first.
+    #
+    # @return [Spree::Address]
+    def address
+      Spree::Address.new(
+        company: name,
+        address1: address1,
+        address2: address2,
+        city: city,
+        state_code: state_code,
+        state_name: state_name,
+        country_code: country_code,
+        postal_code: postal_code,
+        phone: phone
+      )
+    end
+
+    # Whether there is enough of an address to put on a purchase order.
+    #
+    # @return [Boolean]
+    def postable?
+      address1.present? && city.present? && country_code.present?
+    end
+
+    # Mirrors what `dependent: :restrict_with_error` enforces, so the dashboard
+    # can hide the delete control rather than offer one the model will refuse.
+    # A supplier with a purchasing history is kept, not removed — the orders
+    # naming it have to keep meaning something.
+    #
+    # @return [Boolean]
+    def can_be_deleted?
+      !purchase_orders.exists?
+    end
+
+    def event_serializer_class
+      'Spree::Api::V3::SupplierEventSerializer'.safe_constantize
+    end
+  end
+end