spree_core 5.6.1 → 6.0.0.beta1

data/app/models/spree/tax_category.rb

@@ -3,7 +3,11 @@ module Spree
     has_prefix_id :taxcat
 
     acts_as_paranoid
-    validates :name, presence: true, uniqueness: { case_sensitive: false, scope: spree_base_uniqueness_scope + [:deleted_at] }
+
+    include Spree::SingleStoreResource
+
+    validates :name, presence: true,
+                     uniqueness: { case_sensitive: false, scope: [:store_id], conditions: -> { where(deleted_at: nil) } }
 
     has_many :tax_rates, dependent: :destroy, inverse_of: :tax_category
     has_many :products, dependent: :nullify
@@ -13,14 +17,20 @@ module Spree
 
     self.whitelisted_ransackable_attributes = %w[name is_default tax_code]
 
-    def self.default
-      find_by(is_default: true)
+    # The category applied to taxable records that carry none of their own.
+    #
+    # @param store [Spree::Store, nil] store to look within, the current store by default
+    # @return [Spree::TaxCategory, nil]
+    def self.default(store = Spree::Current.store)
+      scope = store ? for_store(store) : all
+      scope.find_by(is_default: true)
     end
 
     def set_default_category
-      # set existing default tax category to false if this one has been marked as default
+      # only one category per store is the default, so marking this one demotes
+      # the store's previous holder
 
-      if is_default && tax_category = self.class.where(is_default: true).where.not(id: id).first
+      if is_default && tax_category = self.class.where(store_id: store_id, is_default: true).where.not(id: id).first
         tax_category.update_columns(is_default: false, updated_at: Time.current)
       end
     end

data/app/models/spree/tax_exemption/item_override.rb

@@ -0,0 +1,22 @@
+module Spree
+  class TaxExemption
+    # A single line's departure from its exemption entry — most often carving a
+    # line out (+exempt: false+ for the own-use item in a resale order), and
+    # optionally giving it a reason of its own.
+    class ItemOverride
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      # Prefixed id of the line item, fulfillment or fee this applies to.
+      attribute :item_id, :string
+      attribute :exempt, :boolean, default: true
+      attribute :reason_code, :string
+
+      validates :item_id, presence: true
+
+      def exempt?
+        exempt
+      end
+    end
+  end
+end

data/app/models/spree/tax_exemption.rb

@@ -0,0 +1,81 @@
+module Spree
+  # A claim that a sale, or part of one, is exempt from tax — resale,
+  # government purchase, a charity's own use. Ephemeral evidence handed to a
+  # tax provider through {Spree::TaxProvider::Base#estimate}, never persisted:
+  # the claim is the input, the zero-amount TaxLine rows are the record.
+  #
+  # Exemption is per jurisdiction (a certificate valid in one state and not the
+  # next) and per item (a resale order can hold own-use lines), which is why
+  # this is a scoped entry rather than a flag. One entry per certificate.
+  class TaxExemption
+    include ActiveModel::Model
+    include ActiveModel::Attributes
+
+    # Why the sale is exempt, in the provider's vocabulary — Avalara's
+    # entityUseCode territory.
+    attribute :reason_code, :string
+    attribute :certificate_number, :string
+
+    # Where the claim holds. Nil country = everywhere the provider taxes,
+    # nil state = the whole country.
+    attribute :country_code, :string
+    attribute :state_code, :string
+
+    # Per-line departures from the entry. Empty = the whole order is claimed.
+    attribute :item_overrides, default: -> { [] }
+
+    validates :reason_code, presence: true
+    validate :item_overrides_can_name_their_item
+
+    # Whether this entry claims exemption for the given item.
+    #
+    # @param item [Spree::LineItem, Spree::Fulfillment, Spree::Fee]
+    # @return [Boolean]
+    def covers_item?(item)
+      override = override_for(item)
+      return override.exempt? unless override.nil?
+
+      true
+    end
+
+    # Whether this entry's scope reaches the given jurisdiction. An entry with
+    # no country claims every jurisdiction; one with a country but no state
+    # claims every state within it.
+    #
+    # @param country_code [String, nil]
+    # @param state_code [String, nil]
+    # @return [Boolean]
+    def covers_jurisdiction?(country_code, state_code = nil)
+      return true if self.country_code.blank?
+      return false unless self.country_code.casecmp?(country_code.to_s)
+      return true if self.state_code.blank?
+
+      self.state_code.casecmp?(state_code.to_s)
+    end
+
+    # The reason to record for an item — the per-line override's when it names
+    # one, the entry's otherwise.
+    #
+    # @param item [Spree::LineItem, Spree::Fulfillment, Spree::Fee]
+    # @return [String, nil]
+    def reason_code_for(item)
+      override_for(item)&.reason_code.presence || reason_code
+    end
+
+    private
+
+    # An override that cannot say which line it applies to does not narrow this
+    # entry — it widens it. #override_for never matches it, so #covers_item?
+    # falls through to true for every line and a per-line carve-out becomes an
+    # order-wide exemption.
+    def item_overrides_can_name_their_item
+      return if Array(item_overrides).all? { |override| override.try(:item_id).present? }
+
+      errors.add(:item_overrides, :invalid)
+    end
+
+    def override_for(item)
+      item_overrides.to_a.find { |override| override.item_id.to_s == item.prefixed_id.to_s }
+    end
+  end
+end

