Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Phase 4: settle the tax provider contract before 6.0 ships
Łukasz Adamczyk67af06054a0a
diff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rbindex 8d401bfee0..d652d48b32 100644--- a/spree/core/app/models/spree/line_item.rb+++ b/spree/core/app/models/spree/line_item.rb@@ -389,7 +389,7 @@ module Spreedef update_tax_chargereturn unless owner- Spree.tax_provider.estimate(owner, [self])+ Spree.tax_provider.estimate(owner, [self], tax_date: Time.current)enddef ensure_proper_currencydiff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rbindex 1fe3613990..91233c4ec8 100644--- a/spree/core/app/models/spree/order.rb+++ b/spree/core/app/models/spree/order.rb@@ -518,11 +518,11 @@ module Spree# Re-estimates tax through the configured provider (writes TaxLine rows# with replace-all semantics).def create_tax_charge!- Spree.tax_provider.estimate(self)+ Spree.tax_provider.estimate(self, tax_date: Time.current)enddef create_shipment_tax_charge!- Spree.tax_provider.estimate(self, fulfillments.to_a) if fulfillments.any?+ Spree.tax_provider.estimate(self, fulfillments.to_a, tax_date: Time.current) if fulfillments.any?enddef update_line_item_prices!diff --git a/spree/core/app/models/spree/tax_provider/base.rb b/spree/core/app/models/spree/tax_provider/base.rbindex c38e4a0dce..22328e5a24 100644--- a/spree/core/app/models/spree/tax_provider/base.rb+++ b/spree/core/app/models/spree/tax_provider/base.rb@@ -5,29 +5,69 @@ module Spree# target item (delete the item's stale lines, insert fresh ones); that is# what keeps tax correct after address or item changes. Commit/void/refund# are lifecycle no-ops for providers without a remote ledger.+ #+ # Providers are stateless and constructed without arguments, so anything+ # request-specific arrives as an argument rather than through the instance.class Base- # Recomputes tax for the given items (defaults to all taxable items of- # the owner: line items, fulfillments and fees).+ # Domains this provider cannot handle, so a merchant is warned when+ # pairing it with a market instead of silently under-collecting. Declared+ # on the class because core reads it while presenting the choice, before+ # any provider is instantiated.#- # @param owner [Spree::Order, Spree::Cart]+ # @return [Array<Symbol>]+ def self.unsupported_capabilities+ []+ end++ # Whether this provider can be selected for a store. External providers+ # override it to require a connected integration or credentials.+ #+ # @param store [Spree::Store]+ # @return [Boolean]+ def self.available_for_store?(_store)+ true+ end++ # Recomputes tax for the given items and writes the TaxLine rows.+ # Replace-all set semantics per target item, and one row for every item+ # the provider formed a treatment for — zero-amount treatments included.+ # Never called on a completed order; the order-level money freeze gates it.+ #+ # @param owner [Spree::Cart, Spree::Order]# @param items [Array<Spree::LineItem, Spree::Fulfillment, Spree::Fee>, nil]- def estimate(owner, items = nil)+ # nil = every taxable item on the owner+ # @param tax_date [Time, nil] date whose rates apply; nil = now+ # @param tax_identifier [Spree::TaxIdentifier, nil] resolved buyer+ # registration, nil for a consumer sale+ # @param exemptions [Array] exemption evidence to apply+ # @param context [Hash] untyped provider extras from set_tax_line_context+ # @return [void] the written rows are the output; raise when the+ # calculation cannot be completed+ def estimate(owner, items = nil, tax_date: nil, tax_identifier: nil, exemptions: [], context: {})raise NotImplementedError, "Please implement 'estimate' in your tax provider: #{self.class.name}"end- # Finalizes tax with the provider at completion (no-op by default).- def commit(owner); end-- # Cancels a previously committed tax document (no-op by default).- def void(owner); end+ # Finalizes tax with the provider when the order is placed. No-op for a+ # provider without a remote ledger — the rows are already the record.+ #+ # @param order [Spree::Order]+ # @return [void]+ def commit(order); end- # Reports a refund against committed tax (no-op by default).- def refund(owner, amount); end+ # Reverses a committed tax document on cancellation.+ #+ # @param order [Spree::Order]+ # @return [void]+ def void(order); end- # @return [Boolean] whether the owner is tax-exempt- def exempt?(_owner)- false- end+ # Reports a partial credit against the committed document, keyed to the+ # original transaction rather than voiding and re-committing it.+ #+ # @param order [Spree::Order]+ # @param return_items [Array<Spree::ReturnItem>]+ # @param tax_date [Time, nil] the original supply date; nil = order.completed_at+ # @return [void]+ def refund(order, return_items, tax_date: nil); endendendenddiff --git a/spree/core/app/models/spree/tax_provider/internal.rb b/spree/core/app/models/spree/tax_provider/internal.rbindex 827c0c1c2f..c6d0e08199 100644--- a/spree/core/app/models/spree/tax_provider/internal.rb+++ b/spree/core/app/models/spree/tax_provider/internal.rb@@ -6,7 +6,19 @@ module Spree# zone). Fees without a tax category are taxed with the default tax# category's rates.class Internal < Base- def estimate(owner, items = nil)+ # Rates are configured per zone with no local-tax breakdown, no buyer+ # registration handling and no distance-selling thresholds. Declared so a+ # merchant pairing this with a market is told, rather than discovering it+ # in a return.+ def self.unsupported_capabilities+ %i[us_local_tax reverse_charge oss_thresholds]+ end++ # +tax_date+ is accepted and ignored: TaxRate rows carry no validity+ # period, so there is only ever one version of the configuration to read.+ # +tax_identifier+ likewise — reverse charge is on the unsupported list,+ # so a buyer registration changes nothing here.+ def estimate(owner, items = nil, tax_date: nil, tax_identifier: nil, exemptions: [], context: {})items ||= owner.line_items.to_a + owner.fulfillments.to_a + owner.fees.to_areturn if items.empty?diff --git a/spree/core/app/workflows/spree/carts/add_item.rb b/spree/core/app/workflows/spree/carts/add_item.rbindex 0bedfc3678..9185354e76 100644--- a/spree/core/app/workflows/spree/carts/add_item.rb+++ b/spree/core/app/workflows/spree/carts/add_item.rb@@ -72,7 +72,7 @@ module Spree@line_item.reload.recalculate_price- ::Spree.tax_provider.estimate(@line_item.owner, [@line_item]) if @line_item_created+ ::Spree.tax_provider.estimate(@line_item.owner, [@line_item], tax_date: Time.current) if @line_item_createdenddef handle_stock_reservationsdiff --git a/spree/core/app/workflows/spree/carts/recalculate_totals.rb b/spree/core/app/workflows/spree/carts/recalculate_totals.rbindex 95bfab8b2b..e19c0f46e3 100644--- a/spree/core/app/workflows/spree/carts/recalculate_totals.rb+++ b/spree/core/app/workflows/spree/carts/recalculate_totals.rb@@ -16,9 +16,10 @@ module Spreeclass RecalculateTotals < Spree::Workflowhooks :set_tax_line_context- # Tax context contributed by set_tax_line_context handlers (exemption- # certificates, customer tax IDs) — read by tax providers that support- # it. Nil until the typed rows are regenerated.+ # Untyped provider extras contributed by set_tax_line_context handlers —+ # anything a specific provider needs that the typed estimate arguments+ # don't carry. Exemptions and the buyer's tax identity are NOT this: they+ # are typed inputs of their own. Nil until the typed rows are regenerated.attr_reader :tax_line_context# @param cart [Spree::Cart, Spree::Order]@@ -57,7 +58,7 @@ module SpreeSpree.adjusters.each { |adjuster| adjuster.adjust(cart) }refresh_discount_and_fee_columns@tax_line_context = run_hooks :set_tax_line_context- Spree.tax_provider.estimate(cart)+ Spree.tax_provider.estimate(cart, tax_date: Time.current, context: tax_line_context)end# Re-derives the denormalized per-adjustable columns and the record'sdiff --git a/spree/core/lib/spree/core/controller_helpers/store.rb b/spree/core/lib/spree/core/controller_helpers/store.rbindex f14600a4d8..fff6881aad 100644--- a/spree/core/lib/spree/core/controller_helpers/store.rb+++ b/spree/core/lib/spree/core/controller_helpers/store.rb@@ -49,7 +49,6 @@ module Spree# * `Spree::VatPriceCalculation#gross_amount`# * `Spree::LineItem#update_price`# * `Spree::Stock::Estimator#taxation_options_for`- # * Subclass the `DefaultTax` calculator#def current_price_options{diff --git a/spree/core/spec/models/spree/order_spec.rb b/spree/core/spec/models/spree/order_spec.rbindex 42c291a7ac..89da96ecc0 100644--- a/spree/core/spec/models/spree/order_spec.rb+++ b/spree/core/spec/models/spree/order_spec.rb@@ -1357,7 +1357,7 @@ describe Spree::Order, type: :model dolet!(:shipment) { create(:shipment, order: order) }it 'estimates tax over the fulfillments' do- expect(provider).to receive(:estimate).with(order, [shipment])+ expect(provider).to receive(:estimate).with(order, [shipment], hash_including(:tax_date))order.create_shipment_tax_charge!endenddiff --git a/spree/core/spec/models/spree/tax_provider/base_spec.rb b/spree/core/spec/models/spree/tax_provider/base_spec.rbnew file mode 100644index 0000000000..481e1611a3--- /dev/null+++ b/spree/core/spec/models/spree/tax_provider/base_spec.rb@@ -0,0 +1,60 @@+require 'spec_helper'++describe Spree::TaxProvider::Base, type: :model do+ subject(:provider) { described_class.new }++ let(:order) { create(:order_with_line_items, line_items_count: 1) }++ describe '#estimate' do+ it 'is the one method a provider must implement' do+ expect { provider.estimate(order) }.to raise_error(NotImplementedError, /estimate/)+ end++ it 'accepts the full typed input set' do+ expect do+ provider.estimate(order, order.line_items.to_a, tax_date: Time.current,+ tax_identifier: nil, exemptions: [], context: { 'key' => 'value' })+ end.to raise_error(NotImplementedError)+ end+ end++ describe 'lifecycle methods' do+ it 'no-ops for a provider without a remote ledger' do+ expect(provider.commit(order)).to be_nil+ expect(provider.void(order)).to be_nil+ expect(provider.refund(order, [], tax_date: order.completed_at)).to be_nil+ end++ it 'takes the refunded items rather than an amount' do+ expect(provider.method(:refund).parameters).to eq([[:req, :order], [:req, :return_items], [:key, :tax_date]])+ end+ end++ describe 'capability declarations' do+ it 'claims everything is supported until a provider says otherwise' do+ expect(described_class.unsupported_capabilities).to eq([])+ expect(described_class.available_for_store?(order.store)).to be(true)+ end++ it 'is answerable without instantiating the provider' do+ expect(described_class).to respond_to(:unsupported_capabilities)+ expect(described_class).to respond_to(:available_for_store?)+ end+ end++ describe 'the internal provider' do+ it 'declares the domains rate configuration cannot express' do+ expect(Spree::TaxProvider::Internal.unsupported_capabilities).to(+ contain_exactly(:us_local_tax, :reverse_charge, :oss_thresholds)+ )+ end++ it 'is available for any store, needing no credentials' do+ expect(Spree::TaxProvider::Internal.available_for_store?(order.store)).to be(true)+ end+ end++ it 'no longer answers a standalone exemption question' do+ expect(provider).not_to respond_to(:exempt?)+ end+end