spree-bank_payments 5.0.0 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62489d37734d726a1b9fa5c30303ccd5165ed2679c18e1e87fe69dbddc25d446
-  data.tar.gz: 502281b05bf1680cf13c92ac26e96fb51d5216e513830ae59e0301c66334ee17
+  metadata.gz: 2d27bec55fd161244f5186eb04cef396352d0216ef058579e59ef76e6c88b022
+  data.tar.gz: 61063e50bfa2e05415b38f7e5856fde515784c963e52d7c2cc23315162ebc27d
 SHA512:
-  metadata.gz: 8a81d4f37d6ccf997de25c8dfadb60c73cc91a0812851bdd5477acc2b323948648e19a7469bf861201cde794984ce9eb962b1d2991aae111f59c6b3ec47ea342
-  data.tar.gz: 16684728ff3aace5f8fabac9c2b48766a044ae9c2dd6d9dd904da5755051156af04e53369e2535e34e069641d2654db61ceec966f32e98bd014d56beb40ef28c
+  metadata.gz: f924f8984181cfdfdfe6c3c3df361e093df31f626d9651c72ae986ccc467d936f0fa155aececd6083ccc3b00b23c2111eb0a4a9619d5fb21744ce1ab1b68aee5
+  data.tar.gz: a9dae769559625ae8ad31b3beca9b30dae51e5db207d8cd8873d47500d75383890d4455b0320d9559d62a9cf6a0ce394ca4f952e7e34e3acedadf337b611bd78

data/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 All notable changes to this project are documented in this file.
 
+## 5.1.0
+
+**The bank-transfer discount is now tax-aware.**
+
+`discount_percent` was applied as a single order-level `Spree::Adjustment`.
+Order-level adjustments never reach Spree's `taxable_adjustment_total`, so on a
+tax-inclusive (VAT) store the customer paid less while the order still recorded
+tax on the undiscounted price. This was documented as a known limitation; it is
+now fixed.
+
+The discount is applied as one adjustment **per line item**, allocated
+proportionally to each line's amount with largest-remainder rounding so the
+parts sum to exactly `-(item_total * pct / 100)` — naive per-line rounding
+drifts by a cent, and `order.total` must match the amount quoted on the payment
+session or auto-apply's exact-equality check sends every payment to the manual
+queue. A new `Spree::BankPayments::Adjuster::Discount`, registered in
+`config.spree.adjusters`, folds these into `taxable_adjustment_total` before tax
+is computed, so recorded tax now falls with the discount. (It is inserted ahead
+of `Spree::Adjustable::Adjuster::Tax` so the array reads in execution order, but
+Spree runs the tax adjuster last by construction — the position is cosmetic.)
+
+The type filters match subclassed gateways, consistently with `is_a?`-based
+detection: a store subclassing `Spree::BankPayments::Gateway` gets the same tax
+treatment and the same cleanup on a payment-method switch.
+
+The discount **stacks with promotions** — it is not a competing promo
+adjustment, so neither side is marked ineligible. A 20% promotion plus a 3%
+transfer discount is 23% off. Set `discount_percent` accordingly.
+
+`remove_existing` now searches every adjustment carrying the order's id rather
+than only order-adjustable ones, so a payment-method switch cannot orphan the
+line-item adjustments (and still cleans up adjustments written by 5.0.x).
+
+Minor, not patch: this changes recorded tax on existing tax-inclusive stores.
+
 ## 5.0.0
 
 First public release on RubyGems, as `spree-bank_payments`.

data/README.md

@@ -147,24 +147,28 @@ handler that calls out to Postmark/Resend/etc. rather than using
 ActionMailer — should disable the default mailer and subscribe to the events
 directly instead of fighting the bundled one.
 
