brot 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf6f5e4155bf59cb2cc724e9ea723bb066d5c95e745e687b66e36ad4d058d81f
-  data.tar.gz: 931cfa4d40375498939bdec52b97b9f63987e16e9efa825aec351987f7b97d6e
+  metadata.gz: 11ae2c0176f01320f17c5755596448f27c35b258c911ade2f6e4f4fba2096273
+  data.tar.gz: b985c0fdb460926d4c30c26c9c47f1815a061545ae1fac068f8d6584bd0c1fdd
 SHA512:
-  metadata.gz: 46155574730e67a42bba7c1a815f1be3dcec94c2fda775a66b646b6237b6f51ee83f1d15907a4d4ed503ef9d0195316a42891d64acaa7326b83b1cca542651e5
-  data.tar.gz: 9e5c22fdb7710f461e28639032e8534c8aafed98c77943e8ba4c27460cda071db18a0bdb10b0f1f11036cd44e117d1acea521762fac85e3c7971a06fd78beaf7
+  metadata.gz: ab2e95235f9d24a157076fee29ceb68499c845a43d4517c0f3a6ef2dbc0f233d7c7f4990ba443487c6d5b8e1c4a0cc00ad12415455d11c60fe6d197306ca0f53
+  data.tar.gz: 3664f7b067f59f1c62a7013e117b8521560e169cda40b3713eaba6178bd3e951dd178f3e6216621b38f4e984fab7ceddbc99b49a49f31b20fcff83cd98abe441

data/.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ruby/setup-ruby@v1
         with:

data/.github/workflows/release.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ruby/setup-ruby@v1
         with:
@@ -33,7 +33,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - uses: ruby/setup-ruby@v1
         with:

data/.rubocop.yml

@@ -7,3 +7,8 @@ AllCops:
   SuggestExtensions: false
   TargetRubyVersion: 4.0
 
+Metrics/ClassLength:
+  Max: 120
+
+Metrics/ModuleLength:
+  Max: 150

data/README.md

@@ -1,73 +1,63 @@
 # brot
 
-`brot` builds ISO 20022 SEPA credit transfer XML for DATEV-style uploads with
+`brot` builds ISO 20022 credit transfer XML for DATEV-style uploads with
 `Nokogiri::XML::Builder`.
 
-The gem emits `pain.001.001.12` and is designed to validate directly against
-the provided `pain.001.001.12.xsd`.
+The gem supports these bundled schema targets:
 
-## Installation
+- `pain.001.001.03`
+- `pain.001.001.12`
 
-```ruby
-gem 'brot'
-```
+Use `Brot::PainVersion::PAIN_001_001_03` or
+`Brot::PainVersion::PAIN_001_001_12` instead of raw symbols when selecting the
+output format.
 
-## What The Gem Does
+The public API is intentionally narrow and DATEV-oriented. It models one
+debtor, one payment information block, one or more transfers, and unstructured
+remittance information.
 
-`brot` is intentionally focused on one narrow job:
+## DATEV Compatibility
 
-- Generate `pain.001.001.12` customer credit transfer files.
-- Build XML with `Nokogiri::XML::Builder`.
-- Validate generated XML against the bundled `pain.001.001.12.xsd`.
-- Stay close to the DATEV upload use case instead of exposing the full ISO
-  20022 surface area.
+Current DATEV compatibility and announced migration path are narrower than the
+gem's bundled schema support:
 
-Current assumptions baked into the serializer:
+- As of March 13, 2026, use `pain.001.001.03` for DATEV uploads.
+- DATEV states that SEPA version 3.7 becomes mandatory in November 2026.
+- Bundesbank maps SEPA version 3.6 to `pain.001.001.03` and SEPA version 3.7
+  to `pain.001.001.09`.
+- `pain.001.001.09` is not implemented in this gem yet.
+- `pain.001.001.12` remains available as a generic ISO 20022 output format,
+  but it should not be treated as a current DATEV upload target.
 
