brot 0.1.1

data/lib/brot/pain00100112/document.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Payment batch document that serializes into pain.001.001.12 XML.
+    #
+    # This is the main entry point of the gem. A document corresponds to one
+    # complete XML file containing one debtor and one or more outgoing credit
+    # transfers.
+    #
+    # @example Build and validate a payment file
+    #   transfer = Brot::Pain00100112::Transfer.new(
+    #     amount: '1250.50',
+    #     creditor_name: 'Example Supplier GmbH',
+    #     creditor_iban: 'DE89370400440532013000',
+    #     end_to_end_id: 'INV-2026-0001',
+    #     remittance_information: 'Invoice 2026-0001'
+    #   )
+    #
+    #   document = Brot::Pain00100112::Document.new(
+    #     message_id: 'MSG-20260313-01',
+    #     payment_information_id: 'PMT-20260313-01',
+    #     initiating_party_name: 'Example Debtor GmbH',
+    #     debtor_name: 'Example Debtor GmbH',
+    #     debtor_iban: 'DE12500105170648489890',
+    #     requested_execution_date: Date.new(2026, 3, 13),
+    #     transfers: [transfer]
+    #   )
+    #
+    #   result = document.validate
+    #   raise result.errors.join("\n") unless result.valid?
+    #
+    # @attr_reader message_id
+    #   Group header message identifier.
+    #   Example: `MSG-20260313-01`
+    # @attr_reader payment_information_id
+    #   Payment information block identifier.
+    #   Example: `PMT-20260313-01`
+    # @attr_reader initiating_party_name
+    #   Name written into `GrpHdr/InitgPty/Nm`.
+    #   Example: `Example Debtor GmbH`
+    # @attr_reader debtor_name
+    #   Name written into `PmtInf/Dbtr/Nm`.
+    #   Example: `Example Debtor GmbH`
+    # @attr_reader debtor_account
+    #   Debtor bank account as an {Account}.
+    # @attr_reader requested_execution_date
+    #   Requested execution date as a {Date}.
+    # @attr_reader transfers
+    #   Array of {Transfer} objects.
+    # @attr_reader batch_booking
+    #   Whether the file asks for batch booking.
+    # @attr_reader created_at
+    #   Creation time written into `GrpHdr/CreDtTm`.
+    class Document
+      attr_reader :batch_booking,
+                  :created_at,
+                  :debtor_account,
+                  :debtor_name,
+                  :initiating_party_name,
+                  :message_id,
+                  :payment_information_id,
+                  :requested_execution_date,
+                  :transfers
+
+      # @param attributes [Hash]
+      # @option attributes [String] :message_id
+      #   Example: `MSG-20260313-01`
+      # @option attributes [String] :payment_information_id
+      #   Example: `PMT-20260313-01`
+      # @option attributes [String] :initiating_party_name
+      #   Example: `Example Debtor GmbH`
+      # @option attributes [String] :debtor_name
+      #   Example: `Example Debtor GmbH`
+      # @option attributes [String] :debtor_iban
+      #   Example: `DE12500105170648489890`
+      # @option attributes [String, nil] :debtor_bic
+      #   Example: `INGDDEFFXXX`
+      # @option attributes [Date, String] :requested_execution_date
+      #   Example: `Date.new(2026, 3, 13)` or `'2026-03-13'`
+      # @option attributes [Array<Transfer>] :transfers
+      #   Must contain at least one transfer.
+      # @option attributes [Boolean] :batch_booking
+      #   Defaults to `true`.
+      # @option attributes [Time, String] :created_at
+      #   Defaults to the current UTC time.
+      def initialize(**attributes)
+        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 `pain.001.001.12` XML.
+      #
+      # @param pretty [Boolean]
+      #   When `true`, outputs formatted XML with indentation.
+      # @return [String]
+      def to_xml(pretty: true)
+        Serializer.new(self).to_xml(pretty: pretty)
+      end
+
+      # Validates the generated XML against the bundled schema by default.
+      #
+      # @param xsd_path [String]
+      #   Optional custom XSD path.
+      # @return [Schema::Result]
+      def validate(xsd_path: Schema.bundled_xsd_path)
+        Schema.validate(to_xml(pretty: false), xsd_path: xsd_path)
+      end
+
+      private
+
+      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
+end

data/lib/brot/pain00100112/schema.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # XML schema validation helpers for generated payment files.
+    #
+    # Use this module when you already have an XML string and want to validate
+    # it against the bundled `pain.001.001.12.xsd`.
+    #
+    # @example Validate XML directly
+    #   xml = document.to_xml(pretty: false)
+    #   result = Brot::Pain00100112::Schema.validate(xml)
+    #
+    #   raise result.errors.join("\n") unless result.valid?
+    module Schema
+      # Result returned by schema validation.
+      #
+      # @example Check a validation result
+      #   result = Brot::Pain00100112::Schema.validate(xml)
+      #
+      #   result.valid?
+      #   # => true
+      #
+      #   result.errors
+      #   # => []
+      Result = Data.define(:errors) do
+        # @return [Boolean]
+        def valid?
+          errors.empty?
+        end
+      end
+
+      module_function
+
+      # Absolute path to the XSD file bundled inside the gem.
+      #
+      # @return [String]
+      def bundled_xsd_path
+        File.expand_path('../../../xsd/pain.001.001.12.xsd', __dir__)
+      end
+
+      # Validates XML against the bundled schema by default.
+      #
+      # @param xml [String]
+      #   A `pain.001.001.12` XML document.
+      # @param xsd_path [String]
+      #   Optional custom XSD path.
+      # @return [Result]
+      def validate(xml, xsd_path: bundled_xsd_path)
+        schema = Nokogiri::XML::Schema(File.read(xsd_path))
+        document = Nokogiri::XML(xml, &:strict)
+        errors = schema.validate(document).map { it.message.strip }
+
+        Result.new(errors: errors)
+      end
+    end
+  end
+end

