spree-kashflow 0.1.0

data/app/jobs/spree/kashflow/sync_refund_job.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Posts a refund to KashFlow as a credit note, linked to the original invoice
+    # via `applyCreditNoteToInvoice`.
+    #
+    # A resumable state machine, the same way as {SyncOrderJob}: posting the
+    # credit note and linking it to the original invoice are two separate calls,
+    # each with its own marker written the instant it succeeds
+    # ({Metafields::REFUND_CREDIT_NOTE_NUMBER} and
+    # {Metafields::REFUND_CREDIT_NOTE_LINKED_AT}), and each guarded independently
+    # in {#sync}. A rerun resumes at the first unfinished step.
+    #
+    class SyncRefundJob < Spree::BaseJob
+      # See {SyncOrderJob}: bad credentials will never succeed on retry.
+      discard_on Spree::Kashflow::AuthenticationError
+
+      # See {SyncOrderJob}: a business rejection does not become acceptance on the
+      # 25th attempt, and {Metafields::ORDER_SYNC_ERROR} already records it.
+      discard_on Spree::Kashflow::ApiError
+
+      # See {SyncOrderJob}: KashFlow being briefly unreachable is retry-safe.
+      retry_on Spree::Kashflow::TransportError, wait: :polynomially_longer, attempts: 5
+
+      ##
+      # @param refund_id [Integer, String] the {Spree::Refund} id
+      # @return [void]
+      # @raise [Spree::Kashflow::Error] any subclass raised while posting; the
+      #   message is written to the order's {Metafields::ORDER_SYNC_ERROR} first
+      #
+      def perform(refund_id)
+        refund = Spree::Refund.find_by(id: refund_id)
+        return if refund.nil?
+
+        order = refund.order
+        integration = Spree::Integrations::Kashflow.active.find_by(store: order.store)
+        return if integration.nil?
+
+        return if credit_note_posted?(refund) && credit_note_linked?(refund)
+
+        sync(refund, order, integration)
+      rescue Spree::Kashflow::Error => e
+        Metafields.write(order, Metafields::ORDER_SYNC_ERROR, e.message)
+        raise
+      end
+
+      private
+
+      ##
+      # A refund on an order that never synced would post a credit note with no
+      # `CustomerReference` for KashFlow to link it to
+      # ({CreditNotePayload#to_h} returns `nil` there) — an orphan
+      # `applyCreditNoteToInvoice` cannot resolve. Refused up front rather than
+      # posted and left dangling.
+      #
+      # @param refund [Spree::Refund]
+      # @param order [Spree::Order]
+      # @param integration [Spree::Integrations::Kashflow]
+      # @return [void]
+      # @raise [Spree::Kashflow::ApiError] when the order has no KashFlow invoice
+      #   number yet
+      #
+      def sync(refund, order, integration)
+        unless order.has_metafield?(CreditNotePayload::INVOICE_NUMBER_METAFIELD_KEY)
+          raise Spree::Kashflow::ApiError,
+            "Order #{order.number.inspect} has no KashFlow invoice number; refusing to post an orphan credit note for refund #{refund.id}"
+        end
+
+        client = integration.client
+        customer_id = client.upsert_customer(CustomerPayload.new(order).to_h)
+
+        # Written the instant `create_invoice` returns, before the link call is
+        # attempted. A credit note is a ledger document: creating it must be
+        # at-most-once, because a duplicate permanently overstates the credit and
+        # nothing in KashFlow flags it. Linking one that already exists is a
+        # separate, re-attemptable step. Writing this marker last — so that a
+        # failed link left the refund "unposted" — is precisely what made a retry
+        # post a *second* credit note, manufacturing the orphan the guard above
+        # exists to prevent rather than avoiding it.
+        unless credit_note_posted?(refund)
+          posted_number = client.create_invoice(credit_note_envelope(refund, order, integration, customer_id))
+          Metafields.write(refund, Metafields::REFUND_CREDIT_NOTE_NUMBER, posted_number)
+        end
+
+        # Guarded separately, and by its own marker rather than by the credit note
+        # number: re-applying a link is unverified against a live account, so it
+        # is never attempted twice.
+        return if credit_note_linked?(refund)
+
+        invoice_number = order.get_metafield(CreditNotePayload::INVOICE_NUMBER_METAFIELD_KEY).value.to_i
+        client.apply_credit_note(credit_note_number: credit_note_number(refund), invoice_number: invoice_number)
+        Metafields.write(refund, Metafields::REFUND_CREDIT_NOTE_LINKED_AT, Time.current)
+      end
+
+      ##
+      # @param refund [Spree::Refund]
+      # @return [TrueClass, FalseClass] whether the credit note has already been
+      #   posted to KashFlow for this refund
+      #
+      def credit_note_posted?(refund)
+        refund.has_metafield?(Metafields::REFUND_CREDIT_NOTE_NUMBER)
+      end
+
+      ##
+      # @param refund [Spree::Refund]
+      # @return [TrueClass, FalseClass] whether the credit note has already been
+      #   linked to the original invoice
+      #
+      def credit_note_linked?(refund)
+        refund.has_metafield?(Metafields::REFUND_CREDIT_NOTE_LINKED_AT)
+      end
+
+      ##
+      # @param refund [Spree::Refund]
+      # @return [Integer, nil] the KashFlow credit note number recorded on the refund
+      #
+      def credit_note_number(refund)
+        refund.get_metafield(Metafields::REFUND_CREDIT_NOTE_NUMBER)&.value&.to_i
+      end
+
+      ##
+      # Wraps {CreditNotePayload#to_h}'s fields in the same WSDL `Invoice` envelope
+      # {SyncOrderJob#invoice_envelope} builds — a credit note is posted through
+      # the same `InsertInvoice_TypeDefined` operation as a real invoice, so it
+      # needs the same `minOccurs="1"` fields. `Paid`/`AmountPaid` are `0`: a
+      # credit note is not itself a payment, it is linked to the original invoice
+      # separately via `applyCreditNoteToInvoice`. See
+      # {SyncOrderJob#invoice_envelope} for the rationale behind the
+      # `ArrayOfInvoiceLine` wrapper around `Lines` and the CIS reverse-charge
+      # trio (UK Construction Industry Scheme fields, structurally required but
+      # not applicable to this integration).
+      #
+      # @param refund [Spree::Refund]
+      # @param order [Spree::Order]
+      # @param integration [Spree::Integrations::Kashflow]
+      # @param customer_id [Integer] the id returned by `Client#upsert_customer`
+      # @return [Hash{String => Object}] a KashFlow `Invoice` structure, in WSDL
+      #   sequence order
+      #
+      def credit_note_envelope(refund, order, integration, customer_id)
+        payload = CreditNotePayload.new(refund, integration: integration).to_h
+        credit_note_date = refund.created_at || Time.current
+
+        {
+          "InvoiceDBID" => 0,
+          "InvoiceNumber" => 0,
+          "InvoiceDate" => credit_note_date,
+          "DueDate" => credit_note_date,
+          "CustomerID" => customer_id,
+          "Paid" => 0,
+          "CustomerReference" => payload["CustomerReference"],
+          "SuppressTotal" => 0,
+          "ProjectID" => 0,
+          "CurrencyCode" => payload["CurrencyCode"],
+          "ExchangeRate" => BigDecimal(1),
+          "Lines" => {"InvoiceLine" => payload["Lines"]},
+          "NetAmount" => payload["NetAmount"],
+          "VATAmount" => payload["VATAmount"],
+          "AmountPaid" => BigDecimal(0),
+          "CISRCNetAmount" => 0,
+          "CISRCVatAmount" => 0,
+          "IsCISReverseCharge" => false
+        }
+      end
+    end
+  end
+end

