spree-kashflow 0.1.0

data/lib/spree/kashflow/client.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "savon"
+
+module Spree
+  module Kashflow
+    ##
+    # Stateless SOAP client for the KashFlow API. Only this class may reference Savon —
+    # every public method returns plain Ruby (Integer, Array<Hash>, TrueClass) so no SOAP
+    # object crosses the gem boundary. KashFlow has no session token: credentials are sent
+    # on every call, so nothing is cached between calls.
+    #
+    class Client
+      # @return [String] the WSDL endpoint KashFlow publishes for the SOAP API
+      WSDL = "https://securedwebapp.com/api/service.asmx?WSDL"
+
+      # @return [Regexp] matches SOAP faults caused by bad credentials
+      AUTH_FAULT = /invalid.*(username|password)|not authori[sz]ed/i
+
+      # @return [String] the in-band `Status` value KashFlow returns on success.
+      #
+      # The WSDL declares `Status` as a bare `s:string` on every `*Response`
+      # element (`minOccurs="0"`), with no `<s:enumeration>` and no
+      # `<wsdl:documentation>` naming the success value — so this constant is
+      # KashFlow's documented convention (`"OK"`), not something the schema
+      # pins down. Comparison is case-insensitive, and an *absent* `Status`
+      # (legal, since `minOccurs="0"`) is treated as success; only a present
+      # `Status` that is not `"OK"` is a business-level rejection.
+      SUCCESS_STATUS = "OK"
+
+      ##
+      # @param username [String] the KashFlow API username
+      # @param password [String] the KashFlow API password
+      #
+      def initialize(username:, password:)
+        @username = username
+        @password = password
+      end
+
+      ##
+      # Verifies the configured credentials against the KashFlow API. Does not rescue —
+      # the caller decides how to handle a raised error.
+      #
+      # @return [TrueClass, FalseClass] true when KashFlow accepts the credentials
+      # @raise [Spree::Kashflow::Error] when KashFlow rejects the credentials or the
+      #   request otherwise fails
+      #
+      def verify_credentials
+        call(:get_currencies)
+        true
+      end
+
+      ##
+      # @return [Array<Hash>] currencies as `{code:, id:}` hashes
+      # @raise [Spree::Kashflow::Error] when the request fails
+      #
+      def currencies
+        rows = extract_rows(call(:get_currencies), "GetCurrenciesResponse", "GetCurrenciesResult", "Currencies")
+        rows.map { |row| {code: row["CurrencyCode"], id: row["CurrencyId"].to_i} }
+      end
+
+      ##
+      # @return [Array<Hash>] nominal codes as `{id:, name:}` hashes
+      # @raise [Spree::Kashflow::Error] when the request fails
+      #
+      def nominal_codes
+        rows = extract_rows(call(:get_nominal_codes), "GetNominalCodesResponse", "GetNominalCodesResult", "NominalCode")
+        rows.map { |row| {id: row["id"].to_i, name: row["Name"]} }
+      end
+
+      ##
+      # @return [Array<Hash>] bank accounts as `{id:, name:}` hashes
+      # @raise [Spree::Kashflow::Error] when the request fails
+      #
+      def bank_accounts
+        rows = extract_rows(call(:get_bank_accounts), "GetBankAccountsResponse", "GetBankAccountsResult", "BankAccount")
+        rows.map { |row| {id: row["AccountID"].to_i, name: row["AccountName"]} }
+      end
+
+      ##
+      # @return [Array<Hash>] invoice payment methods as `{id:, name:}` hashes
+      # @raise [Spree::Kashflow::Error] when the request fails
+      #
+      def payment_methods
+        rows = extract_rows(call(:get_inv_pay_methods), "GetInvPayMethodsResponse", "GetInvPayMethodsResult", "PaymentMethod")
+        rows.map { |row| {id: row["MethodID"].to_i, name: row["MethodName"]} }
+      end
+
+      ##
+      # Creates or updates a customer in KashFlow.
+      #
+      # @param payload [Hash] a KashFlow `Customer` structure
+      # @return [Integer] the KashFlow customer id
+      # @raise [Spree::Kashflow::ApiError] when the request fails, or when
+      #   KashFlow returns no usable customer id
+      #
+      def upsert_customer(payload)
+        response = call(:insert_customer, {"custr" => payload})
+        result = response.dig("InsertCustomerResponse", "InsertCustomerResult")
+        assert_identifier!(result, "customer id")
+      end
+
+      ##
+      # Creates an invoice in KashFlow.
+      #
+      # @param payload [Hash] a KashFlow `Invoice_TypeDefined` structure
+      # @return [Integer] the invoice number KashFlow assigned
+      # @raise [Spree::Kashflow::ApiError] when the request fails, or when
+      #   KashFlow returns no usable invoice number
+      #
+      def create_invoice(payload)
+        response = call(:insert_invoice_type_defined, {"Inv_TD" => payload})
+        result = response.dig("InsertInvoice_TypeDefinedResponse", "InsertInvoice_TypeDefinedResult")
+        assert_identifier!(result, "invoice number")
+      end
+
+      ##
+      # Records a payment against an invoice in KashFlow.
+      #
+      # The WSDL declares `InsertInvoicePaymentResult` as an `s:int` — the id of
+      # the payment KashFlow created. A `0` is therefore a rejection reported
+      # without a `Status`, and returning `true` regardless would leave the
+      # invoice permanently unpaid while the caller recorded a successful sync.
+      #
+      # @param payload [Hash] a KashFlow `Payment` structure
+      # @return [TrueClass] true when the payment was recorded
+      # @raise [Spree::Kashflow::ApiError] when the request fails, or when
+      #   KashFlow returns no payment id
+      #
+      def record_invoice_payment(payload)
+        response = call(:insert_invoice_payment, {"InvoicePayment" => payload})
+        result = response.dig("InsertInvoicePaymentResponse", "InsertInvoicePaymentResult")
+        assert_identifier!(result, "payment id")
+        true
+      end
+
+      ##
+      # Applies a credit note to an invoice in KashFlow.
+      #
+      # The WSDL declares `applyCreditNoteToInvoiceResult` as an `s:boolean`.
+      # A `false` is a refusal to link, and swallowing it produces exactly the
+      # orphan credit note {SyncRefundJob}'s precondition guard exists to
+      # prevent — a credit note sitting in KashFlow attached to nothing.
+      #
+      # @param credit_note_number [Integer] the KashFlow credit note id
+      # @param invoice_number [Integer] the KashFlow invoice id
+      # @return [TrueClass] true when the credit note was applied
+      # @raise [Spree::Kashflow::ApiError] when the request fails, or when
+      #   KashFlow refuses to link the credit note
+      #
+      def apply_credit_note(credit_note_number:, invoice_number:)
+        response = call(:apply_credit_note_to_invoice, {"InvoiceID" => invoice_number, "CreditNoteID" => credit_note_number})
+        result = response.dig("applyCreditNoteToInvoiceResponse", "applyCreditNoteToInvoiceResult")
+        assert_accepted!(result, "did not apply credit note #{credit_note_number} to invoice #{invoice_number}")
+        true
+      end
+
+      private
+
+      ##
+      # @return [Savon::Client] a Savon client bound to the KashFlow WSDL
+      #
+      def savon_client
+        @savon_client ||= Savon.client(
+          wsdl: WSDL,
+          log: false,
+          convert_response_tags_to: ->(tag) { tag }
+        )
+      end
+
+      ##
+      # Invokes a KashFlow SOAP operation, merging credentials into every request, and
+      # maps transport errors, SOAP faults and in-band `Status` rejections onto this
+      # gem's error hierarchy.
+      #
+      # @param operation [Symbol] the Savon operation name
+      # @param message [Hash] the operation's message body, excluding credentials
+      # @return [Hash] the parsed response body
+      # @raise [Spree::Kashflow::AuthenticationError] when KashFlow rejects the credentials
+      # @raise [Spree::Kashflow::ApiError] when KashFlow refuses the operation
+      # @raise [Spree::Kashflow::TransportError] when the KashFlow service could not be reached
+      #
+      def call(operation, message = {})
+        credentials = {"UserName" => @username, "Password" => @password}
+        response = savon_client.call(operation, message: credentials.merge(message))
+        body = response.body
+        assert_status!(body)
+        body
+      rescue Savon::SOAPFault => e
+        fault_message = e.to_hash.dig(:fault, :faultstring) || e.message
+        raise_business_error(fault_message)
+      rescue Savon::HTTPError, HTTPI::SSLError, OpenSSL::SSL::SSLError, SocketError,
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::ETIMEDOUT, Errno::EHOSTUNREACH,
+        Net::OpenTimeout, Net::ReadTimeout => e
+        raise TransportError, e.message
+      end
+
+      ##
+      # KashFlow reports business-level rejections *in band*: the SOAP call
+      # succeeds at HTTP 200 with an empty result element and a `Status` /
+      # `StatusDetail` pair beside it. Left uninspected, a rejection reads as a
+      # `nil` result and coerces to `0` — a value the caller would then record
+      # as a real KashFlow identifier. See {SUCCESS_STATUS} for why the success
+      # value is a convention rather than a schema-declared enumeration.
+      #
+      # @param body [Hash] the parsed response body
+      # @return [void]
+      # @raise [Spree::Kashflow::AuthenticationError] when the rejection is a
+      #   credentials problem
+      # @raise [Spree::Kashflow::ApiError] for any other non-success `Status`
+      #
+      def assert_status!(body)
+        envelope = body.values.detect { |value| value.is_a?(Hash) }
+        return if envelope.nil?
+
+        status = envelope["Status"]
+        return if status.nil?
+        return if status.to_s.strip.casecmp(SUCCESS_STATUS).zero?
+
+        detail = envelope["StatusDetail"]
+        raise_business_error([status, detail].compact_blank.join(": "))
+      end
+
+      ##
+      # @param message [String] the message KashFlow refused the request with
+      # @return [void]
+      # @raise [Spree::Kashflow::AuthenticationError] when the message names a
+      #   credentials problem
+      # @raise [Spree::Kashflow::ApiError] otherwise
+      #
+      def raise_business_error(message)
+        if message.match?(AUTH_FAULT)
+          raise AuthenticationError, message
+        else
+          raise ApiError, message
+        end
+      end
+
+      ##
+      # KashFlow returns `0` (or nothing at all) where it means "refused", and
+      # a `0` recorded as an identifier is worse than a raised error: it looks
+      # like a successful sync, satisfies the caller's idempotency check, and
+      # blocks every retry.
+      #
+      # @param result [Object, nil] the raw result element
+      # @param label [String] what the identifier is, for the error message
+      # @return [Integer] the identifier
+      # @raise [Spree::Kashflow::ApiError] when the result is nil or zero
+      #
+      def assert_identifier!(result, label)
+        identifier = result.to_i
+        return identifier unless result.nil? || identifier.zero?
+
+        raise ApiError, "KashFlow returned no #{label} (result: #{result.inspect})"
+      end
+
+      ##
+      # The counterpart of {#assert_identifier!} for the operations the WSDL types
+      # as `s:boolean` rather than `s:int`. Savon hands the element back as the
+      # string `"true"` / `"false"`, so only an explicit `"true"` is acceptance;
+      # `false`, `nil` and an absent element are all rejections.
+      #
+      # @param result [Object, nil] the raw result element
+      # @param message [String] what KashFlow refused, for the error message
+      # @return [void]
+      # @raise [Spree::Kashflow::ApiError] when the result is not true
+      #
+      def assert_accepted!(result, message)
+        return if result.to_s.strip.casecmp("true").zero?
+
+        raise ApiError, "KashFlow #{message} (result: #{result.inspect})"
+      end
+
+      ##
+      # Normalises a KashFlow list response into an array of row hashes.
+      #
+      # @param body [Hash] the parsed response body
+      # @param response_key [String] the top-level response element name
+      # @param result_key [String] the result element name nested under the response
+      # @param collection_key [String] the element name repeated for each row
+      # @return [Array<Hash>] the rows, or an empty array when the response carries none
+      #
+      def extract_rows(body, response_key, result_key, collection_key)
+        result = body.dig(response_key, result_key)
+        return [] if result.nil?
+
+        rows = result[collection_key]
+        case rows
+        when nil then []
+        when Array then rows
+        else [rows]
+        end
+      end
+    end
+  end
+end