data/app/models/spree/tax_exemption_certificate.rb

@@ -0,0 +1,95 @@
+module Spree
+  # A business customer's evidence that some or all of its purchases are not
+  # taxed — a resale certificate, a government exemption, a charity's own-use
+  # claim. Resolved into ephemeral {Spree::TaxExemption} entries at estimate
+  # time; the zero-amount tax rows a provider writes are the durable record of
+  # what was claimed.
+  #
+  # Scoped by jurisdiction rather than duplicated per branch: a certificate
+  # valid in one state and not the next is the ordinary case, and the country
+  # and state columns say exactly where it holds.
+  class TaxExemptionCertificate < Spree.base_class
+    has_prefix_id :cert
+
+    include Spree::HasStatus
+    include Spree::HasCustomFields
+    include Spree::Metadata
+
+    # A status column moved between values by a workflow — never a callback,
+    # and never a state machine.
+    has_status :pending, :verified, :expired, :revoked, default: :pending
+
+    belongs_to :company, class_name: 'Spree::Company', inverse_of: :tax_exemption_certificates
+    belongs_to :verified_by, class_name: Spree.admin_user_class.to_s, optional: true
+
+    # Confidential, so the private service rather than the public one that
+    # serves product images.
+    has_one_attached :document, service: Spree.private_storage_service_name
+
+    validates :certificate_number, :reason_code, presence: true
+    # Certificates exist only on legal-entity nodes — a division's purchases
+    # read exemption through its legal entity. A validation rather than a
+    # schema difference, so a per-division registration can be allowed later
+    # by relaxing this alone.
+    validate :company_is_legal_entity
+
+    # A certificate is a scanned form, not an archive. Bounded because the
+    # download action reads the whole blob into memory to serve it, so an
+    # unbounded upload would be an unbounded allocation per request.
+    MAX_DOCUMENT_SIZE = 10.megabytes
+
+    validates :document, size: { less_than_or_equal_to: MAX_DOCUMENT_SIZE }
+
+    # Where the certificate holds, as codes: a blank country_code claims every
+    # country, and a country with no state_code claims all of its states.
+    # New writes reject unknown codes; a stored one that stops resolving still
+    # narrows the certificate to nothing, never widens it to everywhere.
+    has_iso_geography
+
+    # Expiry is decided here rather than persisted: the date is the fact, and a
+    # sweeper writing 'expired' would only restate it. Matches how gift cards
+    # and stock reservations treat their own deadlines.
+    scope :active, -> { verified.where('expires_at IS NULL OR expires_at > ?', Time.current) }
+    scope :expired, -> { where(status: 'expired').or(where('expires_at <= ?', Time.current)) }
+    # No address means no jurisdiction to match, which is not the same as
+    # "matches the certificates valid everywhere" — a swapped-in resolver
+    # calling this without a destination must not be handed a claim.
+    scope :for_address, lambda { |address|
+      next none if address.nil?
+
+      where(country_code: [address.country_code.presence, nil].uniq).
+        where(state_code: [address.state_code.presence, nil].uniq)
+    }
+
+    self.whitelisted_ransackable_attributes = %w[certificate_number reason_code status expires_at]
+
+    delegate :store, :store_id, to: :company
+
+    # Accepting a certificate is a decision on record; withdrawing it is
+    # revocation, not deletion.
+    def can_be_deleted?
+      !verified?
+    end
+
+    # Whether the date has passed, regardless of what the column says.
+    def lapsed?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    # Nothing writes the 'expired' status — the date is the fact — so the
+    # predicate and scope HasStatus generated would answer false and empty
+    # forever. Both derive instead, the way Spree::GiftCard does, so a caller
+    # reaching for the obvious name gets the truth.
+    def expired?
+      status == 'expired' || lapsed?
+    end
+
+    private
+
+    def company_is_legal_entity
+      return if company.nil? || company.legal_entity?
+
+      errors.add(:company, :must_be_legal_entity)
+    end
+  end
+end

