sepa_rator 0.15.0

data/lib/sepa_rator/account/address.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module SEPA
+  class Address
+    include ActiveModel::Validations
+    include AttributeInitializer
+    extend Converter
+
+    # PostalAddress6 fields (all schemas)
+    attr_accessor :street_name,
+                  :building_number,
+                  :post_code,
+                  :town_name,
+                  :country_code,
+                  :address_line1,
+                  :address_line2,
+                  # PostalAddress24 fields (.09/.08 and above)
+                  :department,
+                  :sub_department,
+                  :building_name,
+                  :floor,
+                  :post_box,
+                  :room,
+                  :town_location_name,
+                  :district_name,
+                  :country_sub_division,
+                  # PostalAddress27 fields (.13/.12 only)
+                  :care_of,
+                  :unit_number
+
+    convert :street_name,          to: :text
+    convert :building_number,      to: :text
+    convert :post_code,            to: :text
+    convert :town_name,            to: :text
+    convert :country_code,         to: :text
+    convert :address_line1,        to: :text
+    convert :address_line2,        to: :text
+    convert :department,           to: :text
+    convert :sub_department,       to: :text
+    convert :building_name,        to: :text
+    convert :floor,                to: :text
+    convert :post_box,             to: :text
+    convert :room,                 to: :text
+    convert :town_location_name,   to: :text
+    convert :district_name,        to: :text
+    convert :country_sub_division, to: :text
+    convert :care_of,              to: :text
+    convert :unit_number,          to: :text
+
+    # Max lengths use the most permissive schema (PostalAddress27).
+    # Stricter per-schema limits are enforced by XSD validation in validate_final_document!.
+    validates_length_of :street_name,          maximum: 140
+    validates_length_of :building_number,      maximum: 16
+    validates_length_of :post_code,            maximum: 16
+    validates_length_of :town_name,            maximum: 140
+    validates_length_of :country_code,         is: 2
+    validates_length_of :address_line1,        maximum: 70
+    validates_length_of :address_line2,        maximum: 70
+    validates_length_of :department,           maximum: 70,  allow_nil: true
+    validates_length_of :sub_department,       maximum: 70,  allow_nil: true
+    validates_length_of :building_name,        maximum: 140, allow_nil: true
+    validates_length_of :floor,                maximum: 70,  allow_nil: true
+    validates_length_of :post_box,             maximum: 16,  allow_nil: true
+    validates_length_of :room,                 maximum: 70,  allow_nil: true
+    validates_length_of :town_location_name,   maximum: 140, allow_nil: true
+    validates_length_of :district_name,        maximum: 140, allow_nil: true
+    validates_length_of :country_sub_division, maximum: 35,  allow_nil: true
+    validates_length_of :care_of,              maximum: 140, allow_nil: true
+    validates_length_of :unit_number,          maximum: 16,  allow_nil: true
+  end
+end

data/lib/sepa_rator/account/contact_details.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SEPA
+  class ContactDetails
+    include ActiveModel::Validations
+    include AttributeInitializer
+    extend Converter
+
+    NAME_PREFIXES = %w[DOCT MADM MISS MIST MIKS].freeze
+    PREFERRED_METHODS = %w[LETT MAIL PHON FAXX CELL ONLI].freeze
+
+    # Common fields (ContactDetails2, all schemas)
+    attr_accessor :name_prefix,
+                  :name,
+                  :phone_number,
+                  :mobile_number,
+                  :fax_number,
+                  :email_address,
+                  # Contact4 fields (v09+, XSD rejects for v03)
+                  :email_purpose,
+                  :job_title,
+                  :responsibility,
+                  :department,
+                  # Contact13 fields (v13 only, XSD rejects for v03/v09)
+                  :url_address,
+                  # Complex/enum fields handled separately in XML builder
+                  :other_contacts,   # Array<{channel_type:, id:}> (OtherContact1, v09/v13)
+                  :preferred_method  # PreferredContactMethod1Code/2Code (v09/v13)
+
+    convert :name, :phone_number, :mobile_number, :fax_number,
+            :email_purpose, :job_title, :responsibility, :department, to: :text
+
+    # Superset lengths (most permissive schema).
+    # Stricter per-schema limits are enforced by XSD validation in validate_final_document!.
+    validates_inclusion_of :name_prefix, in: NAME_PREFIXES, allow_nil: true
+    validates_length_of :name, maximum: 140, allow_nil: true
+    validates_length_of :phone_number, maximum: 30, allow_nil: true
+    validates_length_of :mobile_number, maximum: 30, allow_nil: true
+    validates_length_of :fax_number, maximum: 30, allow_nil: true
+    validates_length_of :url_address, maximum: 2048, allow_nil: true
+    validates_length_of :email_address, maximum: 2048, allow_nil: true
+    validates_length_of :email_purpose, maximum: 35, allow_nil: true
+    validates_length_of :job_title, maximum: 35, allow_nil: true
+    validates_length_of :responsibility, maximum: 35, allow_nil: true
+    validates_length_of :department, maximum: 70, allow_nil: true
+    validates_inclusion_of :preferred_method, in: PREFERRED_METHODS, allow_nil: true
+
+    validate :validate_other_contacts
+
+    private
+
+    def validate_other_contacts
+      return unless other_contacts
+
+      unless other_contacts.is_a?(Array)
+        errors.add(:other_contacts, 'must be an Array')
+        return
+      end
+
+      other_contacts.each_with_index do |contact, i|
+        unless contact.is_a?(Hash) && contact[:channel_type]
+          errors.add(:other_contacts, "entry #{i} must have :channel_type")
+          next
+        end
+        errors.add(:other_contacts, "entry #{i} channel_type exceeds 4 characters") if contact[:channel_type].to_s.length > 4
+        errors.add(:other_contacts, "entry #{i} id exceeds 128 characters") if contact[:id] && contact[:id].to_s.length > 128
+      end
+    end
+  end
+end