-- Service level is always `SEPA`.
-- Payment method is always `TRF`.
-- Charge bearer is always `SLEV`.
-- Instructed amount is always emitted as `EUR`.
-- A debtor BIC or creditor BIC is optional. If absent, the XML uses the
-  fallback financial institution identifier `NOTPROVIDED`.
+## Official References
 
-## Scope And Gaps
-
-`brot` is intentionally a DATEV-oriented subset of `pain.001.001.12`, not a
-full abstraction over every branch allowed by the ISO 20022 schema.
-
-What is currently supported:
-
-- SEPA credit transfers
-- One debtor per document
-- One payment information block (`PmtInf`) per document
-- One or more credit transfer entries (`CdtTrfTxInf`)
-- Debtor and creditor names
-- Debtor and creditor IBANs
-- Optional debtor and creditor BICs
-- End-to-end IDs
-- Optional instruction IDs
-- Optional purpose codes
-- Unstructured remittance information (`RmtInf/Ustrd`)
-- Validation against the bundled `pain.001.001.12.xsd`
+For authoritative field semantics and message context, use these primary
+sources:
 
-What is not modeled yet, even though the schema allows it:
+- ISO 20022 message catalogue for current `pain.001` definitions, including
+  `pain.001.001.12`:
+  https://www.iso20022.org/iso-20022-message-definitions
+- ISO 20022 message archive for older definitions, including
+  `pain.001.001.03`:
+  https://www.iso20022.org/catalogue-messages/iso-20022-messages-archive?search=pain
+- DATEV note on SEPA version 3.7 becoming mandatory in November 2026:
+  https://www.datev.de/web/de/mydatev/datev-magazin/fuer-selbstbucher/neu-sepa-version-3-7/
+- Deutsche Bundesbank format overview mapping SEPA versions to
+  `pain.001.001.03` and `pain.001.001.09`:
+  https://www.bundesbank.de/de/aufgaben/unbarer-zahlungsverkehr/serviceangebot/xml-formate-im-zv-613692
+- European Payments Council SCT rulebook and implementation-guideline entry
+  point for SEPA-specific usage constraints and terminology:
+  https://www.europeanpaymentscouncil.eu/what-we-do/epc-payment-schemes/sepa-credit-transfer/sepa-credit-transfer-rulebook-and
 
-- Structured remittance information
-- Postal addresses and richer party identification data
-- Ultimate debtor and ultimate creditor
-- Multiple `PmtInf` sections in one document
-- Non-SEPA service levels or non-EUR transfer setups
-- Local instrument and category purpose variants beyond the current subset
-- Intermediary agents and extra account layers
-- Regulatory reporting, tax, cheque, and supplementary data sections
+These external documents describe the full ISO 20022 or EPC meaning of many
+fields. `brot` intentionally implements only the narrower subset documented in
+this README.
 
-The practical meaning is:
+## Installation
 
-- The gem aims to produce a clean DATEV-style payment initiation file for the
-  supported SEPA use case.
-- The gem does not yet try to represent the entire `pain.001.001.12` standard
-  as a generic Ruby object model.
+```ruby
+gem 'brot'
+```
 
 ## Quick Start
 
@@ -75,8 +65,9 @@ The practical meaning is:
 require 'brot'
 require 'date'
 