data/app/models/spree/tax_identifier.rb

@@ -0,0 +1,209 @@
+module Spree
+  # The buyer's tax registration — a VAT or business number, typed by kind.
+  # Handed to a tax provider through {Spree::TaxProvider::Base#estimate}, where
+  # it is what makes EU B2B reverse charge possible.
+  #
+  # Owners, exactly one per row: a customer (the durable profile value), a
+  # company (the business a customer buys for), a cart (an override entered
+  # during checkout) or an order (the frozen snapshot taken at completion).
+  # Orders keep a copy rather than a reference because a registration can be
+  # changed or withdrawn later, and an invoice must still show what was true
+  # when it was issued.
+  #
+  # A **seller** owns one too, and it faces the other way: the others say how
+  # the buyer is taxed, while a seller's registration is what the marketplace's
+  # own commission invoice is made out to, and what makes EU reverse charge on
+  # that fee possible (docs/plans/6.0-multi-vendor-marketplace.md Decision 12).
+  #
+  # == The +kind+ column
+  #
+  # Which registration this is — an EU VAT number, a UK one, an Australian
+  # business number. Any string is accepted, and nothing here narrows it: the
+  # kinds that exist are the ones somebody has a validator or a provider for,
+  # and core ships one, the format check for +eu_vat+.
+  #
+  # It does have to match the key that validator is registered under in
+  # {Spree.tax_identifier_validators}, because that lookup is by exact string. A kind
+  # nothing is registered for is stored and used as entered — never
+  # format-checked, never sent to a registry — and {#validatable?} reports as
+  # much. So a misspelled kind fails silently rather than loudly, and a VAT
+  # number filed under +vat+ rather than +eu_vat+ skips the check core does
+  # ship.
+  #
+  # The kinds in circulation read as a region or country prefix plus the tax's
+  # name: +eu_vat+, +gb_vat+, +ch_vat+, +au_abn+. Matching that spares a
+  # validator gem and a storefront from having to agree with each other
+  # directly. It is a habit of the gems that use it, not a rule this model
+  # applies.
+  class TaxIdentifier < Spree.base_class
+    has_prefix_id :txi
+
+    # Statuses the platform records rather than the buyer chooses: nil means
+    # validation was never attempted, which includes having no validator
+    # registered for the kind.
+    VALIDATION_STATUSES = %w[pending verified unverified unavailable unsupported].freeze
+
+    # Which link of the resolution chain produced an order's snapshot.
+    SOURCES = %w[override company customer].freeze
+
+    # Whoever holds this registration. Polymorphic rather than one nullable FK
+    # per owner: there is one relationship here with two cardinalities — a
+    # customer, company or seller holds one per kind, a cart or order holds
+    # one — and a further owner should cost no schema change.
+    belongs_to :owner, polymorphic: true
+
+    # Whitespace and case only. Punctuation is deliberately kept: for several
+    # kinds it is part of the canonical number (Switzerland's CHE-123.456.789
+    # MWST, Canada's PST-1234-5678), and the buyer's own spelling is what they
+    # will recognise on an invoice. A validator needing a different wire format
+    # produces it itself.
+    normalizes :value, with: ->(value) { value&.to_s&.gsub(/\s+/, '')&.upcase }
+
+    # A verdict belongs to the number it answered about, so changing the number
+    # ends it. Reset as part of the write, not afterwards: the response to the
+    # request that made the change has to report the new state, not a stale
+    # verdict or a blank one.
+    before_save :reset_validation_verdict, if: :number_changing?
+    after_commit :publish_number_changed, on: %i[create update]
+
+    validates :kind, :value, presence: true
+    # One per kind per owner — what the storefront upsert assumes, and what
+    # makes resolution deterministic.
+    validates :kind, uniqueness: { scope: [:owner_type, :owner_id] }
+    # Data hygiene, not a format claim — no tax regime issues numbers this long.
+    validates :value, length: { maximum: 64 }
+    validates :validation_status, inclusion: { in: VALIDATION_STATUSES }, allow_nil: true
+    validates :source, inclusion: { in: SOURCES }, allow_nil: true
+    # An order's snapshot is a copy of a number already accepted, so a rule
+    # tightened since — or a country leaving the VAT area — must not fail the
+    # order it was placed on.
+    validate :value_format, unless: :order_owned?
+    # Registrations exist only on legal-entity nodes — a division's purchases
+    # read theirs through the legal entity. A validation rather than a schema
+    # difference, so a per-division foreign registration can be allowed later
+    # by relaxing this alone.
+    validate :company_is_legal_entity
+
+    scope :for_kind, ->(kind) { where(kind: kind) }
+    scope :verified, -> { where(validation_status: 'verified') }
+
+    # An order-owned row is a completion snapshot: immutable once written, so
+    # the tax treatment of a placed order can always be explained.
+    def readonly?
+      persisted? && order_owned?
+    end
+
+    def verified?
+      validation_status == 'verified'
+    end
+
+    # Whether a registry can be asked about a number of this kind here. What
+    # tells the admin apart the two reasons a row has no verdict: not attempted
+    # yet, or nothing here knows how to ask.
+    #
+    # A format-only validator does not count. Core registers one for +eu_vat+,
+    # so a stock install rejects a mistyped VAT number on save and still leaves
+    # the verdict blank — the shape being right is not evidence that the
+    # business is registered, and only a registry can supply that.
+    #
+    # @return [Boolean]
+    def validatable?
+      return false if order_owned?
+
+      validator = validator_class
+      return false if validator.nil?
+      # A validator predating the predicate, or one not built on Base at all —
+      # the registry takes any class name. Assume it can ask, which is what
+      # every validator did before the predicate existed.
+      return true unless validator.respond_to?(:checks_registry?)
+
+      validator.checks_registry?
+    end
+
+    private
+
+    # An order-owned row is the frozen completion snapshot, which is what makes
+    # it immutable and exempt from re-validation.
+    def order_owned?
+      owner_type == 'Spree::Order'
+    end
+
+    # Format knowledge lives entirely in the registered validator, so a kind
+    # with none is accepted as entered: a single rule spanning every tax regime
+    # on earth would be a guess, and its failure mode is turning away a real
+    # business customer.
+    def value_format
+      # Blank is the presence validation's business; saying it twice for one
+      # mistake helps nobody.
+      return if value.blank?
+
+      validator = validator_class
+      return if validator.nil?
+      return if validator.valid_format?(value)
+
+      # Named after the regime the buyer picked rather than left generic: "is
+      # invalid" on a field labelled Number tells them nothing they can act on,
+      # and the same validation speaks for every kind an extension registers.
+      errors.add(:value, :invalid, kind: kind_label)
+    end
+
+    # The kind as the dashboard shows it, falling back to the raw key so an
+    # extension's kind reads as itself rather than blank.
+    def kind_label
+      Spree.t("tax_identifier_kinds.#{kind}", default: kind.to_s.humanize)
+    end
+
+    # The class registered for this kind, or nil when nothing is registered and
+    # when what is registered cannot be loaded.
+    #
+    # A registry entry naming a class that is gone — an initializer left behind
+    # after its gem was dropped, or a typo — used to be inert, since the lookup
+    # only asked whether the key existed. It is read on every save and on every
+    # admin serialization, so letting it raise would take out the whole tax
+    # identifier listing over one stale line of configuration.
+    # Deliberately not memoized: the registry is mutable configuration, and a
+    # cached class would go on answering for a validator that has since been
+    # swapped. The lookup costs microseconds against a request that also hits
+    # the database.
+    def validator_class
+      Spree.tax_identifier_validators[kind].presence&.to_s&.safe_constantize
+    end
+
+    def number_changing?
+      !order_owned? && (will_save_change_to_value? || will_save_change_to_kind?)
+    end
+
+    # `pending` when something here can answer for the new number, and nothing at
+    # all when nothing can — a kind with no validator gets no promise, and the old
+    # answer cannot stay: Purchase::Taxation#best_of prefers a verified row, so a
+    # stale `verified` would be actively chosen to decide tax.
+    #
+    # A new row has no earlier verdict to invalidate, so a number imported with one
+    # already recorded keeps it.
+    def reset_validation_verdict
+      return if new_record? && !validatable?
+
+      self.validation_status = validatable? ? 'pending' : nil
+      self.validated_at = nil
+      self.validation_evidence = nil unless validatable?
+    end
+
+    # Announces the fact; Spree::TaxIdentifierValidationSubscriber decides what
+    # to do about it. Published only when the number itself changed, so the
+    # verdict the check writes back cannot trigger another check.
+    def publish_number_changed
+      return unless saved_changes.key?('value') || saved_changes.key?('kind')
+
+      publish_event('tax_identifier.number_changed')
+    end
+
+    # Registrations exist only on legal-entity nodes — a division's purchases
+    # read theirs through the legal entity.
+    def company_is_legal_entity
+      return unless owner.is_a?(Spree::Company)
+      return if owner.legal_entity?
+
+      errors.add(:owner, :must_be_legal_entity)
+    end
+  end
+end

