brot 0.1.1 → 0.3.0

data/lib/brot/document.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Brot
+  # Payment batch document that serializes into a supported pain.001 version.
+  class Document
+    attr_reader :batch_booking,
+                :created_at,
+                :debtor_account,
+                :debtor_name,
+                :initiating_party_name,
+                :message_id,
+                :payment_information_id,
+                :requested_execution_date,
+                :transfers,
+                :version
+
+    # @param attributes [Hash]
+    # @option attributes [PainVersion, Symbol, String] :version
+    #   Defaults to {PainVersion::PAIN_001_001_03}.
+    def initialize(**attributes)
+      @version = PainVersion.fetch(attributes.fetch(:version, PainVersion.default))
+      assign_identifiers(attributes)
+      assign_party_details(attributes)
+      assign_payment_schedule(attributes)
+    end
+
+    # Returns the sum of all transfer amounts.
+    #
+    # @return [BigDecimal]
+    def control_sum
+      transfers.sum(BigDecimal('0'), &:amount)
+    end
+
+    # Returns the number of transfers in the document.
+    #
+    # @return [Integer]
+    def number_of_transactions
+      transfers.length
+    end
+
+    # Serializes the document into the configured pain.001 XML version.
+    #
+    # @param pretty [Boolean]
+    # @return [String]
+    def to_xml(pretty: true)
+      serializer_config.serializer_class.new(self).to_xml(pretty: pretty)
+    end
+
+    # Validates the generated XML against the configured bundled schema by default.
+    #
+    # @param xsd_path [String, nil]
+    # @return [Schema::Result]
+    def validate(xsd_path: nil)
+      Schema.validate(to_xml(pretty: false), version: version, xsd_path: xsd_path)
+    end
+
+    # Validates the generated XML and raises when the schema check fails.
+    #
+    # @param xsd_path [String, nil]
+    # @return [Schema::Result]
+    def validate!(xsd_path: nil)
+      Schema.validate!(to_xml(pretty: false), version: version, xsd_path: xsd_path)
+    end
+
+    private
+
+    def serializer_config
+      version
+    end
+
+    def assign_identifiers(attributes)
+      @message_id = Utils.normalize_text!('message_id', attributes.fetch(:message_id), max: 35)
+      @payment_information_id = Utils.normalize_text!(
+        'payment_information_id',
+        attributes.fetch(:payment_information_id),
+        max: 35
+      )
+    end
+
+    def assign_party_details(attributes)
+      @initiating_party_name = Utils.normalize_text!(
+        'initiating_party_name',
+        attributes.fetch(:initiating_party_name),
+        max: 70
+      )
+      @debtor_name = Utils.normalize_text!('debtor_name', attributes.fetch(:debtor_name), max: 70)
+      @debtor_account = Account.new(iban: attributes.fetch(:debtor_iban), bic: attributes[:debtor_bic])
+    end
+
+    def assign_payment_schedule(attributes)
+      @requested_execution_date = Utils.normalize_date!(attributes.fetch(:requested_execution_date))
+      @transfers = normalize_transfers!(attributes.fetch(:transfers))
+      @batch_booking = attributes.fetch(:batch_booking, true) ? true : false
+      @created_at = Utils.normalize_time!(attributes.fetch(:created_at, Time.now.utc))
+    end
+
+    def normalize_transfers!(transfers)
+      value = Array(transfers)
+      raise ValidationError, 'at least one transfer is required' if value.empty?
+      raise ValidationError, 'transfers must all be Transfer instances' unless value.all?(Transfer)
+
+      value
+    end
+  end
+end

data/lib/brot/pain_version.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Brot
+  # Supported pain.001 schema versions.
+  class PainVersion
+    attr_reader :identifier, :namespace, :serializer_class, :xsd_path
+
+    # @param identifier [String]
+    # @param namespace [String]
+    # @param serializer_class [Class]
+    # @param xsd_path [String]
+    def initialize(identifier:, namespace:, serializer_class:, xsd_path:)
+      @identifier = identifier.freeze
+      @namespace = namespace.freeze
+      @serializer_class = serializer_class
+      @xsd_path = xsd_path.freeze
+      freeze
+    end
+
+    PAIN_001_001_12 = new(
+      identifier: 'pain.001.001.12',
+      namespace: 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.12',
+      serializer_class: Serializers::Pain00100112,
+      xsd_path: File.expand_path('../../xsd/pain.001.001.12.xsd', __dir__)
+    )
+
+    PAIN_001_001_03 = new(
+      identifier: 'pain.001.001.03',
+      namespace: 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.03',
+      serializer_class: Serializers::Pain00100103,
+      xsd_path: File.expand_path('../../xsd/pain.001.001.03.xsd', __dir__)
+    )
+
+    ALL = [
+      PAIN_001_001_12,
+      PAIN_001_001_03
+    ].freeze
+
+    class << self
+      # @return [PainVersion]
+      def default
+        PAIN_001_001_03
+      end
+
+      # @return [Array<PainVersion>]
+      def all
+        ALL
+      end
+
+      # @param value [PainVersion, String, Symbol]
+      # @return [PainVersion]
+      def fetch(value)
+        return value if value.is_a?(PainVersion)
+
+        normalized = value.to_s.strip.downcase.tr('_', '.')
+        match = ALL.find { it.identifier == normalized }
+        return match if match
+
+        supported = ALL.map(&:identifier).join(', ')
+        raise ValidationError, "version must be one of #{supported}"
+      end
+
+      # @param namespace [String]
+      # @return [PainVersion]
+      def from_namespace(namespace)
+        match = ALL.find { it.namespace == namespace }
+        return match if match
+
+        raise ValidationError, "unsupported document namespace #{namespace.inspect}"
+      end
+    end
+
+    # @return [String]
+    def to_s
+      identifier
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{identifier}>"
+    end
+  end
+end