data/lib/spree/kashflow/engine.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Rails engine for the KashFlow integration.
+    #
+    # Loads the gem's +app/+ tree into the host application and applies the
+    # gem's single decorator on each reload.
+    #
+    class Engine < ::Rails::Engine
+      require "spree/core"
+      isolate_namespace Spree
+
+      # Deliberately not "spree-kashflow": engine_name generates route helper
+      # prefixes and must be a valid Ruby identifier, so it cannot contain a dash.
+      engine_name "spree_kashflow"
+
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      ##
+      # Loads the gem's decorators. Called on every reload in development.
+      #
+      # @return [void]
+      #
+      def self.activate
+        # Three levels up from lib/spree/kashflow/ to reach the gem root.
+        Dir.glob(File.join(File.dirname(__FILE__), "../../../app/**/*_decorator*.rb")).sort.each do |c|
+          Rails.configuration.cache_classes ? require(c) : load(c)
+        end
+      end
+
+      config.to_prepare(&method(:activate).to_proc)
+    end
+  end
+end

data/lib/spree/kashflow/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # Base class for every error this gem raises.
+    #
+    class Error < StandardError; end
+
+    ##
+    # Raised when KashFlow rejects the configured credentials. Not retryable.
+    #
+    class AuthenticationError < Error; end
+
+    ##
+    # Raised when KashFlow accepts the request but refuses the operation.
+    #
+    class ApiError < Error; end
+
+    ##
+    # Raised when the KashFlow service could not be reached. Retryable.
+    #
+    class TransportError < Error; end
+
+    ##
+    # Raised by {Spree::Kashflow::InvoicePayload#to_h} when the assembled invoice
+    # lines fail to reconcile against either the line's own net total or the
+    # order's total. Nothing is posted to KashFlow when this is raised.
+    #
+    class TotalMismatchError < Error; end
+  end
+end