data/app/models/spree/tax_identifiers/validation_result.rb

@@ -0,0 +1,41 @@
+module Spree
+  module TaxIdentifiers
+    # What a validator reports back about a registration. Ephemeral: the
+    # validation service is what writes it onto the row.
+    class ValidationResult
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+
+      STATUSES = %w[verified unverified unavailable unsupported].freeze
+
+      attribute :status, :string
+      # The registry's canonical form of the number, when it reports one. Never
+      # written over the entered value — the buyer's own spelling is what they
+      # will recognise on an invoice.
+      attribute :normalized_value, :string
+      attribute :message, :string
+      attribute :checked_at, :datetime
+
+      # What was asked and what came back — the registry only ever answers
+      # "valid now", so this is the only proof a past sale will have.
+      attribute :evidence, default: -> { {} }
+
+      validates :status, inclusion: { in: STATUSES }
+
+      def verified?
+        status == 'verified'
+      end
+
+      # @return [Hash] the columns {Spree::TaxIdentifiers::Validate} persists
+      def to_columns
+        {
+          validation_status: status,
+          validated_at: checked_at || Time.current,
+          validation_evidence: evidence.to_h.merge(
+            { 'message' => message, 'normalized_value' => normalized_value }.compact
+          )
+        }
+      end
+    end
+  end
+end

