spree_core 5.6.1 → 6.0.0.beta2

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

@@ -0,0 +1,120 @@
+module Spree
+  module DeliveryRateProvider
+    # Strategy that answers "what does this delivery method cost for this
+    # package, and what metadata comes with the quote?".
+    #
+    # Stored as a string class name on DeliveryMethod and constantized at call
+    # time; registered via Spree.delivery_rate_providers. The Estimator
+    # dispatches here in place of calling the calculator directly, so
+    # filtering, VAT gross-up, tax resolution and sorting stay in one place
+    # for every provider.
+    #
+    # External providers resolve credentials through the delivery method's
+    # store integration — they never store credentials themselves.
+    class Base
+      include Spree::IntegrationBackedProvider
+
+      attr_reader :delivery_method
+
+      class << self
+        # Whether this provider quotes real shipments to an address — true
+        # for carriers, which therefore can only price methods whose
+        # fulfillment provider ships. The Internal (calculator) provider
+        # prices anything.
+        #
+        # @return [Boolean]
+        def requires_address?
+          false
+        end
+
+        # Whether the method's calculator decides the price. False for
+        # carrier providers, which quote live rates — their methods still
+        # carry a calculator (the Estimator consults `available?`) but its
+        # amount is never used, so admin UIs hide the pricing form.
+        #
+        # @return [Boolean]
+        def uses_calculator?
+          false
+        end
+
+        # The carrier services this store can offer, for the admin service
+        # picker. Fetch them live from the carrier wherever the API allows —
+        # a hardcoded list shows services the merchant has not enabled and
+        # hides the ones they have.
+        #
+        # Return {ServiceCatalog.listing} with `[{ carrier:, service:,
+        # label: }]`, {ServiceCatalog.unavailable} with the seller's message
+        # when the listing cannot be fetched (unconnected integration,
+        # credential tier without access, carrier outage), or
+        # {ServiceCatalog.none} — the default — when the provider lists no
+        # services and the merchant types identifiers free-form.
+        #
+        # Never raise: the picker degrades to free-form entry, and a failed
+        # listing must not block configuring a delivery method.
+        #
+        # @param _integration [Spree::Integration, nil]
+        # @return [Spree::DeliveryRateProvider::ServiceCatalog]
+        def service_catalog(_integration)
+          ServiceCatalog.none
+        end
+      end
+
+      # @param delivery_method [Spree::DeliveryMethod]
+      def initialize(delivery_method)
+        @delivery_method = delivery_method
+      end
+
+      # Every quote this delivery method yields for a package — the entry
+      # point the Estimator calls. Carrier providers override this to return
+      # one Estimate per service ("UPS Ground", "UPS Express", …) from a
+      # single API call; single-quote providers implement {#estimate} and get
+      # wrapped automatically. An empty array offers nothing.
+      #
+      # @param package [Spree::Stock::Package]
+      # @return [Array<Spree::DeliveryRateProvider::Estimate>]
+      def estimates(package)
+        Array(estimate(package)).compact
+      end
+
+      # Quotes this delivery method for a package, for providers that yield a
+      # single rate.
+      #
+      # Returning nil suppresses the method, matching the calculator contract
+      # where a nil cost hides it — that equivalence is what lets FlatRate's
+      # thresholds keep working through the Internal provider.
+      #
+      # @param _package [Spree::Stock::Package]
+      # @return [Spree::DeliveryRateProvider::Estimate, nil]
+      def estimate(_package)
+        raise NotImplementedError, "Please implement 'estimate' or 'estimates' in your delivery rate provider: #{self.class.name}"
+      end
+
+      # Reserves the quote with the carrier once a customer selects it.
+      # Spree does not invoke this yet — it is reserved for the rate booking
+      # flow; until then a provider gem calls it from its own fulfillment
+      # provider.
+      def book(_delivery_rate); end
+
+      # Releases a previously booked quote. Same status as {#book}.
+      def release(_delivery_rate); end
+
+      private
+
+      def store
+        delivery_method.store
+      end
+
+      # The connected, active integration carrying this provider's credentials.
+      # Memoizes the missing case too — an unconnected integration must not
+      # cost a query per estimate.
+      #
+      # @return [Spree::Integration, nil]
+      def integration
+        return if self.class.integration_class.blank?
+        return @integration if defined?(@integration)
+
+        @integration = store&.integrations&.active&.find_by(type: self.class.integration_class)
+      end
+    end
+  end
+end