data/app/models/spree/integrations/kashflow.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Spree
+  module Integrations
+    ##
+    # Per-store KashFlow credentials and posting configuration.
+    #
+    # The four numeric preferences decide which ledger accounts money lands in and deliberately have no
+    # defaults: a wrong nominal code silently posts revenue to the wrong place, so the integration cannot
+    # be saved until an operator chooses them.
+    #
+    class Kashflow < Spree::Integration
+      preference :username, :string
+      preference :password, :password
+      preference :sales_nominal_code, :integer
+      preference :shipping_nominal_code, :integer
+      preference :bank_account_id, :integer
+      preference :payment_method_id, :integer
+
+      validates :preferred_username, :preferred_password, presence: true
+      validates :preferred_sales_nominal_code,
+        :preferred_shipping_nominal_code,
+        :preferred_bank_account_id,
+        :preferred_payment_method_id,
+        presence: true,
+        numericality: {only_integer: true, greater_than: 0}
+
+      ##
+      # @return [String] the admin group this integration is listed under
+      #
+      def self.integration_group
+        "Accounting"
+      end
+
+      ##
+      # @return [String] path to the bundled logo, relative to the asset root
+      #
+      def self.icon_path
+        "integration_icons/kashflow-logo.png"
+      end
+
+      ##
+      # @return [String] the name shown in the admin
+      #
+      def self.integration_name
+        Spree.t("admin.integrations.kashflow.brand_name")
+      end
+
+      ##
+      # Verifies the stored credentials against the KashFlow API.
+      #
+      # @return [TrueClass, FalseClass] true when KashFlow accepts the credentials
+      #
+      def can_connect?
+        client.verify_credentials
+      rescue Spree::Kashflow::Error => e
+        self.connection_error_message = e.message
+        false
+      end
+
+      ##
+      # @return [Spree::Kashflow::Client] a client bound to this integration's credentials
+      #
+      def client
+        Spree::Kashflow::Client.new(username: preferred_username, password: preferred_password)
+      end
+
+      ##
+      # @return [Array<Array(String, Integer)>] nominal code `[name, id]` pairs for
+      #   `options_for_select`; empty when credentials are absent or the lookup fails
+      #
+      def nominal_code_options
+        @nominal_code_options ||= options_from { client.nominal_codes }
+      end
+
+      ##
+      # @return [Array<Array(String, Integer)>] bank account `[name, id]` pairs for
+      #   `options_for_select`; empty when credentials are absent or the lookup fails
+      #
+      def bank_account_options
+        @bank_account_options ||= options_from { client.bank_accounts }
+      end
+
+      ##
+      # @return [Array<Array(String, Integer)>] invoice payment method `[name, id]` pairs for
+      #   `options_for_select`; empty when credentials are absent or the lookup fails
+      #
+      def payment_method_options
+        @payment_method_options ||= options_from { client.payment_methods }
+      end
+
+      private
+
+      ##
+      # Fetches rows from KashFlow and maps them to `options_for_select` pairs. Degrades to an
+      # empty array whenever the dropdown can't be trusted: credentials not yet entered (the
+      # client is never built in that case) or the connected account rejecting or failing the
+      # request — an admin opening this form must always see it render, not a 500.
+      #
+      # @yieldreturn [Array<Hash>] rows as `{id:, name:}` hashes
+      # @return [Array<Array(String, Integer)>]
+      #
+      def options_from
+        return [] if preferred_username.blank? || preferred_password.blank?
+
+        yield.map { |row| [row[:name], row[:id]] }
+      rescue Spree::Kashflow::Error
+        []
+      end
+    end
+  end
+end