-## Known limitations
-
-**The discount does not affect tax on a tax-inclusive (VAT) store.**
-
-`discount_percent` is applied as a single order-level `Spree::Adjustment`
-against `order.item_total`. Spree computes `taxable_adjustment_total` by
-summing tax-relevant adjustments on *line items and shipments only* — an
-order-level adjustment is never included in that sum. The practical effect:
-on a VAT store, the customer pays less, but the order still records tax as
-if calculated on the undiscounted price. The discount and the tax figure
-disagree.
-
-This is not a bug we plan to quietly patch later — fixing it properly means
-moving the discount onto line-item adjustments, the way Spree's own
-promotions do, which is a bigger change than this gem currently makes. If
-your store is VAT/tax-inclusive, know this before you set a
-`discount_percent`, and evaluate whether the mismatch is acceptable for your
-accounting.
+## Tax, and stacking with promotions
+
+The discount is applied as one `Spree::Adjustment` per **line item** (sourced
+from the payment method, not a promotion action), allocated proportionally to
+each line's amount and reconciled with largest-remainder rounding so the parts
+sum to exactly `-(item_total * discount_percent / 100)` — to the cent.
+
+Because they are line-item adjustments, they reach Spree's
+`taxable_adjustment_total`, so **recorded tax falls with the discount**. On a
+tax-inclusive (VAT) store a 3% discount on a £100 line reduces recorded VAT
+from £16.67 to £16.17. The pre-5.1 order-level adjustment did not do this — the
+customer paid less while the order still recorded tax on the undiscounted
+price. That is fixed.
+
+**The discount stacks with promotions.** It is deliberately not a competing
+promotion: Spree picks a single winner among competing promo adjustments, but
+this is a separate concession for paying by transfer, so it is never marked
+ineligible and never makes a promotion ineligible. A 20% promotion plus a 3%
+transfer discount is 23% off. Set `discount_percent` with that in mind.
+
+Base is always `item_total`, never `order.total` — the discount never applies
+to shipping or tax.
 
 ## The instructions partial ships no CSS
 

data/app/models/spree/bank_payments/adjuster/discount.rb

@@ -0,0 +1,55 @@
+module Spree
+  module BankPayments
+    module Adjuster
+      # Folds this gem's line-item discount adjustments into
+      # +taxable_adjustment_total+ so the discount actually reduces recorded
+      # tax on a tax-inclusive (VAT) store.
+      #
+      # Must be registered in `config.spree.adjusters` (see
+      # config/initializers/spree.rb): AdjustmentsUpdater runs every registered
+      # non-tax adjuster, persists the running totals, and only then runs the
+      # tax adjuster -- which recomputes each tax adjustment from
+      # LineItem#taxable_basis, itself derived from taxable_amount
+      # (= amount + taxable_adjustment_total). Unregistered, the discount never
+      # reaches that total and tax stays on the undiscounted price.
+      #
+      # Position within the adjusters array is not significant: the updater
+      # pulls the tax adjuster out by name and always runs it last.
+      #
+      # Deliberately NOT modelled on the winner-picking half of
+      # Spree::Adjustable::Adjuster::Promotion. That adjuster marks every
+      # competing promo but the best one `eligible: false`, because only one
+      # promotion may apply. A payment-method discount is not competing with
+      # promotions -- it is a separate concession for paying by transfer, and
+      # must stack (a 20% promo plus a 3% transfer discount is 23% off). So
+      # this adjuster only sums; it never touches `eligible`, and this gem's
+      # adjustments are excluded from `competing_promos` (which is hardcoded
+      # to source_type 'Spree::PromotionAction') so Spree's promo adjuster
+      # cannot mark them ineligible either.
+      #
+      # Nor does it call Adjustment#update! the way the promotion adjuster
+      # does: the source here is a Spree::PaymentMethod, which has no
+      # `compute_amount`. The amounts are computed once, exactly, by
+      # ApplyDiscount and are authoritative.
+      class Discount < Spree::Adjustable::Adjuster::Base
+        def update
+          @totals[:taxable_adjustment_total] += bank_transfer_discount_total
+        end
+
+        private
+
+        # The type filter covers subclassed gateways. ApplyDiscount decides with
+        # `is_a?`, so a store subclassing the gateway would otherwise get
+        # adjustments created that this adjuster ignores -- VAT silently
+        # unfixed, which is the bug this class exists to prevent.
+        def bank_transfer_discount_total
+          adjustments.
+            eligible.
+            where(source_type: 'Spree::PaymentMethod',
+                  source_id: Spree::BankPayments.gateway_scope.select(:id)).
+            sum(:amount)
+        end
+      end
+    end
+  end
+end