data/app/models/spree/delivery_rate_provider/estimate.rb

@@ -0,0 +1,44 @@
+module Spree
+  module DeliveryRateProvider
+    # A single quote returned by a delivery rate provider.
+    #
+    # +cost+ is pre-tax and pre-VAT-gross-up: the Estimator applies
+    # +gross_amount+ and resolves the tax rate afterwards, exactly as it does
+    # for calculator output. Everything else is carrier metadata that flows
+    # onto the persisted DeliveryRate.
+    class Estimate
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      attribute :cost, :decimal
+      # True when the price is not known yet and will be quoted separately —
+      # freight a forwarder rates after the merchant reviews the order. The
+      # estimator skips markup and tax for these, and display surfaces say so
+      # rather than showing the zero cost as free shipping.
+      attribute :unpriced, :boolean, default: false
+      # ISO code of the currency the provider quoted in. Nil means the
+      # store's own currency (Internal); carrier quotes come back in the
+      # carrier account's currency and are dropped when it differs from the
+      # cart's — a number in the wrong currency must never reach checkout.
+      attribute :currency, :string
+      attribute :carrier, :string
+      attribute :service_level, :string
+      # Optional display name; when blank the Estimator derives one from
+      # carrier + service_level (or falls back to the method name).
+      attribute :name, :string
+      attribute :estimated_delivery_date, :date
+      attribute :metadata, default: -> { {} }
+
+      # Stable identity of the carrier service within a method — what
+      # DeliveryMethodService rows match against for selection filtering and
+      # label/markup overrides.
+      #
+      # @return [String, nil]
+      def service_key
+        return if carrier.blank? && service_level.blank?
+
+        [carrier, service_level].compact.join('/')
+      end
+    end
+  end
+end

data/app/models/spree/delivery_rate_provider/freight.rb