data/app/models/spree/refund_decorator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Spree
+  ##
+  # The only decorator in this gem, and it must not grow.
+  #
+  # Spree 5.6 publishes no `refund.created` event, and the returns flow
+  # (`reimbursement.reimbursed`, handled by
+  # {Spree::Kashflow::ReimbursementSubscriber}) does not cover an admin issuing
+  # an ad-hoc refund directly against a payment — the most common manual path.
+  # Left unmirrored, that path would reintroduce the ledger drift KashFlow
+  # credit notes exist to prevent, so this decorator enqueues
+  # {Spree::Kashflow::SyncRefundJob} on every refund. It does nothing else:
+  # no client, no payload building, no integration lookup — the job already
+  # no-ops when no active integration exists.
+  #
+  # If Spree ever adds a `refund.created` event, delete this decorator in
+  # favour of a `Spree::Kashflow::RefundCreatedSubscriber`.
+  #
+  module RefundDecorator
+    ##
+    # @param base [Class] {Spree::Refund}, the class this module is prepended to
+    # @return [void]
+    #
+    def self.prepended(base)
+      base.after_create_commit -> { Spree::Kashflow::SyncRefundJob.perform_later(id) }
+    end
+
+    ::Spree::Refund.prepend self
+  end
+end

data/app/presenters/spree/kashflow/credit_note_payload.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Maps a Spree refund onto the shape KashFlow's `Invoice` complex type expects.
+    # KashFlow has no `InsertCreditNote` operation: a credit note is an invoice with
+    # negative values, posted through the same `InsertInvoice_TypeDefined` path and
+    # then linked to the invoice it credits via `applyCreditNoteToInvoice` (Task 7's
+    # job, not this class's — this class only carries the original invoice number
+    # through `CustomerReference` so that call can be made).
+    #
+    # A refund equal to the order's total produces a full negative mirror of the
+    # invoice's lines, built by delegating to {Spree::Kashflow::InvoicePayload#to_h}
+    # so the credit note inherits that class's reconciliation guard rather than
+    # bypassing it. A partial refund produces a single negative line for the
+    # refunded amount: Spree carries no information tying a partial refund back to
+    # specific line items or VAT rates, so no apportionment across the original
+    # lines is attempted. Instead, VAT on that single line is approximated at the
+    # order's blended rate (`order.included_tax_total / (order.total -
+    # order.included_tax_total)`) — a deliberate simplification, not a derivation
+    # from the refunded item(s), since Spree does not expose which items a partial
+    # refund was for.
+    #
+    # Pure object: reads the refund and its associations, performs no network
+    # calls, and writes nothing back to Spree.
+    #
+    class CreditNotePayload
+      # @return [String] the order metafield key this gem reads the original
+      #   KashFlow invoice number from
+      INVOICE_NUMBER_METAFIELD_KEY = Spree::Kashflow::Metafields::ORDER_INVOICE_NUMBER
+
+      ##
+      # @param refund [Spree::Refund] the refund to post as a KashFlow credit note
+      # @param integration [Spree::Integrations::Kashflow] the integration whose
+      #   nominal codes decide which ledger accounts a partial-refund line posts to
+      #
+      def initialize(refund, integration:)
+        @refund = refund
+        @integration = integration
+      end
+
+      ##
+      # @return [Hash{String => Object}] a KashFlow `Invoice` structure with
+      #   negative values, ready to hand to KashFlow's invoice-insert operation
+      # @raise [Spree::Kashflow::TotalMismatchError] when the refund is full and
+      #   the underlying invoice's lines fail to reconcile against the order's
+      #   total (see {Spree::Kashflow::InvoicePayload#to_h})
+      #
+      def to_h
+        full_refund? ? full_refund_to_h : partial_refund_to_h
+      end
+
+      private
+
+      # @return [Spree::Refund]
+      attr_reader :refund
+
+      # @return [Spree::Integrations::Kashflow]
+      attr_reader :integration
+
+      # @return [Spree::Order]
+      def order
+        refund.order
+      end
+
+      ##
+      # @return [Boolean] whether the refund amount equals the order's total
+      #
+      def full_refund?
+        refund.amount == order.total
+      end
+
+      ##
+      # A full negative mirror of {Spree::Kashflow::InvoicePayload#to_h}'s output.
+      # Deliberately calls `#to_h`, not `#lines` — `#lines` bypasses that class's
+      # correctness guard, and a credit note has no arithmetic of its own to
+      # re-verify the guard against, so it inherits the guard by going through the
+      # reconciled method rather than reimplementing reconciliation here.
+      #
+      # @return [Hash{String => Object}]
+      #
+      def full_refund_to_h
+        invoice = InvoicePayload.new(order, integration: integration).to_h
+
+        {
+          "CurrencyCode" => invoice["CurrencyCode"],
+          "CustomerReference" => invoice_number,
+          "Lines" => invoice["Lines"].map { |line| negate_line(line) },
+          "NetAmount" => -invoice["NetAmount"],
+          "VATAmount" => -invoice["VATAmount"]
+        }
+      end
+
+      ##
+      # @param line [Hash{String => Object}] a KashFlow `InvoiceLine` structure
+      # @return [Hash{String => Object}] the same line with `Rate` and `VatAmount`
+      #   negated; `Quantity` is left positive since KashFlow expresses a credit
+      #   through negative values, not a negative quantity
+      #
+      def negate_line(line)
+        line.merge("Rate" => -line["Rate"], "VatAmount" => -line["VatAmount"])
+      end
+
+      ##
+      # A single negative line for the refunded amount, since Spree carries no
+      # information tying a partial refund to specific line items.
+      #
+      # @return [Hash{String => Object}]
+      #
+      def partial_refund_to_h
+        line = partial_refund_line
+
+        {
+          "CurrencyCode" => order.currency,
+          "CustomerReference" => invoice_number,
+          "Lines" => [line],
+          "NetAmount" => line["Rate"],
+          "VATAmount" => line["VatAmount"]
+        }
+      end
+
+      ##
+      # @return [Hash{String => Object}] the single `InvoiceLine` for a partial
+      #   refund, in WSDL `<s:sequence>` order
+      #
+      def partial_refund_line
+        net_total = (refund.amount / (1 + blended_vat_rate)).round(2)
+        vat_total = refund.amount - net_total
+
+        {
+          "Quantity" => BigDecimal(1),
+          "Description" => "Refund: #{refund.reason.name}",
+          "Rate" => -net_total,
+          "ChargeType" => integration.preferred_sales_nominal_code,
+          "VatRate" => (blended_vat_rate * 100).round(2),
+          "VatAmount" => -vat_total,
+          # KashFlow does not sync against the Spree catalogue, so there is no
+          # KashFlow product to reference.
+          "ProductID" => 0,
+          "Sort" => 1,
+          # No KashFlow project is associated with these invoices.
+          "ProjID" => 0,
+          # Assigned by KashFlow on insert; not known until then.
+          "LineID" => 0
+        }
+      end
+
+      ##
+      # An approximation: Spree does not record which line items or VAT rates a
+      # partial refund applies to, so this spreads the order's overall VAT/net
+      # ratio across the refunded amount rather than deriving it from specific
+      # lines.
+      #
+      # Returns zero when there is no net to divide by — an order whose total is
+      # entirely VAT, or a zero-total order. Guarded rather than left to raise:
+      # `ZeroDivisionError` is not a {Spree::Kashflow::Error}, so it would escape
+      # {SyncRefundJob}'s rescue and the refund would fail with no
+      # `kashflow.sync_error` recorded anywhere.
+      #
+      # @return [BigDecimal] the order's blended VAT rate, expressed as a
+      #   fraction of net (not a percentage)
+      #
+      def blended_vat_rate
+        net = order.total - order.included_tax_total
+        return BigDecimal(0) if net.zero?
+
+        order.included_tax_total / net
+      end
+
+      ##
+      # @return [String, nil] the original KashFlow invoice number this credit
+      #   note is for, read from the order's metafields
+      #
+      def invoice_number
+        order.get_metafield(INVOICE_NUMBER_METAFIELD_KEY)&.value
+      end
+    end
+  end
+end