data/lib/spree/kashflow/metafields.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    ##
+    # The Spree metafield keys ({Spree::Metafields#set_metafield} /
+    # {Spree::Metafields#get_metafield} "namespace.key" strings) this gem reads and
+    # writes. Centralised here so call sites never repeat the string literal, and so
+    # a later task (or the README) has one place to look up the whole table.
+    #
+    # `Spree::Metafields#set_metafield` auto-creates its backing
+    # `Spree::MetafieldDefinition` the first time a `"namespace.key"` string is used
+    # (`Spree::Metafields#resolve_metafield_definition_id_from_string`,
+    # spree_core-5.6.1 `app/models/concerns/spree/metafields.rb:222`) — confirmed
+    # empirically against the dummy app (see Task 7's report). No definition needs to
+    # be pre-seeded, but the auto-created definition takes `display_on`'s default of
+    # `"both"`, which would make a KashFlow invoice number — and raw KashFlow fault
+    # text in {ORDER_SYNC_ERROR} — storefront-visible by accident. Every write this
+    # gem makes therefore goes through {.write}, which seeds the definition as
+    # `"back_end"` first. These are internal accounting-sync markers; nothing here is
+    # ever meant for a customer.
+    #
+    module Metafields
+      # @return [String] order metafield; the KashFlow invoice number. Written
+      #   immediately after `InsertInvoice_TypeDefined` returns, before any
+      #   follow-on call, so a later failure can never cause the invoice to be
+      #   posted twice. Its presence is the per-step guard {SyncOrderJob} uses to
+      #   skip re-posting the invoice, and it is the identifier
+      #   {CreditNotePayload} carries as `CustomerReference` when a refund is
+      #   posted as a credit note.
+      ORDER_INVOICE_NUMBER = "kashflow.invoice_number"
+
+      # @return [String] order metafield; the timestamp at which the order's
+      #   payment was recorded against the KashFlow invoice. Written immediately
+      #   after `InsertInvoicePayment` succeeds, and checked separately from
+      #   {ORDER_INVOICE_NUMBER} so a retry resumes at the payment step instead of
+      #   re-posting the invoice or skipping the job wholesale.
+      ORDER_PAYMENT_RECORDED_AT = "kashflow.payment_recorded_at"
+
+      # @return [String] order metafield; the KashFlow customer id returned by
+      #   `Client#upsert_customer`.
+      ORDER_CUSTOMER_CODE = "kashflow.customer_code"
+
+      # @return [String] order metafield; the timestamp of the last successful sync.
+      ORDER_SYNCED_AT = "kashflow.synced_at"
+
+      # @return [String] order metafield; the message of the last sync failure.
+      #   Cleared (destroyed) on the next successful sync.
+      ORDER_SYNC_ERROR = "kashflow.sync_error"
+
+      # @return [String] refund metafield; the KashFlow credit note (invoice) number.
+      #   Written immediately after the credit note is posted, before the link
+      #   call, so a failing link can never cause a second credit note. Its
+      #   presence is the per-step guard {SyncRefundJob} uses to skip re-posting.
+      REFUND_CREDIT_NOTE_NUMBER = "kashflow.credit_note_number"
+
+      # @return [String] refund metafield; the timestamp at which the credit note
+      #   was linked to the original invoice via `applyCreditNoteToInvoice`.
+      #   Checked separately from {REFUND_CREDIT_NOTE_NUMBER} so a retry re-runs
+      #   only the link step. Re-applying a link is unverified against a live
+      #   account, so this marker exists to avoid attempting it twice.
+      REFUND_CREDIT_NOTE_LINKED_AT = "kashflow.credit_note_linked_at"
+
+      # @return [String] the `display_on` value every definition this gem owns
+      #   is seeded with: admin-only, never rendered on the storefront.
+      DISPLAY_ON = "back_end"
+
+      ##
+      # Writes one of this gem's metafields, seeding its backing
+      # `Spree::MetafieldDefinition` as {DISPLAY_ON} first so Spree's auto-create
+      # path never gets to default it to `"both"`.
+      #
+      # Idempotent and cheap: after the first write per key the seed is a single
+      # indexed lookup. Deliberately not a boot-time initializer or a migration —
+      # the gem ships neither, and a definition seeded at boot would need the
+      # database up before the app could load.
+      #
+      # @param record [#set_metafield] the {Spree::Order} or {Spree::Refund} to write to
+      # @param key [String] one of this module's `"namespace.key"` constants
+      # @param value [Object, nil] the value to store; `nil` clears the metafield
+      # @return [void]
+      #
+      # @example
+      #   Spree::Kashflow::Metafields.write(order, Spree::Kashflow::Metafields::ORDER_INVOICE_NUMBER, 4471)
+      #
+      def self.write(record, key, value)
+        ensure_definition!(record, key)
+        record.set_metafield(key, value)
+      end
+
+      ##
+      # @param record [ActiveRecord::Base] the resource the definition belongs to
+      # @param key [String] a `"namespace.key"` string
+      # @return [Spree::MetafieldDefinition] the seeded (or already-present) definition
+      #
+      def self.ensure_definition!(record, key)
+        namespace, definition_key = key.split(".", 2)
+
+        Spree::MetafieldDefinition.find_or_create_by!(
+          namespace: namespace,
+          key: definition_key,
+          resource_type: record.class.name
+        ) { |definition| definition.display_on = DISPLAY_ON }
+      end
+    end
+  end
+end