data/lib/brot/schema.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Brot
+  # XML schema validation helpers for generated payment files.
+  module Schema
+    # Result returned by schema validation.
+    Result = Data.define(:errors) do
+      # @return [Boolean]
+      def valid?
+        errors.empty?
+      end
+    end
+
+    module_function
+
+    # Absolute path to a bundled XSD file.
+    #
+    # @param version [PainVersion, Symbol, String]
+    # @return [String]
+    def bundled_xsd_path(version)
+      PainVersion.fetch(version).xsd_path
+    end
+
+    # Validates XML against the bundled schema for the requested version by default.
+    #
+    # @param xml [String]
+    # @param version [PainVersion, Symbol, String, nil]
+    # @param xsd_path [String, nil]
+    # @return [Result]
+    def validate(xml, version: nil, xsd_path: nil)
+      document = Nokogiri::XML(xml, &:strict)
+      schema_path = xsd_path || bundled_xsd_path(version || infer_version(document))
+      schema = Nokogiri::XML::Schema(File.read(schema_path))
+      errors = schema.validate(document).map { it.message.strip }
+
+      Result.new(errors: errors)
+    end
+
+    # Validates XML and raises when the schema check fails.
+    #
+    # @param xml [String]
+    # @param version [PainVersion, Symbol, String, nil]
+    # @param xsd_path [String, nil]
+    # @return [Result]
+    def validate!(xml, version: nil, xsd_path: nil)
+      result = validate(xml, version: version, xsd_path: xsd_path)
+      raise ValidationError, result.errors.join("\n") unless result.valid?
+
+      result
+    end
+
+    def infer_version(document)
+      namespace = document.root&.namespace&.href
+      return PainVersion.from_namespace(namespace) if namespace
+
+      raise ValidationError, 'xml document namespace is missing'
+    end
+    private_class_method :infer_version
+  end
+end