data/app/presenters/spree/kashflow/customer_payload.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Maps a Spree order's billing details onto the shape KashFlow's `Customer`
+    # complex type expects. Pure object: reads the order and its associations, performs
+    # no network calls, and writes nothing back to Spree.
+    #
+    class CustomerPayload
+      # @return [Array<String>] ISO 3166-1 alpha-2 codes of EU member states, used to
+      #   derive the `EC` VAT-treatment flag. The United Kingdom is deliberately absent:
+      #   post-Brexit it is neither EU nor "outside" for KashFlow's purposes.
+      EU_COUNTRY_CODES = %w[
+        AT BE BG HR CY CZ DK EE FI FR DE GR HU IE IT LV LT LU MT NL PL PT RO SK SI ES SE
+      ].freeze
+
+      # @return [String] the ISO 3166-1 alpha-2 code KashFlow treats as the United Kingdom
+      UNITED_KINGDOM_CODE = "GB"
+
+      # @return [String] the order metadata key a host application must write for
+      #   `VATNumber` to be included in the payload. Spree has no dedicated VAT number
+      #   column, so this gem reads it out of `order.metadata` under this key.
+      VAT_NUMBER_METADATA_KEY = "vat_number"
+
+      ##
+      # @param order [Spree::Order] a completed order with a billing address
+      #
+      def initialize(order)
+        @order = order
+      end
+
+      ##
+      # Keys are emitted in the WSDL `Customer` `<s:sequence>`'s relative order —
+      # `… Address4, CountryName, CountryCode, Postcode, Website, EC, OutsideEC,
+      # … ContactFirstName, ContactLastName, … VATNumber`. Savon serialises a
+      # Hash body in insertion order, and a .NET ASMX endpoint enforcing that
+      # sequence drops or mis-binds an out-of-order element rather than raising,
+      # so the order of these keys is load-bearing, not cosmetic.
+      #
+      # @return [Hash{String => Object}] a KashFlow `Customer` structure keyed by the
+      #   WSDL field names, ready to hand to KashFlow's customer-upsert operation
+      #
+      def to_h
+        payload = {
+          "Code" => order.email,
+          "Name" => customer_name,
+          "Email" => order.email,
+          "Address1" => bill_address&.address1,
+          "Address2" => bill_address&.address2,
+          "Address3" => bill_address&.city,
+          "Address4" => bill_address&.state_name_text,
+          "CountryCode" => billing_country_code,
+          "Postcode" => bill_address&.zipcode,
+          "EC" => ec_flag,
+          "OutsideEC" => outside_ec_flag,
+          "ContactFirstName" => bill_address&.firstname,
+          "ContactLastName" => bill_address&.lastname
+        }
+        payload["VATNumber"] = vat_number if vat_number.present?
+        payload
+      end
+
+      private
+
+      # @return [Spree::Order]
+      attr_reader :order
+
+      ##
+      # Nullable on purpose. A digital-only order can complete with no billing
+      # address at all, and a `NoMethodError` here would escape the sync job's
+      # `Spree::Kashflow::Error` rescue entirely — failing with no
+      # `kashflow.sync_error` recorded. Every caller navigates this safely and
+      # sends the address fields as absent instead.
+      #
+      # @return [Spree::Address, nil] the order's billing address, when it has one
+      #
+      def bill_address
+        order.bill_address
+      end
+
+      ##
+      # KashFlow separates the customer (an organisation, for business buyers) from the
+      # contact person on the order. The billing company stands in for the former when
+      # present; an individual buyer's name is used otherwise.
+      #
+      # @return [String, nil] the billing company name, the billing full name when
+      #   there is no company, or the order's email when there is no billing
+      #   address at all
+      #
+      def customer_name
+        bill_address&.company.presence || bill_address&.full_name.presence || order.email
+      end
+
+      ##
+      # @return [String, nil] the billing address's ISO 3166-1 alpha-2 country code
+      #
+      def billing_country_code
+        bill_address&.country&.iso
+      end
+
+      ##
+      # @return [String, nil] the store's own ISO 3166-1 alpha-2 country code
+      #
+      def store_country_code
+        order.store&.default_country&.iso
+      end
+
+      ##
+      # @return [String, nil] the order's VAT number, read from order metadata since
+      #   Spree has no dedicated column for it
+      #
+      def vat_number
+        order.metadata&.dig(VAT_NUMBER_METADATA_KEY)
+      end
+
+      ##
+      # @return [Integer] 1 when the billing country is in the EU and differs from the
+      #   store's own country, 0 otherwise
+      #
+      def ec_flag
+        return 0 if billing_country_code == store_country_code
+        EU_COUNTRY_CODES.include?(billing_country_code) ? 1 : 0
+      end
+
+      ##
+      # @return [Integer] 1 when the billing country is outside both the UK and the EU,
+      #   0 otherwise (including when it matches the store's own country)
+      #
+      def outside_ec_flag
+        return 0 if billing_country_code == store_country_code
+        return 0 if EU_COUNTRY_CODES.include?(billing_country_code)
+        return 0 if billing_country_code == UNITED_KINGDOM_CODE
+        1
+      end
+    end
+  end
+end