-transfer = Brot::Pain00100112::Transfer.new(
+transfer = Brot::Transfer.new(
   amount: '1250.50',
+  currency: 'EUR',
   creditor_name: 'Example Supplier GmbH',
   creditor_iban: 'DE89370400440532013000',
   creditor_bic: 'COBADEFFXXX',
@@ -85,7 +76,7 @@ transfer = Brot::Pain00100112::Transfer.new(
   instruction_id: 'PAY-0001'
 )
 
-document = Brot::Pain00100112::Document.new(
+document = Brot::Document.new(
   message_id: 'MSG-20260313-01',
   payment_information_id: 'PMT-20260313-01',
   initiating_party_name: 'Example Debtor GmbH',
@@ -94,7 +85,7 @@ document = Brot::Pain00100112::Document.new(
   debtor_bic: 'INGDDEFFXXX',
   requested_execution_date: Date.new(2026, 3, 13),
   transfers: [transfer],
-  batch_booking: true
+  version: Brot::PainVersion::PAIN_001_001_03
 )
 
 xml = document.to_xml
@@ -103,61 +94,103 @@ result = document.validate
 raise result.errors.join("\n") unless result.valid?
 ```
 
+If you omit `version:`, the document defaults to
+`Brot::PainVersion::PAIN_001_001_03`.
+Call `document.validate!` if you prefer a raised `Brot::ValidationError`.
+
+For current DATEV uploads, stick to
+`Brot::PainVersion::PAIN_001_001_03`.
+
+## Supported Subset
+
+Current assumptions baked into the serializer:
+
+- Service level is always `SEPA`.
+- Payment method is always `TRF`.
+- Charge bearer is always `SLEV`.
+- One debtor and one `PmtInf` block are emitted per document.
+- Remittance information is emitted as unstructured text only.
+- If a debtor BIC or creditor BIC is absent, the XML falls back to
+  `NOTPROVIDED`.
+
+Currency support:
+
+- `Brot::Transfer` accepts `currency:` and defaults it to `EUR`.
+- The bundled `pain.001.001.03` and `pain.001.001.12` schemas both emit the
+  supplied transfer currency and support mixed-currency documents.
+- DATEV-specific acceptance is governed by DATEV's supported schema versions,
+  not by the gem alone.
+
+Supported input data:
+
+- Debtor and creditor names
+- Debtor and creditor IBANs
+- Optional debtor and creditor BICs
+- End-to-end IDs
+- Optional instruction IDs
+- Optional purpose codes
+- Optional transfer currencies, defaulting to `EUR`
+- Unstructured remittance information
+- Validation against bundled XSDs for both supported versions
+
+Not modeled:
+
+- Structured remittance information
+- Postal addresses and richer party identification
+- Ultimate debtor and ultimate creditor
+- Multiple `PmtInf` sections in one document
+- Non-SEPA service levels
+- Broader ISO 20022 branches outside the current DATEV-oriented subset
+
 ## Public API
 
 The main public classes are:
 
-- `Brot::Pain00100112::Account`
-- `Brot::Pain00100112::Transfer`
-- `Brot::Pain00100112::Document`
-- `Brot::Pain00100112::Schema`
-- `Brot::Pain00100112::Schema::Result`
+- `Brot::Account`
+- `Brot::Transfer`
+- `Brot::Document`
+- `Brot::Schema`
+- `Brot::PainVersion`
+- `Brot::Schema::Result`
 
-### `Brot::Pain00100112::Account`
+### `Brot::Account`
 
-Use `Account` when you want a standalone object representing debtor or creditor
-banking details. You do not need to instantiate it manually for normal usage,
-because `Document` and `Transfer` build accounts from `*_iban` and `*_bic`
-attributes internally.
+Use `Brot::Account` for standalone debtor or creditor banking details when you
+need it directly. Most callers do not instantiate it manually because
+`Brot::Document` and `Brot::Transfer` build accounts from `*_iban` and `*_bic`
+arguments.
 
 Example:
 
 ```ruby
-account = Brot::Pain00100112::Account.new(
+account = Brot::Account.new(
   iban: 'DE89370400440532013000',
   bic: 'COBADEFFXXX'
 )
-
-account.iban
-# => "DE89370400440532013000"
-
-account.bic
-# => "COBADEFFXXX"
 ```
 
 Attributes:
 
 - `iban`
-  Example: `DE89370400440532013000`
-  Must be a syntactically valid IBAN. Spaces are removed automatically.
+  Validated IBAN with spaces removed.
 - `bic`
-  Example: `COBADEFFXXX`
-  Optional. If omitted, the serializer falls back to `NOTPROVIDED` in the XML.
+  Optional validated BIC.
 
-Useful methods:
+Method:
 
 - `bic_or_placeholder`
-  Returns the actual BIC if present, otherwise `NOTPROVIDED`.
+  Returns the BIC if present, otherwise `NOTPROVIDED`.
 
-### `Brot::Pain00100112::Transfer`
+### `Brot::Transfer`
 
-Use `Transfer` for each outgoing credit transfer inside the payment batch.
+Use `Brot::Transfer` for each outgoing credit transfer inside the batch.
 
 Example:
 
 ```ruby
-transfer = Brot::Pain00100112::Transfer.new(
+transfer = Brot::Transfer.new(
   amount: '1250.50',
+  currency: 'USD',
   creditor_name: 'Example Supplier GmbH',
   creditor_iban: 'DE89370400440532013000',
   creditor_bic: 'COBADEFFXXX',
@@ -171,254 +204,121 @@ transfer = Brot::Pain00100112::Transfer.new(
 Initialization attributes:
 
 - `amount`
-  Example: `'1250.50'`
-  Required. Must be positive and have at most two decimal places.
+  Required. Positive, maximum two decimal places.
 - `creditor_name`
-  Example: `'Example Supplier GmbH'`
-  Required. Maximum length is 70 characters in this implementation.
+  Required. Maximum 70 characters.
 - `creditor_iban`
-  Example: `'DE89370400440532013000'`
   Required. Validated as an IBAN.
 - `creditor_bic`
-  Example: `'COBADEFFXXX'`
   Optional. Validated as a BIC if supplied.
+- `currency`
+  Optional. Three-letter ISO-style currency code. Defaults to `EUR`.
 - `end_to_end_id`
-  Example: `'INV-2026-0001'`
-  Required. Maximum length is 35 characters.
-- `remittance_information`
-  Example: `'Invoice 2026-0001'`
-  Required. Maximum length is 140 characters.
-- `instruction_id`
-  Example: `'PAY-0001'`
-  Optional. Maximum length is 35 characters.
-- `purpose_code`
-  Example: `'SUPP'`
-  Optional. Maximum length is 4 characters.
-
-Readable attributes after initialization:
-
-- `amount`
-- `creditor_name`
-- `creditor_account`
-- `end_to_end_id`
+  Required. Maximum 35 characters.
 - `remittance_information`
+  Required. Maximum 140 characters.
 - `instruction_id`
+  Optional. Maximum 35 characters.
 - `purpose_code`
+  Optional. Maximum 4 characters.
 
-### `Brot::Pain00100112::Document`
+### `Brot::Document`
 
-Use `Document` to represent the full payment file. This is the main entry
-point of the gem.
+Use `Brot::Document` for the full payment file.
 
-Example:
+Example using generic `.12` output:
 
 ```ruby
-document = Brot::Pain00100112::Document.new(
+document = Brot::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',
-  debtor_bic: 'INGDDEFFXXX',
   requested_execution_date: Date.new(2026, 3, 13),
   transfers: [transfer],
-  batch_booking: true,
-  created_at: Time.utc(2026, 3, 13, 12, 0, 0)
+  version: Brot::PainVersion::PAIN_001_001_12
 )
 ```
 
 Initialization attributes:
 
 - `message_id`
-  Example: `'MSG-20260313-01'`
-  Required. Group header message identifier. Maximum length is 35 characters.
+  Required. Maximum 35 characters.
 - `payment_information_id`
-  Example: `'PMT-20260313-01'`
-  Required. Payment information block identifier. Maximum length is 35
-  characters.
+  Required. Maximum 35 characters.
 - `initiating_party_name`
-  Example: `'Example Debtor GmbH'`
-  Required. Maximum length is 70 characters.
+  Required. Maximum 70 characters.
 - `debtor_name`
-  Example: `'Example Debtor GmbH'`
-  Required. Maximum length is 70 characters.
+  Required. Maximum 70 characters.
 - `debtor_iban`
-  Example: `'DE12500105170648489890'`
   Required. Validated as an IBAN.
 - `debtor_bic`
-  Example: `'INGDDEFFXXX'`
   Optional. Validated as a BIC if supplied.
 - `requested_execution_date`
-  Example: `Date.new(2026, 3, 13)` or `'2026-03-13'`
-  Required. Date only.
+  Required. `Date` or ISO 8601 date string.
 - `transfers`
-  Example: `[transfer_1, transfer_2]`
-  Required. Must contain at least one `Brot::Pain00100112::Transfer`.
+  Required. Must contain at least one `Brot::Transfer`.
 - `batch_booking`
-  Example: `true`
   Optional. Defaults to `true`.
 - `created_at`
-  Example: `Time.utc(2026, 3, 13, 12, 0, 0)`
-  Optional. Defaults to the current UTC time.
-
-Readable attributes after initialization:
-
-- `message_id`
-- `payment_information_id`
-- `initiating_party_name`
-- `debtor_name`
-- `debtor_account`
-- `requested_execution_date`
-- `transfers`
-- `batch_booking`
-- `created_at`
+  Optional. Defaults to current UTC time.
+- `version`
+  Optional. Defaults to `Brot::PainVersion::PAIN_001_001_03`.
+  Supported values are `Brot::PainVersion::PAIN_001_001_03` and
+  `Brot::PainVersion::PAIN_001_001_12`.
 
 Useful methods:
 
-- `to_xml(pretty: true)`
-  Serializes the document to `pain.001.001.12` XML.
-- `validate(xsd_path: Brot::Pain00100112::Schema.bundled_xsd_path)`
-  Validates the generated XML and returns a `Schema::Result`.
 - `control_sum`
-  Returns the sum of all transfer amounts as a `BigDecimal`.
 - `number_of_transactions`
-  Returns the number of transfers.
-
-### `Brot::Pain00100112::Schema`
-
-Use `Schema` when you want to validate XML directly without first building a
-`Document` object.
-
-Example:
-
-```ruby
-xml = document.to_xml(pretty: false)
-result = Brot::Pain00100112::Schema.validate(xml)
+- `to_xml(pretty: true)`
+- `validate(xsd_path: nil)`
+- `validate!(xsd_path: nil)`
 
-raise result.errors.join("\n") unless result.valid?
-```
+Version-specific output differences:
 
-Available methods:
+- `pain.001.001.03` uses namespace
+  `urn:iso:std:iso:20022:tech:xsd:pain.001.001.03`
+- `pain.001.001.12` uses namespace
+  `urn:iso:std:iso:20022:tech:xsd:pain.001.001.12`
+- `.03` writes `BIC` and plain `ReqdExctnDt`
+- `.12` writes `BICFI` and `ReqdExctnDt/Dt`
+- For DATEV compatibility today, prefer `.03`
 
-- `bundled_xsd_path`
-  Returns the absolute path of the XSD bundled inside the gem.
-- `validate(xml, xsd_path: bundled_xsd_path)`
-  Validates an XML string against the bundled schema by default.
+### `Brot::Schema`
 
-### `Brot::Pain00100112::Schema::Result`
+Use `Brot::Schema` when you want to validate XML directly.
 
-`Schema.validate` and `Document#validate` both return a
-`Brot::Pain00100112::Schema::Result`.
-
-Example:
+Examples:
 
 ```ruby
-result = document.validate
-
+result = Brot::Schema.validate(xml)
 result.valid?
-# => true
-
-result.errors
-# => []
 ```
 
-Attributes and methods:
-
-- `errors`
-  An array of schema validation error messages.
-- `valid?`
-  Returns `true` when `errors` is empty.
-
-## End-To-End Example
-
-This example shows the normal workflow from transfers to XML generation and
-validation:
-
 ```ruby
-require 'brot'
-require 'date'
-
-transfers = [
-  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'
-  ),
-  Brot::Pain00100112::Transfer.new(
-    amount: '349.99',
-    creditor_name: 'Another Supplier GmbH',
-    creditor_iban: 'DE44500105175407324931',
-    end_to_end_id: 'INV-2026-0002',
-    remittance_information: 'Invoice 2026-0002'
-  )
-]
-
-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',
-  debtor_bic: 'INGDDEFFXXX',
-  requested_execution_date: Date.new(2026, 3, 13),
-  transfers: transfers
-)
-
-xml = document.to_xml
-result = document.validate
-
-abort(result.errors.join("\n")) unless result.valid?
-
-puts xml
+path = Brot::Schema.bundled_xsd_path(Brot::PainVersion::PAIN_001_001_12)
+result = Brot::Schema.validate(xml, xsd_path: path)
 ```
 
-## Validation
-
-The gem ships with the `pain.001.001.12.xsd` file, so validation works without
-an external path:
-
 ```ruby
-result = document.validate
-
-raise result.errors.join("\n") unless result.valid?
+Brot::Schema.validate!(xml)
 ```
 
-If you want to override the schema file, pass `xsd_path:` explicitly.
+Methods:
 
-## Error Handling
+- `bundled_xsd_path(version)`
+- `validate(xml, version: nil, xsd_path: nil)`
+- `validate!(xml, version: nil, xsd_path: nil)`
 
-Invalid input values raise `Brot::Pain00100112::ValidationError`.
+If you omit both `version:` and `xsd_path:`, the gem infers the bundled schema
+from the XML document namespace.
 
-Typical examples:
+### `Brot::PainVersion`
 
-- Invalid IBAN
-- Invalid BIC
-- Empty required text fields
-- Amounts that are zero, negative, or have too many decimal places
-- Missing transfers
+`Brot::PainVersion` is the public value object for supported output formats.
+Prefer these constants when constructing documents or looking up bundled XSDs:
 
-Example:
-
-```ruby
-begin
-  Brot::Pain00100112::Transfer.new(
-    amount: '0',
-    creditor_name: 'Broken Example',
-    creditor_iban: 'INVALID',
-    end_to_end_id: 'X',
-    remittance_information: 'Broken'
-  )
-rescue Brot::Pain00100112::ValidationError => error
-  warn error.message
-end
-```
-
-## Development
-
-```sh
-bundle install
-bundle exec rake
-```
+- `Brot::PainVersion::PAIN_001_001_03`
+- `Brot::PainVersion::PAIN_001_001_12`

data/brot.gemspec

@@ -10,8 +10,8 @@ Gem::Specification.new do |spec|
 
   spec.summary = 'Build ISO 20022 pain.001 payment initiation XML for DATEV uploads.'
   spec.description = <<~TEXT
-    brot builds SEPA credit transfer XML with Nokogiri::XML::Builder.
-    The output targets pain.001.001.12 for DATEV-oriented uploads.
+    brot builds ISO 20022 credit transfer XML with Nokogiri::XML::Builder.
+    The output targets pain.001.001.03 or pain.001.001.12 for DATEV-oriented uploads.
   TEXT
   spec.homepage = 'https://github.com/garriguv/brot'
   spec.license = 'MIT'

data/lib/brot/account.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Brot
+  # Bank account details used in debtor and creditor sections.
+  class Account
+    attr_reader :bic, :iban
+
+    # @param iban [String]
+    # @param bic [String, nil]
+    def initialize(iban:, bic: nil)
+      @iban = Utils.normalize_iban!(iban)
+      @bic = bic.nil? ? nil : Utils.normalize_bic!(bic)
+    end
+
+    # Returns the BIC if present, otherwise `NOTPROVIDED`.
+    #
+    # @return [String]
+    def bic_or_placeholder
+      bic || Utils.default_financial_institution_id
+    end
+  end
+end