data/lib/sepa_rator/account/creditor_account.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SEPA
+  class CreditorAccount < Account
+    attr_accessor :creditor_identifier, :initiating_party_lei, :initiating_party_bic
+
+    validates_with CreditorIdentifierValidator, message: 'is invalid'
+    validates_with LEIValidator, field_name: :initiating_party_lei, message: 'is invalid'
+    validates_with BICValidator, field_name: :initiating_party_bic, message: 'is invalid'
+
+    def initiating_party_id(builder, schema_name)
+      build_organisation_id(builder, creditor_identifier, schema_name,
+                            lei: initiating_party_lei, org_bic: initiating_party_bic)
+    end
+  end
+end

data/lib/sepa_rator/account/creditor_address.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SEPA
+  class CreditorAddress < Address; end
+end

data/lib/sepa_rator/account/debtor_account.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SEPA
+  class DebtorAccount < Account
+    attr_accessor :initiating_party_identifier, :initiating_party_lei, :initiating_party_bic
+
+    convert :initiating_party_identifier, to: :text
+    # Max256Text (v13 GenericOrganisationIdentification3); stricter v03/v09 limits enforced by XSD
+    validates_length_of :initiating_party_identifier, within: 1..256, allow_nil: true
+    validates_with LEIValidator, field_name: :initiating_party_lei, message: 'is invalid'
+    validates_with BICValidator, field_name: :initiating_party_bic, message: 'is invalid'
+
+    def initiating_party_id(builder, schema_name)
+      return unless initiating_party_identifier || initiating_party_bic || initiating_party_lei
+
+      build_organisation_id(builder, initiating_party_identifier, schema_name,
+                            lei: initiating_party_lei, org_bic: initiating_party_bic)
+    end
+  end
+end

data/lib/sepa_rator/account/debtor_address.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SEPA
+  class DebtorAddress < Address; end
+end

data/lib/sepa_rator/account.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SEPA
+  class Account
+    include ActiveModel::Validations
+    include AttributeInitializer
+    extend Converter
+
+    attr_accessor :name, :iban, :bic, :address, :agent_lei, :contact_details
+
+    convert :name, to: :text
+
+    validates_length_of :name, within: 1..70
+    validates_with BICValidator, IBANValidator, message: 'is invalid'
+    validates_with LEIValidator, field_name: :agent_lei, message: 'is invalid'
+
+    validate do |record|
+      next unless record.address
+
+      unless record.address.valid?
+        record.address.errors.each do |error|
+          record.errors.add(:address, error.full_message)
+        end
+      end
+    end
+
+    validate do |record|
+      next unless record.contact_details
+
+      unless record.contact_details.valid?
+        record.contact_details.errors.each do |error|
+          record.errors.add(:contact_details, error.full_message)
+        end
+      end
+    end
+
+    def initiating_party_id(builder, schema_name); end
+
+    protected
+
+    # Builds Id > OrgId block. XSD sequence: BICOrBEI/AnyBIC → LEI → Othr
+    def build_organisation_id(builder, identifier, schema_name, **options)
+      builder.Id do
+        builder.OrgId do
+          build_org_bic_and_lei(builder, schema_name, options)
+          if identifier
+            builder.Othr do
+              builder.Id(identifier)
+              builder.SchmeNm { builder.Prtry(options[:scheme]) } if options[:scheme]
+            end
+          end
+        end
+      end
+    end
+
+    def build_org_bic_and_lei(builder, schema_name, options)
+      if options[:org_bic]
+        bic_tag = SCHEMA_FEATURES[schema_name][:org_bic_tag]
+        builder.__send__(bic_tag, options[:org_bic])
+      end
+      builder.LEI(options[:lei]) if options[:lei] && LEI_SCHEMAS.include?(schema_name)
+    end
+  end
+end