data/lib/spree/kashflow/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Spree
+  module Kashflow
+    VERSION = "0.1.0"
+  end
+end

data/lib/spree/kashflow.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "spree/core"
+require "savon"
+require "spree/kashflow/version"
+require "spree/kashflow/errors"
+require "spree/kashflow/metafields"
+require "spree/kashflow/client"
+require "spree/kashflow/engine"

data/lib/spree-kashflow.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its *name*, so `gem "spree-kashflow"` in a host
+# Gemfile issues `require "spree-kashflow"`. The real entry point is
+# `spree/kashflow` (matching the Spree::Kashflow namespace), so this shim keeps
+# the default `Bundler.require` working.
+require "spree/kashflow"

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: spree-kashflow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aypex
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: savon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.17'
+- !ruby/object:Gem::Dependency
+  name: spree
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.6.0
+- !ruby/object:Gem::Dependency
+  name: spree_extension
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pushes completed Spree orders to KashFlow as invoices and refunds as
+  credit notes over the KashFlow SOAP API, configured per store through Spree's Integrations
+  framework.
+email: hello@aypex.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- app/assets/images/integration_icons/kashflow-logo.png
+- app/jobs/spree/kashflow/sync_order_job.rb
+- app/jobs/spree/kashflow/sync_refund_job.rb
+- app/models/spree/integrations/kashflow.rb
+- app/models/spree/refund_decorator.rb
+- app/presenters/spree/kashflow/credit_note_payload.rb
+- app/presenters/spree/kashflow/customer_payload.rb
+- app/presenters/spree/kashflow/invoice_payload.rb
+- app/subscribers/spree/kashflow/order_completed_subscriber.rb
+- app/subscribers/spree/kashflow/reimbursement_subscriber.rb
+- app/views/spree/admin/integrations/forms/_kashflow.html.erb
+- config/initializers/spree.rb
+- config/locales/en.yml
+- config/routes.rb
+- lib/spree-kashflow.rb
+- lib/spree/kashflow.rb
+- lib/spree/kashflow/client.rb
+- lib/spree/kashflow/engine.rb
+- lib/spree/kashflow/errors.rb
+- lib/spree/kashflow/metafields.rb
+- lib/spree/kashflow/version.rb
+homepage: https://github.com/aypex-io/spree-kashflow
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/aypex-io/spree-kashflow
+  bug_tracker_uri: https://github.com/aypex-io/spree-kashflow/issues
+  changelog_uri: https://github.com/aypex-io/spree-kashflow/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: KashFlow accounting integration for Spree
+test_files: []