@@ -0,0 +1,41 @@
+module Spree
+  module DeliveryRateProvider
+    # Quotes nothing, and says so.
+    #
+    # International freight is priced by a forwarder after someone looks at
+    # the order — the carton count, the cubic meters, the destination port —
+    # not by an API at checkout. So this provider returns a rate with no
+    # price, carrying the logistics summary the merchant will send to the
+    # forwarder in place of an amount.
+    #
+    # Which freight method a shipment is offered is
+    # {Spree::DeliveryMethodRules::VolumeRule}'s job: a merchant configures
+    # "Pallet" and "40ft container" as ordinary delivery methods on this
+    # provider, each bounded by the cubic meters it covers.
+    #
+    # See docs/plans/6.0-b2b-wholesale-shipping.md.
+    class Freight < Base
+      # There is no price to calculate, so the method's calculator is never
+      # consulted and admin UIs hide its pricing form.
+      def self.uses_calculator?
+        false
+      end
+
+      # Freight ships to an address like any carrier does.
+      def self.requires_address?
+        true
+      end
+
+      # @param package [Spree::Stock::Package]
+      # @return [Spree::DeliveryRateProvider::Estimate]
+      def estimate(package)
+        Estimate.new(
+          cost: 0,
+          unpriced: true,
+          name: delivery_method.name,
+          metadata: { 'freight_summary' => package.freight_summary.as_json }
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+module Spree
+  module DeliveryRateProvider
+    # Default provider: prices through the delivery method's calculator, so
+    # every store that doesn't opt into an external provider behaves exactly
+    # as before. Custom merchant calculators keep working unchanged, including
+    # the ones that suppress a method by returning nil.
+    #
+    # Carries no carrier metadata and no delivery date: turning the method's
+    # configured business days into a date needs a per-market holiday calendar
+    # core doesn't have, and guessing one would put a wrong date in front of
+    # customers. Carrier-backed providers return the real date.
+    class Internal < Base
+      # The calculator is the whole point of this provider.
+      def self.uses_calculator?
+        true
+      end
+
+      # @param package [Spree::Stock::Package]
+      # @return [Spree::DeliveryRateProvider::Estimate, nil]
+      def estimate(package)
+        cost = delivery_method.calculator.compute(package)
+        return if cost.nil?
+
+        Estimate.new(cost: cost)
+      end
+    end
+  end
+end

data/app/models/spree/delivery_rate_provider/service_catalog.rb

@@ -0,0 +1,48 @@
+module Spree
+  module DeliveryRateProvider
+    # The answer to "which carrier services can this store offer?", as the
+    # admin service picker needs it: either the services themselves, or the
+    # reason the provider could not list them.
+    #
+    # Providers fetch live where their API allows it. When it does not — an
+    # unconnected integration, a credential tier that forbids the listing
+    # endpoint, a carrier outage — they return {.unavailable} with the
+    # seller's own message, and the picker explains the situation instead of
+    # showing a silently empty or invented list.
+    class ServiceCatalog
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      # @return [Array<Hash>] `[{ carrier:, service:, label: }]`
+      attribute :services, default: -> { [] }
+      # @return [String, nil] why the services could not be listed
+      attribute :error_message, :string
+
+      # A provider that lists no services at all — the merchant enters
+      # carrier/service identifiers free-form and every quoted rate is
+      # offered. Not an error state.
+      #
+      # @return [ServiceCatalog]
+      def self.none
+        new
+      end
+
+      # @param services [Array<Hash>] each `{ carrier:, service:, label: }`
+      # @return [ServiceCatalog]
+      def self.listing(services)
+        new(services: Array(services))
+      end
+
+      # @param message [String] the seller's message, shown to the merchant
+      # @return [ServiceCatalog]
+      def self.unavailable(message)
+        new(error_message: message)
+      end
+
+      # @return [Boolean]
+      def available?
+        error_message.blank?
+      end
+    end
+  end
+end

data/app/models/spree/delivery_zone.rb

@@ -0,0 +1,64 @@
+module Spree
+  class DeliveryZone < Spree.base_class
+    include Spree::SingleStoreResource
+
+    has_prefix_id :dz
+
+    # Single consolidated metadata JSON column (docs/plans/decisions.md
+    # 2026-03-16 "Consolidate metadata") — write-only developer escape hatch.
+    attribute :metadata, default: -> { {} }
+
+    belongs_to :store, class_name: 'Spree::Store'
+    # Zones are destination sets owned by a delivery profile; within it they
+    # hang off an origin group, so the same profile can quote different
+    # tables per warehouse. The profile's methods bind to at most one zone.
+    belongs_to :delivery_profile, class_name: 'Spree::DeliveryProfile', inverse_of: :delivery_zones
+    belongs_to :delivery_origin_group, class_name: 'Spree::DeliveryOriginGroup', inverse_of: :delivery_zones
+
+    has_many :members, class_name: 'Spree::DeliveryZoneMember', dependent: :destroy, inverse_of: :delivery_zone
+    # Destroy, not nullify: a nil zone means "no destination restriction", so
+    # orphaning a zone's methods would silently promote them from serving one
+    # region to quoting worldwide. The method belongs to the zone structurally
+    # anyway — its zone must sit in its own origin group — so deleting the zone
+    # deletes what it carried.
+    has_many :delivery_methods, class_name: 'Spree::DeliveryMethod', dependent: :destroy, inverse_of: :delivery_zone
+
+    validates :name, presence: true, uniqueness: { scope: [:store_id, *spree_base_uniqueness_scope] }
+    validates :store, presence: true
+
+    # Mirrors DeliveryMethod: a zone created without an explicit profile
+    # joins the store's default one, landing in its default origin group
+    # unless one is named.
+    before_validation :assign_default_delivery_profile, on: :create
+    before_validation :assign_default_origin_group, on: :create
+    validate :origin_group_must_belong_to_profile,
+             if: -> { delivery_origin_group_id_changed? || delivery_profile_id_changed? }
+
+    self.whitelisted_ransackable_attributes = %w[name]
+
+    # @param address [Spree::Address, nil]
+    # @return [Boolean] whether any member of this zone matches the address
+    def include?(address)
+      return false if address.nil?
+
+      members.any? { |member| member.match?(address) }
+    end
+
+    private
+
+    def assign_default_delivery_profile
+      self.delivery_profile ||= store&.default_delivery_profile
+    end
+
+    def assign_default_origin_group
+      self.delivery_origin_group ||= delivery_profile&.default_origin_group
+    end
+
+    def origin_group_must_belong_to_profile
+      return if delivery_origin_group.nil? || delivery_profile.nil?
+      return if delivery_origin_group.delivery_profile_id == delivery_profile_id
+
+      errors.add(:delivery_origin_group, :invalid)
+    end
+  end
+end

data/app/models/spree/delivery_zone_member.rb

@@ -0,0 +1,98 @@
+module Spree
+  class DeliveryZoneMember < Spree.base_class
+    has_prefix_id :dzm
+
+    MEMBER_TYPES = %w[country state postal_code].freeze
+
+    # ISO codes of countries with numeric postal formats, where lexicographic
+    # ranges over normalized codes are meaningful. Prefix members are allowed
+    # for every country; range members only for these. Extend via
+    # `Spree::DeliveryZoneMember.range_capable_country_codes += %w[XY]`.
+    class_attribute :range_capable_country_codes, default: %w[
+      AR AT AU BD BE BG BR CH CN CZ DE DK DZ EE EG ES FI FR GR HR HU ID IL IN
+      IS IT JP KR LK LT LU MA MX MY NO NZ PH PK PL PT RO RS RU SA SE SG SI SK
+      TH TN TR TW UA US UY VN ZA
+    ].freeze
+
+    belongs_to :delivery_zone, class_name: 'Spree::DeliveryZone', inverse_of: :members
+
+    has_iso_geography
+
+    normalizes :postal_code_prefix, :postal_code_from, :postal_code_to,
+               with: ->(value) { Spree::Address.normalize_postal_code(value).presence }
+
+    # Mapping a retired subdivision code to its successor needs both halves,
+    # which normalizes can't see — it runs per attribute — so it stays a
+    # callback.
+    before_validation :resolve_geography
+
+    validates :member_type, presence: true, inclusion: { in: MEMBER_TYPES }
+    validates :country_code, presence: true, if: -> { member_type.in?(MEMBER_TYPES) }
+    validates :state_code, presence: true, if: -> { member_type == 'state' }
+    validate :postal_definition, if: -> { member_type == 'postal_code' }
+
+    # @param address [Spree::Address]
+    # @return [Boolean] whether the address falls inside this member
+    #
+    # A state member compares the country too: a subdivision code is only
+    # unique within its country, so "CA" alone would match California and
+    # several other places.
+    def match?(address)
+      case member_type
+      when 'country' then same_country?(address)
+      when 'state' then same_country?(address) && address.state_code.present? && address.state_code == state_code
+      when 'postal_code' then same_country?(address) && postal_match?(address.normalized_postal_code)
+      else false
+      end
+    end
+
+    # @return [Boolean] whether this member defines a from/to range (vs a prefix)
+    def postal_range?
+      postal_code_from.present? || postal_code_to.present?
+    end
+
+    private
+
+    def same_country?(address)
+      country_code.present? && address.country_code == country_code
+    end
+
+    # An unresolvable code is left in place for the geography validation to
+    # report, rather than nilled into a less telling presence error.
+    def resolve_geography
+      return if state_code.blank? || country_code.blank?
+
+      resolved = Spree::IsoData.subdivision_code(country_code, state_code)
+      self.state_code = resolved if resolved
+    end
+
+    def postal_match?(zipcode)
+      return false if zipcode.blank?
+
+      if postal_code_prefix.present?
+        zipcode.start_with?(postal_code_prefix)
+      else
+        zipcode >= postal_code_from && zipcode <= postal_code_to
+      end
+    end
+
+    def postal_definition
+      if postal_code_prefix.present?
+        errors.add(:postal_code_prefix, :delivery_zone_prefix_and_range_exclusive, message: Spree.t('errors.messages.delivery_zone_prefix_and_range_exclusive')) if postal_range?
+        return
+      end
+
+      if postal_code_from.blank? || postal_code_to.blank?
+        errors.add(:base, :delivery_zone_postal_definition_required, message: Spree.t('errors.messages.delivery_zone_postal_definition_required'))
+        return
+      end
+
+      unless country_code.present? && range_capable_country_codes.include?(country_code)
+        errors.add(:base, :delivery_zone_range_not_supported, message: Spree.t('errors.messages.delivery_zone_range_not_supported'))
+        return
+      end
+
+      errors.add(:postal_code_to, :delivery_zone_range_inverted, message: Spree.t('errors.messages.delivery_zone_range_inverted')) if postal_code_to < postal_code_from
+    end
+  end
+end

data/app/models/spree/digital.rb

@@ -1,18 +1,14 @@
-module Spree
-  class Digital < Spree.base_class
-    has_prefix_id :dig
-
-    publishes_lifecycle_events
-
-    belongs_to :variant
-    has_many :digital_links, dependent: :destroy
+# frozen_string_literal: true
 
-    has_one_attached :attachment, service: Spree.private_storage_service_name
-
-    validates :attachment, attached: true
-    validates :variant, presence: true
-
-    delegate :product, to: :variant
-    delegate :filename, :content_type, to: :attachment
-  end
+module Spree
+  # Deprecation alias for Spree::DigitalAsset, renamed from Spree::Digital in
+  # 6.0. Retained for one release; removed in 6.1.
+  #
+  # A plain constant alias rather than a DeprecatedConstantProxy: the proxy
+  # would name the calling site, but it fails `is_a?`/`===` checks, so legacy
+  # code branching on the old constant would silently take the wrong path.
+  #
+  # The underlying class, table (spree_digital_assets), prefix (dig) and
+  # model_name are all Spree::DigitalAsset; only the constant differs.
+  Digital = DigitalAsset
 end

data/app/models/spree/digital_asset.rb

@@ -0,0 +1,144 @@
+module Spree
+  class DigitalAsset < Spree.base_class
+    include Spree::Metadata
+
+    has_prefix_id :dig
+
+    publishes_lifecycle_events
+
+    # Provider config lives under one key in `metadata` so a provider owns its
+    # own namespace without colliding with other developer metadata. The values
+    # match the provider's `settings_schema`; the provider reads them in
+    # `deliver`.
+    PROVIDER_SETTINGS_KEY = 'provider'.freeze
+
+    belongs_to :variant, class_name: 'Spree::Variant'
+    has_many :digital_links, class_name: 'Spree::DigitalLink', dependent: :destroy
+
+    has_one_attached :attachment, service: Spree.private_storage_service_name
+
+    # A blank provider_type is the uploaded-file default; the provider class
+    # says whether an attachment is required, so file assets keep today's rule
+    # and provider-backed assets (which carry no file) are exempt.
+    DEFAULT_PROVIDER = 'Spree::DigitalAssetProvider::File'.freeze
+
+    validate :provider_type_is_registered, if: -> { provider_type.present? }
+    # Only ask a valid provider whether it needs a file — an unregistered
+    # provider_type is already rejected above, and calling requires_attachment?
+    # on a class that is not a provider would 500 instead.
+    validates :attachment, attached: true, if: -> { provider_registered? && provider_class.requires_attachment? }
+    validates :authorized_clicks, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
+    validates :authorized_days, numericality: { only_integer: true, greater_than: 0 }, allow_nil: true
+
+    delegate :product, to: :variant
+    delegate :filename, :content_type, :byte_size, to: :attachment
+
+    # Download allowances fall back to the owning store's settings when the
+    # asset leaves them blank, so a catalog can mix evergreen files with
+    # time-limited ones without changing the store default.
+    #
+    # The store is passed in by the caller, which already holds it — resolving
+    # it here would walk variant → product → store for every link checked.
+    #
+    # @param store [Spree::Store]
+    # @return [Integer]
+    def effective_authorized_clicks(store = self.store)
+      authorized_clicks || store.preferred_digital_asset_authorized_clicks
+    end
+
+    # @param store [Spree::Store]
+    # @return [Integer]
+    def effective_authorized_days(store = self.store)
+      authorized_days || store.preferred_digital_asset_authorized_days
+    end
+
+    # @return [Spree::Store] the store this asset's product belongs to
+    def store
+      product.store
+    end
+
+    # The strategy that produces this asset's deliverable. A blank provider_type
+    # resolves to the uploaded-file default, exactly as DeliveryMethod resolves
+    # its provider — so an unset column is a File asset, not an error.
+    #
+    # @return [Class]
+    def provider_class
+      (provider_type.presence || DEFAULT_PROVIDER).safe_constantize || DEFAULT_PROVIDER.constantize
+    end
+
+    # The provider's per-asset configuration, as declared by its
+    # `settings_schema`. Stored under one key in `metadata`.
+    #
+    # @return [Hash]
+    def provider_settings
+      metadata.fetch(PROVIDER_SETTINGS_KEY, {}) || {}
+    end
+
+    # @param values [Hash]
+    def provider_settings=(values)
+      self.metadata = metadata.merge(PROVIDER_SETTINGS_KEY => (values || {}))
+    end
+
+    # Produces the deliverable for one authorized download — a redirect URL or
+    # an inline value — via the provider. Callers stay out of the storage layer
+    # so a provider-backed asset can answer without an attachment.
+    #
+    # @param digital_link [Spree::DigitalLink]
+    # @param expires_in [ActiveSupport::Duration]
+    # @return [Spree::DigitalDelivery, nil]
+    def deliver(digital_link, expires_in:)
+      provider_class.new(self).deliver(digital_link, expires_in: expires_in)
+    end
+
+    # @return [Boolean] whether there is anything to hand to a customer
+    def downloadable?
+      attachment.attached?
+    end
+
+    # @param expires_in [ActiveSupport::Duration] lifetime of the signed URL
+    # @return [String, nil] nil when there is nothing to download
+    def download_url(expires_in:)
+      return unless downloadable?
+
+      attachment.url(expires_in: expires_in, disposition: :attachment)
+    end
+
+    private
+
+    # A provider_type must name a registered provider — a stale class name from
+    # a removed gem, or a typo, is rejected rather than blowing up at download.
+    def provider_type_is_registered
+      return if provider_registered?
+
+      errors.add(:provider_type, :not_registered)
+    end
+
+    # A blank provider_type is the File default (always registered); otherwise
+    # it must name a registered provider. Guards the attachment validation so it
+    # never calls requires_attachment? on a class that is not a provider.
+    def provider_registered?
+      provider_type.blank? || Spree.digital_asset_providers.map(&:to_s).include?(provider_type)
+    end
+
+    # The legacy digital.* events are dual-emitted for one release
+    # (webhook contract bridge — removed in 6.1).
+    def publish_create_event
+      publish_event('digital.created')
+      super
+    end
+
+    # Cannot call super like its siblings: touch_only_update? clears its flags
+    # when read, so the guard must run exactly once for both event names.
+    def publish_update_event
+      return if touch_only_update?
+
+      publish_event('digital.updated')
+      publish_event("#{event_prefix}.updated")
+    end
+
+    def publish_delete_event
+      publish_event('digital.deleted', @_pre_destroy_payload || event_payload)
+      super
+    end
+  end
+end