data/lib/brot/serializer_base.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Brot
+  # Helper methods shared by serializer implementations.
+  module SerializerWritingHelpers
+    GROUP_HEADER_FIELDS = [
+      [:MsgId, :message_id.to_proc],
+      [:CreDtTm, ->(doc) { doc.created_at.iso8601 }],
+      [:NbOfTxs, ->(doc) { doc.number_of_transactions.to_s }],
+      [:CtrlSum, ->(doc) { Utils.format_amount(doc.control_sum) }]
+    ].freeze
+
+    PAYMENT_INFORMATION_FIELDS = [
+      [:PmtInfId, :payment_information_id.to_proc],
+      [:PmtMtd, ->(_) { 'TRF' }],
+      [:BtchBookg, :batch_booking.to_proc],
+      [:NbOfTxs, ->(doc) { doc.number_of_transactions.to_s }],
+      [:CtrlSum, ->(doc) { Utils.format_amount(doc.control_sum) }]
+    ].freeze
+
+    private
+
+    def named_party(xml, element_name, name)
+      xml.public_send(element_name) { xml.Nm(name) }
+    end
+
+    def payment_header(xml)
+      write_fields(xml, PAYMENT_INFORMATION_FIELDS)
+      payment_type_information(xml)
+      requested_execution_date(xml)
+    end
+
+    def debtor_details(xml)
+      named_party(xml, :Dbtr, document.debtor_name)
+      debtor_account(xml)
+      agent(xml, :DbtrAgt, document.debtor_account)
+      xml.ChrgBr('SLEV')
+    end
+
+    def transfer_details(xml)
+      document.transfers.each { build_credit_transfer(xml, it) }
+    end
+
+    def write_fields(xml, fields)
+      fields.each do |element_name, extractor|
+        xml.public_send(element_name, extractor.call(document))
+      end
+    end
+  end
+
+  # Shared XML writer helpers for payment initiation serializers.
+  class SerializerBase
+    include SerializerWritingHelpers
+
+    # @param document [Document]
+    def initialize(document)
+      @document = document
+    end
+
+    # @param pretty [Boolean]
+    # @return [String]
+    def to_xml(pretty: true)
+      builder = Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
+        build_document(xml)
+      end
+
+      return builder.to_xml if pretty
+
+      builder.doc.to_xml(save_with: Nokogiri::XML::Node::SaveOptions::AS_XML)
+    end
+
+    private
+
+    attr_reader :document
+
+    def build_credit_transfer(xml, transfer)
+      xml.CdtTrfTxInf do
+        payment_identification(xml, transfer)
+        amount(xml, transfer)
+        agent(xml, :CdtrAgt, transfer.creditor_account)
+        creditor(xml, transfer)
+        purpose(xml, transfer.purpose_code)
+        remittance_information(xml, transfer.remittance_information)
+      end
+    end
+
+    def build_document(xml)
+      xml.Document(xmlns: namespace) do
+        xml.CstmrCdtTrfInitn do
+          group_header(xml)
+          payment_information(xml)
+        end
+      end
+    end
+
+    def group_header(xml)
+      xml.GrpHdr do
+        write_fields(xml, GROUP_HEADER_FIELDS)
+        named_party(xml, :InitgPty, document.initiating_party_name)
+      end
+    end
+
+    def payment_information(xml)
+      xml.PmtInf do
+        payment_header(xml)
+        debtor_details(xml)
+        transfer_details(xml)
+      end
+    end
+
+    def payment_type_information(xml)
+      xml.PmtTpInf do
+        xml.SvcLvl { xml.Cd('SEPA') }
+      end
+    end
+
+    def payment_identification(xml, transfer)
+      xml.PmtId do
+        xml.InstrId(transfer.instruction_id) if transfer.instruction_id
+        xml.EndToEndId(transfer.end_to_end_id)
+      end
+    end
+
+    def amount(xml, transfer)
+      xml.Amt do
+        xml.InstdAmt(Utils.format_amount(transfer.amount), Ccy: transfer.currency)
+      end
+    end
+
+    def creditor(xml, transfer)
+      named_party(xml, :Cdtr, transfer.creditor_name)
+      xml.CdtrAcct { account_identification(xml, transfer.creditor_account) }
+    end
+
+    def debtor_account(xml)
+      xml.DbtrAcct { account_identification(xml, document.debtor_account) }
+    end
+
+    def account_identification(xml, account)
+      xml.Id { xml.IBAN(account.iban) }
+    end
+
+    def agent(xml, element_name, account)
+      xml.public_send(element_name) do
+        xml.FinInstnId do
+          if account.bic
+            xml.public_send(bic_element_name, account.bic)
+          else
+            other_financial_institution_id(xml)
+          end
+        end
+      end
+    end
+
+    def other_financial_institution_id(xml)
+      xml.Othr { xml.Id(Utils.default_financial_institution_id) }
+    end
+
+    def purpose(xml, purpose_code)
+      return unless purpose_code
+
+      xml.Purp { xml.Cd(purpose_code) }
+    end
+
+    def remittance_information(xml, value)
+      xml.RmtInf { xml.Ustrd(value) }
+    end
+  end
+end

data/lib/brot/serializers/pain00100103.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Brot
+  module Serializers
+    # Concrete serializer for pain.001.001.03 output.
+    class Pain00100103 < SerializerBase
+      private
+
+      def bic_element_name
+        :BIC
+      end
+
+      def namespace
+        'urn:iso:std:iso:20022:tech:xsd:pain.001.001.03'
+      end
+
+      def requested_execution_date(xml)
+        xml.ReqdExctnDt(document.requested_execution_date.iso8601)
+      end
+    end
+  end
+end

data/lib/brot/{pain00100112/serializer.rb → serializers/pain00100112.rb}

@@ -1,12 +1,9 @@
 # frozen_string_literal: true
 
 module Brot
-  module Pain00100112
+  module Serializers
     # Concrete serializer for pain.001.001.12 output.
-    #
-    # Most callers should use {Document#to_xml} instead of instantiating this
-    # class directly.
-    class Serializer < SerializerBase
+    class Pain00100112 < SerializerBase
       private
 
       def bic_element_name
@@ -14,7 +11,7 @@ module Brot
       end
 
       def namespace
-        NAMESPACE
+        'urn:iso:std:iso:20022:tech:xsd:pain.001.001.12'
       end
 
       def requested_execution_date(xml)