data/app/services/spree/bank_payments/apply_discount.rb

@@ -27,15 +27,19 @@ module Spree
         return unless bank_transfer?
         return if percent.zero?
 
-        order.adjustments.create!(
-          adjustable: order,
-          order: order,
-          source: payment_method,
-          amount: discount_amount,
-          label: label,
-          eligible: true,
-          included: false
-        )
+        allocation.each do |line_item, amount|
+          next if amount.zero?
+
+          Spree::Adjustment.create!(
+            adjustable: line_item,
+            order: order,
+            source: payment_method,
+            amount: amount,
+            label: label,
+            eligible: true,
+            included: false
+          )
+        end
 
         order.update_with_updater!
       end
@@ -57,30 +61,88 @@ module Spree
       # Base is item_total, never order.total: order.total is gross and would
       # also discount shipping.
       #
-      # NOTE: this is an ORDER-level adjustment, so it does NOT reduce recorded
-      # VAT. included_tax_total is summed from line items and shipments; an
-      # order-level adjustment never reaches taxable_adjustment_total. On a
-      # tax-inclusive store the customer pays less while the order still
-      # records tax on the undiscounted price. Making the discount tax-aware
-      # would require line-item adjustments (as Spree promotions use) -- a
-      # deliberate open design question, not an oversight.
+      # This is the authoritative figure. The per-line allocation below must
+      # sum to exactly this, to the cent.
       def discount_amount
         -(order.item_total * percent / 100).round(2)
       end
 
+      # The discount is spread across LINE ITEMS rather than sitting on the
+      # order, so that it reaches Spree::LineItem#taxable_adjustment_total and
+      # actually reduces recorded tax on a tax-inclusive (VAT) store. An
+      # order-level adjustment never reaches that sum, which is why the
+      # pre-5.1 behaviour left the order recording VAT on the undiscounted
+      # price while the customer paid less.
+      #
+      # Largest-remainder allocation, NOT naive per-line rounding. Rounding
+      # each line independently drifts: 3 items at 33.33 with 2.5% gives
+      # 0.83 x 3 = 2.49 against an intended 2.50. That cent matters far more
+      # than it looks -- order.total must equal the amount quoted on the
+      # payment session, and auto-apply requires exact amount equality, so a
+      # single cent of drift diverts every payment into the manual admin
+      # queue.
+      #
+      # @return [Array<Array(Spree::LineItem, BigDecimal)>]
+      def allocation
+        line_items = order.line_items.to_a
+        weights = line_items.map { |line_item| line_item.amount.to_d }
+        weight_total = weights.sum
+
+        target_cents = (discount_amount.abs * 100).round.to_i
+        return [] if target_cents.zero?
+
+        cents =
+          if weight_total <= 0
+            # Degenerate (all-zero or negative line items): nothing sensible to
+            # weight by, so spread evenly and let the remainder rule finish it.
+            largest_remainder(Array.new(line_items.size, 1.to_d), line_items.size.to_d, target_cents)
+          else
+            largest_remainder(weights, weight_total, target_cents)
+          end
+
+        line_items.zip(cents.map { |c| -(c.to_d / 100) })
+      end
+
+      # Floor every share, then hand the leftover cents out one at a time to
+      # the largest fractional remainders (ties broken by original order, so
+      # the result is deterministic). Sums to `target_cents` by construction.
+      def largest_remainder(weights, weight_total, target_cents)
+        exact = weights.map { |weight| target_cents * weight / weight_total }
+        floors = exact.map(&:floor)
+        leftover = target_cents - floors.sum
+
+        ranked = exact.each_with_index.
+                 sort_by { |value, index| [-(value - value.floor), index] }.
+                 map(&:last)
+
+        ranked.first(leftover).each { |index| floors[index] += 1 }
+        floors
+      end
+
       def label
         Spree.t('bank_payments.discount_label', percent: payment_method.formatted_discount_percent)
       end
 