data/app/models/spree/tax_identifiers/validator/base.rb

@@ -0,0 +1,53 @@
+module Spree
+  module TaxIdentifiers
+    module Validator
+      # Contract for checking a buyer's tax registration. Registered per kind in
+      # {Spree.tax_identifier_validators}, because whether a number is
+      # well-formed and whether it is really registered are questions for the
+      # jurisdiction that issued it — not for the market's tax engine.
+      #
+      # Two halves, deliberately split by cost: the format check is synchronous,
+      # offline and cheap enough to run on every save; the registry check makes
+      # a network call and runs in a job.
+      class Base
+        # Whether the value looks like a number of this kind. Called on save, so
+        # it must not touch the network.
+        #
+        # Permissive by default: a validator that only knows how to talk to a
+        # registry accepts anything core allowed through.
+        #
+        # @param value [String] already normalized (whitespace stripped, upcased)
+        # @return [Boolean]
+        def self.valid_format?(_value)
+          true
+        end
+
+        # Whether this validator can ask a registry at all. False for a
+        # format-only validator such as {EuVat}, and what stops core enqueueing
+        # a check nobody is going to answer — an unasked question is not an
+        # unavailable registry, and recording it as one would fill the admin
+        # with failures that mean nothing.
+        #
+        # @return [Boolean]
+        def self.checks_registry?
+          true
+        end
+
+        # Asks the registry whether the number is registered. Runs in
+        # {Spree::TaxIdentifiers::ValidateJob}.
+        #
+        # A registry that cannot answer must return an +unavailable+ result
+        # rather than raise: the number stays usable and the platform records
+        # that nobody could answer.
+        #
+        # @param tax_identifier [Spree::TaxIdentifier] carries the kind, the
+        #   value and its owner — reach the store through the owner when the
+        #   registry needs credentials
+        # @return [Spree::TaxIdentifiers::ValidationResult]
+        def call(tax_identifier:)
+          raise NotImplementedError, "Please implement 'call' in your tax ID validator: #{self.class.name}"
+        end
+      end
+    end
+  end
+end