data/lib/brot/transfer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Brot
+  # Single credit transfer entry inside a payment batch.
+  class Transfer
+    attr_reader :amount,
+                :creditor_account,
+                :creditor_name,
+                :currency,
+                :end_to_end_id,
+                :instruction_id,
+                :purpose_code,
+                :remittance_information
+
+    # @param attributes [Hash]
+    def initialize(**attributes)
+      assign_creditor_details(attributes)
+      assign_payment_references(attributes)
+    end
+
+    private
+
+    def assign_creditor_details(attributes)
+      @amount = Utils.normalize_amount!(attributes.fetch(:amount))
+      @currency = Utils.normalize_currency!(attributes.fetch(:currency, 'EUR'))
+      @creditor_name = Utils.normalize_text!('creditor_name', attributes.fetch(:creditor_name), max: 70)
+      @creditor_account = Account.new(iban: attributes.fetch(:creditor_iban), bic: attributes[:creditor_bic])
+    end
+
+    def assign_payment_references(attributes)
+      @end_to_end_id = Utils.normalize_text!('end_to_end_id', attributes.fetch(:end_to_end_id), max: 35)
+      @remittance_information = Utils.normalize_text!(
+        'remittance_information',
+        attributes.fetch(:remittance_information),
+        max: 140
+      )
+      @instruction_id = normalize_optional_text(attributes[:instruction_id], 'instruction_id', 35)
+      @purpose_code = normalize_optional_text(attributes[:purpose_code], 'purpose_code', 4)
+    end
+
+    def normalize_optional_text(value, name, max)
+      value.nil? ? nil : Utils.normalize_text!(name, value, max: max)
+    end
+  end
+end

data/lib/brot/utils.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Brot
+  # Normalization and validation helpers for payment data.
+  module Utils
+    module_function
+
+    def normalize_text!(name, value, max:)
+      text = String(value).strip
+      raise ValidationError, "#{name} must not be empty" if text.empty?
+      raise ValidationError, "#{name} exceeds #{max} characters" if text.length > max
+
+      text
+    end
+
+    def normalize_iban!(iban)
+      value = String(iban).upcase.delete(' ')
+      raise ValidationError, 'iban is invalid' unless valid_iban?(value)
+
+      value
+    end
+
+    def normalize_bic!(bic)
+      value = String(bic).upcase.strip
+      raise ValidationError, 'bic is invalid' unless /\A[A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\z/.match?(value)
+
+      value
+    end
+
+    def normalize_amount!(amount)
+      value = BigDecimal(amount.to_s)
+      raise ValidationError, 'amount must be positive' unless value.positive?
+      raise ValidationError, 'amount must have at most two decimal places' unless two_decimal_places?(value)
+
+      value
+    rescue ArgumentError
+      raise ValidationError, 'amount is invalid'
+    end
+
+    def normalize_currency!(currency)
+      value = String(currency).upcase.strip
+      raise ValidationError, 'currency is invalid' unless /\A[A-Z]{3}\z/.match?(value)
+
+      value
+    end
+
+    def normalize_date!(date)
+      return date if date.is_a?(Date)
+      return Date.iso8601(date) if date.is_a?(String)
+
+      raise ValidationError, 'requested_execution_date must be a Date or ISO 8601 string'
+    end
+
+    def normalize_time!(value)
+      return value.getutc if value.respond_to?(:getutc)
+      return Time.iso8601(value).getutc if value.is_a?(String)
+
+      raise ValidationError, 'created_at must be a Time-like object or ISO 8601 string'
+    end
+
+    def format_amount(amount)
+      Kernel.format('%.2f', amount)
+    end
+
+    def default_financial_institution_id
+      'NOTPROVIDED'
+    end
+
+    def valid_iban?(value)
+      return false unless /\A[A-Z]{2}\d{2}[A-Z0-9]{11,30}\z/.match?(value)
+
+      iban_mod97(value) == 1
+    end
+
+    def iban_mod97(iban)
+      rearranged = "#{iban[4..]}#{iban[0, 4]}"
+      remainder = 0
+
+      rearranged.each_char do |char|
+        chunk = "#{remainder}#{char.ord >= 65 ? char.ord - 55 : char}"
+        remainder = chunk.to_i % 97
+      end
+
+      remainder
+    end
+
+    def two_decimal_places?(value)
+      ((value * 100) % 1).zero?
+    end
+  end
+end

data/lib/brot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Brot
-  VERSION = '0.1.1'
+  VERSION = '0.3.0'
 end

data/lib/brot.rb

@@ -7,7 +7,16 @@ require 'time'
 
 module Brot
   class Error < StandardError; end
+  class ValidationError < Error; end
 end
 
 require_relative 'brot/version'
-require_relative 'brot/pain00100112'
+require_relative 'brot/utils'
+require_relative 'brot/account'
+require_relative 'brot/transfer'
+require_relative 'brot/serializer_base'
+require_relative 'brot/serializers/pain00100112'
+require_relative 'brot/serializers/pain00100103'
+require_relative 'brot/pain_version'
+require_relative 'brot/schema'
+require_relative 'brot/document'