+      # Type filter covers subclasses (see gateway_type_names): `bank_transfer?`
+      # matches them with `is_a?`, so every SQL filter here must too.
       def settled_by_bank_transfer?
         order.payments.completed.joins(:payment_method).
-          where(spree_payment_methods: { type: 'Spree::BankPayments::Gateway' }).exists?
+          where(spree_payment_methods: { type: Spree::BankPayments.gateway_type_names }).exists?
       end
 
+      # Scoped by `order.all_adjustments` (every adjustment carrying this
+      # order_id, whatever it is adjustable to) rather than `order.adjustments`
+      # (order-adjustable only). Since 5.1 the discount lives on line items, so
+      # the narrower scope would find nothing and silently orphan the whole
+      # discount on a payment-method switch -- the customer keeps a transfer
+      # discount while paying by card. The wider scope also still catches the
+      # order-level adjustments written by earlier versions of this gem.
+      #
+      # Matches subclassed gateways too, for the same reason as above.
       def remove_existing
-        existing = order.adjustments.where(source_type: 'Spree::PaymentMethod').
-                   joins("INNER JOIN spree_payment_methods ON spree_payment_methods.id = spree_adjustments.source_id").
-                   where(spree_payment_methods: { type: 'Spree::BankPayments::Gateway' })
+        existing = order.all_adjustments.
+                   where(source_type: 'Spree::PaymentMethod',
+                         source_id: Spree::BankPayments.gateway_scope.select(:id))
 
         return if existing.empty?
 

data/config/initializers/spree.rb

@@ -1,6 +1,16 @@
 Rails.application.config.after_initialize do
   Rails.application.config.spree.payment_methods << Spree::BankPayments::Gateway
 
+  # Must be here rather than in `to_prepare` below: spree_core ASSIGNS
+  # `config.spree.adjusters = [Promotion, Tax]` in its own after_initialize,
+  # and `to_prepare` callbacks run earlier in boot, so a to_prepare-only
+  # registration would be silently wiped. Engine initializers (this file
+  # included) are loaded after spree_core's engine registers its hook, so this
+  # block runs after that assignment. See
+  # Spree::BankPayments.register_discount_adjuster! for why the ordering
+  # within the array matters.
+  Spree::BankPayments.register_discount_adjuster!
+
   # I4: without this the unmatched-transfers queue (and the "record a
   # received transfer" form that is the only ingress under the default
   # Manual reconciler) is reachable only by typing the URL.
@@ -52,4 +62,13 @@ Rails.application.config.to_prepare do
   # Subscribers must re-register per reload too: spree_core's own to_prepare hook
   # calls Spree::Events.reset!, which drops Proc-based subscribers registered at boot.
   Spree::BankPayments.register_default_mailer_subscribers! unless Spree::BankPayments::Config.disable_default_mailer
+
+  # Also re-registered per reload, for the Zeitwerk reason above rather than
+  # the Spree::Events one: Adjuster::Discount autoloads from app/models, so
+  # after a reload the adjusters array holds a stale, unloaded class object.
+  # register_discount_adjuster! rejects by class NAME and re-inserts, so this
+  # swaps in the fresh constant without ever stacking duplicates. On the very
+  # first boot the array is not seeded yet and this call is a no-op; the
+  # after_initialize call above does the real registration.
+  Spree::BankPayments.register_discount_adjuster!
 end

data/lib/spree/bank_payments/version.rb

@@ -1,6 +1,6 @@
 module Spree
   module BankPayments
     # Major version tracks Spree's major version: 5.x supports Spree 5.x.
-    VERSION = '5.0.0'.freeze
+    VERSION = '5.1.0'.freeze
   end
 end

data/lib/spree/bank_payments.rb

@@ -18,6 +18,73 @@ module Spree
       'spree_bank_payments_'
     end
 