data/app/models/spree/tax_identifiers/validator/eu_vat.rb

@@ -0,0 +1,76 @@
+# Loaded here rather than with core's other gems: valvat's entry point pulls in
+# its VIES lookup client, and with it REXML and net/http — around 90ms and a
+# hundred files for a SOAP service this validator never calls. Loading it with
+# the class keeps that off anything that never resolves this constant, which in
+# development and test is most rake tasks and consoles. An eager-loading
+# production boot resolves it like every other model and pays it once.
+require 'valvat'
+
+module Spree
+  module TaxIdentifiers
+    module Validator
+      # The offline half of checking an EU VAT number, and only that half.
+      #
+      # Registered for +eu_vat+ out of the box, because a number's shape is
+      # arithmetic rather than a service: the rules are published in the
+      # directive, they do not change between installations, and checking them
+      # costs nothing. This follows the same reasoning that puts postal codes on
+      # +validates_zipcode+ and phone numbers on +phonelib+ — a merchant should
+      # not have to install anything to be told that +DE123+ is not a VAT
+      # number.
+      #
+      # What it deliberately does not do is ask VIES whether the number is
+      # *registered*. That is a network call to a service which is regularly
+      # slow or down, so it stays with the extension that wants it. Declaring
+      # {checks_registry?} false is what keeps core from queueing a check
+      # nobody here can answer; an extension covering the registry re-registers
+      # +eu_vat+ and takes over both halves.
+      #
+      # A passing check is not a claim that the business exists — only that the
+      # number is not a typo. Registration is what +verified+ means, and only a
+      # registry can say it.
+      class EuVat < Base
+        # No registry client here, so core never enqueues a check for a number
+        # of this kind. Verdicts stay blank rather than reading +unavailable+,
+        # which is the honest answer: nobody was asked.
+        #
+        # @return [Boolean]
+        def self.checks_registry?
+          false
+        end
+
+        # True when the number is well-formed for the member state that issued
+        # it.
+        #
+        # Checksums are applied for the 24 member states valvat has an algorithm
+        # for and syntax alone decides Czechia, Latvia and Slovakia. That
+        # fallback is the point: refusing every number we cannot fully verify
+        # would turn away real customers in those three to catch a typo, and
+        # turning away a paying business is the more expensive mistake.
+        #
+        # valvat recognises the 27 member states and Great Britain, and nothing
+        # else — so excluding Great Britain is the whole of the area check.
+        # Northern Ireland kept EU VAT treatment for goods under the Windsor
+        # Framework and is the reason that exclusion reads on the prefix: its
+        # +XI+ numbers report +GB+ as their country.
+        #
+        # @param value [String] already normalized (whitespace stripped, upcased)
+        # @return [Boolean]
+        def self.valid_format?(value)
+          entered = value.to_s
+          # valvat strips punctuation before checking, while Spree keeps what
+          # the buyer typed — punctuation is part of the canonical number in
+          # other regimes. An EU VAT number has none, so anything valvat had to
+          # remove would be stored in a spelling no registry will match, and is
+          # a typo rather than a house style.
+          return false unless entered == Valvat::Utils.normalize(entered)
+
+          vat = Valvat.new(entered)
+          return false if vat.iso_country_code == 'GB' && vat.vat_country_code != 'XI'
+
+          Valvat::Checksum.validate(vat)
+        end
+      end
+    end
+  end
+end