brot 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf6f5e4155bf59cb2cc724e9ea723bb066d5c95e745e687b66e36ad4d058d81f
+  data.tar.gz: 931cfa4d40375498939bdec52b97b9f63987e16e9efa825aec351987f7b97d6e
+SHA512:
+  metadata.gz: 46155574730e67a42bba7c1a815f1be3dcec94c2fda775a66b646b6237b6f51ee83f1d15907a4d4ed503ef9d0195316a42891d64acaa7326b83b1cca542651e5
+  data.tar.gz: 9e5c22fdb7710f461e28639032e8534c8aafed98c77943e8ba4c27460cda071db18a0bdb10b0f1f11036cd44e117d1acea521762fac85e3c7971a06fd78beaf7

data/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake test
+
+      - name: Run RuboCop
+        run: bundle exec rubocop

data/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rake test
+
+      - name: Run RuboCop
+        run: bundle exec rubocop
+
+  release:
+    name: Publish to RubyGems
+    needs: [test]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+
+      - uses: rubygems/release-gem@v1

data/.rubocop.yml

@@ -0,0 +1,9 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 4.0
+

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'minitest', '~> 5.25'
+  gem 'rake', '~> 13.3'
+  gem 'rubocop', '~> 1.76'
+  gem 'rubocop-minitest', '~> 0.38'
+  gem 'rubocop-rake', '~> 0.7'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Vincent Garrigues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,424 @@
+# brot
+
+`brot` builds ISO 20022 SEPA 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`.
+
+## Installation
+
+```ruby
+gem 'brot'
+```
+
+## What The Gem Does
+
+`brot` is intentionally focused on one narrow job:
+
+- 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 assumptions baked into the serializer:
+
+- 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`.
+
+## 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`
+
+What is not modeled yet, even though the schema allows it:
+
+- 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
+
+The practical meaning is:
+
+- 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.
+
+## Quick Start
+
+```ruby
+require 'brot'
+require 'date'
+
+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'
+)
+
+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: [transfer],
+  batch_booking: true
+)
+
+xml = document.to_xml
+result = document.validate
+
+raise result.errors.join("\n") unless result.valid?
+```
+
+## Public API
+
+The main public classes are:
+
+- `Brot::Pain00100112::Account`
+- `Brot::Pain00100112::Transfer`
+- `Brot::Pain00100112::Document`
+- `Brot::Pain00100112::Schema`
+- `Brot::Pain00100112::Schema::Result`
+
+### `Brot::Pain00100112::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.
+
+Example:
+
+```ruby
+account = Brot::Pain00100112::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.
+- `bic`
+  Example: `COBADEFFXXX`
+  Optional. If omitted, the serializer falls back to `NOTPROVIDED` in the XML.
+
+Useful methods:
+
+- `bic_or_placeholder`
+  Returns the actual BIC if present, otherwise `NOTPROVIDED`.
+
+### `Brot::Pain00100112::Transfer`
+
+Use `Transfer` for each outgoing credit transfer inside the payment batch.
+
+Example:
+
+```ruby
+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'
+)
+```
+
+Initialization attributes:
+
+- `amount`
+  Example: `'1250.50'`
+  Required. Must be positive and have at most two decimal places.
+- `creditor_name`
+  Example: `'Example Supplier GmbH'`
+  Required. Maximum length is 70 characters in this implementation.
+- `creditor_iban`
+  Example: `'DE89370400440532013000'`
+  Required. Validated as an IBAN.
+- `creditor_bic`
+  Example: `'COBADEFFXXX'`
+  Optional. Validated as a BIC if supplied.
+- `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`
+- `remittance_information`
+- `instruction_id`
+- `purpose_code`
+
+### `Brot::Pain00100112::Document`
+
+Use `Document` to represent the full payment file. This is the main entry
+point of the gem.
+
+Example:
+
+```ruby
+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: [transfer],
+  batch_booking: true,
+  created_at: Time.utc(2026, 3, 13, 12, 0, 0)
+)
+```
+
+Initialization attributes:
+
+- `message_id`
+  Example: `'MSG-20260313-01'`
+  Required. Group header message identifier. Maximum length is 35 characters.
+- `payment_information_id`
+  Example: `'PMT-20260313-01'`
+  Required. Payment information block identifier. Maximum length is 35
+  characters.
+- `initiating_party_name`
+  Example: `'Example Debtor GmbH'`
+  Required. Maximum length is 70 characters.
+- `debtor_name`
+  Example: `'Example Debtor GmbH'`
+  Required. Maximum length is 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.
+- `transfers`
+  Example: `[transfer_1, transfer_2]`
+  Required. Must contain at least one `Brot::Pain00100112::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`
+
+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)
+
+raise result.errors.join("\n") unless result.valid?
+```
+
+Available methods:
+
+- `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::Pain00100112::Schema::Result`
+
+`Schema.validate` and `Document#validate` both return a
+`Brot::Pain00100112::Schema::Result`.
+
+Example:
+
+```ruby
+result = document.validate
+
+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
+```
+
+## 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?
+```
+
+If you want to override the schema file, pass `xsd_path:` explicitly.
+
+## Error Handling
+
+Invalid input values raise `Brot::Pain00100112::ValidationError`.
+
+Typical examples:
+
+- Invalid IBAN
+- Invalid BIC
+- Empty required text fields
+- Amounts that are zero, negative, or have too many decimal places
+- Missing transfers
+
+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
+```

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+require 'rubocop/rake_task'
+
+Minitest::TestTask.create
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/brot.gemspec

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative 'lib/brot/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'brot'
+  spec.version = Brot::VERSION
+  spec.authors = ['Vincent Garrigues']
+  spec.email = ['vincent@garriguv.io']
+
+  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.
+  TEXT
+  spec.homepage = 'https://github.com/garriguv/brot'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 4.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.glob(
+    [
+      '.github/workflows/*.yml',
+      '.rubocop.yml',
+      'Gemfile',
+      'LICENSE.txt',
+      'README.md',
+      'Rakefile',
+      'brot.gemspec',
+      'lib/**/*.rb',
+      'test/**/*.rb',
+      'xsd/**/*.xsd'
+    ]
+  )
+  spec.bindir = 'exe'
+  spec.executables = []
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'nokogiri', '~> 1.18'
+end

data/lib/brot/pain00100112/account.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Brot
+  module Pain00100112
+    # Bank account details used in debtor and creditor sections.
+    #
+    # You will usually not instantiate {Account} directly because {Document}
+    # and {Transfer} build account objects internally from `*_iban` and
+    # `*_bic` keyword arguments.
+    #
+    # @example Build an account manually
+    #   account = Brot::Pain00100112::Account.new(
+    #     iban: 'DE89370400440532013000',
+    #     bic: 'COBADEFFXXX'
+    #   )
+    #
+    #   account.iban
+    #   # => "DE89370400440532013000"
+    #
+    # @attr_reader iban
+    #   The normalized IBAN.
+    #   Example: `DE89370400440532013000`
+    # @attr_reader bic
+    #   The normalized BIC, or `nil` if none was provided.
+    #   Example: `COBADEFFXXX`
+    class Account
+      attr_reader :bic, :iban
+
+      # @param iban [String]
+      #   Required IBAN.
+      #   Example: `DE89370400440532013000`
+      # @param bic [String, nil]
+      #   Optional BIC.
+      #   Example: `COBADEFFXXX`
+      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
+end