data/lib/sepa_rator/concerns/attribute_initializer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module SEPA
+  module AttributeInitializer
+    def self.included(base)
+      base.include ActiveModel::AttributeAssignment
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def permitted_attributes
+        @permitted_attributes ||= begin
+          own_setters = instance_methods(false)
+                        .select { |m| m.to_s.end_with?('=') }
+                        .to_set { |m| m.to_s.chomp('=') }
+
+          if superclass.respond_to?(:permitted_attributes)
+            own_setters | superclass.permitted_attributes
+          else
+            own_setters
+          end
+        end.freeze
+      end
+    end
+
+    def initialize(attributes = {})
+      assign_attributes(attributes)
+    rescue ActiveModel::UnknownAttributeError => e
+      raise ArgumentError, "Unknown attribute: #{e.attribute}"
+    end
+
+    private
+
+    def _assign_attribute(key, value)
+      raise ArgumentError, "Unknown attribute: #{key}" unless self.class.permitted_attributes.include?(key.to_s)
+
+      public_send("#{key}=", value)
+    end
+  end
+end

data/lib/sepa_rator/concerns/regulatory_reporting_validator.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SEPA
+  # Extracted validation logic for regulatory reporting fields on CreditTransferTransaction.
+  # Keeps the transaction class under the Metrics/ClassLength limit.
+  module RegulatoryReportingValidator
+    REGULATORY_INDICATORS = %w[CRED DEBT BOTH].freeze
+    COUNTRY_CODE_REGEX = /\A[A-Z]{2}\z/
+    CURRENCY_CODE_REGEX = /\A[A-Z]{3}\z/
+
+    private
+
+    def validate_regulatory_reportings
+      return unless regulatory_reportings
+
+      unless regulatory_reportings.is_a?(Array)
+        errors.add(:regulatory_reportings, 'must be an Array')
+        return
+      end
+
+      errors.add(:regulatory_reportings, 'maximum 10 entries') if regulatory_reportings.length > 10
+
+      regulatory_reportings.each_with_index do |reporting, i|
+        unless reporting.is_a?(Hash)
+          errors.add(:regulatory_reportings, "entry #{i} must be a Hash")
+          next
+        end
+        if reporting[:indicator] && !REGULATORY_INDICATORS.include?(reporting[:indicator])
+          errors.add(:regulatory_reportings, "entry #{i} indicator must be one of #{REGULATORY_INDICATORS.join(', ')}")
+        end
+        validate_regulatory_reporting_details(reporting, i)
+      end
+    end
+
+    def validate_regulatory_reporting_details(reporting, entry_index)
+      validate_regulatory_authority(reporting[:authority], entry_index)
+      return unless reporting[:details]
+
+      unless reporting[:details].is_a?(Array)
+        errors.add(:regulatory_reportings, "entry #{entry_index} details must be an Array")
+        return
+      end
+
+      reporting[:details].each_with_index do |detail, j|
+        unless detail.is_a?(Hash)
+          errors.add(:regulatory_reportings, "entry #{entry_index} detail #{j} must be a Hash")
+          next
+        end
+        validate_regulatory_detail(detail, entry_index, j)
+      end
+    end
+
+    def validate_regulatory_authority(authority, entry_index)
+      return unless authority
+
+      unless authority.is_a?(Hash)
+        errors.add(:regulatory_reportings, "entry #{entry_index} authority must be a Hash")
+        return
+      end
+      validate_authority_name(authority[:name], entry_index)
+      validate_country_code(authority[:country], "entry #{entry_index} authority country")
+    end
+
+    def validate_authority_name(name, entry_index)
+      return unless name && name.to_s.length > 140
+
+      errors.add(:regulatory_reportings, "entry #{entry_index} authority name exceeds 140 characters")
+    end
+
+    def validate_regulatory_detail(detail, entry_idx, detail_idx)
+      prefix = "entry #{entry_idx} detail #{detail_idx}"
+      validate_regulatory_detail_text_fields(detail, prefix)
+      validate_regulatory_detail_typed_fields(detail, prefix)
+      validate_regulatory_detail_amount(detail[:amount], prefix)
+      Array(detail[:information]).each_with_index do |inf, idx|
+        errors.add(:regulatory_reportings, "#{prefix} information #{idx} exceeds 35 characters") if inf.to_s.length > 35
+      end
+    end
+
+    def validate_regulatory_detail_text_fields(detail, prefix)
+      errors.add(:regulatory_reportings, "#{prefix} code too long") if detail[:code] && detail[:code].to_s.length > 10
+      errors.add(:regulatory_reportings, "#{prefix} type too long") if detail[:type] && detail[:type].to_s.length > 35
+      errors.add(:regulatory_reportings, "#{prefix} type_proprietary too long") if detail[:type_proprietary] && detail[:type_proprietary].to_s.length > 35
+    end
+
+    def validate_regulatory_detail_typed_fields(detail, prefix)
+      errors.add(:regulatory_reportings, "#{prefix} type and type_proprietary are mutually exclusive") if detail[:type] && detail[:type_proprietary]
+      errors.add(:regulatory_reportings, "#{prefix} date must be a Date") if detail[:date] && !detail[:date].is_a?(Date)
+      validate_country_code(detail[:country], "#{prefix} country")
+    end
+
+    def validate_regulatory_detail_amount(amount, prefix)
+      return unless amount
+
+      unless amount.is_a?(Hash) && amount[:value] && amount[:currency]
+        errors.add(:regulatory_reportings, "#{prefix} amount must have :value and :currency")
+        return
+      end
+      unless amount[:value].is_a?(Integer) || amount[:value].is_a?(Float) || amount[:value].is_a?(BigDecimal)
+        errors.add(:regulatory_reportings, "#{prefix} amount value must be numeric")
+      end
+      errors.add(:regulatory_reportings, "#{prefix} amount currency invalid") unless amount[:currency].to_s.match?(CURRENCY_CODE_REGEX)
+    end
+
+    def validate_country_code(value, field_label)
+      return unless value && !value.to_s.match?(COUNTRY_CODE_REGEX)
+
+      errors.add(:regulatory_reportings, "#{field_label} must be a 2-letter code")
+    end
+  end
+end

