Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.rb
index 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 Spree
def update_tax_charge
return unless owner
- Spree.tax_provider.estimate(owner, [self])
+ Spree.tax_provider.estimate(owner, [self], tax_date: Time.current)
end
def ensure_proper_currency
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 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)
end
def 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?
end
def 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.rb
index 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); end
end
end
end
diff --git a/spree/core/app/models/spree/tax_provider/internal.rb b/spree/core/app/models/spree/tax_provider/internal.rb
index 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_a
return if items.empty?
diff --git a/spree/core/app/workflows/spree/carts/add_item.rb b/spree/core/app/workflows/spree/carts/add_item.rb
index 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_created
end
def handle_stock_reservations
diff --git a/spree/core/app/workflows/spree/carts/recalculate_totals.rb b/spree/core/app/workflows/spree/carts/recalculate_totals.rb
index 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 Spree
class RecalculateTotals < Spree::Workflow
hooks :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 Spree
Spree.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's
diff --git a/spree/core/lib/spree/core/controller_helpers/store.rb b/spree/core/lib/spree/core/controller_helpers/store.rb
index 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.rb
index 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 do
let!(: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!
end
end
diff --git a/spree/core/spec/models/spree/tax_provider/base_spec.rb b/spree/core/spec/models/spree/tax_provider/base_spec.rb
new file mode 100644
index 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