+    # Registers Spree::BankPayments::Adjuster::Discount in
+    # `Rails.application.config.spree.adjusters`.
+    #
+    # Being in that array at all is what matters: AdjustmentsUpdater runs every
+    # registered non-tax adjuster and persists the resulting totals onto the
+    # adjustable BEFORE computing tax, so an unregistered adjuster means the
+    # line-item discounts never reach taxable_adjustment_total and tax is still
+    # computed on the undiscounted price.
+    #
+    # Position within the array is NOT significant. AdjustmentsUpdater picks the
+    # tax adjuster out by name (`adjusters - [tax_adjuster]`) and always runs it
+    # last, whatever the order. We insert ahead of it so the array reads in
+    # execution order, but appending would behave identically -- do not treat
+    # the insertion point as load-bearing.
+    #
+    # Called from BOTH hooks in config/initializers/spree.rb, for two different
+    # reasons:
+    #
+    # * `after_initialize`, because spree_core *assigns* (not appends to)
+    #   `config.spree.adjusters` in its own after_initialize. A `to_prepare`
+    #   registration runs earlier in boot (run_prepare_callbacks is a finisher
+    #   ahead of finisher_hook) and would be wiped by that assignment.
+    # * `to_prepare`, because the adjuster autoloads from app/models: Zeitwerk
+    #   re-creates the class on every code reload in development, leaving the
+    #   array holding a stale, unloaded constant. Re-running swaps in the
+    #   fresh one.
+    #
+    # Idempotent, and safe to call before spree_core has seeded the array
+    # (a no-op then -- the after_initialize call registers for real).
+    def self.register_discount_adjuster!
+      adjusters = Rails.application.config.spree.adjusters
+      return if adjusters.blank?
+
+      # Reject by NAME, not by identity: after a reload the array holds the
+      # previous incarnation of the class, which is not `equal?` to the fresh
+      # constant, so a `include?` guard would let duplicates accumulate.
+      adjusters.reject! { |adjuster| adjuster.name == 'Spree::BankPayments::Adjuster::Discount' }
+
+      # Cosmetic: keeps the array in execution order. AdjustmentsUpdater runs
+      # the tax adjuster last regardless, so `<<` would be equivalent.
+      tax_index = adjusters.index { |adjuster| adjuster.name == 'Spree::Adjustable::Adjuster::Tax' }
+      if tax_index
+        adjusters.insert(tax_index, Spree::BankPayments::Adjuster::Discount)
+      else
+        adjusters << Spree::BankPayments::Adjuster::Discount
+      end
+    end
+
+    # Every STI type name that counts as one of this gem's gateways.
+    #
+    # `ApplyDiscount#bank_transfer?` tests with `is_a?`, which matches
+    # subclasses, so a store subclassing the gateway HAS the discount applied.
+    # The SQL filters must agree, or those adjustments would be created but
+    # never counted into taxable_adjustment_total (VAT silently unfixed -- the
+    # exact bug 5.1.0 fixes) and never removed on a payment-method switch
+    # (leaking margin). Resolved at call time so it reflects whatever is loaded.
+    def self.gateway_type_names
+      ([Spree::BankPayments::Gateway] + Spree::BankPayments::Gateway.descendants).map(&:name).uniq
+    end
+
+    # Subquery of payment-method ids for those types. `unscoped` deliberately:
+    # a soft-deleted payment method must still have its stale adjustments found
+    # and removed.
+    def self.gateway_scope
+      Spree::PaymentMethod.unscoped.where(type: gateway_type_names)
+    end
+
     def self.pg_trgm_available?
       return @pg_trgm_available if defined?(@pg_trgm_available)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree-bank_payments
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.0
 platform: ruby
 authors:
 - Aypex
@@ -82,6 +82,7 @@ files:
 - app/jobs/spree/bank_payments/poll_job.rb
 - app/jobs/spree/bank_payments/send_reminders_job.rb
 - app/mailers/spree/bank_payments/instructions_mailer.rb
+- app/models/spree/bank_payments/adjuster/discount.rb
 - app/models/spree/bank_payments/base.rb
 - app/models/spree/bank_payments/gateway.rb
 - app/models/spree/bank_payments/incoming_transfer.rb
@@ -143,7 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Bank transfer checkout for Spree, with pluggable payment reconciliation
 test_files: []