data/lib/brot/pain00100112/serializer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Concrete serializer for pain.001.001.12 output.
+    #
+    # Most callers should use {Document#to_xml} instead of instantiating this
+    # class directly.
+    class Serializer < SerializerBase
+      private
+
+      def bic_element_name
+        :BICFI
+      end
+
+      def namespace
+        NAMESPACE
+      end
+
+      def requested_execution_date(xml)
+        xml.ReqdExctnDt { xml.Dt(document.requested_execution_date.iso8601) }
+      end
+    end
+  end
+end

data/lib/brot/pain00100112/serializer_base.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # 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.
+    #
+    # This is an internal base class. For normal application code, use
+    # {Document#to_xml} rather than calling serializer classes directly.
+    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.amount)
+          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, amount)
+        xml.Amt do
+          xml.InstdAmt(Utils.format_amount(amount), Ccy: 'EUR')
+        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
+end

data/lib/brot/pain00100112/transfer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Single credit transfer entry inside a payment batch.
+    #
+    # Each instance becomes one `CdtTrfTxInf` block inside the output XML.
+    #
+    # @example Create a transfer
+    #   transfer = Brot::Pain00100112::Transfer.new(
+    #     amount: '1250.50',
+    #     creditor_name: 'Example Supplier GmbH',
+    #     creditor_iban: 'DE89370400440532013000',
+    #     creditor_bic: 'COBADEFFXXX',
+    #     end_to_end_id: 'INV-2026-0001',
+    #     remittance_information: 'Invoice 2026-0001',
+    #     instruction_id: 'PAY-0001',
+    #     purpose_code: 'SUPP'
+    #   )
+    #
+    # @attr_reader amount
+    #   Transfer amount as a `BigDecimal`.
+    #   Example input: `'1250.50'`
+    # @attr_reader creditor_name
+    #   Name written into `Cdtr/Nm`.
+    #   Example: `Example Supplier GmbH`
+    # @attr_reader creditor_account
+    #   Creditor bank account as an {Account}.
+    # @attr_reader end_to_end_id
+    #   End-to-end reference.
+    #   Example: `INV-2026-0001`
+    # @attr_reader remittance_information
+    #   Unstructured remittance information.
+    #   Example: `Invoice 2026-0001`
+    # @attr_reader instruction_id
+    #   Optional instruction identifier.
+    #   Example: `PAY-0001`
+    # @attr_reader purpose_code
+    #   Optional purpose code.
+    #   Example: `SUPP`
+    class Transfer
+      attr_reader :amount,
+                  :creditor_account,
+                  :creditor_name,
+                  :end_to_end_id,
+                  :instruction_id,
+                  :purpose_code,
+                  :remittance_information
+
+      # @param attributes [Hash]
+      # @option attributes [String, Numeric] :amount
+      #   Example: `'1250.50'`
+      # @option attributes [String] :creditor_name
+      #   Example: `Example Supplier GmbH`
+      # @option attributes [String] :creditor_iban
+      #   Example: `DE89370400440532013000`
+      # @option attributes [String, nil] :creditor_bic
+      #   Example: `COBADEFFXXX`
+      # @option attributes [String] :end_to_end_id
+      #   Example: `INV-2026-0001`
+      # @option attributes [String] :remittance_information
+      #   Example: `Invoice 2026-0001`
+      # @option attributes [String, nil] :instruction_id
+      #   Example: `PAY-0001`
+      # @option attributes [String, nil] :purpose_code
+      #   Example: `SUPP`
+      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))
+        @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
+end

data/lib/brot/pain00100112/utils.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Normalization and validation helpers for payment data.
+    #
+    # This module is internal. Application code should normally use the public
+    # classes {Account}, {Transfer}, {Document}, and {Schema}.
+    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
+        unless /\A[A-Z0-9]{4}[A-Z]{2}[A-Z0-9]{2}(?:[A-Z0-9]{3})?\z/.match?(value)
+          raise ValidationError,
+                'bic is invalid'
+        end
+
+        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_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
+end

data/lib/brot/pain00100112.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Public namespace for the pain.001.001.12 implementation.
+    #
+    # Main entry points:
+    #
+    # - {Document} for building complete payment files
+    # - {Transfer} for individual outgoing payments
+    # - {Schema} for validating XML against the bundled XSD
+    NAMESPACE = 'urn:iso:std:iso:20022:tech:xsd:pain.001.001.12'
+
+    # Raised when input data cannot be normalized into a valid payment file.
+    class ValidationError < Brot::Error; end
+  end
+end
+
+require_relative 'pain00100112/account'
+require_relative 'pain00100112/document'
+require_relative 'pain00100112/schema'
+require_relative 'pain00100112/serializer_base'
+require_relative 'pain00100112/serializer'
+require_relative 'pain00100112/transfer'
+require_relative 'pain00100112/utils'

data/lib/brot/version.rb

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

data/lib/brot.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+require 'date'
+require 'nokogiri'
+require 'time'
+
+module Brot
+  class Error < StandardError; end
+end
+
+require_relative 'brot/version'
+require_relative 'brot/pain00100112'

data/test/brot_test.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'test_helper'
+
+class BrotTest < Minitest::Test
+  def test_has_a_version_number
+    refute_nil Brot::VERSION
+  end
+end