data/lib/sepa_rator/concerns/schema_validation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SEPA
+  module SchemaValidation
+    SCHEMA_DIR = File.expand_path('../../schema', __dir__).freeze
+    SCHEMA_CACHE_MUTEX = Mutex.new
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def schema_cache
+        @schema_cache ||= {}
+      end
+    end
+
+    private
+
+    def validate_final_document!(document, schema_name)
+      raise ArgumentError, "Unknown schema: #{schema_name}" unless SCHEMA_FEATURES.key?(schema_name)
+
+      xsd = self.class.schema_cache[schema_name]
+      unless xsd
+        SCHEMA_CACHE_MUTEX.synchronize do
+          xsd = self.class.schema_cache[schema_name] ||=
+            Nokogiri::XML::Schema(File.read("#{SCHEMA_DIR}/#{schema_name}.xsd"))
+        end
+      end
+
+      validation_errors = xsd.validate(document)
+      return if validation_errors.empty?
+
+      sanitized = validation_errors.map { |e| e.message.gsub(/'[^']{20,}'/, "'[REDACTED]'") }
+      raise SEPA::SchemaValidationError.new(
+        "Incompatible with schema #{schema_name}: #{sanitized.join(', ')}",
+        validation_errors.map(&:message)
+      )
+    end
+  end
+end

data/lib/sepa_rator/concerns/xml_builder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SEPA
+  module XmlBuilder
+    private
+
+    def build_postal_address(builder, address)
+      builder.PstlAdr do
+        POSTAL_ADDRESS_FIELDS.each do |xml_tag, attr|
+          value = address.public_send(attr)
+          builder.__send__(xml_tag, value) if value
+        end
+      end
+    end
+
+    def build_agent_bic(builder, bic, schema_name, fallback: true, lei: nil)
+      lei_emitted = lei && LEI_SCHEMAS.include?(schema_name)
+
+      builder.FinInstnId do
+        # XSD sequence: BICFI/BIC → ClrSysMmbId → LEI → Nm → PstlAdr → Othr
+        builder.__send__(schema_features(schema_name)[:bic_tag], bic) if bic
+        builder.LEI(lei) if lei_emitted
+        if !bic && !lei_emitted && fallback
+          builder.Othr do
+            builder.Id('NOTPROVIDED')
+          end
+        end
+      end
+    end
+
+    def build_remittance_information(builder, transaction)
+      has_structured = transaction.structured_remittance_information || transaction.additional_remittance_information
+      return unless transaction.remittance_information || has_structured
+
+      builder.RmtInf do
+        if has_structured
+          builder.Strd do
+            build_creditor_reference_information(builder, transaction) if transaction.structured_remittance_information
+            Array(transaction.additional_remittance_information).each { |info| builder.AddtlRmtInf(info) }
+          end
+        else
+          builder.Ustrd(transaction.remittance_information)
+        end
+      end
+    end
+
+    def build_creditor_reference_information(builder, transaction)
+      builder.CdtrRefInf do
+        ref_type = transaction.structured_remittance_reference_type || 'SCOR'
+        builder.Tp do
+          builder.CdOrPrtry { builder.Cd(ref_type) }
+          builder.Issr(transaction.structured_remittance_issuer) if transaction.structured_remittance_issuer
+        end
+        builder.Ref(transaction.structured_remittance_information)
+      end
+    end
+
+    def build_contact_details(builder, contact_details)
+      return unless contact_details
+
+      builder.CtctDtls do
+        CONTACT_DETAILS_FIELDS.each do |xml_tag, attr|
+          value = contact_details.public_send(attr)
+          builder.__send__(xml_tag, value) if value
+        end
+        contact_details.other_contacts&.each do |contact|
+          builder.Othr do
+            builder.ChanlTp(contact[:channel_type])
+            builder.Id(contact[:id]) if contact[:id]
+          end
+        end
+        builder.PrefrdMtd(contact_details.preferred_method) if contact_details.preferred_method
+      end
+    end
+
+    def build_ultimate_party(builder, tag, name, contact_details: nil)
+      return unless name
+
+      builder.__send__(tag) do
+        builder.Nm(name)
+        build_contact_details(builder, contact_details)
+      end
+    end
+
+    def build_purpose(builder, purpose_code)
+      return unless purpose_code
+
+      builder.Purp { builder.Cd(purpose_code) }
+    end
+
+    def build_payment_identification(builder, transaction)
+      builder.PmtId do
+        builder.InstrId(transaction.instruction) if transaction.instruction && !transaction.instruction.empty?
+        builder.EndToEndId(transaction.reference)
+        builder.UETR(transaction.uetr) if transaction.uetr && !transaction.uetr.empty?
+      end
+    end
+
+    def build_iban_account(builder, tag, iban)
+      builder.__send__(tag) do
+        builder.Id do
+          builder.IBAN(iban)
+        end
+      end
+    end
+
+    def format_amount(value)
+      format('%.2f', value)
+    end
+  end
+end

data/lib/sepa_rator/converter.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SEPA
+  module Converter
+    def convert(*attributes, options)
+      include InstanceMethods
+
+      method_name = "convert_#{options[:to]}"
+      raise ArgumentError, "Converter '#{options[:to]}' does not exist!" unless InstanceMethods.method_defined?(method_name)
+
+      attributes.each do |attribute|
+        define_method "#{attribute}=" do |value|
+          instance_variable_set("@#{attribute}", public_send(method_name, value))
+        end
+      end
+    end
+
+    module InstanceMethods
+      def convert_text(value)
+        return unless value
+
+        # Replace special characters (EPC Best Practices, Chapter 6.2)
+        # http://www.europeanpaymentscouncil.eu/index.cfm/knowledge-bank/epc-documents/sepa-requirements-for-an-extended-character-set-unicode-subset-best-practices/
+        value.to_s
+             .encode('UTF-8', invalid: :replace, undef: :replace, replace: '?')
+             .tr('€', 'E')
+             .gsub('@', '(at)')
+             .tr('_', '-')
+             .tr('&', '+')
+             .gsub(/\n+/, ' ')
+             .gsub(%r{[^a-zA-Z0-9\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u024F ':?,\-(+.)/]}, '')
+             .strip
+      end
+
+      def convert_decimal(value)
+        return unless value
+
+        value = BigDecimal(value.to_s, exception: false)
+
+        return unless value&.finite? && value.positive?
+
+        value.round(2)
+      end
+    end
+  end
+end

data/lib/sepa_rator/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SEPA
+  class Error < RuntimeError; end
+  class ValidationError < Error; end
+
+  class SchemaValidationError < Error
+    attr_reader :validation_errors
+
+    def initialize(message, validation_errors = [])
+      @validation_errors = validation_errors
+      super(message)
+    end
+  end
+end